Lookup por Lote

Resolva até 100 identificadores de comércio para seus estados de ciclo de vida em uma única chamada, com resultados parciais.

POST /api/commerce-lifecycle-snapshots/batch-lookup

Resolve um conjunto fechado de identificadores (até 100) para seus estados de ciclo de vida em uma única operação. Diferente do list, não é paginado: você fornece o conjunto exato a consultar.

Auth: Obrigatório — permissão commerce-lifecycle-snapshot:view

Resultados parciais. A request nunca falha por completo por causa de identificadores que não existem ou que ainda não têm estado calculado: os resolvidos chegam em data e o restante é reportado explicitamente em unresolved.

Corpo da Requisição

Campo	Tipo	Obrigatório	Descrição
`commerce_ids`	UUID[]	Um dos dois	Lista de UUIDs de comércios (máx. 100).
`external_ids`	string[]	Um dos dois	Lista de códigos externos (máx. 100).
`activity_generation_config_id`	UUID	Não	Se fornecido, retorna apenas estados dessa AGC. Se omitido, retorna estados de todas as AGCs dos comércios solicitados.

Você deve enviar exatamente um de commerce_ids ou external_ids — não ambos, não nenhum. Enviar os dois (ou nenhum) responde 400. Os tipos de identificador não podem ser misturados em uma mesma request.

Exemplo

curl -X POST "https://api.reten.ai/api/commerce-lifecycle-snapshots/batch-lookup" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ids": ["SV-001", "SV-002", "SV-099"],
    "activity_generation_config_id": "a1b2c3d4-0000-4000-8000-000000000001"
  }'

const response = await fetch(
  "https://api.reten.ai/api/commerce-lifecycle-snapshots/batch-lookup",
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      external_ids: ["SV-001", "SV-002", "SV-099"],
      activity_generation_config_id: "a1b2c3d4-0000-4000-8000-000000000001",
    }),
  },
);
const result = await response.json();

import requests

response = requests.post(
    "https://api.reten.ai/api/commerce-lifecycle-snapshots/batch-lookup",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "external_ids": ["SV-001", "SV-002", "SV-099"],
        "activity_generation_config_id": "a1b2c3d4-0000-4000-8000-000000000001",
    },
)
result = response.json()

Resposta `200 OK`

{
  "data": [
    {
      "id": "5d000000-0000-4000-8000-000000000001",
      "commerce_id": "c0000000-0000-4000-8000-000000000001",
      "external_id": "SV-001",
      "activity_generation_config_id": "a1b2c3d4-0000-4000-8000-000000000001",
      "code": "AT_RISK_MONTHLY",
      "label": "At risk (monthly)",
      "stage": "ENGAGEMENT",
      "last_computed_at": "2026-06-10T06:00:00.000Z",
      "state_changed_at": "2026-06-08T06:00:00.000Z"
    },
    {
      "id": "5d000000-0000-4000-8000-000000000002",
      "commerce_id": "c0000000-0000-4000-8000-000000000002",
      "external_id": "SV-002",
      "activity_generation_config_id": "a1b2c3d4-0000-4000-8000-000000000001",
      "code": "HEALTHY",
      "label": "Healthy",
      "stage": "ENGAGEMENT",
      "last_computed_at": "2026-06-10T06:00:00.000Z",
      "state_changed_at": "2026-06-03T06:00:00.000Z"
    }
  ],
  "unresolved": ["SV-099"]
}

Campo	Tipo	Descrição
`data`	snapshot[]	Estados resolvidos, no formato do recurso snapshot (recurso bruto, sem relações aninhadas).
`unresolved`	string[]	Identificadores da request que não puderam ser resolvidos. Inclui tanto comércios inexistentes quanto comércios sem estado calculado — a API não os distingue.

Erros

Status	Descrição
`400`	Foram enviados ambos os identificadores ou nenhum; mais de 100 elementos; ou um UUID inválido em `commerce_ids`.
`401`	Chave de API ausente ou inválida.
`403`	A credencial não tem a permissão `commerce-lifecycle-snapshot:view`.