Enviar Resultado

POST /api/integration/activity-results/tasks

Envia o resultado de uma atividade do tipo tarefa. O resultado é associado à atividade correspondente e atualiza seu status na Reten.

A operação é um UPSERT idempotente: se a atividade ainda não tiver resultado, ele é criado; se já tiver, seus detalhes são sobrescritos com o último envio (last-write-wins). Você pode reenviar o resultado sem obter um conflito.

Autenticação: Exigida — permissão activity-result:submit

Headers exigidos

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 requisição a esse projeto, então o activity_id deve pertencer a ele. Sem o header, o resultado assume o projeto da sua atividade. Um header enviado é validado — veja Erros de projeto.
• Um resultado sem activity_id não tem atividade da qual assumir o projeto: com uma chave de projeto, assume o projeto da chave; com uma chave de tenant ou um token de usuário, precisa do header, e sem ele a API responde 400.
• Uma chave de projeto sempre trabalha no seu próprio projeto: um activity_id de outro projeto responde 404.

Corpo da requisição

Campos de task_result

Exemplo

curl -X POST BASE_URL/api/integration/activity-results/tasks \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "activity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "commerce_external_id": "COM-001",
    "occurred_at": "2026-04-11T10:30:00.000Z",
    "task_result": {
      "result": "SALE_COMPLETED",
      "comment": "Customer accepted renewal offer",
      "operator_external_id": "OP-042"
    }
  }'

const response = await fetch(
  `${BASE_URL}/api/integration/activity-results/tasks`,
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      activity_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      commerce_external_id: "COM-001",
      occurred_at: "2026-04-11T10:30:00.000Z",
      task_result: {
        result: "SALE_COMPLETED",
        comment: "Customer accepted renewal offer",
        operator_external_id: "OP-042",
      },
    }),
  }
);

const data = await response.json();

import requests

response = requests.post(
    f"{BASE_URL}/api/integration/activity-results/tasks",
    headers={
        "x-api-key": "YOUR_API_KEY",
    },
    json={
        "activity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "commerce_external_id": "COM-001",
        "occurred_at": "2026-04-11T10:30:00.000Z",
        "task_result": {
            "result": "SALE_COMPLETED",
            "comment": "Customer accepted renewal offer",
            "operator_external_id": "OP-042",
        },
    },
)

data = response.json()

Resposta 201 Created

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "source": "RETEN_ACTIVITY",
  "origin": "EXTERNAL",
  "activityId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "providerActivityId": null,
  "commerceExternalId": "COM-001",
  "resultStatus": "COMPLETED",
  "occurredAt": "2026-04-11T10:30:00.000Z",
  "createdAt": "2026-04-11T10:30:05.000Z",
  "updatedAt": "2026-04-11T10:30:05.000Z",
  "result": {
    "code": "SALE_COMPLETED",
    "label": "Venta completada"
  },
  "comment": "Customer accepted renewal offer",
  "operatorExternalId": "OP-042",
  "futureScheduledAt": null
}

Regras de validação

• commerce_external_id só é exigido para execuções independentes (sem activity_id); nesse caso, se o comércio não existir, ele é criado como placeholder. Com uma atividade vinculada, o comércio é derivado dela e esse campo é opcional.
• operator_external_id é opcional; se enviado e o operador não existir, ele é criado como placeholder.
• O código de result deve ser um tipo de resultado ativo (consulte Listar Configurações); caso contrário, a requisição retorna 422 — El tipo de resultado seleccionado no está activo.
• Se o tipo de resultado tiver requiresFutureScheduledAt: true, o campo future_scheduled_at é obrigatório (se faltar, 422 — Este tipo de resultado requiere una fecha comprometida.) e deve cair hoje ou depois no fuso horário do tenant (senão, 422 — La fecha programada no puede ser en el pasado.)
• Se a atividade já tiver um resultado, o envio o sobrescreve (UPSERT idempotente); nenhum conflito é retornado
• A atividade vinculada deve estar em um estado que aceite resultado (READY, DISPATCHED, RETRYING ou COMPLETED — em COMPLETED, o envio sobrescreve o resultado existente); caso contrário, a requisição retorna 422 — La actividad no está en un estado válido para registrar resultado.
• Não é permitido registrar um resultado para uma atividade cuja data de execução já ultrapassou o corte de fim de dia; nesse caso, a requisição retorna 422 — La actividad corresponde a un día ya cerrado y no admite registrar resultado. Execuções independentes (STANDALONE, sem activity_id) estão isentas dessa regra

Erros