Integrações: como sistemas conversam entre si

Por que integrar

Sistema que vive isolado obriga alguém a fazer o trabalho manualmente. Pedido entrou no webapp, alguém copia pro sistema de envio. Pagamento confirmou, alguém marca no financeiro. Cliente mandou mensagem, alguém digita a resposta.

Cada passo manual é um ponto de falha. A pessoa esquece, erra o dado, digita o valor errado, esquece de atualizar o status. E quanto mais o negócio cresce, mais esses passos manuais viram gargalo. O que funciona com 10 pedidos por dia quebra com 50.

Integração elimina esse trabalho repetitivo. O sistema faz sozinho o que antes dependia de uma pessoa copiando dado de um lugar pra outro. No AutoPars, são 5 integrações rodando juntas: pagamento, frete, WhatsApp, email e mídia. Cada uma resolve um pedaço do fluxo.

API: a porta de entrada

API (Application Programming Interface) é a interface que permite que um sistema converse com outro. Na prática: você manda uma requisição HTTP com os dados e recebe uma resposta estruturada.

Na prática, funciona assim: seu sistema manda uma requisição com dados estruturados, o outro sistema processa e devolve uma resposta. Você não precisa saber como o outro sistema funciona internamente.

Exemplo real do AutoPars: consultar o status de um envio no Melhor Envio.

GET https://api.melhorenvio.com/api/v2/me/shipment/tracking
Authorization: Bearer SEU_TOKEN

A API responde com JSON contendo o status atual do envio. O sistema lê a resposta e atualiza o pedido automaticamente. O comprador vê “em trânsito” sem ninguém ter digitado nada.

O padrão REST

A maioria das APIs que você vai encontrar segue o padrão REST:

• URLs representam recursos: /api/products, /api/orders/123
• Verbos HTTP indicam a ação: GET = ler, POST = criar, PUT = atualizar, DELETE = remover
• Respostas vêm em JSON

Quando você domina REST, consegue integrar com praticamente qualquer serviço moderno. A lógica é sempre a mesma — muda o endpoint, muda o payload, mas o padrão é igual. E os códigos de status HTTP seguem convenção: 200 é sucesso, 201 é criado, 400 é erro de validação, 401 é não autenticado, 404 é não encontrado, 500 é erro interno do servidor. Saber ler esses códigos acelera muito o debugging quando uma integração não funciona.

Webhook: notificação em tempo real

API é quando você pergunta. Webhook é quando o outro sistema te avisa.

A diferença é importante. Se seu sistema precisa saber quando um pagamento foi confirmado, tem duas abordagens:

Polling (ruim): seu sistema pergunta pro gateway de pagamento a cada 30 segundos: “pagou? pagou? pagou?” Gasta recurso, é lento, e se o intervalo for grande demais, o cliente espera sem necessidade.

Webhook (bom): o gateway de pagamento manda um POST pra uma URL do seu sistema no momento exato da confirmação. Instantâneo, eficiente, sem desperdício.

No AutoPars, quando o comprador paga um boleto no Asaas, o sistema não fica perguntando. O Asaas manda um POST automático:

{
  "event": "PAYMENT_CONFIRMED",
  "payment": {
    "id": "pay_123",
    "value": 299.90,
    "status": "CONFIRMED"
  }
}

O sistema recebe, valida a origem, atualiza o pedido e dispara as próximas ações: notifica o vendedor via Zapi (WhatsApp) e manda email de confirmação via Resend. Tudo automático, em segundos.

Cuidados com webhooks

Webhooks funcionam bem mas precisam de atenção:

Sempre valide a origem. Qualquer pessoa pode mandar um POST pra sua URL de webhook. Valide token, assinatura ou IP do remetente. Sem validação, alguém pode simular um pagamento confirmado e liberar produto sem pagar.

Trate duplicatas. O mesmo evento pode chegar mais de uma vez (o provedor reenvia se não recebeu 200 OK na primeira tentativa). Seu sistema precisa ser idempotente: receber o mesmo evento duas vezes não pode causar ação duplicada.

Responda rápido. Retorne 200 OK imediatamente e processe em background se for pesado. Se demorar pra responder, o provedor pode considerar que falhou e reenviar.

E logue tudo. Quando algo não funciona (e vai acontecer), o log do webhook recebido é o que salva. Sem log, você fica no escuro tentando adivinhar o que deu errado.

As 5 integrações do AutoPars

Asaas (pagamento)

O fluxo completo: sistema cria a cobrança via API (boleto, Pix ou cartão) → cliente paga → Asaas avisa via webhook → sistema atualiza o pedido → notifica vendedor e comprador.

O que parece simples tem camadas. Boleto vence e precisa de tratamento (reenviar cobrança? cancelar pedido?). Pix confirma em tempo real mas precisa de QR code gerado dinamicamente. Cartão pode ter chargeback semanas depois e precisa de estorno no sistema. Cada forma de pagamento tem lógica própria.

