Sincronizar dados através da API
1) Por que precisa de sincronização e quais são os objetivos
Consistência de domínios: perfil, carteira, diretórios, limites, KYC.
Menos espaço: quase real-time para processos críticos (pagamentos, bônus).
Sustentabilidade: Estamos a passar por interrupções de rede/provedor sem perda de eventos.
Economia: Minimizamos o egress/CPU através de delta e pacotes.
As métricas de sucesso: lag (s) entre a fonte e o consumidor, freshness, proporção de duplicados, porcentagem de conflitos, custo GB/hora sink.
2) Modelos de sincronização
2. 1 Pull (polling)
O cliente pede alterações em intervalos.
Os benefícios são simplicidade, controle de carga.
Contras: liga, sondagens «vazias», risco de omissão em alta velocidade de alteração.
Melhorias: If-Modificed-Since, Etag/If-None-Match, mudança _ tocen.
2. 2 Push (webhooks/events)
A fonte está a atingir o destinatário.
Os benefícios são quase real-time, poupança de sondagens.
Contras: precisa de entregas com retais, dedução, segurança (assinatura, mTLS).
Requisitos: Consumeiros Idumpotentes, backoff exponencial, replay.
2. 3 CDC/streaming (Mudança Data Capture)
Imagem das alterações do logem de transações/registro de eventos (Kafka, Debezium).
Os benefícios, a totalidade, a ordem, a escala.
Contras: complexidade, é necessário controlar os tipos de operações (insert/update/delete/tombstone).
2. 4 Híbrido
Webhooks como «trigger», polling - como fallback e para reconciação.
3) Delta Incorporados
3. 1 Watermark (marca do tempo)
O cliente armazena 'last _ seen _ ts' e pede' updated _ at> watermark '.
Riscos: deriva do relógio - use UTC e NTP; Pega uma janela de sobreposição (overlap) de 1-2 min e um dedup de ID + versão.
3. 2 Change Token / Cursor
O token estável da sequência é '?'
Os benefícios são resistência à ordem, à escala.
Requisitos: cursores não duráveis, TTL e replay seguro.
3. 3 Offsets numerados (auto-increment)
`id > last_id`. É simples, mas quebra-se com o charding e os «buracos» na sequência.
4) Paginação de grandes amostras
Keyset/cursor (preferencialmente): '? after = cursor & limit = 1000' - estável em alterações.
Offset/limit - simples, mas caro e sujeito a mudanças.
Especifique sempre o stable sort key (por exemplo, «(updated _ at, id)»).
json
{
"items": [ { "id": "u_1", "updated_at": "2025-11-03T16:59:10Z" } ],
"next_cursor": "eyJ1cGRhdGVkX2F0IjoiMjAyNS0xMS0wM1QxNjo1OToxMFoifQ==",
"has_more": true
}5) Semântica de alterações: upsert, merge, delete
5. 1 Upsert/merge
'PUT/resource/diante de' é um substituto completo.
O'PATCH/resource/diante de 'é uma atualização parcial (merge-patch validado).
Idempotidade por 'Idempotency-Key' para todos os write.
5. 2 Remoções
Soft delete (campo 'deleted = true', 'deleted _ at') - salvamos o histórico; O sink dá tombstone.
Hard delete - Dê o evento 'deleted' antes de desaparecer.
json
{ "id":"u_1", "event":"deleted", "deleted_at":"2025-11-03T17:00:00Z" }6) Controle de versões e competição
6. 1 ETag/If-Match (bloqueios otimistas)
A leitura devolve 'ETag:' v123 '.
Atualização com 'If-Match:' v123 '- Proteção contra' atualizações perdidas '.
No conflito, 409 Conflict com 'erro _ código:' CONFLICT _ VERSION '.
6. 2 Versionização de registros
Campo 'version '/' updated _ at' - por delta e dedução.
6. 3 Conflitos
Políticas: last-write-wins, server-wins, merge-estrategy por campos (por exemplo, somas → adutoras, bandeiras → prioridade de origem).
7) Pedido e dedução
7. 1 Ordem de entregas
As garantias são: at-least-once, além de idempotidade → padrão de facto.
Para fluxos de dinheiro críticos - efeitos exactly-once através de idempotency store.
7. 2 Chaves de Idempotação
Composição de campos de domínio: 'fonte _ id' evento _ tipo 'sequence'.
TTL armazenamento 24-72 horas (ou mais com SLA).
7. 3 Deduplicação
Mantenha a última versão/seq aplicada no receptor; Esqueçam os mais velhos.
8) Repetições, temporizações, backoff
Retriable: 5xx/429/408/temporizadores; Non-retriable: 400/401/403/404/409/422/410/412.
Backoff exponencial + jitter: 1s, 2s, 4s... até 30-60s.
Retry-After respeitar para 429/503.
Temporizações do cliente: conexão 3-5s, consulta geral 10-30s; limite total de tentativas 3-6.
9) Controle de laje e SLA
9. 1 SLI/SLO
SLI LAG: média/p95 liga entre 'occurred _ at' e 'aplicado no consumidor'.
SLO: por exemplo, "p95 lag ≤ 60s (28d)", "proporção de eventos perdidos = 0", "proporção de duplicados ≤ 0. 01%».
Error Budet: Desperdiçamos em lançamentos/experiências.
9. 2 Métricas
`sync_lag_seconds`, `events_received_total`, `events_applied_total`, `duplicates_total`, `conflicts_total`, `retries_total`, `backlog_size`, `cursor_advance_rate`.
10) Reconciliação (croquis) e backfill
Cruzamentos diurnos/horários: total/hashi por janela.
API de reposição: 'GET/reconciação? from =... & to =... 'devolve os valores de controle e as divergências.
Backfill: fornecimento seguro de dados históricos com pacotes de cursor, sem origem DDOS; cumpra os limites.
11) Esquemas e exemplos
11. 1 Evento webhook (assined)
json
{
"event": "user. updated",
"id": "evt_01HX",
"occurred_at": "2025-11-03T18:00:05Z",
"sequence": 123456,
"data": { "id": "u_1", "email": "a@b. com", "updated_at": "2025-11-03T18:00:02Z" }
}- `X-Signature: sha256=
- `X-Event-Id: evt_01HX`
- `X-Retry: 0..N`
11. 2 Amostra Aumentativa (polling)
`GET /v1/users? updated_after=2025-11-03T17: 58:00Z&cursor=...&limit=1000`
11. 3 Idempotent upsert
POST /v1/users
Idempotency-Key: upsert-u_1-20251103T1800Z
{ "id":"u_1","email":"a@b. com","version":124 }
→ 201/200 (stable)12) Segurança e complacência
Auth: OAuth2 scopes/JWT; para canais de sinca - mTLS sob demanda.
Assinaturas HMAC títulos para webhooks, rotação de segredos.
Minimização PII, camuflagem nos logs; GDPR/DSAR: descarga/remoção.
RBAC/ABAC: acesso por tenante/organização, quotas rigorosas.
13) Observabilidade e logs
Лейблы: `env`, `service`, `tenant`, `source`, `cursor`, `seq`, `event_type`.
Correlação: 'trace _ id' da entrada → aplique em logs e pistas.
Dashboards: lag, backlog, velocidade do cursor, erros por tipo, 429/5xx, custo (egress/min).
14) FinOps: custo de sincronização
Pacote (batch size 100-1000) + compressão (gzip/br).
Armazenamento em dinheiro e ETag para páginas não modificadas.
Fina payload's: apenas campos alterados, referência ao recurso completo sob demanda.
Limites de paralelismo e «janelas noturnas» para backfill.
15) Testes e qualidade
15. 1 Contratos e malas negativas
Valide os esquemas JSON, os campos obrigatórios, a estabilidade de 'erro _ código'.
Testes: out-of-order, duplicados, omissão de eventos, conflito de versões, 429/5xx.
15. 2 Chaos/jogos
Injeções: atrasos de rede, drop 10-30% eventos, reorder.
Critérios para manter a ordem/integridade? Não há perdas? Uma liga dentro do SLO?
16) Folha de cheque de implementação
- O modelo selecionado (push/pull/hybrid) e a origem da verdade.
- Delta incorporados: watermark ou cursor/tocen.
- Paginação: cursor/keyset com variedade estável.
- Idempotency-store, chaves e TTL; deadup por '(id, versão/seq)'.
- ETag/If-Match e política de conflito (LWW/server-wins/merge).
- Retry/backoff/jitter, respeito 'Retry-After'.
- Métricas de lag/backlog/duplicates/confidts, frascos e alertas.
- Recepção API + cruzamentos diários.
- Segurança: OAuth2/JWT, assinaturas de webhooks, mTLS, políticas PII.
- FinOps: batch + compressão, limites de paralelismo, quotas egress.
- Conjunto de testes: reorder, duplicates, outages, backfill.
17) Plano de implementação (3 iterações)
1. MVP (1-2 semanas):
Cursor-paginação, watermark-delta, upsert idumpotente, metricas de base lag/backlog, retry + backoff.
2. Scale (2-3 semanas):
Webhooks como desencadeador + polling-fallback, assinaturas HMAC, reconciação, ETag/If-Match, dashboards e burn-alert na laje.
3. Pro (3-4 semanas):
CDC/streaming (Kafka/Debezium) para domínios quentes, auto-backfill, DR., FinOps otimização (batch/brotley), SLA para lag e relatórios.
18) Mini-FAQ
O que escolher watermark ou cursor?
O Cursor/keyset é mais resistente a reorder e zoom; watermark é mais fácil de iniciar, mas adicione overlap e dedup.
É necessário exactly-once?
De qualquer forma, é caro. Prática: at-least-once + idempotidade; exactly-once - apenas para efeitos monetários.
Como minimizar os conflitos?
Use ETag/If-Match, projete merge por campos, evite efeitos colaterais «ocultos».
Resultado
Sincronização confiável é Delta Incorporativo + paginação correta + Idempotação e controle de versões, reforçado pela observabilidade, verificação e transporte de baixo custo. Selecione um modelo adequado (push/pull/CDC), fixe o SLO na laje, implemente políticas de conflito e testes de guiões «sujos» - e seu compartilhamento de dados se tornará previsível, sustentável e econômico.