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
- Visão geral da integração — onde o feed se encaixa no quadro geral
- Parâmetros de listagem — a gramática
q[]/o[]/e/pse aplica nos pulls quando precisar filtrar