Lookup por Lote

Resuelve hasta 100 identificadores de comercio a sus estados de ciclo de vida en una sola llamada, con resultados parciales.

POST /api/commerce-lifecycle-snapshots/batch-lookup

Resuelve un conjunto cerrado de identificadores (hasta 100) a sus estados de ciclo de vida en una sola operación. A diferencia del list, no es paginado: tú provees el conjunto exacto a consultar.

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

Resultados parciales. La request nunca falla en bloque por identificadores que no existen o que aún no tienen estado calculado: los resueltos llegan en data y el resto se reporta explícitamente en unresolved.

Cuerpo de la Petición

Campo	Tipo	Requerido	Descripción
`commerce_ids`	UUID[]	Uno de los dos	Lista de UUIDs de comercios (máx. 100).
`external_ids`	string[]	Uno de los dos	Lista de códigos externos (máx. 100).
`activity_generation_config_id`	UUID	No	Si se provee, solo devuelve estados de esa AGC. Si se omite, devuelve estados de todas las AGC de los comercios pedidos.

Debes enviar exactamente uno de commerce_ids o external_ids — no ambos, no ninguno. Enviar los dos (o ninguno) responde 400. No se pueden mezclar tipos de identificador en una misma request.

Ejemplo

curl -X POST "https://api.reten.ai/api/commerce-lifecycle-snapshots/batch-lookup" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ids": ["SV-001", "SV-002", "SV-099"],
    "activity_generation_config_id": "a1b2c3d4-0000-4000-8000-000000000001"
  }'

const response = await fetch(
  "https://api.reten.ai/api/commerce-lifecycle-snapshots/batch-lookup",
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      external_ids: ["SV-001", "SV-002", "SV-099"],
      activity_generation_config_id: "a1b2c3d4-0000-4000-8000-000000000001",
    }),
  },
);
const result = await response.json();

import requests

response = requests.post(
    "https://api.reten.ai/api/commerce-lifecycle-snapshots/batch-lookup",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "external_ids": ["SV-001", "SV-002", "SV-099"],
        "activity_generation_config_id": "a1b2c3d4-0000-4000-8000-000000000001",
    },
)
result = 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"
    }
  ],
  "unresolved": ["SV-099"]
}

Campo	Tipo	Descripción
`data`	snapshot[]	Estados resueltos, en la forma del recurso snapshot (recurso crudo, sin relaciones anidadas).
`unresolved`	string[]	Identificadores del request que no se pudieron resolver. Incluye tanto comercios inexistentes como comercios sin estado calculado — la API no los distingue.

Errores

Status	Descripción
`400`	Se enviaron ambos identificadores o ninguno; más de 100 elementos; o un UUID inválido en `commerce_ids`.
`401`	Clave de API faltante o inválida.
`403`	La credencial no tiene el permiso `commerce-lifecycle-snapshot:view`.