Melhores Práticas de Integrações

Circuit-break em chamadas de fornecedores; não bloqueie a thread de requisição em latência externa ilimitada.

Como Usar Esta Lista

• Revise antes de adicionar uma nova dependência de SDK SaaS
• Exija um documento de design de integração para fluxos de pagamento e PII
• Combine com o Playbook de Falha de Integração
• Teste de carga com respostas 503 simuladas do fornecedor

A - Arquitetura

• Chamadas de SDK apenas de módulos de serviço de integração - não de manipuladores de rota.
• Cliente singleton por fornecedor por processo com timeout explícito.
• Erros do fornecedor mapeados para AppError com códigos estáveis para clientes.
• ID de correlação registrado em cada requisição de saída.
• Fila assíncrona para trabalho lento ou não crítico do fornecedor (e-mail, PDF, sincronização de CRM).

B - Confiabilidade

• Timeout por requisição (tipicamente 5-15s) - veja Timeouts em Todos os Lugares.
• Tentativas com backoff exponencial + jitter apenas para operações idempotentes.
• Circuit breaker em fornecedores de caminho crítico - veja Circuit Breakers.
• Respeite Retry-After em 429 de parceiros.
• Orçamento total de prazo para requisições voltadas ao usuário documentado.

C - Webhooks de Entrada

• Verificação de assinatura no corpo bruto antes do parse JSON.
• Manipulador idempotente com constraint de ID de evento único do fornecedor.
• Retorne 2xx após enfileiramento durável, não após processamento completo.
• Rota de webhook separada do parser global express.json().
• DLQ ou tabela de eventos falhados para repetição manual.

D - Pagamentos e SMS (Stripe/Twilio)

• Chave de Idempotência em criações da Stripe - veja Padrões de SDK Stripe, Twilio e.
• Apenas chaves de teste em ambientes não produtivos e CI.
• apiVersion da Stripe fixado no código.
• Assinatura de entrada da Twilio validada em todos os webhooks.
• Sem dados de cartão ou segredos em logs - redija serializadores.

E - Segurança e Conformidade

• Chaves de API em gerenciador de segredos, rotacionadas em agendamento.
• IAM de privilégio mínimo para integrações de SDK AWS.
• Guarda-SSRF em URLs fornecidas pelo usuário chamando fetch de saída - veja Guarda-SSRF.
• DPAs de fornecedor assinados quando PII sai da sua VPC.
• Escaneamento de dependências em pacotes de SDK de integração.

F - Operações

• Verificações de saúde sintéticas contra endpoints de teste do fornecedor.
• Dashboards: taxa de erro, latência, estado do breaker por fornecedor.
• Assinaturas de página de status para Stripe, Twilio, AWS.
• Runbook para SEV1 do fornecedor com macros de suporte.
• Reconciliação pós-interrupção para pagamentos (DB vs dashboard do fornecedor).

FAQs

Relacionados

• Noções Básicas de Integrações - limite de serviço
• Verificação de Webhook - HMAC de entrada
• Retry & Resiliência de Saída - backoff
• Playbook de Falha de Integração - incidentes
• Melhores Práticas de Resiliência - transversais

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.