Cinco erros críticos de integração da API ao iniciar

Erro nº 1. Nenhuma idempotação e «tempestade» de retrações

Sintomas: duplicações de encomendas/pagamentos, variação de quantias, devoluções controversas, alertas de DLQ aumentam.

Raiz: reapresentação de pedidos/webhooks e flappies de rede são normais. Se a operação «criar/descontar» não for idimpotente, os retratos multiplicam os danos.

Como é correto

Idempotency-Key/' operation _ id 'para todos os métodos inseguros (POST/PATCH).

Índice único em BD por 'operation _ id'. Repetição, devolva o último resultado.

Webhooks por meio da tabela Inbox (dedupe por 'event _ id + indicação'). Eventos de saída - Outbox.

Retrai: no máximo 1 a 2 vezes, expositor + jitter, apenas para operações seguras.

Convenção HTTP (exemplo):

http
POST /v1/payments
Idempotency-Key: ik_f35a2
Content-Type: application/json

{"amount": 5000, "currency": "EUR", "source": "card_..."}

Proteção SQL (simplificado):

sql
ALTER TABLE payments ADD CONSTRAINT uniq_op UNIQUE (operation_id);

Retrai com jitter (pseudocode):

python for i in range(2):
try: return call_api(payload, timeout=0. 6)
except Timeout:
sleep(0. 05 2i + random. uniform(0, 0. 05))
raise UpstreamUnavailable

Folha de cheque:

Toda a lógica «monetária/criadora» tem «operation _ id» e índice uniq.
Os webhooks que entram são apenas pelo Inbox com o work idumpotente.
O SDK cliente instala automaticamente o Idempotency-Key.

Erro número 2. Tempos/retraí contra SLO: «superaquecimento» das dependências

Sintomas: p95 desaparece de repente, as filas crescem, circuito breaker flutua.

Raiz: O SLO total da resposta é de 400-600 ms, e o tempo de API externo é de 1-2 s, e também retrai x 3. Você faz mais tempo do que pode, e pega o vício de novo.

Como é correto

Budet timing: Se o SLO 400 ms, tempo upstream: 250-300 ms; tempo total da consulta ≤ SLO.

Limits/Backpressure: semafora/worker-pool para chamadas para cada dependência. Cheio de → 429/503 imediatamente.

Circuito breaker: 'open' para times/5xx, 'half-open' é dosado.

Admisse controle: limite o paralelismo (por fluxo, por endpoint/PSP).

Exemplo (Go):

go sem: = make (chan estrutt se 64 )//limite de concorrência para PSP func callPSP (ctx context. Context, req Req) (Res, error) {
select {
case sem <- struct{}{}:
defer func(){ <-sem }()
c, cancel:= context. WithTimeout(ctx, 300time. Millisecond)
defer cancel()
return psp. Do(c, req)
default:
return Res a.r., ErrBusy//falha imediata em vez de fila sem fim
}
}

Folha de cheque:

Os times são mais curtos que o SLO; retrai ≤ 2; Há um jitter.
Pula/semafora para APIs externas; circuito breaker com métricas.
Em «busy», devolvemos 429/Retry-After, em vez de manter ligações.

Erro no 3. Segurança fraca: assinaturas de webhooks, segredos, TLS

Sintomas de «estranhos» webhooks passam, segredos em código/logs, riscos MITM.

Raiz: Sem comprovação de assinatura/frescura, segredos vividos em arquivos end, antigos TLS e títulos fracos.

Como é correto

Assinatura de webhooks HMAC-SHA256 + 'X-Timestamp' (janela ≤ 5-10 min), comparação rigorosa da assinatura.

mTLS para integrações críticas ou IP allow-list.

Rotação de segredos por Vault/Cloud KMS; O mínimo de direitos; auditoria da subtração.

TLS 1. 2/1. 3 only, HSTS, CORS certos (lista estreita de fontes).

Comprovação de assinatura (Python):

python def verify(sig_hdr, ts_hdr, body, secret):
if abs(time. time() - int(ts_hdr)) > 600: raise Expired()
calc = hmac. new(secret, (ts_hdr + "." + body). encode(), hashlib. sha256). hexdigest()
if not hmac. compare_digest(calc, sig_hdr): raise BadSig()

Folha de cheque:

Todos os webhooks são assinados e verificados; a janela de frescura é limitada.
Segredos no KMS/Vault, há rotação e auditoria.
TLS/HSTS incluídos; O CORS é pontual; Onde for apropriado.

Erro nº 4. Contrato de Drift, esquema de vida

Sintomas: «Apenas uma parte dos clientes», 500/422 em logs, versões diferentes de SDK e API discutem.

Raiz: não há descrição rigorosa de contratos, mudanças incompatíveis de volta, campos «silenciosos», significados diferentes em nomes idênticos.

