Como integrar o WhatsApp ao ERP, CRM ou loja com API e webhooks

O atendimento acontece no WhatsApp, mas o resto do negócio mora em outros sistemas: o ERP com pedidos e estoque, o CRM com a lista de clientes, a loja online, o sistema de agenda. Enquanto eles não conversam, alguém faz a ponte à mão. Copia o número do pedido, cola na conversa, volta para o sistema e atualiza o status.

Este artigo tem duas partes. A primeira é para quem decide: o que vale automatizar e como pensar a integração. A segunda é para quem desenvolve: como chamar a API, receber webhooks e fazer isso com segurança.

Parte 1: para quem decide

O que uma integração resolve

A integração tira o trabalho manual de repetir a mesma informação em dois lugares e faz o WhatsApp reagir ao que acontece nos outros sistemas, e vice-versa. Alguns exemplos genéricos:

• Aviso de pedido. A loja marca um pedido como enviado, e o cliente recebe uma mensagem sem ninguém digitar.
• Cobrança e lembrete. O financeiro do ERP gera um título a vencer, e uma mensagem sai com o aviso.
• Contato no CRM. Quando o cliente muda de etapa na conversa, o CRM recebe a informação.
• Agenda ligada ao site ou ao sistema próprio. Uma clínica consulta horários livres e cria o agendamento pelo sistema que já usa.
• Pedidos e chamados. Pedidos da loja e tickets de suporte entram no atendimento e têm o status atualizado.
• Alerta para a equipe. Um evento (conversa nova, canal desconectado, chamado com prazo estourado) dispara um aviso em outro sistema.

API e webhook, qual usar

A diferença é quem toma a iniciativa.

Quase toda integração usa as duas: o webhook avisa que algo aconteceu, e a API faz a ação de volta.

O que perguntar antes de começar

1. Qual processo vai ser automatizado? Escolha um, o que mais consome tempo hoje.
2. Qual sistema é a fonte da verdade? Estoque, preço, status do pedido: defina quem manda.
3. Quem cuida quando der erro? Toda integração falha em algum momento. Alguém precisa ver e corrigir.
4. O que acontece se a mensagem sair duplicada ou não sair? Dependendo do caso, o prejuízo é pequeno ou grande.
5. O cliente concordou em receber a mensagem? Automatizar o envio não elimina as regras do WhatsApp nem a LGPD.

Disponibilidade

A API e os webhooks estão disponíveis a partir do plano Pro. Cada integração usa credenciais da própria empresa, o que mantém os dados de uma conta separados dos de outra. Para agências, isso significa uma integração por cliente, cada uma com o seu token.

Parte 2: para quem desenvolve

A documentação completa, com os formatos de cada recurso, está em /docs/api. Abaixo ficam os conceitos e os cuidados.

Autenticação: um token por empresa

Em Configurações, na área de desenvolvedores, você cria tokens da API. Cada token pertence a uma empresa e é enviado no cabeçalho Authorization: Bearer <token>. O valor aparece uma única vez, então guarde-o num cofre de segredos.

Cada token tem habilidades: consultar, criar e alterar, enviar mensagens e pedidos da loja. Crie um token por sistema e dê a ele só o que precisa. Se um sistema for comprometido, você revoga um token sem afetar os outros.

O que a API faz hoje

• Atendimento. Consultar conversas, mensagens e contatos, enviar mensagem de texto e marcar uma conversa como resolvida.
• Agenda. Listar agendas e horários livres, consultar agendamentos, criar, remarcar e cancelar.
• Leads do site. Consultar leads, quando o app de Formulários ou de Captura de leads está instalado.
• Pedidos. Consultar e criar pedidos e alterar o status, quando o app de Pedidos está instalado e o token tem a habilidade de pedidos.
• Chamados. Consultar, criar, mudar o status e anotar, quando o app de Tickets está instalado.

Dois limites para não prometer demais. O envio de mensagem é de texto: POST /api/v1/messages, com o destino (uma conversa ou um telefone) e o texto, de até 4096 caracteres. Não há envio de mídia pela API. E não há uma rota só para cadastrar ou editar contatos: a API consulta os existentes, e um contato novo nasce junto com a mensagem para um telefone, o agendamento ou o pedido que traz esse telefone.

Um detalhe do envio: a resposta é 202, ou seja, a mensagem foi aceita para envio, não necessariamente entregue. Se o número da empresa estiver desconectado, a chamada volta com erro 409. Mensagem para quem nunca conversou com a empresa pode ficar retida pelas proteções do produto, e a resposta informa o motivo.

Idempotência: não envie a mesma coisa duas vezes

Rede cai, timeout acontece, e o seu sistema tenta de novo. Sem cuidado, o cliente recebe duas vezes o mesmo aviso de pagamento.

