Crear Actividad

POST /api/activities

Crea una nueva actividad TASK con asignación de comercio.

Auth: Requerida — permiso CREATE_ACTIVITY

Cuerpo de la Solicitud

Campo	Tipo	Requerido	Descripción
`type`	string	Sí	`TASK`
`reason`	string	Sí	Razón para crear la actividad
`channel`	string	Sí	`SALESMAN`, `CALLCENTER`
`commerce_id`	UUID	Sí	ID del comercio objetivo
`idempotency_key`	string	Sí	Clave única por tenant (evita duplicados)
`scheduled_at`	ISO 8601	Sí	Cuándo debe ejecutarse la actividad
`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	No	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:

Campo	Tipo	Requerido	Descripción
`assigned_route_id`	UUID	No	Ruta asignada
`assigned_route_external_id`	string	No	Ruta asignada por ID externo
`assigned_operator_id`	UUID	No	Operador asignado
`assigned_operator_external_id`	string	No	Operador asignado por ID externo

Ejemplo

curl -X POST https://api.reten.ai/api/activities \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-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>",
    "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>",
    },
    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.

{
  "id": "ee0e8400-e29b-41d4-a716-446655440000",
  "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
`404`	Comercio no encontrado
`409`	La clave de idempotencia ya existe