Pular para o conteúdo principal

Checklist de Go-Live

Antes de colocar sua integracao em Producao, valide os itens abaixo. Eles cobrem os erros mais comuns de integracoes M2M.

Autenticacao e credenciais​

  • Troquei X-Client-Id / X-Client-Secret por um JWT de curta duracao via POST /v1/auth/token (o SDK faz auto-refresh).
  • O client_secret esta em um cofre de segredos (AWS Secrets Manager, Vault) — nunca no codigo-fonte, repositorio ou logs.
  • Estou usando as credenciais zk_live_* (Producao), nao as de teste.
  • Solicitei apenas os scopes que minha integracao usa (menor privilegio) e trato 403 scope_insufficient.
  • Defini rotina de rotacao do secret a cada 90 dias.

Idempotencia​

  • Envio Idempotency-Key (UUID) em todas as rotas financeiras (POST /v1/operations/direct, POST /v1/stock, POST /v1/stock/request-anticipation).
  • Reuso a mesma chave ao reenviar a mesma requisicao (retry) — nao gero uma chave nova por tentativa.
  • Trato 409 idempotency_key_reused_with_different_body.

Tratamento de erros​

  • Trato o envelope de erro ({"detail": ...}) e os codigos de erro relevantes (404, 409, 422, 423).
  • Trato os erros estruturados de limite/CET (LIMIT_*, CET_OUT_OF_BOUNDS).
  • Faco retry com backoff em 429, 502 e 503.
  • Registro o header X-Request-Id de cada resposta (essencial para suporte).

Webhooks​

  • Endpoint publico (HTTPS) configurado e respondendo 2xx rapidamente.
  • Valido a assinatura HMAC-SHA256 de cada evento (ver Seguranca de Webhooks).
  • Processo eventos de forma idempotente (podem chegar repetidos via retry).
  • Trato os eventos relevantes do catalogo.

Rate limits e ambiente​

Pronto para produzir​

  • Fiz um fluxo ponta a ponta (autenticar -> simular -> criar -> webhook -> conciliar).
  • Tenho observabilidade (logs com X-Request-Id, alertas de erro).