Chequlist de integração de API

0) Visão rápida (quem faz o quê)

• O dono da integração foi designado
• Contatos on-call (24 x 7/escravo. relógio) prescrito
• SLO/SLA concordantes e janela de suporte de lançamentos
• Status de página e canal de incidentes (email/Slack/Webhook)

1) Acessíveis, ambientes, versões

• Acesso ao sandbox/staging/producition obtido
• Versão da API confirmada: '/v1 '/cabeçalho 'X-API-Versão'
• O IP de Allowlist e as regras de rede estão configuradas
• Relógio e TZ: todos os tempos em UTC, sincronização NTP
• Verificada compatibilidade SDK/clientes em SemVer e matriz de versão

2) Autenticação e tokens

• Mecanismo alinhado: OAuth2 Clientes Credentals/Auth Code + PKCE/API Key/ mTLS
• O tempo de vida do Access Tokyo e a rotação do Refresh Token estão configurados
• Para API Key: segredo é exibido uma vez, armazenado no gestor de segredos
• JWKS/JTI/' kid 'são verificados, o clock skew está ativado €5 min
• 'Autorization' os cabeçalhos não são logados (redação)

bash curl -sS -H "Authorization: Bearer $TOKEN" https://api. example. com/v1/ping

3) Segurança e privacidade

• TLS 1. 2 +/HSTS, opcional mTLS
• PII Minimização: Enviamos apenas as máscaras desejadas nos logs
• Políticas de armazenamento e remoção (GDPR/DSAR) documentadas
• Secret rotation: chave ativa/seguinte, plano de rollover
• Anti-Abuse: kupcha/velocidade de criação de chaves/restrições de inscrição

4) Limites, quotas e bacoff

• Anunciados 'X-RateLimit '/' X-Cota-' títulos
• O cliente respeita 429 e 'Retry-After'
• Retraí somente para 5xx/408/429, backoff exponencial + jitter
• Limite de tentativas/tempo definido (por exemplo, ≤ 5 tentativas, ≤ 60s totais)

5) Idempotidade e conflitos

• Todas as operações write são enviadas de 'Idempotency-Key' (TTL ≥ 24-72 h)
• Conflito de duplicação → 409 IDEMP _ REPLAY está sendo processado
• ETag/' If-Match 'está ativado para atualizações competitivas (se houver)

bash curl -X POST /v1/payments \
-H "Idempotency-Key: pay-<uuid>" \
-d '{"amount":"12. 34","currency":"EUR"}'

6) Paginação e Delta Incorporados

• Usando cursor/keyset paginação ('next _ cursor', 'has _ more')
• Arrumação estável '(updated _ at, id)' documentada
• Descarregamentos incorporados: watermark ou mudança tocen
• Janelas de sobreposição (overlap 1-2 min) e dedução por '(id, versão/seq)'

7) Formato de erro e diagnóstico

• Formato unificado 'aplicação/perfem + json' (RFC 7807)
• Suporte de campos: 'erro _ código', 'trace _ id', 'retriable', 'detail'
• Mapa de erros e ações do cliente são descritos (runbook)

json
{
"type":"https://docs. example. com/errors/validation_failed",
"title":"Validation failed",
"status":422,
"error_code":"VAL_001",
"trace_id":"a1b2c3",
"retriable":false
}

8) Webhooks: recibos e repetições

• Confirmação de sucesso - qualquer 2xx; ACK rápido após enqueê
• Подпись HMAC (`X-Signature: sha256=...`), `X-Webhook-Id`, `X-Retry`
• Política de retrações: backoff + jitter, até 24-72 horas
• DLQ + Replay: disponíveis e testados
• Armazém de dedução do receptor, TTL ≥ janelas de retrações

9) Observabilidade e rastreamento

• Os ganchos OpenTelemetry no cliente/SDK
• Correlação 'trace _ id '/' X-Request-ID' em toda a cadeia
• Дашборды: `requests_total`, `errors_total{status}`, `latency_p95`, `retry_count`, `429_rate`
• Alarms: alta de 5xx/429, crescimento de p95, queda de sucess rate, liga de webhooks

