Pular para o conteúdo
D-APITestar grátis

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.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.