Listar Atividades

GET /api/integration/activities/tasks

Retorna uma lista paginada de atividades do tipo tarefa visíveis para a chave de API da sua integração, de um projeto ou de todo o tenant (veja Header exigido).

Autenticação: Exigida — permissão activity:view

Header exigido

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

x-project-id é opcional: este é um endpoint project-optional. Com uma chave de tenant ou um token de usuário, enviar o header restringe a lista a esse projeto; sem ele, a lista abrange todos os projetos do tenant, e cada atividade traz o seu projectId. Uma chave de projeto sempre lista as atividades do seu próprio projeto. Um header enviado é validado — veja Erros de projeto.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`page`	number	Não	Número da página (padrão: `1`)
`per_page`	number	Não	Resultados por página (padrão: `25`, máximo: `100`)
`status`	string	Não	Filtrar por status da atividade (ver Activity States). Valores filtráveis: `READY`, `RETRYING`, `DISPATCHED`, `COMPLETED`, `CANCELED`, `FAILED`
`result_status`	string	Não	Filtrar por status do resultado (ver Activity States). Valores filtráveis: `COMPLETED`, `NOT_EXECUTED`
`channel`	string	Não	Filtrar por canal (`SALESMAN`, `CALLCENTER`, etc.)
`external_commerce_id`	string	Não	Filtrar por ID externo do comércio
`external_operator_id`	string	Não	Filtrar por ID externo do operador
`scheduled_from`	string	Não	Data mínima de agendamento (ISO 8601)
`scheduled_to`	string	Não	Data máxima de agendamento (ISO 8601)

Exemplo

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()

Resposta `200 OK`

O exemplo a seguir é ilustrativo do formato da resposta. Os valores de campos como id, scheduledAt, status, lifecycleStatus, etc., variam de acordo com o estado real de cada atividade. Para o catálogo completo dos possíveis valores de status e lifecycleStatus, veja 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
  }
}

Exemplo de execução independente (STANDALONE)

Os itens com activityOrigin: "STANDALONE" vêm de um resultado registrado como execução independente, sem uma atividade anterior: scheduledAt repete o occurredAt do resultado, e activityResult vem sempre preenchido. Um activityResult preenchido também aparece nos itens ACTIVITY depois de tratados.

Abaixo é mostrado apenas o item — o envelope pagination ao redor é idêntico ao do exemplo 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 da atividade

Campo	Tipo	Descrição
`id`	string	Identificador único da atividade
`activityOrigin`	`"ACTIVITY"` \| `"STANDALONE"`	Origem da atividade
`projectId`	string	Projeto ao qual a atividade pertence
`type`	string \| null	Tipo de atividade (ex.: `"TASK"`)
`status`	string \| null	Status atual da atividade — veja Activity States para o catálogo completo
`score`	number \| null	Pontuação de prioridade da atividade (definida na criação)
`channel`	string \| null	Canal da atividade (`SALESMAN`, `CALLCENTER`, etc.)
`scheduledAt`	string \| null	Data agendada (ISO 8601)
`occurredAt`	string \| null	Data em que a atividade foi tratada (ISO 8601)
`createdAt`	string \| null	Data de criação (ISO 8601)
`lifecycleStatus`	string \| null	Status do ciclo de vida para exibição (somente leitura, calculado) — veja Activity States
`lifecycleStatusLabel`	string \| null	Rótulo legível do status do ciclo de vida
`lifecycleStatusDetail`	string \| null	Detalhe adicional do status
`canForceRetryDispatch`	boolean	Indica se é possível forçar um novo despacho
`commerceExternalId`	string	ID externo do comércio associado
`commerceName`	string	Nome do comércio
`reason`	object \| null	Motivo da atividade (`code`, `label`)
`userStatus`	object \| null	Status personalizado do usuário (`code`, `label`)
`commerceAssignment`	object \| null	Informação de atribuição do comércio
`activityDetails`	object \| null	Detalhes específicos do tipo de atividade
`activityResult`	object \| null	Resultado da atividade (se existir)

Campos de `activityDetails` (tipo TASK)

Campo	Tipo	Descrição
`type`	`"TASK"`	Discriminador de tipo
`assignedRouteCode`	string \| null	Código da rota atribuída
`assignedOperatorExternalId`	string \| null	ID externo do operador atribuído
`assignedRoute`	object \| null	Rota atribuída (`code`, `name`)
`assignedOperator`	object \| null	Operador atribuído (`externalId`, `name`, `type`)

Campos de `activityResult`

Campo	Tipo	Descrição
`id`	string	Identificador do resultado
`resultStatus`	string	Status do resultado — veja Activity States §resultStatus
`source`	string	Origem do resultado
`origin`	string	Canal de origem
`channel`	string \| null	Canal do resultado
`occurredAt`	string	Data em que ocorreu (ISO 8601)
`createdAt`	string	Data de criação (ISO 8601)
`resultDetails`	object \| null	Detalhes do resultado de tarefa

Campos de `resultDetails` (tipo TASK)

Campo	Tipo	Descrição
`type`	`"TASK"`	Discriminador de tipo
`result`	object	Tipo de resultado enviado (`code`, `label`)
`comment`	string \| null	Comentário enviado junto com o resultado
`requiresFutureScheduledAt`	boolean	Indica se o tipo de resultado enviado exige uma data `future_scheduled_at`
`externalOperatorId`	string \| null	ID externo do operador que enviou o resultado
`operator`	object \| null	Operador que enviou o resultado (`externalId`, `name`)

Erros

Status	Descrição
`401`	Chave de API ausente ou inválida
`403`	A chave não tem a permissão `activity:view`
`400` / `403` / `404`	O `x-project-id` enviado não é válido — veja Erros de projeto