Integrações que não quebram: princípios para conectar sistemas críticos

Integrações costumam ser construídas para o cenário em que tudo funciona: o sistema de origem envia, o de destino recebe, a informação aparece onde deveria. Mas, na operação real, redes oscilam, serviços ficam indisponíveis, mensagens chegam duplicadas ou fora de ordem e fornecedores mudam suas APIs.

Uma integração confiável não é aquela que nunca falha — isso não existe. É aquela que falha de forma previsível, visível e recuperável. Os princípios a seguir ajudam a chegar lá.

Projete para a repetição: idempotência

Toda operação que pode ser reenviada deve ser idempotente: processar a mesma mensagem duas vezes precisa produzir o mesmo resultado que processá-la uma vez. Sem isso, uma simples nova tentativa após um tempo de espera pode gerar dois pedidos, duas cobranças ou dois lançamentos contábeis.

Na prática, isso significa:

• atribuir um identificador único a cada evento ou requisição na origem;
• registrar no destino quais identificadores já foram processados;
• tratar uma repetição como sucesso, e não como erro;
• preferir operações do tipo "definir o estado como X" a "somar Y ao estado atual".

Espere falhas: novas tentativas com critério

Quando uma chamada falha, tentar de novo imediatamente costuma piorar a situação — especialmente se o serviço de destino está sobrecarregado. Use novas tentativas com intervalo crescente (por exemplo, 1, 2, 4, 8 minutos), com um limite máximo.

Também é importante distinguir tipos de erro:

• Erros temporários (indisponibilidade, tempo esgotado, limite de requisições) devem ser tentados novamente.
• Erros permanentes (dados inválidos, recurso inexistente, falta de permissão) não se resolvem com repetição e devem ir direto para análise.

Falhe de forma visível: filas de reprocessamento

Erros silenciosos são o pior cenário. Uma integração que descarta mensagens com problema pode passar semanas "funcionando" enquanto os dados divergem entre os sistemas.

Mensagens que esgotaram as tentativas devem ir para uma fila de reprocessamento — às vezes chamada de dead letter queue —, com:

• o conteúdo original da mensagem;
• o motivo e o horário da falha;
• um responsável definido para análise;
• a possibilidade de reprocessar depois da correção, sem intervenção no banco de dados.

Se ninguém sabe que uma integração falhou, ela não falhou uma vez: ela está falhando continuamente.

Veja o que acontece: observabilidade

Para operar integrações críticas, é preciso responder rapidamente a perguntas como "essa nota fiscal foi enviada?", "por que esse pedido não chegou?" ou "o volume de hoje está normal?". Isso exige observabilidade desde o primeiro dia:

• logs estruturados com o identificador da transação em todas as etapas;
• métricas de volume, latência e taxa de erro por integração;
• alertas acionáveis, enviados a quem pode agir, com contexto suficiente para começar a investigação;
• painéis que mostrem a saúde de cada conexão.

Documente o contrato

Uma API é um contrato entre equipes — muitas vezes de empresas diferentes. Contratos implícitos geram interpretações diferentes e quebram quando alguém muda um campo "sem importância". Uma boa documentação inclui:

• especificação OpenAPI versionada junto com o código;
• exemplos reais de requisição e resposta, inclusive de erro;
• política de versionamento e descontinuação, com prazos;
• limites de uso, regras de autenticação e códigos de erro explicados.

Proteja as credenciais

Integrações concentram acessos poderosos. Chaves de API e tokens devem ficar em cofres de segredos, nunca no código-fonte ou em planilhas compartilhadas. Defina permissões mínimas para cada integração, faça a rotação periódica das credenciais e registre o uso de cada chave.

Um checklist para começar

Antes de colocar uma nova integração em produção, verifique:

• As operações são idempotentes?
• Há novas tentativas com intervalo crescente e limite?
• Mensagens com falha vão para uma fila com responsável?
• Existem logs, métricas e alertas por integração?
• O contrato está documentado e versionado?
• As credenciais estão protegidas e com acesso mínimo?

Com esses princípios, integrações deixam de ser um ponto de fragilidade e passam a ser uma vantagem operacional: informação registrada uma única vez, disponível onde é necessária e rastreável do início ao fim.