Como é correto

Contrato-1: OpenAPI/AsyncAPI + geração de servidores/clientes; para eventos - Avro/Protobuf + Schema Registry.

Versioning: 'v1 → v2' (URI/heder), plano deprecation, período grace.

Backward-compat: apenas alterações aditivas em lançamentos menores; a proibição de remover/renomear sem v-bump.

Testes contratuais Pact/Buf - provedor/consumador são verificados na CI.

Exemplos:

yaml
OpenAPI: tipo de valor nítido em unidades menores amount _ menor:
tipo: integra mínimo: 0 descrição: Soma em unidades mínimas de moeda (inteira)

Folha de cheque:

Os contratos são armazenados em git, o CI é validado/quebrado em caso de incompatibilidade.
Registros de padrão para eventos, compatibilidade «back/forward».
Doutor de alterações, datas de despricagem, estande de teste para os parceiros.

Erro número 5. Lançamento «cego»: sem métricas/logs/trailers e barras de areia

Os sintomas são de «não se vê nada», o suporte é estragado e o debag, com as mãos à venda.

Raiz: sem observação, sem sintéticos, a caixa de areia foi testada com palavras.

Como é correto

Métricas RED/USE: rate/erro/latency em cada endpoint, rotas/métodos.

Correlação: 'trace _ id' em todos os logs e respostas; Ligamento de zapros↔vebkhuk.

Sintética: health-amostras (login/areia deposit), monitoramento SLA T + 60 para webhooks.

Chaves/domínios completamente isolados, PSP fictício, gravações «não entram nos relatórios».

Resposta com ID trace:

http
HTTP/1. 1 202 Accepted
Trace-Id: 7f2b3d8e9c1a4
Location: /v1/ops/req_42/status

Folha de cheque:

Métricas RED/USE, dashboards, alertas (sintomas + causas).
Trailers end-to-end; logi JSON, sem PII, com 'trace _ id'.
Sintéticos de regiões-chave; A caixa de areia é obrigatória, as chaves são diferentes.

Plano Prelounch (T-7 → T-0)

T-7 dias:

Contrato-scan final: não há alterações incompatíveis; esquemas freeze.
Segredos/certificados: verifique rotação, acessibilidade, políticas KMS.
Sintética 24 x 7, alertas amarrados a on-call.

T-3 dias:

Mini-teste de carga (burst 2-5 min): p95/pula/fila na área verde.
DRY-RUN webhooks (repetições, 5xx, jitter), verificação DLQ.
L1/L2 contatos, war-room.

T-0:

Tráfego de canais 5% → 25% → 50% em gays SLO; Pronto para rollback.
Ativado kill-switch/função-flags em fichas de risco.
O War-room está ativo e os padrões de status estão preparados.

Plano Rollback (se algo correr mal)

1. Desligar o tráfego para a versão/rota estável anterior.

2. Desativar alterações controversas.

3. Estabilizar as filas/pula, parar os retais na tempestade.

4. Pós-incidente: reunir timeline, raízes, tarefas (fix-avançado/fixação do contrato).

Tabela de auto-lançamento (curta)

Bloco	Pergunta	Sim/Não
Idempotação	Todos os métodos «criadores» têm Idempotency-Key/' operation _ id 'e índice uniq?
Retraias/temporais	Os times são mais curtos que o SLO; retrai ≤2; O jitter está ligado?
Segurança	Webhooks assinados, janela de frescura ≤10 minas, segredos no KMS?
Contratos	A CI está a apanhar a incompatibilidade?
Observabilidade	RED/USE, trailers, sintético T + 60, banco de areia isolado?
Rollback	Há um botão de reversão/kill-switch, um plano de comunicação?

Frequentes «Como é que...»

... o provedor não suporta o Idempotency-Key?

Guarde 'hash (body)' + 'parceiro _ request _ id' e digite sua idempotidade.

... os webhooks às vezes vêm «antes» da resposta?

Mantenha o status de «operation _ id» e mantenha temporariamente «unknown → recordile»; o recônciler periódico vai encerrar as divergências.

... temos de apoiar clientes antigos e novos?

Versionize endpoint's ('/v1 'e '/v2'), role pelo cabeçalho/URI, mantenha a compatibilidade backward no mínimo N meses.

Currículos

As falhas de integração são quase sempre a mesma coisa, sem idempotidade, horários errados e retais, assinatura fraca de webhooks, contratos à deriva e falta de visibilidade. Fixe os contratos com antecedência, ative a observabilidade, estabeleça os limites/beckprescher, assine todas as interações externas e execute o sintético. Mesmo que os parceiros falhem, o seu lançamento será gerido sem o dinheiro perdido nos retais e sem a noite sem dormir em toda a equipa.