API de Integración de Tareas
Conecta tu sistema con Reten para consultar actividades de tipo tarea, enviar resultados y recibir gestiones.
La API de integración de tareas de Reten permite a los desarrolladores del tenant consultar actividades de tipo tarea asignadas, enviar resultados y recibir gestiones en tiempo real. Esta sección cubre exclusivamente la integración para actividades de tipo TASK. Existen dos modos de integración según la dirección del flujo de datos.
Esta documentación está dirigida a desarrolladores del tenant que integran sus sistemas con Reten usando un proveedor disponible en la plataforma (por ejemplo, YOM). Si necesitas incorporar un nuevo proveedor a la plataforma, contacta al equipo de Reten.
Modos de integración
| Modo | Dirección | Descripción | Caso de uso |
|---|---|---|---|
| Pull | Tu sistema → Reten | Tu sistema consulta actividades y envía resultados mediante la API REST | Integración asíncrona, procesamiento por lotes, sistemas que prefieren controlar el ritmo de consulta |
| Push (Dispatch) | Reten → Proveedor | Reten envía las actividades al endpoint del proveedor en tiempo real | Integración en tiempo real, sistemas que necesitan recibir actividades inmediatamente al ser creadas |
Autenticación rápida
Las integraciones se autentican con una clave de API, enviada en el header x-api-key:
x-api-key: YOUR_API_KEYLa clave de API autentica tu integración, define los permisos disponibles y resuelve automáticamente el tenant asociado. No es necesario enviar el header x-tenant-id. Listar tareas y enviar resultados son endpoints project-optional: una clave de proyecto siempre trabaja en su propio proyecto, mientras que una clave de tenant abarca todos los proyectos del tenant y envía x-project-id sólo para acotar una solicitud a un proyecto o para enviar un resultado sin activity_id — ver Alcance de la clave.
Los endpoints de integración también aceptan un token de usuario (JWT), pero la clave de API es el método pensado para integraciones. Consulta Autenticación para más detalles.
Ambientes
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.
Primeros pasos
Quickstart: Integración Pull
Configura tu primera integración en 4 pasos con ejemplos listos para ejecutar.
Recibir Gestiones (Dispatch)
Aprende cómo Reten despacha actividades al endpoint del proveedor configurado.
Autenticación
Detalles sobre headers requeridos, permisos y claves de API.
Manejo de Errores
Formato de errores, códigos de estado y soluciones.
Endpoints disponibles
| Método | Ruta | Descripción |
|---|---|---|
GET | /api/integration/activities/tasks | Listar actividades de tipo tarea visibles para tu clave de API |
POST | /api/integration/activity-results/tasks | Enviar el resultado de una gestión de tipo tarea |
GET | /api/integration/task-result-type-configs | Listar configuraciones de tipos de resultado disponibles |
POST | /api/integration/commerces/batch-upsert | Crear o actualizar hasta 500 comercios en una sola solicitud — ver Upsert por Lote |
POST | /api/integration/operators/batch-upsert | Crear o actualizar hasta 500 operadores en una sola solicitud — ver Upsert por Lote |
POST | /api/integration/routes/batch-upsert | Crear o actualizar hasta 500 rutas en una sola solicitud — ver Upsert por Lote |