Os POST que enviam ou criam algo (mensagem, agendamento, pedido, chamado) aceitam o cabeçalho opcional Idempotency-Key. Com a mesma chave, o mesmo token e o mesmo corpo, a segunda chamada devolve a resposta da primeira, marcada com Idempotent-Replayed: true, em vez de repetir a ação. A chave vale por 24 horas e tem até 100 caracteres. Se você reutilizar a chave com outro corpo, recebe erro. Só respostas de sucesso ficam guardadas, então uma chamada que falhou na validação pode ser corrigida e reenviada com a mesma chave.

Como gerar a chave: use algo que identifique o fato de negócio, como pedido-1234-enviado, e não um número aleatório novo a cada tentativa. Assim a repetição do mesmo evento sempre cai na mesma chave.

Webhooks: receber os eventos

Você cadastra um endereço HTTPS público e escolhe os eventos, ou todos. Cada empresa pode ter até 10 endereços. Endereços internos não são aceitos. Entre os eventos estão:

• mensagens: message.received, message.sent, message.status;
• conversas: conversation.opened, conversation.assigned, conversation.resolved;
• contatos: contact.created, contact.updated, contact.stage_changed;
• captação: lead.created, form.submitted, pixel.event;
• agenda: appointment.created, appointment.rescheduled, appointment.cancelled;
• pedidos, negociações e chamados, quando o respectivo app está instalado;
• channel.status, quando o estado da conexão do número muda.

Cada entrega é um POST com JSON contendo id, event, created_at e data. Os cabeçalhos trazem X-Integra-Event, X-Integra-Delivery (o identificador da entrega) e X-Integra-Signature.

Verifique a assinatura

Qualquer pessoa que descubra o seu endereço pode mandar um POST falso. A assinatura impede isso. O cabeçalho tem o formato t=<timestamp>,v1=<hex>. O valor v1 é um HMAC-SHA256 de <timestamp>.<corpo bruto>, usando como chave o segredo do webhook, que aparece uma única vez quando você o cria.

Faça assim:

1. Leia o corpo bruto da requisição, antes de qualquer conversão para objeto.
2. Calcule o HMAC com o seu segredo e compare com v1, em tempo constante.
3. Confira se o t é recente, por exemplo dentro de alguns minutos, para barrar reenvio de uma captura antiga.
4. Se algo não bater, responda com erro e não processe.

Responda rápido e trate repetições

O IntegraWhats espera uma resposta 2xx em até 10 segundos e não segue redirecionamentos. Faça o mínimo na hora de receber: valide, grave numa fila e responda. Processe depois.

Quando a entrega falha, por erro de rede ou por status fora de 2xx, ela é repetida depois de 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas e 24 horas. Depois de 50 falhas seguidas o endereço é desligado e você precisa reativá-lo no painel.

Isso tem uma consequência importante: o mesmo evento pode chegar mais de uma vez, e não dá para contar com a ordem. Guarde o X-Integra-Delivery de cada entrega processada e ignore a repetição. E olhe para o estado atual do dado, não só para a sequência de eventos.

Checklist de produção

• Um token por sistema, com o mínimo de habilidades.
• Segredos fora do código e fora do repositório.
• Idempotency-Key em toda chamada que cria algo.
• Assinatura conferida em todo webhook.
• Resposta 2xx rápida e processamento em fila.
• Deduplicação pelo identificador da entrega.
• Alerta para quando o webhook for desligado por falhas.
• Teste com um número de WhatsApp de teste antes de ligar em produção.

Como começar no IntegraWhats

Com o plano Pro ou superior, abra Configurações e a área de desenvolvedores, crie um token com as habilidades que precisa e cadastre o endereço do webhook. Há um botão para enviar um evento de teste. O endereço da documentação é /docs/api.

Perguntas frequentes

Posso enviar imagem ou documento pela API?

Hoje não. A API envia mensagens de texto. Mídia continua sendo enviada pela equipe na caixa de entrada.

Dá para cadastrar um contato pela API?

Não há uma rota só para isso. O contato é criado junto com outra ação: enviar uma mensagem para um telefone novo, criar um agendamento ou registrar um pedido com telefone.

Quantos webhooks posso cadastrar?

Até 10 endereços por empresa, cada um com os eventos que você escolher.

O que acontece se o meu servidor ficar fora do ar?

As entregas são repetidas por até 24 horas, conforme a sequência de tentativas. Passado esse prazo a entrega é marcada como falha, e depois de 50 falhas seguidas o endereço é desligado. Para recuperar o que passou, consulte a API pelo estado atual dos dados.

Uma agência pode integrar vários clientes?

Sim. Cada empresa tem os seus tokens e os seus webhooks, então cada cliente tem a própria integração, isolada das outras.