Guía para SaaS Builders

Si estás construyendo un SaaS (como un CRM, ERP o plataforma de marketing) y querés ofrecer integraciones de WhatsApp a tus propios clientes, esta guía explica cómo estructurar tu arquitectura utilizando SinapsIA Connect.

1. Arquitectura Multi-Tenant: ¿Quién es quién?

El gateway utiliza un formato estricto para identificar y aislar entornos: tenantId__clientId__label.

  • tenantId: Es tu empresa/SaaS. Vos sos nuestro cliente directo. Tenés una API Key que te permite gestionar todo debajo de este paraguas.
  • clientId: Son tus clientes finales (las empresas o usuarios que pagan tu SaaS).
  • label: Un identificador adicional (ej. ventas, soporte, main) por si un cliente tuyo necesita conectar múltiples números.

Ejemplo práctico: Si tu SaaS se llama "OmniChat" y le vendés el servicio a la "Zapatería Pepe", cuando ellos conecten su número, la instancia debería llamarse: omnichat__pepe__ventas.

2. Provisioning y Configuración Inicial

Para que tu SaaS pueda operar a gran escala, primero debe ser provisionado en nuestro Gateway. Nuestro equipo configurará tu cuenta, asignará tus límites iniciales y te entregará tu API Key Maestra.

Paso a paso:

  • Contactá a soporte@sinapsia.com.ar indicando el nombre de tu SaaS y el volumen estimado de clientes.
  • Recibirás tu tenantId único y tu API Key.
  • Con esas credenciales, ya podrás comenzar a crear instancias para tus clientes usando POST /instance/create.

3. Límites por Plan y Gestión de Cupos (Error 402)

Tu SaaS tiene asignado un límite máximo de instancias concurrentes (instanceLimit). Si intentás hacer un POST /instance/create y la creación excede tu límite global, el gateway devolverá un error 402 Payment Required.

Mejores prácticas para tu backend:

  • Llevar un registro local de cuántas instancias activas consumieron tus clientes.
  • Prevenir que clientes morosos mantengan instancias activas.
  • Ejecutar siempre DELETE /instance/:name cuando un cliente tuyo cancela su suscripción o desconecta su número. Esto libera tu cupo inmediatamente.

4. Flujo de Reconexión de Instancias

Las sesiones de WhatsApp pueden desconectarse por múltiples razones (el usuario cerró la sesión desde su celular, el dispositivo vinculado se reseteó, inactividad prolongada). Cuando esto ocurre, el gateway enviará el evento instance.disconnected a la URL de webhook que configuraste.

bash
// 1. Recibís evento de desconexión en tu webhook
{
  "event": "instance.disconnected",
  "instanceName": "mi-saas__cliente01__main"
}

// 2. Opcional: Eliminar la instancia vieja para limpiar el estado
DELETE /instance/mi-saas__cliente01__main

// 3. Crear una nueva instancia (o la misma si la eliminaste)
POST /instance/create
{ ... }

// 4. Solicitar nuevo QR para que tu cliente lo escanee
GET /instance/mi-saas__cliente01__main/qr

¿Qué pasa con la cola de mensajes? Si ocurre una desconexión y decidís eliminar la instancia (DELETE), todos los mensajes que estaban pendientes de envío se marcarán como failed. Tu sistema deberá leer estos fallos vía API o Webhook para decidir si reencolarlos una vez que el cliente reconecte su número, o notificarle al usuario que no se pudieron entregar.