Guía de Connector para SaaS

Connector para SaaS es una capa de conexión de cuentas para productos SaaS. Úsala cuando cada usuario final necesite conectar su propia cuenta de Gmail, Slack, Notion u otro tercero, y tu backend necesite ejecutar acciones de Connector después de la autorización. OOMOL Console gestiona Projects, configuraciones de proveedor, claves API y cuentas conectadas; tu backend crea enlaces de autorización, maneja callbacks, selecciona cuentas e inicia llamadas de acción.

Una integración completa tiene dos partes: configurar un proyecto y un servicio en OOMOL Console, y luego hacer que tu backend cree enlaces de autorización, maneje callbacks, seleccione cuentas y ejecute acciones.

Temas principales:

• Qué recursos prepara un administrador en OOMOL Console.
• Qué IDs y secretos necesita almacenar tu backend.
• Qué hacen tu frontend y backend cuando un usuario final conecta una cuenta.
• Cómo seleccionar la cuenta conectada y ejecutar una acción.
• Qué páginas, estados, registros y vistas de uso de Console ayudan a la solución de problemas.

Modelo de integración

Una integración SaaS tiene una fase de configuración y una fase de ejecución.

Los administradores completan la fase de configuración en OOMOL Console antes del flujo del usuario final. Se prepara el Project, la configuración de proveedor y la clave API del backend, y se registran los IDs y secretos necesarios en tiempo de ejecución.

La fase de ejecución ocurre en el backend de tu producto. Representa tu Project SaaS al crear solicitudes de autorización de cuenta, leer el estado de la solicitud y ejecutar acciones. Las solicitudes de ejecución incluyen la clave API del Project:

authorization: Bearer <project-api-key>

La clave API del proyecto permanece en tu backend. Los usuarios finales solo usan la interfaz de tu producto o abren la URL de autorización OAuth devuelta por Connector.

Datos a almacenar

Una integración típica almacena estos valores:

Si tus usuarios pueden conectar varias cuentas de Gmail, almacena el connectedAccountId o alias de cada cuenta para que las llamadas en tiempo de ejecución no dependan de la selección predeterminada de “última cuenta”.

Paso 1: Crear un proyecto

Un proyecto es el límite de aislamiento para una integración SaaS. Aísla configuraciones de proveedor, claves API, cuentas conectadas, registros de ejecución y uso.

En OOMOL Console:

1. Abre Projects en la barra lateral izquierda.
2. Haz clic en Create project.
3. Introduce el nombre del proyecto.
4. Después de crearlo, abre el proyecto y almacena el ID del proyecto como PROJECT_ID.

La página del proyecto tiene entradas como Provider configs, API Keys, Connected accounts, Execution logs y Usage. La configuración restante ocurre dentro de este proyecto.

El nombre del proyecto aparece en la página de entrada de autorización OAuth. Las integraciones en producción deben usar un nombre de producto que los usuarios finales puedan reconocer, lo que hace que el destino de la autorización sea claro.

Paso 2: Crear una configuración de proveedor

Una configuración de proveedor define cómo se conecta este proyecto a un servicio de Connector. Las solicitudes en tiempo de ejecución la pasan como providerConfigId. Para Gmail OAuth:

1. Abre Provider configs en la barra lateral del proyecto.
2. Haz clic en Create provider config.
3. Selecciona o rellena estos campos.
4. Haz clic en Create.

Después de crearla, almacena el ID de configuración del proveedor como PROVIDER_CONFIG_ID. Tu backend debería pasarlo explícitamente al crear enlaces de autorización y ejecutar acciones.

Cuando cada proyecto SaaS usa su propio cliente OAuth, cambia Client config source a un cliente personalizado y proporciona el clientId y clientSecret correspondientes.

Con un cliente OAuth personalizado, configura la URL de callback de Connector en la consola del proveedor. OOMOL Console o tu configuración de despliegue proporciona esta URL orientada al administrador.