promql rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m])

10) Desempenho e sustentabilidade

• Pool de conexões, keep-alive, HTTP/2/3 onde possível
• O paralelismo é limitado (backpressure), a fila do cliente não é «inflada»
• Políticas de circuito-breaker/timeout/fallback configuradas
• Testes de carga: burst 10 x, longas conexões, início frio

11) Dados, moedas, tempo

• Formatos: ISO-8601 UTC, dinheiro - linhas decimais/minor units, locais independentes do ambiente
• Codificações/idiomas concordados (por exemplo, 'Aceitt-Language' para mensagens, mas 'erro _ código' para máquina)
• A política de arredondamento/comissão está documentada

12) Acertos e relatórios (reconciação)

• Cruzamentos diários/horários com valores de referência
• API/descarregamento para solda testados (CSV/JSON, manifestos/hashi)
• Divergências - em tíquetes com referências a 'trace _ id'

13) Complaens e aspectos legais

• Os termos de uso da API foram aceitos (fair use/export control)
• PII/detentores de dados - papéis e áreas de armazenamento definidas
• Legal Hold/auditoria-regulação de ações incluídas em incidentes

14) Documentação e portal de desenvolvimento

• Os OpenAPI/AsyncAPI são válidos, os exemplos «copiar-colar» estão disponíveis
• SDK (TS/Py/Java/Go/.NET) - versões concordadas, Cookbook disponível
• Try-it playground funciona, as chaves de areia estão ativas
• Changelog/depressões/roadmap são visíveis no portal

15) Testes: funcionais, negativos, caos

Funcionais

• CRUD/cenários-chave ultrapassados (happy path)
• Paginação/cursor/Delta incorporados

Negativo

• 401/403/404/409/422/429/5xx e processamento de 'Retry-After'
• Assinatura de webhook errada, tokens vencidos, corpos grandes

Caos

• Drop 10-30% dos eventos, reorder, atraso de 1-10 min
• Desativar dependências (PSP/KYC) → corretamente falback/erro

16) Recepção e lançamento (go-live)

• PRR final (Produção Readiness Review) ultrapassado
• Inclusão canária: 10% → 25% → 50% → 100%
• Retorno automático por SLO sinais (erros/latência/429)
• Matriz de contatos de incidentes e caminho de escalação foram publicados
• Backlogs CAPA após o piloto formado

17) Exploração e apoio

• Runbook/playbooks: «5xx spike», «429 storm», «webhook backlog», «timeout»
• Relatórios regulares para SLO/Erro Boodget
• Rotação de segredos e chaves no horário
• Plano de depredação/migração de versões acordado (data sunset)

18) Modelos de artefatos

Modelo env-config

yaml api:
base_url: https://api. example. com/v1 timeout_ms: 10000 retries: { max: 5, strategy: expo-jitter }
auth:
kind: oauth2 token_url: https://auth. example. com/oauth2/token scopes: [wallet:read, wallet:write]
webhooks:
secret_ref: secret/webhook-hmac parallelism: 10 max_body_kb: 256

Política de Retrações (pseudo)

json
{"initial":1,"max":60,"factor":2. 0,"jitter":0. 2,"retriable":["5xx","408","429"]}

19) Folha de cheque final «por assinatura»

• Ambientes/versões/chaves/allowlist prontos
• Auth/JWT/keys/mTLS configurados e testados
• Limites/quotas/retais/idempotação implementados
• Paginação/cursor/delta funcionam em dados
• Webhooks: assinaturas, repetições, DLQ/Replay testados
• Erros 'problem + json', 'trace _ id' é colado em todos os logs
• Dashboards/alertas recolhidos, OTel incluído
• Testes de carga/negativo/caos concluídos
• Os relatórios e acréscimos são convergentes, os runbooks estão formalizados
• PRR/canário/plano rollback pronto, contatos on-call especificados

Resultado

Esta lista encerra os aspectos técnicos, operacionais e complexos da integração da API. Passe de cima para baixo, automatize a verificação de limites, idempotação e webhooks, inclua a observabilidade e o plano de reversão - e seu lançamento será previsível, sem «surpresas» na produção.