integração · erp e gestão
Integração WhatsApp com ERP para enviar boleto, nota e pedido sem travar o sistema
Com a integração WhatsApp com ERP, o seu sistema de gestão manda boleto, nota fiscal e aviso de pedido pelo número do próprio cliente, em lote, sem segurar o request e com o resultado de cada envio voltando por webhook.
SaaS testa 14 dias com o time técnico ajudando na integração.
- conexões na D-API
- 1.875
- de uptime garantido em contrato
- 99,9%
- datacenters no Brasil
- 4
- por ligação de WhatsApp na API não-oficial
- R$ 0
Documento com nome de arquivo
send/document aceita fileName, mimetype e caption. O cliente final recebe Boleto-0423.pdf, e não um anexo genérico.
Lote sem request pendurado
Com async: true a API devolve um commandId na hora. O command.result avisa sucesso ou falha de cada envio.
Ordem garantida por cliente
sequential: true faz o boleto e a mensagem seguinte saírem na ordem certa para o mesmo destinatário.
Resposta ligada ao documento
Quando o cliente responde citando o boleto, o webhook traz o ID da mensagem citada em context_info.
A integração WhatsApp com ERP costuma nascer de um pedido simples do cliente do seu sistema de gestão: “quero mandar o boleto pelo WhatsApp em vez de e-mail”. Atrás dele vêm outros. Nota fiscal depois do faturamento, aviso de pedido separado, lembrete de vencimento, segunda via quando o cliente pede. Para um ERP ou sistema de gestão vendido como SaaS, o desafio é fazer isso para centenas de empresas, cada uma com o próprio número, sem que o fechamento do mês derrube a fila de jobs.
Esta página mostra o desenho com a D-API, usando como exemplo um ERP para distribuidoras que envia boleto e DANFE ao cliente de cada distribuidora.
O que o ERP ganha com o WhatsApp
E-mail de cobrança vai para o spam e para a caixa que ninguém abre. No WhatsApp, o documento chega no mesmo lugar em que o cliente já conversa com o vendedor da distribuidora. O ganho para o seu SaaS é um recurso que o cliente sente no caixa: menos boleto esquecido, menos ligação pedindo segunda via.
Do lado técnico, o ERP precisa de quatro capacidades:
- Enviar documento com nome de arquivo e legenda legíveis.
- Enviar em lote sem segurar requests e sem misturar a ordem das mensagens de um mesmo cliente.
- Saber o que aconteceu com cada envio, para marcar o título como notificado.
- Ligar a resposta do cliente ao documento a que ela se refere.
Boleto e nota fiscal como documento
A rota é POST /api/v1/messages/send/document. Além de sessionId, to e document, ela aceita fileName, mimetype e caption. O nome do arquivo faz diferença: o cliente final vê Boleto-0423-Mercadinho-Bom-Preco.pdf na conversa e encontra o documento depois pela busca do próprio WhatsApp. Para imagem, áudio e vídeo há rotas equivalentes, detalhadas em enviar mídia pela API.
Lote de fechamento sem travar o ERP
No modo padrão, a API responde depois que o WhatsApp executa o envio. Para um PDF por vez, tudo bem. No dia 25, quando a distribuidora fatura 400 pedidos, o seu worker abriria 400 requests longos em sequência.
Com async: true no corpo, a API enfileira o envio e responde na hora com commandId e status: "queued". O envio acontece em segundo plano. Para que o boleto e a mensagem com o link do Pix saiam na ordem certa para o mesmo cliente, acrescente sequential: true. A ordem preservada é a de chegada na API, por sessão e destinatário. Envios para outros clientes continuam em paralelo.
curl -X POST https://api.d-api.cloud/api/v1/messages/send/document \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "distribuidora-norte",
"to": "5511999999999",
"document": "https://erp.seu-saas.com/titulos/0423/boleto.pdf",
"fileName": "Boleto-0423-Mercadinho-Bom-Preco.pdf",
"mimetype": "application/pdf",
"caption": "Boleto do pedido 0423, vencimento 10/12.",
"async": true,
"sequential": true
}'
Dois limites entram no desenho do worker. Cada destinatário aceita até 100 envios pendentes na fila sequencial; acima disso a API responde 429, com o header Retry-After indicando de 1 a 60 segundos de espera. E, para a ordem valer, o seu sistema precisa enviar em série para o mesmo cliente: requests disparados em paralelo chegam em ordem indefinida. Como a resposta do modo assíncrono é imediata, enviar em série continua rápido. O guia de comandos assíncronos cobre o restante do fluxo.
Resultado de cada envio no command.result
O commandId é a ponte entre o título do ERP e o resultado do envio. Grave-o no título na hora do envio. Quando o comando termina, o webhook de conta command.result chega com o mesmo commandId, success dizendo se deu certo, data.messageId no sucesso e error na falha.
app.post('/hooks/dapi-comandos', express.raw({ type: 'application/json' }), async (req, res) => {
if (!isValidSignature(req.body, req.get('X-DAPI-Signature'), process.env.DAPI_CMD_SECRET!)) {
return res.sendStatus(401);
}
res.sendStatus(200);
const { data } = JSON.parse(req.body.toString());
const titulo = await titulos.byCommandId(data.commandId);
if (!titulo || titulo.notifiedAt) return;
if (data.success) {
await titulos.markNotified(titulo.id, data.data.messageId);
} else {
await titulos.markNotificationFailed(titulo.id, data.error);
}
});
Esse webhook é configurado uma vez por conta, no painel em Integrações, Webhook de Comandos, ou por PUT /api/v1/account/webhooks/command. Com secret configurado, cada entrega vem assinada em X-DAPI-Signature, um HMAC-SHA256 em hexadecimal do corpo bruto, e o isValidSignature do exemplo compara esse valor em tempo constante, por isso a rota lê o corpo cru. A entrega tem retentativa, então o mesmo commandId pode chegar duas vezes, e a checagem notifiedAt do exemplo resolve isso.
Um ponto de produto: comando que falha não é reexecutado pela D-API. Sessão desconectada no meio do lote vira success: false com o motivo em error. O seu ERP decide se reagenda, o que é o comportamento certo para cobrança, em que mandar o mesmo boleto duas vezes gera ruído com o cliente final.
Leitura e resposta ligadas ao título
Com o messageId gravado, os eventos de status fecham o ciclo. message.delivered e message.read trazem message_id e remote_jid, e passam por deduplicação de 30 segundos por mensagem. O ERP mostra “boleto visualizado em 12/11 às 9h40” no título, e o financeiro da distribuidora sabe quem cobrar por telefone.
Quando o cliente responde citando o boleto (“já paguei, segue o comprovante”), o messages.received traz context_info.quoted_message_id com o ID da mensagem citada. É o elo para anexar o comprovante ao título certo sem ninguém procurar manualmente. O catálogo de eventos de webhook mostra esses campos.
Pix, cadastro e segunda via
Três recursos completam a régua de cobrança. POST /api/v1/interactive/send/pix envia a chave Pix com botão de cópia e valor opcional, o que reduz erro de digitação no pagamento; a página sobre botão Pix pela API mostra os campos. POST /api/v1/contacts/check valida em lote os telefones do cadastro antes da primeira régua. E a segunda via pode virar autoatendimento: o cliente manda “segunda via”, o seu handler identifica o CNPJ pelo telefone e responde com o PDF.
Se parte dos clientes do seu ERP exigir a API Oficial da Meta, a conexão oficial usa o mesmo sessionId nas rotas de envio. A diferença é que ela ignora o async e responde sempre de forma síncrona, porque o envio passa direto pela Meta. Para quem cobra pelo WhatsApp oficial, o artigo sobre mensagens de serviço e cobrança explica a parte de tarifas.
Por onde começar
Conecte o número de uma distribuidora piloto, envie um boleto real no modo síncrono e confira como ele chega. Depois configure o webhook de comandos com secret, mova o envio para async: true com sequential: true e grave o commandId no título. Com isso rodando, ligue message.read ao título e trate as respostas com quoted_message_id. A cobrança é por conexão ativa, sem tarifa por mensagem na API não oficial, o que deixa previsível o custo de uma régua com vários lembretes. Os valores estão na tabela de preços.
Time D-API. Atualizado em .
Perguntas frequentes
O ERP pode enviar o PDF por URL em vez de base64?
Pode. O campo document aceita o arquivo que o seu sistema já publica. Para lotes, prefira URL e async: true, que mantém o request leve e o processamento fora do seu servidor.
Quantos envios em ordem posso enfileirar para o mesmo cliente?
Até 100 envios pendentes por destinatário na fila sequencial. Acima disso a API responde 429 com o header Retry-After, entre 1 e 60 segundos, e o envio não entra na fila.
Se um envio falhar, a D-API tenta de novo sozinha?
Não. Um comando assíncrono que falha não é reexecutado, porque repetir um envio pode duplicar a mensagem. O command.result traz success false e o motivo em error, e o seu ERP decide se reenvia.
Dá para cobrar com Pix na mesma conversa?
Dá. POST /api/v1/interactive/send/pix envia uma mensagem com botão de cópia da chave Pix e valor opcional. Na API Oficial, só dentro da janela de 24 horas.
Posso validar o telefone do cadastro antes do primeiro envio?
Sim. POST /api/v1/contacts/check recebe uma lista de números e informa quais estão no WhatsApp, o que ajuda a limpar o cadastro de clientes do ERP.