Para un servicio con clave API, elige el tipo de autenticación de clave API correspondiente. Cuando un usuario final conecta una cuenta, tu backend envía la clave API del proveedor del usuario a Connector para su almacenamiento.

Paso 3: Crear una clave API del proyecto

Almacena la clave API del Project en el almacenamiento de secretos del backend y úsala solo desde código de servidor de confianza.

En la página del proyecto:

1. Abre API Keys en la barra lateral del proyecto.
2. Haz clic en Create API Key.
3. Introduce un nombre de clave. Usa un nombre que facilite la rotación y la solución de problemas, como production server key o staging server key.
4. Haz clic en Create.
5. Copia la clave en texto plano del diálogo de una sola vez y almacénala como PROJECT_API_KEY.

La clave en texto plano se devuelve solo una vez. Las listas posteriores muestran solo el prefijo de la clave, la hora de creación, la hora de uso reciente y metadatos similares. Si la clave se filtra, revócala en Console y crea una nueva.

Paso 4: Permitir que el usuario final conecte una cuenta

Ahora pasa al flujo de ejecución del producto. Supón que tu producto tiene un usuario con el ID customer-1 y que quiere conectar Gmail.

Tu backend crea un enlace de autorización OAuth:

CONNECTOR=https://connector.oomol.com
PROJECT_API_KEY=oo_proj_...

curl -sS -X POST "$CONNECTOR/v1/saas/connected-accounts/link" \
  -H "content-type: application/json" \
  -H "authorization: Bearer $PROJECT_API_KEY" \
  -d '{
    "providerConfigId": "pc-1",
    "userId": "customer-1",
    "alias": "work",
    "returnUri": "https://app.example/connector/callback"
  }'

La respuesta contiene data.id y data.authorizationUrl. Antes de redirigir al usuario final, almacena data.id en tu backend de confianza junto con el Project esperado, la configuración de proveedor y el usuario del producto. Luego redirige al usuario al data.authorizationUrl propiedad de Connector.

Esa página muestra brevemente el título de visualización del proyecto, el icono del proyecto y el nombre de visualización de la configuración del proveedor, y luego redirige a la página OAuth real del proveedor. Después de que el usuario autoriza, el proveedor llama de vuelta a Connector, y Connector redirige al returnUri que proporcionaste.

Si tiene éxito, returnUri recibe parámetros de consulta como:

status=success
service=gmail
providerConfigId=pc-1
externalUserId=customer-1
connectedAccountId=ca-1

Trata estos parámetros de consulta solo como retroalimentación de navegación. No uses un connectedAccountId proporcionado por el navegador como la vinculación de la cuenta. Consulta la solicitud de conexión guardada desde tu backend con la clave API del Project; la ruta de la API conserva el nombre connection-requests:

curl -sS "$CONNECTOR/v1/saas/connection-requests/$REQUEST_ID" \
  -H "authorization: Bearer $PROJECT_API_KEY"

Conserva el data.connectedAccountId de la respuesta solo cuando data.status sea connected y su projectId, providerConfigId y externalUserId coincidan con los valores que tu backend almacenó para esa solicitud. Maneja failed y expired como estados terminales sin crear una vinculación de cuenta.

Si el usuario cancela o el proveedor devuelve un error, returnUri recibe:

status=error
code=<connector-error-code>
message=<human-readable-message>

returnUri debe usar http o https. Los enlaces OAuth caducan después de 10 minutos de forma predeterminada.

Paso 5: Ejecutar una acción

Una vez conectada la cuenta, el backend puede ejecutar acciones con el selector de cuenta almacenado.

curl -sS -X POST "$CONNECTOR/v1/saas/actions/gmail.send_email" \
  -H "content-type: application/json" \
  -H "authorization: Bearer $PROJECT_API_KEY" \
  -H "x-request-id: req-saas-action-1" \
  -d '{
    "providerConfigId": "pc-1",
    "userId": "customer-1",
    "connectedAccountId": "ca-1",
    "input": {
      "to": "someone@example.com",
      "subject": "Hello",
      "body": "Hello from My SaaS"
    }
  }'

