Integração de API e webhooks sob medida
Quase qualquer pessoa monta hoje uma integração que funciona no primeiro dia. Difícil é continuar funcionando no dia em que o outro extremo demora dez segundos para responder, devolve erro no meio de um lote ou reenvia o mesmo evento três vezes.
A integração “vai bem”, mas a cada duas semanas alguém pergunta por um pedido que não chegou. Ninguém sabe responder sem abrir o banco de dados, porque não existe um lugar onde olhar o que aconteceu com aquela mensagem específica.
Por que uma ferramenta no-code nem sempre basta
As plataformas de automação visual resolvem muito bem 80 % dos casos, e são usadas aqui todo dia. Deixam de bastar em três situações concretas: quando o volume faz o preço por execução perder o sentido, quando é preciso uma transação de verdade entre dois passos, e quando a lógica de erro é mais complexa que a lógica de negócio. Este último caso é mais frequente do que parece — o que demora a construir não é o caminho feliz, é todo o resto. A decisão correta raramente é “tudo sob medida”: costuma ser deixar na ferramenta o que lhe cabe e tirar para código as duas ou três peças que a extrapolam.
Os fluxos que precisam ser resolvidos
Cada um com a decisão de projeto que define se aguenta produção.
Entrega ao menos uma vez, processamento exatamente uma vez
Praticamente nenhum emissor de webhooks garante entrega única. O que se constrói no receptor é a capacidade de reconhecer o evento repetido e descartá-lo, gravando a chave do evento junto com a operação na mesma transação.
Sem isso, uma retentativa do emissor gera uma cobrança duplicada, um pedido duplicado ou um e-mail enviado duas vezes. E o emissor retenta mais vezes do que se espera.
Receber rápido, processar depois
O endpoint que recebe o webhook valida a assinatura, persiste o evento e responde. O trabalho real acontece numa fila à parte, com retentativas de espaçamento crescente e uma fila de falhados onde termina o que não pode ser processado.
Processar dentro da requisição faz com que um terceiro lento provoque timeouts, e muitos emissores desativam um webhook que falha de forma repetida. Perde-se a integração por uma lentidão pontual.
Assinatura, não confiança
Toda entrada verifica sua assinatura com comparação em tempo constante e rejeita marcas de tempo antigas. Toda saída se autentica com credenciais rotacionáveis e de escopo mínimo.
Um endpoint público sem verificação é um formulário de escrita aberto à internet contra o seu sistema de gestão.
Ordem e limites de chamada
Os eventos não chegam necessariamente em ordem e o outro extremo tem um limite de chamadas por minuto. As duas coisas se resolvem no desenho: número de versão por entidade para descartar o que é velho, e controle de ritmo com espera respeitando o cabeçalho de retentativa.
Ignorar a ordem faz um estado antigo sobrescrever o novo. Ignorar o limite provoca bloqueios que se manifestam justamente nos picos de volume.
O que você recebe
- ▪ Endpoints de entrada com verificação de assinatura e registro de eventos
- ▪ Fila com retentativa exponencial e fila de falhados revisável
- ▪ Chave de idempotência por operação, persistida junto ao efeito
- ▪ Painel de estado por mensagem: recebida, processada, falhada, em retentativa
- ▪ Alarme por antiguidade de pendentes e por crescimento da fila de falhados
Como construímos
Idempotência por padrão
Toda operação pode ser repetida sem duplicar nada. É o que permite reprocessar sem medo, e sem isso nenhuma integração sobrevive à primeira queda de rede.
Estado observável
Cada mensagem tem estado consultável: pendente, enviada, confirmada, falhada. Uma integração que só aparece quando falha já tinha falhado antes.
Um único dono por dado
Para cada campo há um sistema que manda e os outros obedecem. Sincronização bidirecional sem essa regra termina em loops e em dados que mudam sozinhos.
IA onde se decide, não onde se calcula
Classificar, extrair e redigir são tarefas de modelo. Somar, validar e encaminhar são tarefas de código. Trocar isso de lugar sai caro e fica impossível de auditar.
Como abordamos o problema
Quem diagnostica é quem constrói, sem hand-offs pelo caminho. O método completo e o resto das capacidades estão na página de integração de sistemas.
- 01 Diagnóstico · 3–5 dias
Mapeamos sistemas, fluxos de dados e dependências reais, inclusive as que ninguém documentou. Saída: escopo fechado e a lista do que hoje está quebrado.
- 02 Desenho da integração · 1 semana
Contratos de dados, direção da sincronização, política de retentativas e quem é dono de cada campo. Decide-se antes de escrever código porque é o caro de mudar depois.
- 03 Implementação e testes · 2–6 semanas
Construção com a casuística real, não com o caminho feliz. Testes contra os sistemas de verdade e implantação em fases.
- 04 Produção e observabilidade · contínuo
Painel de estado, alarmes quando algo passa tempo demais sem confirmação e manutenção das integrações quando as APIs de terceiros mudam.
Relacionado a este caso
O que costuma vir antes ou depois, com o motivo do link.
Sistemas legados
Quando o outro extremo não tem API, o padrão deixa de ser este e passa a ser outro.
Ver →Integração de ERP
O destino mais habitual destes conectores.
Ver →n8n, Zapier ou Make
A comparação entre as plataformas visuais e o ponto em que cada uma para de servir. É a decisão anterior a escrever qualquer conector.
Ver →Implementação
Como estes conectores chegam a produção: ambientes, implantação em fases e quem fica responsável pela manutenção depois.
Ver →Perguntas deste caso
Qual a diferença entre integrar por API e por webhook? +
A direção da iniciativa. Com API você pergunta quando quiser: é previsível e o ritmo é seu, mas você chega tarde e gasta chamadas perguntando por coisas que não mudaram. Com webhook o outro sistema avisa quando algo acontece: é imediato e eficiente, mas obriga a estar sempre disponível e a tolerar repetições. A maioria das integrações sérias usa as duas: webhook para saber e API para confirmar o detalhe.
O que acontece se o outro sistema cair? +
As mensagens se acumulam na fila e são retentadas com espaçamento crescente até o serviço voltar. O que nunca se deve fazer é deixar que a queda de um terceiro pare a sua operação: o fluxo próprio continua e a sincronização se põe em dia depois. É exatamente para isso que a fila existe.
Vocês usam n8n ou constroem tudo sob medida? +
As duas coisas, e a escolha é argumentada caso a caso. O n8n cobre muito bem a orquestração e os fluxos que mudam com frequência, com a vantagem de a sua equipe poder editá-los sem depender de nós. O que vai para código são as peças com requisitos duros: alto volume, transações, lógica de erro complexa ou algo que precise ser auditável. Misturar os dois mundos costuma sair mais barato do que escolher um por dogma.
Quem mantém a integração quando a API de um terceiro muda? +
Faz parte do contrato de manutenção, e convém que seja explícito. As APIs de terceiros mudam sem avisar ninguém em particular: aposentam versões, endurecem limites, alteram campos. Uma integração sem ninguém vigiando essas mudanças funciona até o dia em que deixa de funcionar, e normalmente se descobre por uma reclamação de cliente.
Comece pelo diagnóstico
Três a cinco dias para saber o que se conecta primeiro, com escopo e preço fechados antes de escrever uma linha de código.
Falar com um especialista ↗Outros casos