Estados de Ciclo de Vida de Comércios

Estados de ciclo de vida (lifecycle states) são a foto atual do estado de retenção de cada comércio, calculada pelo motor da Reten. Cada estado responde à pergunta: "em que ponto do ciclo de retenção está este comércio, sob qual configuração, e desde quando?".

Esta seção documenta o contrato de leitura e escrita desses estados.

Capabilities

A API expõe cinco capabilities sobre o recurso commerce-lifecycle-snapshots:

Autenticação

Todos os endpoints de estados de ciclo de vida aceitam dois métodos de autenticação:

Permissões necessárias:

O recurso: snapshot de estado

Um estado de ciclo de vida (snapshot) é representado com esta forma canônica. As superfícies que retornam o recurso "bruto" (list, lookup por lote, upsert) usam exatamente estes campos:

{
  "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-05-22T06:00:00.000Z"
}

Modelo de identificadores (dual)

Um comércio pode ser referenciado de duas formas equivalentes em toda a API de estados:

• UUID da Reten (commerce_id) — o identificador interno, ex. c0000000-0000-4000-8000-000000000001.
• Código externo (external_id) — o código do comércio no seu próprio sistema, ex. "SV-001".

Cada endpoint declara qual(is) aceita:

Estágios do ciclo de vida (stage)

O campo stage assume um de três valores possíveis:

• ACTIVATION
• ENGAGEMENT
• RESURRECTION

O par (stage, code) define o estado visível de um comércio.

Frescor: last_computed_at vs state_changed_at

São dois timestamps com semânticas distintas; entender a diferença é fundamental para consumir esses dados corretamente.

Regras de state_changed_at:

• Ao criar, é inicializado igual a last_computed_at.
• Ao atualizar, só muda se o par (stage, code) for diferente do que já existia. Se apenas o label ou o last_computed_at mudar mas (stage, code) permanecer o mesmo, state_changed_at não se move.

Exemplo da evolução de um mesmo comércio:

Comportamento com dados sem resolver ou stale

Sem resolver (unresolved)

Um identificador está sem resolver quando não existe um snapshot para ele. A API agrupa dois casos igualmente (de forma intencional — o resultado é inobtenível de qualquer forma):

• O comércio não existe no tenant.
• O comércio existe mas ainda não tem estado calculado.

Como se manifesta em cada endpoint:

Stale (dados antigos)

A API não marca frescor nem apaga estados antigos: um snapshot vive até que o motor o sobrescreva. O "frescor" é decidido pelo consumidor, comparando last_computed_at com o momento atual e aplicando seu próprio limite (ex. "considero stale tudo o que foi calculado há mais de 24h").

Para encontrar estados recentes sem percorrer tudo, o list aceita o filtro state_changed_since, que retorna apenas os estados cujo state_changed_at é posterior a uma data dada.

Identificador de AGC e fluxo de setup

O estado de ciclo de vida é por par (comércio, AGC), não único por comércio. Uma "Activity Generation Config" (AGC) é a configuração sob a qual o motor calcula os estados; um mesmo comércio pode ter um estado diferente sob cada AGC.

Por isso o parâmetro activity_generation_config_id aparece em todos os endpoints — de leitura e de escrita:

• É opcional em leitura. Se você omiti-lo, obtém os estados de todas as AGCs do comércio/tenant.
• Importa se você quiser evitar "misturar" dados. Filtrar por uma AGC específica garante que você leia apenas os estados calculados sob essa configuração, sem misturar resultados de outras AGCs.
• É obrigatório em escrita (upsert individual e por lote), porque um estado sempre é escrito sob uma AGC específica.

Como obter os IDs de AGC disponíveis

Se você quiser filtrar por AGC, primeiro descubra as AGCs de um projeto com:

GET /api/activity-generation-configs

Auth: requer a permissão activity-generation-config:view. O endpoint é project-scoped: retorna apenas as AGCs do projeto ativo. Uma chave de projeto vê as AGCs do seu próprio projeto; uma chave de tenant ou um token JWT envia x-project-id com o projeto a ler (sem ele a API responde 400 — Falta el header obligatorio x-project-id.) e repete a chamada para cada projeto de GET /api/projects para cobrir todo o tenant — veja Escopo da chave. Responde um array; pegue o id da AGC que te interessa e use-o como activity_generation_config_id:

[
  {
    "id": "a1b2c3d4-0000-4000-8000-000000000001",
    "name": "B2B Retention",
    "description": "Retention cycle for wholesale customers"
  },
  {
    "id": "a1b2c3d4-0000-4000-8000-000000000002",
    "name": "Q1 Resurrection",
    "description": "First-quarter win-back campaign"
  }
]