Reglas:

• Pasa exactamente uno de providerConfigId o service. Las integraciones en producción deberían preferir providerConfigId.
• Pasa como máximo uno de connectedAccountId o alias. Las integraciones en producción deberían pasar uno de ellos explícitamente.
• Si no hay ningún selector de cuenta presente, Connector elige la última cuenta conectada activa bajo el mismo projectId + providerConfigId + userId.
• El prefijo de servicio del ID de acción debe coincidir con el servicio de la configuración del proveedor. Por ejemplo, gmail.send_email debe usar una configuración de proveedor de Gmail.

La respuesta exitosa incluye executionId, actionId y la salida de la acción. Almacena executionId en tus propios registros de operación para soporte y solución de problemas.

Paso 6: Gestionar las conexiones de los usuarios

Los productos normalmente necesitan mostrar a los usuarios qué cuentas han conectado. El enfoque recomendado es almacenar connectedAccountId, alias, service, providerConfigId y tu propio userId en la base de datos de tu producto después de un callback exitoso, y luego renderizar la lista de cuentas a partir de esos datos.

Para verificar el estado del lado de Connector, usa Connected accounts en OOMOL Console para ver las cuentas conectadas bajo el proyecto actual.

El campo available indica si la cuenta puede ejecutar acciones actualmente. Es true solo cuando la configuración del proveedor está activa, la cuenta conectada está activa, la aplicación subyacente está activa y existe una credencial.

Si tu producto permite a los usuarios renombrar cuentas, actualiza primero el nombre para mostrar en la base de datos de tu producto. Cuando un administrador necesita verificar el estado del lado de Connector, usa Console para inspeccionar la cuenta correspondiente.

Cuando un usuario desconecta una cuenta, haz que el backend de tu producto ejecute el flujo de desconexión y actualice la base de datos de tu producto. Los administradores pueden usar Console para verificar si la cuenta sigue disponible.

La desconexión conserva el registro de la cuenta conectada pero elimina la credencial subyacente. Los registros históricos aún pueden hacer referencia a la cuenta; las acciones futuras no pueden usarla.

Paso 7: Solucionar problemas y operar

Al solucionar problemas de la acción de un usuario, abre Execution logs en OOMOL Console. Los filtros comunes incluyen providerConfigId, userId, appId, status=success|error y action.

Al solucionar problemas, acota la vista primero por servicio o configuración de proveedor. Si tus registros de operación almacenan executionId, úsalo para conectar una operación del lado del producto con el registro del lado de Connector.

Para las operaciones, usa Usage para revisar las tendencias de uso diario y el uso agrupado por servicio. Las ventanas comunes son de 7, 30 o 90 días.

days solo admite 7, 30 o 90.

Qué llama tu backend en tiempo de ejecución

Para el flujo de Gmail OAuth de esta guía, el backend maneja tres tareas:

• Crear un enlace de autorización y enviar al usuario a la entrada de autorización de Connector.
• Confirmar la solicitud de autorización después del callback y luego almacenar connectedAccountId.
• Ejecutar acciones con la cuenta almacenada cuando el usuario activa una función del producto.

Prefiere OOMOL Console para la configuración y las operaciones, como crear proyectos, crear configuraciones de proveedor, crear claves API de proyecto, revisar cuentas conectadas, leer registros de ejecución y comprobar el uso.

Solución de problemas

Cuando falla la conexión de la cuenta o la ejecución de una acción, comprueba en este orden:

1. Confirma que tu backend usa la PROJECT_API_KEY para el Project actual y la mantiene en el almacenamiento de secretos del backend.
2. Confirma que la solicitud usa el providerConfigId para la configuración de proveedor que creaste.
3. Confirma que cada cuenta para el mismo usuario tiene un alias único.
4. Abre Connected accounts en Console y comprueba si la cuenta sigue disponible.
5. Abre Execution logs en Console y filtra por configuración de proveedor, ID de usuario o executionId.