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": "PENDING",
  "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
}

El dispatch de actividades de tipo MESSAGE estará disponible próximamente.

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
`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:

Estado del dispatch	Descripción	Acción
`READY`	Actividad lista para dispatch	Pendiente de envío
`DISPATCHED`	Enviada exitosamente (respuesta `2xx`)	Completo
`RETRYING`	Fallo temporal — reintentando	Reten reintenta automáticamente
`FAILED`	Todos los reintentos agotados	Requiere intervención manual

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.