Entrar
.md

Feed de dados

A Guper expõe dois feeds append-only que publicam uma notificação toda vez que um cliente ou pedido muda. Seu sistema downstream consulta na cadência dele e confirma o que consumiu — entrega at-least-once, sem webhooks pra gerenciar, sem endpoint público pra expor.

Dois feeds:

  • Customer feed — entradas surgem quando um cliente é criado, atualizado, marcado ou tem dados de perfil alterados.
  • Order feed — entradas surgem quando um pedido é criado, modificado, cancelado ou tem acúmulos/promoções aplicadas.

Fluxo em 3 passos

┌────────────┐   ┌────────────┐   ┌────────────┐
│ 1. Consul- │ → │ 2. Buscar  │ → │ 3. Confir- │
│ tar feed   │   │ o detalhe  │   │ mar token  │
└────────────┘   └────────────┘   └────────────┘

Passo 1 — Consultar o feed

GET no endpoint do feed pra receber uma lista de { id, token }. Cada token identifica uma entrada pendente; quando você confirma (passo 3) ela some do feed.

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

Passo 2 — Buscar o registro completo

Para cada entrada, faça GET no recurso pelo ID:

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

Passo 3 — Confirmar

PUT no feed devolvendo o token pra confirmar que consumiu. Enquanto não confirmar, ele continua aparecendo nas próximas consultas.

PUT /api/register/customer/feed
{ "token": "<token do passo 1>" }

Por que polling em vez de webhooks?

  • Você não expõe endpoint público — InfoSec agradece.
  • Entrega at-least-once — worker que crashou volta e continua de onde parou; a gente nunca dropa silenciosamente.
  • Backpressure embutido — você decide a cadência; o feed espera.
  • Replay não é uma API separada — você controla o progresso pelos acks.

Cadência recomendada

Pra integração operacional, polling a cada 10–30 segundos é mais que suficiente. Pra mirror de analytics/BI sem necessidade de tempo real, 5 minutos está bom. Não tem intervalo mínimo imposto.

Autenticação

Ambos endpoints do feed exigem um token x-guper-authorization válido — veja Autenticação.

Veja também