Entrar
.md

Feed de datos

Guper expone dos feeds append-only que publican una notificación cada vez que un cliente o un pedido cambia. Tu sistema downstream los consulta a su propia cadencia y confirma lo que consumió — entrega at-least-once, sin webhooks que administrar, sin endpoint público que exponer.

Dos feeds:

  • Customer feed — aparecen entradas cuando un cliente es creado, actualizado, etiquetado o tiene cambios en sus datos de perfil.
  • Order feed — aparecen entradas cuando un pedido es creado, modificado, cancelado o tiene acumulaciones/promociones aplicadas.

El flujo en 3 pasos

┌────────────┐   ┌────────────┐   ┌────────────┐
│ 1. Consul- │ → │ 2. Obtener │ → │ 3. Confir- │
│ tar feed   │   │ el detalle │   │ mar token  │
└────────────┘   └────────────┘   └────────────┘

Paso 1 — Consultar el feed

Haz GET al endpoint del feed para recibir una lista de pares { id, token }. Cada token identifica de forma única esa entrada pendiente; cuando la confirmas (paso 3), desaparece del feed.

GET /api/register/customer/feed
GET /api/order/feed

Paso 2 — Obtener el registro completo

Para cada entrada, haz GET al recurso correspondiente por ID:

GET /api/register/customer/{personId}
GET /api/order/{orderId}

Paso 3 — Confirmar

Haz PUT devolviendo el token al feed para confirmar que ya consumiste la entrada. Mientras no lo hagas, seguirá apareciendo en consultas posteriores.

PUT /api/register/customer/feed
{ "token": "<token del paso 1>" }

¿Por qué polling en lugar de webhooks?

  • No expones un endpoint público de tu lado — más fácil para InfoSec.
  • Entrega at-least-once — un worker que se cayó vuelve a hacer poll y retoma donde se quedó; nunca descartamos un evento de manera silenciosa.
  • Backpressure incorporado — tú decides la cadencia; el feed espera.
  • El replay no es una API aparte — controlas el progreso con los acks.

Cadencia recomendada

Para la mayoría de las integraciones operativas, hacer polling cada 10–30 segundos es más que suficiente. Para mirrors de analytics/BI que no necesitan datos en tiempo real, 5 minutos está bien. No hay un intervalo mínimo impuesto.

Autenticación

Ambos endpoints del feed requieren un token x-guper-authorization válido — ver Autenticación.

Ver también