Recibir Gestiones (Dispatch)
Cómo Reten despacha actividades al endpoint del proveedor configurado en tiempo real.
El modo Push (Dispatch) permite que Reten envíe actividades directamente al endpoint del proveedor configurado en tiempo real, sin necesidad de que tu sistema consulte periódicamente la API.
El dispatch requiere que el tenant tenga al menos un proveedor configurado en la plataforma. Los proveedores disponibles son registrados por el equipo de Reten. Si necesitas incorporar un nuevo proveedor, contacta a Reten.
Concepto
Cuando un administrador del tenant configura el dispatch para un proveedor y canal específico, Reten envía automáticamente las actividades nuevas al endpoint registrado del proveedor. El flujo es:
- Se crea una actividad en Reten (manual desde la app de Reten o por el Growth Engine de Reten)
- Reten evalúa las configuraciones de dispatch activas para el tenant y canal
- Reten construye el payload con los datos de la actividad
- Reten envía el payload al endpoint del proveedor vía HTTP POST
- El proveedor procesa la actividad y puede enviar resultados de vuelta a Reten vía
POST /api/integration/activity-results/tasks
Configuración
Ambientes de Reten
| Ambiente | Panel de Admin | API Base URL |
|---|---|---|
| Development | app-development.reten.ai | https://api-development.reten.ai |
| Staging | app-staging.reten.ai | https://api-staging.reten.ai |
| Production | app.reten.ai | https://api.reten.ai |
Usa la URL del panel de admin para gestionar claves de API y configuraciones de dispatch. Reemplaza BASE_URL en los ejemplos de código con la API Base URL de tu ambiente.
El dispatch se configura desde el panel de administración del tenant:
- Navega a Gestiones → Configuración de Dispatch
- Haz clic en Crear configuración
- Selecciona el proveedor y canal
- Ingresa la URL del endpoint del proveedor
- Configura las credenciales de autenticación del proveedor
- Activa la configuración
La configuración del dispatch es responsabilidad del administrador del tenant. Deberás contar con la URL del endpoint del proveedor y las credenciales de autenticación que este requiera.
Payload de actividad
Cuando Reten envía una actividad al endpoint del proveedor, el cuerpo de la solicitud HTTP POST contiene un objeto con la siguiente estructura.
Esta es la estructura por defecto del payload. Si el proveedor requiere un formato distinto, el administrador del tenant puede configurar un mapeo de payload para transformar los campos antes del envío — no es necesario que el proveedor adapte su interfaz a este formato.
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"activityOrigin": "ACTIVITY",
"type": "TASK",
"status": "READY",
"score": 85,
"channel": "SALESMAN",
"scheduledAt": "2026-04-15T09:00:00.000Z",
"occurredAt": null,
"createdAt": "2026-04-10T14:30:00.000Z",
"lifecycleStatus": "SCHEDULED",
"lifecycleStatusLabel": "Programada",
"lifecycleStatusDetail": null,
"canForceRetryDispatch": false,
"commerceExternalId": "COM-001",
"commerceName": "Farmacia Central",
"reason": {
"code": "CHURN_RISK",
"label": "Riesgo de fuga"
},
"userStatus": null,
"commerceAssignment": {
"commerceExternalId": "COM-001",
"assignmentReason": "Asignación por ruta",
"commerce": {
"externalId": "COM-001",
"name": "Farmacia Central"
}
},
"activityDetails": {
"type": "TASK",
"assignedRouteCode": "RUTA-NORTE-01",
"assignedOperatorExternalId": "OP-042",
"assignedRoute": {
"code": "RUTA-NORTE-01",
"name": "Ruta Norte"
},
"assignedOperator": {
"externalId": "OP-042",
"name": "Carlos Pérez",
"type": "SALESMAN"
}
},
"activityResult": null
}La estructura del payload es idéntica a la respuesta del endpoint Listar Actividades — consulta esa referencia para la descripción detallada de cada campo.
Campos clave del payload
| Campo | Uso recomendado |
|---|---|
id | Almacenar como referencia para enviar resultados vía activity_id |
commerceExternalId | Identificar el comercio en el sistema del proveedor |
commerceName | Mostrar al operador |
activityDetails.assignedOperatorExternalId | Asignar al operador correspondiente en el sistema del proveedor |
activityDetails.assignedRoute | Contexto de ruta para planificación |
scheduledAt | Fecha programada para la gestión |
score | Puntuación de prioridad — útil para enrutamiento o ranking en el sistema del proveedor |
reason | Contexto sobre por qué se creó la actividad |
Comportamiento de reintentos
Si el endpoint del proveedor no responde con un código 2xx, Reten reintenta el envío automáticamente. Los status operacionales que toma la actividad durante el ciclo de dispatch (ver Activity States para el catálogo completo y las transiciones válidas):
| Estado del dispatch | Descripción | Acción |
|---|---|---|
| Actividad está completamente resuelta y lista para accionar. Si el cliente tiene configurado un proveedor para hacer dispatch de las actividades, la próxima acción del sistema intenta despachar, de lo contrario la actividad permanece READY y podrá ser accionada desde la plataforma interna por algún operador. | Actividad lista para dispatch | Pendiente de envío |
| Actividad fue entregada al proveedor externo. Aplica únicamente cuando el cliente tiene un proveedor de dispatch configurado para la actividad; clientes que operan exclusivamente desde la plataforma interna de Reten no transitan por este estado. Tener proveedor de dispatch no impide que el resultado se registre desde la plataforma interna: el outcome puede llegar tanto desde el proveedor externo como desde la plataforma interna. | Enviada exitosamente (respuesta 2xx) | Completo |
| Ha fallado al menos un intento de dispatch; el sistema reintentará automáticamente. Cada reintento mantiene la actividad en este estado. Pasa a DISPATCHED cuando un intento tiene éxito, o a FAILED cuando se agotan los reintentos disponibles. | Fallo temporal — reintentando | Reten reintenta automáticamente |
| Actividad alcanzó un estado terminal fallido por una de dos vías: (a) los intentos de dispatch se agotaron sin éxito; o (b) un proceso de cierre de fin de día detectó una actividad que quedó reintentando, y la marcó como FAILED con resultado NOT_EXECUTED. Aunque es terminal, una actividad FAILED puede recuperarse manualmente vía endpoint dedicado, que la reintenta una vez; el intento puede terminar en DISPATCHED, RETRYING o nuevamente FAILED. | Todos los reintentos agotados | Requiere intervención manual (force-retry-dispatch) |
El endpoint del proveedor debe responder con un código HTTP 2xx (ej. 200 OK) para confirmar la recepción. Cualquier otro código se considera un fallo y dispara el proceso de reintentos.
Mapeo de payload
El administrador del tenant puede configurar un mapeo de payload que transforma la estructura del objeto antes de enviarlo al endpoint del proveedor. Esto permite adaptar los nombres de campos y la estructura a lo que el sistema del proveedor espera, sin necesidad de cambios adicionales.
El mapeo se configura durante la creación o edición de la configuración de dispatch desde el panel de administración.
Siguiente paso
Una vez que el proveedor recibe actividades vía dispatch, tu sistema puede enviar resultados de vuelta a Reten vía POST /api/integration/activity-results/tasks. Usa el campo id del payload recibido como activity_id al enviar el resultado.