Listar Estados

Lista paginada dos estados de ciclo de vida do tenant, com filtros por código, estágio, AGC e frescor.

GET /api/commerce-lifecycle-snapshots

Retorna uma lista paginada dos estados de ciclo de vida do tenant, com filtros opcionais. Sem filtro de AGC, percorre os estados de todas as AGCs do tenant.

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

Headers

Header	Obrigatório	Valor
`x-api-key`	Sim (partner)	`YOUR_API_KEY`

Alternativamente, com JWT: Authorization: Bearer <token> + x-tenant-id: <tenant-id>.

Parâmetros de Consulta

Parâmetro	Tipo	Padrão	Descrição
`page`	number	`1`	Número da página (mínimo 1).
`per_page`	number	`25`	Itens por página (mínimo 1, máximo 100).
`code`	string	-	Filtra por código de estado de retenção (correspondência exata, ex. `AT_RISK_MONTHLY`).
`stage`	enum	-	Filtra por estágio: `ACTIVATION`, `ENGAGEMENT` ou `RESURRECTION`.
`activity_generation_config_id`	UUID	-	Filtra por AGC. Se omitido, lista os estados de todas as AGCs.
`state_changed_since`	ISO 8601	-	Retorna apenas estados cujo `state_changed_at` é posterior a esta data. Útil para sincronização incremental.
`sort`	string	`-state_changed_at`	Ordena por `state_changed_at`. Convenção de prefixo `-`: `state_changed_at` → ascendente; `-state_changed_at` → descendente (mais recente primeiro).

Por padrão (sem sort) a ordem é descendente por state_changed_at — os estados que mudaram mais recentemente aparecem primeiro. O único campo ordenável é state_changed_at; qualquer outro valor de sort retorna 400.

Exemplo

curl "https://api.reten.ai/api/commerce-lifecycle-snapshots?stage=ENGAGEMENT&per_page=25&state_changed_since=2026-06-01T00:00:00Z" \
  -H "x-api-key: YOUR_API_KEY"

const params = new URLSearchParams({
  stage: "ENGAGEMENT",
  per_page: "25",
  state_changed_since: "2026-06-01T00:00:00Z",
});
const response = await fetch(
  `https://api.reten.ai/api/commerce-lifecycle-snapshots?${params}`,
  { headers: { "x-api-key": "YOUR_API_KEY" } },
);
const data = await response.json();

import requests

response = requests.get(
    "https://api.reten.ai/api/commerce-lifecycle-snapshots",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={
        "stage": "ENGAGEMENT",
        "per_page": 25,
        "state_changed_since": "2026-06-01T00:00:00Z",
    },
)
data = 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"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 2,
    "total_pages": 1,
    "has_next": false,
    "has_previous": false
  }
}

Campos de paginação

Campo	Tipo	Descrição
`page`	number	Página atual.
`per_page`	number	Itens por página.
`total`	number	Contagem total exata de estados que correspondem aos filtros.
`total_pages`	number	`ceil(total / per_page)`.
`has_next`	boolean	`true` se houver uma próxima página.
`has_previous`	boolean	`true` se houver uma página anterior.

O formato de cada elemento de data é o recurso snapshot.

Erros

Status	Descrição
`400`	Parâmetro inválido (ex. `sort` fora da whitelist, `stage` inválido, `per_page` acima de 100).
`401`	Chave de API ausente ou inválida.
`403`	A credencial não tem a permissão `commerce-lifecycle-snapshot:view`.