Listar Actividades

GET /api/integration/activities/tasks

Retorna una lista paginada de actividades de tipo tarea visibles para la clave de API de tu integración, de un proyecto o de todo el tenant (ver Header requerido).

Autenticación: Requerida — permiso activity:view

Header requerido

Header	Valor
`x-api-key`	`YOUR_API_KEY`

x-project-id es opcional: este es un endpoint project-optional. Con una clave de tenant o un token de usuario, enviar el header acota la lista a ese proyecto; sin él, la lista abarca todos los proyectos del tenant, y cada actividad trae su projectId. Una clave de proyecto siempre lista las actividades de su propio proyecto. Un header enviado se valida — ver Errores de proyecto.

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
`page`	number	No	Número de página (por defecto: `1`)
`per_page`	number	No	Resultados por página (por defecto: `25`, máximo: `100`)
`status`	string	No	Filtrar por estado de actividad (ver Activity States). Valores filtrables: `READY`, `RETRYING`, `DISPATCHED`, `COMPLETED`, `CANCELED`, `FAILED`
`result_status`	string	No	Filtrar por estado del resultado (ver Activity States). Valores filtrables: `COMPLETED`, `NOT_EXECUTED`
`channel`	string	No	Filtrar por canal (`SALESMAN`, `CALLCENTER`, etc.)
`external_commerce_id`	string	No	Filtrar por ID externo del comercio
`external_operator_id`	string	No	Filtrar por ID externo del operador
`scheduled_from`	string	No	Fecha mínima de programación (ISO 8601)
`scheduled_to`	string	No	Fecha máxima de programación (ISO 8601)

Ejemplo

curl -X GET "BASE_URL/api/integration/activities/tasks?page=1&per_page=10&status=READY" \
  -H "x-api-key: YOUR_API_KEY"

const params = new URLSearchParams({
  page: "1",
  per_page: "10",
  status: "READY",
});

const response = await fetch(
  `${BASE_URL}/api/integration/activities/tasks?${params}`,
  {
    headers: {
      "x-api-key": "YOUR_API_KEY",
    },
  }
);

const data = await response.json();

import requests

response = requests.get(
    f"{BASE_URL}/api/integration/activities/tasks",
    headers={
        "x-api-key": "YOUR_API_KEY",
    },
    params={
        "page": 1,
        "per_page": 10,
        "status": "READY",
    },
)

data = response.json()

Respuesta `200 OK`

El siguiente es un ejemplo ilustrativo de la forma del response. Los valores de campos como id, scheduledAt, status, lifecycleStatus, etc., varían según el estado real de cada actividad. Para el catálogo completo de posibles valores de status y lifecycleStatus, ver Activity States.

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "activityOrigin": "ACTIVITY",
      "projectId": "3f6c2b1a-8d4e-4f7a-9b2c-5e1d0a7f6c34",
      "type": "TASK",
      "status": "READY",
      "score": 85,
      "channel": "SALESMAN",
      "scheduledAt": "2026-04-10T18:00:00.000Z",
      "occurredAt": null,
      "createdAt": "2026-04-10T14:30:00.000Z",
      "lifecycleStatus": "READY",
      "lifecycleStatusLabel": "Lista",
      "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
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 47,
    "total_pages": 5,
    "has_next": true,
    "has_previous": false
  }
}

Ejemplo de ejecución independiente (STANDALONE)

Los items con activityOrigin: "STANDALONE" provienen de un resultado registrado como ejecución independiente, sin una actividad previa: scheduledAt repite el occurredAt del resultado, y activityResult siempre viene poblado. Un activityResult poblado también aparece en los items ACTIVITY una vez gestionados.

