Listar Estados

Lista paginada de los estados de ciclo de vida del tenant, con filtros por código, etapa, AGC y frescura.

GET /api/commerce-lifecycle-snapshots

Devuelve una lista paginada de los estados de ciclo de vida del tenant, con filtros opcionales. Sin filtro de AGC, recorre los estados de todas las AGC del tenant.

Auth: Requerida — permiso commerce-lifecycle-snapshot:view

Encabezados

Encabezado	Requerido	Valor
`x-api-key`	Sí (partner)	`YOUR_API_KEY`

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

Parámetros de Consulta

Parámetro	Tipo	Por defecto	Descripción
`page`	number	`1`	Número de página (mínimo 1).
`per_page`	number	`25`	Elementos por página (mínimo 1, máximo 100).
`code`	string	-	Filtra por código de estado de retención (coincidencia exacta, ej. `AT_RISK_MONTHLY`).
`stage`	enum	-	Filtra por etapa: `ACTIVATION`, `ENGAGEMENT` o `RESURRECTION`.
`activity_generation_config_id`	UUID	-	Filtra por AGC. Si se omite, lista los estados de todas las AGC.
`state_changed_since`	ISO 8601	-	Devuelve solo estados cuyo `state_changed_at` es posterior a esta fecha. Útil para sincronización incremental.
`sort`	string	`-state_changed_at`	Orden por `state_changed_at`. Convención de prefijo `-`: `state_changed_at` → ascendente; `-state_changed_at` → descendente (más reciente primero).

Por defecto (sin sort) el orden es descendente por state_changed_at — los estados que cambiaron más recientemente aparecen primero. El único campo ordenable es state_changed_at; cualquier otro valor de sort devuelve 400.

Ejemplo

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()

Respuesta `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": "En riesgo (mensual)",
      "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": "Saludable",
      "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 paginación

Campo	Tipo	Descripción
`page`	number	Página actual.
`per_page`	number	Elementos por página.
`total`	number	Conteo total exacto de estados que coinciden con los filtros.
`total_pages`	number	`ceil(total / per_page)`.
`has_next`	boolean	`true` si hay una página siguiente.
`has_previous`	boolean	`true` si hay una página anterior.

La forma de cada elemento de data es el recurso snapshot.

Errores

Status	Descripción
`400`	Parámetro inválido (ej. `sort` fuera de la whitelist, `stage` no válido, `per_page` mayor a 100).
`401`	Clave de API faltante o inválida.
`403`	La credencial no tiene el permiso `commerce-lifecycle-snapshot:view`.