No AutoPars, implementei split de pagamento: o valor da venda é dividido automaticamente entre a plataforma (taxa) e o vendedor (valor líquido). O Asaas faz o split no nível do gateway — o dinheiro já cai dividido.

Melhor Envio (frete)

Três etapas: cálculo de frete, geração de etiqueta e rastreamento.

O comprador coloca o CEP, o sistema consulta a API do Melhor Envio com o CEP de origem (vendedor), CEP de destino (comprador), e dimensões do produto. Retorna opções de transportadora com preço e prazo. O comprador escolhe, e quando o pedido é confirmado, o sistema gera a etiqueta de envio automaticamente.

Rastreamento funciona via webhook: o Melhor Envio avisa quando o status do envio muda (postado, em trânsito, saiu pra entrega, entregue). O sistema atualiza e o comprador vê o status sem ninguém copiar código de rastreio manualmente.

Zapi (WhatsApp)

Notificação automática pelo WhatsApp. “Seu pedido foi confirmado”, “sua peça saiu pra entrega”, “pagamento recebido”. O sistema manda a mensagem via API da Zapi. Ninguém digita manualmente.

WhatsApp tem uma taxa de abertura muito maior que email. No contexto do AutoPars, onde o vendedor é dono de loja de autopeças e vive no WhatsApp, receber notificação ali é mais eficiente que email.

Resend (email transacional)

Confirmação de cadastro, recuperação de senha, status de pedido, nota fiscal. Email transacional é diferente de email marketing — é email que o sistema dispara em resposta a uma ação do usuário, não campanha em massa.

Resend tem uma API limpa e documentação boa. Implementar leva horas, não dias. O email sai formatado em HTML com template responsivo. Um detalhe que faz diferença: email transacional precisa de domínio verificado com SPF e DKIM configurados corretamente, senão cai em spam. O Resend facilita essa parte, mas é responsabilidade do dev garantir que a configuração de DNS tá certa antes de ir pra produção.

Cloudflare Stream (mídia)

Upload de imagens e vídeos de produtos. O vendedor sobe o arquivo no frontend, o sistema salva no Cloudflare com URL otimizada pra CDN global. Imagens servidas do ponto mais próximo do comprador, carregamento rápido.

Como organizo no código

Com 5 integrações no mesmo projeto, organização é o que evita o código virar bagunça. Cada integração é um módulo isolado com sua própria estrutura:

src/
  integrations/
    asaas/
      client.ts       (configuração base: URL, token, headers)
      payments.ts     (criar, consultar, cancelar cobrança)
      webhooks.ts     (handler que recebe e processa eventos)
    melhor-envio/
      client.ts
      shipping.ts     (cálculo de frete, geração de etiqueta)
      tracking.ts     (consulta e webhook de rastreamento)
    whatsapp/
      client.ts
      messages.ts     (templates de mensagem, envio)
    resend/
      client.ts
      emails.ts       (templates, envio transacional)
    cloudflare/
      client.ts
      upload.ts       (upload de imagem/vídeo, URL de CDN)

Se o Asaas muda a API v2 pra v3, só mexo na pasta asaas/. Se preciso trocar Zapi por Evolution API pro WhatsApp, troco a implementação dentro de whatsapp/ sem mexer no resto do sistema. Cada integração é uma caixa preta pro resto do código.

Práticas que evitam dor de cabeça

Tokens de API ficam em variáveis de ambiente, nunca no código. Se vazar um token no Git, o estrago pode ser grande.

Tenha fallback pra quando a API externa cair. E ela vai cair. Melhor Envio fora do ar não pode impedir o comprador de finalizar o pedido. Mostra mensagem, salva os dados, e processa quando voltar.

Logue todas as requisições e respostas. Quando o webhook do Asaas chega e o pedido não atualiza, o log mostra se o evento chegou, se o payload tava correto, e onde o processamento falhou.

Timeout de 5 segundos em toda requisição externa. Se a API não responder em 5 segundos, não vai responder. Seu sistema não pode ficar travado esperando.

E retry com backoff exponencial pra falhas temporárias. Primeira tentativa imediata, segunda em 1 segundo, terceira em 4 segundos. Se falhou 3 vezes, loga o erro e notifica.

Quanto isso adiciona ao projeto

Cada integração adiciona de 1 a 2 semanas ao desenvolvimento, dependendo da complexidade da API e da qualidade da documentação.

APIs bem documentadas (Resend, Stripe) são rápidas. Docs claros, SDK atualizado, exemplos que funcionam. Implemento em 3-4 dias.

APIs com documentação ruim ou SDK desatualizado levam mais tempo. Preciso testar endpoint por endpoint, descobrir comportamentos não documentados, e tratar erros que a documentação não menciona.

No AutoPars com 5 integrações, isso representou cerca de 40% do tempo total de desenvolvimento. Pro usuário final é invisível — ele clica em “comprar” e tudo acontece. Mas por trás, são 5 sistemas diferentes conversando pra fazer aquele clique funcionar.

Se você tá planejando um webapp sob medida, leve integrações em conta no orçamento e no prazo. Cada API que o sistema precisa conversar adiciona complexidade real.