Consultar por Comércio

Obtenha o estado (ou estados) de ciclo de vida de um único comércio, por UUID ou por código externo.

GET /api/commerce-lifecycle-snapshots/:commerceIdentifier

Retorna os estados de ciclo de vida de um único comércio, enriquecidos com os dados do comércio e da AGC. O path aceita um identificador dual: um UUID da Reten ou o código externo do comércio, indistintamente.

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

Responde com um array, não um objeto. Sem filtro de AGC, o mesmo comércio pode ter vários estados (um por AGC), por isso sempre é retornada uma lista. Com activity_generation_config_id, o array terá 1 elemento.

Parâmetro de Rota

Parâmetro	Tipo	Descrição
`:commerceIdentifier`	UUID \| string	UUID do comércio na Reten (ex. `c0000000-...`) ou seu código externo (ex. `SV-001`).

Parâmetros de Consulta

Parâmetro	Tipo	Padrão	Descrição
`activity_generation_config_id`	UUID	-	Se fornecido, retorna apenas o estado sob essa AGC. Se omitido, retorna os estados de todas as AGCs do comércio.

Exemplo

# Por código externo
curl "https://api.reten.ai/api/commerce-lifecycle-snapshots/SV-001" \
  -H "x-api-key: YOUR_API_KEY"

# Por UUID, restrito a uma AGC
curl "https://api.reten.ai/api/commerce-lifecycle-snapshots/c0000000-0000-4000-8000-000000000001?activity_generation_config_id=a1b2c3d4-0000-4000-8000-000000000001" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch(
  "https://api.reten.ai/api/commerce-lifecycle-snapshots/SV-001",
  { headers: { "x-api-key": "YOUR_API_KEY" } },
);
const snapshots = await response.json();

import requests

response = requests.get(
    "https://api.reten.ai/api/commerce-lifecycle-snapshots/SV-001",
    headers={"x-api-key": "YOUR_API_KEY"},
)
snapshots = response.json()

Resposta `200 OK`

Cada elemento é o recurso snapshot mais dois objetos aninhados: commerce e activity_generation_config.

[
  {
    "id": "5d000000-0000-4000-8000-000000000003",
    "commerce_id": "c0000000-0000-4000-8000-000000000003",
    "external_id": "SV-003",
    "activity_generation_config_id": "a1b2c3d4-0000-4000-8000-000000000002",
    "code": "WIN_BACK",
    "label": "Active win-back",
    "stage": "RESURRECTION",
    "last_computed_at": "2026-06-10T06:00:00.000Z",
    "state_changed_at": "2026-06-09T06:00:00.000Z",
    "commerce": {
      "id": "c0000000-0000-4000-8000-000000000003",
      "name": "Minimarket El Sol",
      "external_id": "SV-003"
    },
    "activity_generation_config": {
      "id": "a1b2c3d4-0000-4000-8000-000000000002",
      "name": "Q1 Resurrection",
      "description": "First-quarter win-back campaign"
    }
  }
]

Campos aninhados

Campo	Tipo	Descrição
`commerce`	object \| null	`id`, `name` e `external_id` do comércio.
`activity_generation_config`	object \| null	`id`, `name` e `description` da AGC.

Erros

Status	Descrição
`404`	O comércio não existe, ou existe mas não tem nenhum estado calculado (com o filtro de AGC aplicado, se um foi enviado).
`401`	Chave de API ausente ou inválida.
`403`	A credencial não tem a permissão `commerce-lifecycle-snapshot:view`.

Diferente do lookup por lote, aqui um comércio sem estado calculado responde 404 (não um corpo vazio). Se você precisar distinguir "sem resolver" sem tratar a ausência como erro, use o lookup por lote.