Consultar por Comercio

Obtén el estado (o estados) de ciclo de vida de un único comercio, por UUID o por código externo.

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

Devuelve los estados de ciclo de vida de un único comercio, enriquecidos con los datos del comercio y de la AGC. El path acepta un identificador dual: un UUID de Reten o el código externo del comercio, indistintamente.

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

Responde un array, no un objeto. Sin filtro de AGC, un mismo comercio puede tener varios estados (uno por AGC), por eso siempre se devuelve una lista. Con activity_generation_config_id, el array tendrá 1 elemento.

Parámetro de Ruta

Parámetro	Tipo	Descripción
`:commerceIdentifier`	UUID \| string	UUID del comercio en Reten (ej. `c0000000-...`) o su código externo (ej. `SV-001`).

Parámetros de Consulta

Parámetro	Tipo	Por defecto	Descripción
`activity_generation_config_id`	UUID	-	Si se provee, devuelve solo el estado bajo esa AGC. Si se omite, devuelve los estados de todas las AGC del comercio.

Ejemplo

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

# Por UUID, acotado a una 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()

Respuesta `200 OK`

Cada elemento es el recurso snapshot más dos objetos anidados: commerce y 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": "Recuperación activa",
    "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": "Resurrección Q1",
      "description": "Campaña de recuperación primer trimestre"
    }
  }
]

Campos anidados

Campo	Tipo	Descripción
`commerce`	object \| null	`id`, `name` y `external_id` del comercio.
`activity_generation_config`	object \| null	`id`, `name` y `description` de la AGC.

Errores

Status	Descripción
`404`	El comercio no existe, o existe pero no tiene ningún estado calculado (con el filtro de AGC aplicado, si se envió).
`401`	Clave de API faltante o inválida.
`403`	La credencial no tiene el permiso `commerce-lifecycle-snapshot:view`.

A diferencia del lookup por lote, aquí un comercio sin estado calculado responde 404 (no un cuerpo vacío). Si necesitas distinguir "sin resolver" sin tratar la ausencia como error, usa el lookup por lote.