Abajo se muestra solo el item — el envoltorio pagination que lo rodea es idéntico al del ejemplo anterior.

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "activityOrigin": "STANDALONE",
  "projectId": "3f6c2b1a-8d4e-4f7a-9b2c-5e1d0a7f6c34",
  "type": null,
  "reason": null,
  "userStatus": null,
  "status": null,
  "score": null,
  "scheduledAt": "2026-04-12T16:45:00.000Z",
  "occurredAt": "2026-04-12T16:45:00.000Z",
  "createdAt": "2026-04-12T16:47:00.000Z",
  "lifecycleStatus": null,
  "lifecycleStatusLabel": null,
  "lifecycleStatusDetail": null,
  "canForceRetryDispatch": false,
  "channel": "SALESMAN",
  "commerceExternalId": "COM-001",
  "commerceName": "Farmacia Central",
  "commerceAssignment": null,
  "activityResult": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "resultStatus": "COMPLETED",
    "source": "STANDALONE",
    "origin": "PLATFORM",
    "channel": "SALESMAN",
    "occurredAt": "2026-04-12T16:45:00.000Z",
    "createdAt": "2026-04-12T16:47:00.000Z",
    "resultDetails": {
      "type": "TASK",
      "result": {
        "code": "RESCHEDULE",
        "label": "Reprogramar visita"
      },
      "comment": null,
      "requiresFutureScheduledAt": true,
      "externalOperatorId": "OP-042",
      "operator": {
        "externalId": "OP-042",
        "name": "Carlos Pérez"
      }
    }
  },
  "activityDetails": {
    "type": "TASK",
    "assignedRouteCode": null,
    "assignedOperatorExternalId": "OP-042",
    "assignedRoute": null,
    "assignedOperator": {
      "externalId": "OP-042",
      "name": "Carlos Pérez",
      "type": "SALESMAN"
    }
  }
}

Campos de la actividad

Campo	Tipo	Descripción
`id`	string	Identificador único de la actividad
`activityOrigin`	`"ACTIVITY"` \| `"STANDALONE"`	Origen de la actividad
`projectId`	string	Proyecto al que pertenece la actividad
`type`	string \| null	Tipo de actividad (ej. `"TASK"`)
`status`	string \| null	Estado actual de la actividad — ver Activity States para el catálogo completo
`score`	number \| null	Puntuación de prioridad de la actividad (asignada al crearla)
`channel`	string \| null	Canal de la actividad (`SALESMAN`, `CALLCENTER`, etc.)
`scheduledAt`	string \| null	Fecha programada (ISO 8601)
`occurredAt`	string \| null	Fecha en que ocurrió la gestión (ISO 8601)
`createdAt`	string \| null	Fecha de creación (ISO 8601)
`lifecycleStatus`	string \| null	Estado del ciclo de vida para visualización (read-only, computed) — ver Activity States
`lifecycleStatusLabel`	string \| null	Etiqueta legible del estado del ciclo de vida
`lifecycleStatusDetail`	string \| null	Detalle adicional del estado
`canForceRetryDispatch`	boolean	Indica si se puede forzar un re-dispatch
`commerceExternalId`	string	ID externo del comercio asociado
`commerceName`	string	Nombre del comercio
`reason`	object \| null	Razón de la actividad (`code`, `label`)
`userStatus`	object \| null	Estado personalizado del usuario (`code`, `label`)
`commerceAssignment`	object \| null	Información de asignación del comercio
`activityDetails`	object \| null	Detalles específicos del tipo de actividad
`activityResult`	object \| null	Resultado de la gestión (si existe)

Campos de `activityDetails` (tipo TASK)

Campo	Tipo	Descripción
`type`	`"TASK"`	Discriminador de tipo
`assignedRouteCode`	string \| null	Código de la ruta asignada
`assignedOperatorExternalId`	string \| null	ID externo del operador asignado
`assignedRoute`	object \| null	Ruta asignada (`code`, `name`)
`assignedOperator`	object \| null	Operador asignado (`externalId`, `name`, `type`)

Campos de `activityResult`

Campo	Tipo	Descripción
`id`	string	Identificador del resultado
`resultStatus`	string	Estado del resultado — ver Activity States §resultStatus
`source`	string	Origen del resultado
`origin`	string	Canal de origen
`channel`	string \| null	Canal del resultado
`occurredAt`	string	Fecha en que ocurrió (ISO 8601)
`createdAt`	string	Fecha de creación (ISO 8601)
`resultDetails`	object \| null	Detalles del resultado de tipo tarea

Campos de `resultDetails` (tipo TASK)

Campo	Tipo	Descripción
`type`	`"TASK"`	Discriminador de tipo
`result`	object	Tipo de resultado enviado (`code`, `label`)
`comment`	string \| null	Comentario enviado junto con el resultado
`requiresFutureScheduledAt`	boolean	Indica si el tipo de resultado enviado exige una fecha `future_scheduled_at`
`externalOperatorId`	string \| null	ID externo del operador que envió el resultado
`operator`	object \| null	Operador que envió el resultado (`externalId`, `name`)

Errores

Status	Descripción
`401`	Clave de API faltante o inválida
`403`	La clave no tiene el permiso `activity:view`
`400` / `403` / `404`	El `x-project-id` enviado no es válido — ver Errores de proyecto