Actividades
Crear Actividad
Crear una nueva actividad asignada a un comercio.
POST /api/activities
Crea una nueva actividad TASK con asignación de comercio.
Auth: Requerida — permiso activity:create
Cuerpo de la Solicitud
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
type | string | Sí | TASK |
reason | string | Sí | Código de razón: solo minúsculas, dígitos y _ (^[a-z0-9_]+$), máximo 100 caracteres. Un código que no está en el catálogo de razones del tenant se agrega al vuelo, con una etiqueta derivada del código (monthly_visit → Monthly visit) |
channel | string | Sí | SALESMAN, CALLCENTER |
commerce_id | UUID | Condicional | ID del comercio objetivo. Envía este campo o commerce_external_id: al menos uno es obligatorio. Si envías los dos, gana commerce_id |
commerce_external_id | string | Condicional | Comercio objetivo por ID externo (máximo 255 caracteres). Si ningún comercio lo tiene, la API crea un comercio placeholder con ese ID externo |
idempotency_key | string | Sí | Clave única por tenant (evita duplicados) |
scheduled_at | ISO 8601 | Sí | Cuándo debe ejecutarse la actividad |
intent_category | string | No | ONBOARDING, MARKETING, COLLECTION, RETENTION, NOTIFICATION, SURVEY o VALIDATION. Por defecto NOTIFICATION |
suggested_execution_time | ISO 8601 | No | Tiempo sugerido para la ejecución |
user_status | string | No | Contexto de estado del usuario |
score | integer | No | Puntuación de prioridad |
assignment_reason | string | No | Razón de la asignación |
activity_details | object | Sí, para TASK | Detalles específicos del tipo — la forma depende de type (ver abajo) |
activity_details
Para type: "TASK", el objeto activity_details lleva la asignación de ruta/operador y es obligatorio. La ruta y el operador son obligatorios, cada uno por ID o por ID externo; si envías las dos formas, gana el ID. Un ID externo que ninguna ruta u operador tiene hace que la API cree un placeholder con él.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
assigned_route_id | UUID | Condicional | Ruta asignada. Envía este campo o assigned_route_external_id |
assigned_route_external_id | string | Condicional | Ruta asignada por ID externo (máximo 255 caracteres) |
assigned_operator_id | UUID | Condicional | Operador asignado. Envía este campo o assigned_operator_external_id |
assigned_operator_external_id | string | Condicional | Operador asignado por ID externo (máximo 255 caracteres) |
Ejemplo
curl -X POST https://api.reten.ai/api/activities \
-H "Authorization: Bearer <token>" \
-H "x-tenant-id: <tenant-id>" \
-H "x-project-id: <project-id>" \
-H "Content-Type: application/json" \
-d '{
"type": "TASK",
"reason": "monthly_visit",
"channel": "SALESMAN",
"commerce_id": "880e8400-e29b-41d4-a716-446655440000",
"idempotency_key": "task-2025-01-15-001",
"scheduled_at": "2025-01-16T09:00:00.000Z",
"activity_details": {
"assigned_route_id": "dd0e8400-e29b-41d4-a716-446655440000",
"assigned_operator_id": "cc0e8400-e29b-41d4-a716-446655440000"
}
}'const response = await fetch("https://api.reten.ai/api/activities", {
method: "POST",
headers: {
"Authorization": "Bearer <token>",
"x-tenant-id": "<tenant-id>",
"x-project-id": "<project-id>",
"Content-Type": "application/json",
},
body: JSON.stringify({
type: "TASK",
reason: "monthly_visit",
channel: "SALESMAN",
commerce_id: "880e8400-e29b-41d4-a716-446655440000",
idempotency_key: "task-2025-01-15-001",
scheduled_at: "2025-01-16T09:00:00.000Z",
activity_details: {
assigned_route_id: "dd0e8400-e29b-41d4-a716-446655440000",
assigned_operator_id: "cc0e8400-e29b-41d4-a716-446655440000",
},
}),
});
const activity = await response.json();import requests
response = requests.post(
"https://api.reten.ai/api/activities",
headers={
"Authorization": "Bearer <token>",
"x-tenant-id": "<tenant-id>",
"x-project-id": "<project-id>",
},
json={
"type": "TASK",
"reason": "monthly_visit",
"channel": "SALESMAN",
"commerce_id": "880e8400-e29b-41d4-a716-446655440000",
"idempotency_key": "task-2025-01-15-001",
"scheduled_at": "2025-01-16T09:00:00.000Z",
"activity_details": {
"assigned_route_id": "dd0e8400-e29b-41d4-a716-446655440000",
"assigned_operator_id": "cc0e8400-e29b-41d4-a716-446655440000",
},
},
)
activity = response.json()Respuesta 201 Created
Una actividad TASK nace en READY y queda lista para despacharse de inmediato: la identidad del comercio asignado es lo único que el despacho necesita. Ver Activity States para el catálogo completo.
Si una actividad del proyecto activo ya tiene esa idempotency_key, la API no crea nada y responde 200 OK con la actividad existente.
{
"id": "ee0e8400-e29b-41d4-a716-446655440000",
"projectId": "3f6c2b1a-8d4e-4f7a-9b2c-5e1d0a7f6c34",
"type": "TASK",
"reason": {
"code": "monthly_visit",
"label": "Visita Mensual"
},
"channel": "SALESMAN",
"status": "READY",
"userStatus": null,
"idempotencyKey": "task-2025-01-15-001",
"scheduledAt": "2025-01-16T09:00:00.000Z",
"commerceAssignment": {
"commerceId": "880e8400-e29b-41d4-a716-446655440000"
}
}Respuestas de Error
| Estado | Descripción |
|---|---|
400 | Error de validación: un campo faltante o inválido, o un campo que el endpoint no acepta |
400 | Ni commerce_id ni commerce_external_id — Se requiere al menos uno de los campos commerce_id o commerce_external_id. |
400 | TASK sin activity_details — TASK activities require activityDetails |
400 | activity_details sin ruta o sin operador — assigned_route_id is required for TASK activities / assigned_operator_id is required for TASK activities |
400 | La ruta o el operador asignado está inactivo — Assigned route is not active / Assigned operator is not active |
400 | user_status no es un código activo del catálogo de estados de retención del tenant — User retention status "<code>" is not configured for this tenant |
404 | commerce_id, assigned_route_id o assigned_operator_id no existe — Commerce not found / Route not found / Operator not found |
409 | La idempotency_key ya la usa una actividad de otro proyecto del tenant — La clave de idempotencia ya está en uso. |