API de WhatsApp para ERP: NF, boleto e pedidos

API de WhatsApp para ERP: documentos e avisos que saem sozinhos

Com uma API de WhatsApp, o ERP envia nota fiscal, boleto, pedido e aviso de entrega direto do evento que os gera, pelo número da empresa que usa o sistema. Ninguém baixa PDF para anexar no WhatsApp Web, e o cliente final recebe o documento onde ele realmente lê.

Por Time de engenharia D-APIAtualizado em 24 de set de 20265 min de leitura

O trabalho manual que o seu ERP ainda deixa para o usuário

O ERP emite a nota, gera o boleto e fecha o pedido. Depois disso, alguém do financeiro abre o PDF, salva na área de trabalho, abre o WhatsApp Web e manda arquivo por arquivo. Em empresa pequena, essa rotina come uma manhã inteira no fim do mês. Em empresa média, vira uma pessoa dedicada.

E-mail resolve só no papel: o boleto cai no spam, o cliente diz que não recebeu e a cobrança atrasa. Quando o próprio ERP manda o documento pelo WhatsApp da empresa, esse passo some e o usuário do seu sistema percebe a diferença na primeira semana.

Mapa de eventos: o que o ERP já sabe e vira mensagem

O ERP é o sistema que mais tem gatilhos prontos. Quase toda mudança de status já existe no seu banco; falta só ligar à API de WhatsApp.

Evento no ERP	Mensagem para o cliente final	Rota usada
NF-e autorizada	PDF da DANFE com o número da nota	`send/document`
Boleto ou fatura gerada	PDF do boleto e linha com vencimento	`send/document`
Pedido de venda confirmado	Resumo do pedido ou PDF do orçamento aprovado	`send/text` ou `send/document`
Item em falta reposto	Aviso para quem pediu o produto	`send/text` ou `send/image`
Pedido expedido	Transportadora, código de rastreio e previsão	`send/text`
Título vencido há 3 dias	Lembrete com segunda via anexada	`send/document`

Repare que nenhum desses envios depende de alguém lembrar. A regra fica no ERP, versionada junto com o resto do produto, e cada empresa cliente liga ou desliga o que quiser nas configurações.

Exemplo: nota fiscal autorizada, PDF no WhatsApp

No handler que recebe a autorização da SEFAZ, basta uma chamada. O PDF precisa estar numa URL acessível pela API (um link assinado do seu storage com validade curta resolve) ou ir em base64:

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": "erp-empresa-4821",
    "to": "5511999999999",
    "document": "https://storage.seuerp.com.br/nfe/35240912345678000190550010000123451.pdf",
    "fileName": "NF-12345.pdf",
    "mimetype": "application/pdf",
    "async": true
  }'

O fileName é o que o cliente final vê no anexo, então vale usar algo legível como "NF-12345.pdf" em vez da chave de acesso. O async devolve um commandId na hora e libera o processo de faturamento; o resultado de cada envio fica disponível para consulta ou chega pelo webhook. Os outros formatos de arquivo estão em enviar imagem, áudio e documento.

Uma conexão por empresa cliente, não uma para o ERP inteiro

O erro mais caro nesse tipo de integração é mandar tudo por um número central do próprio ERP. O cliente final recebe a nota de um remetente que não conhece, responde perguntando sobre o pedido e ninguém da empresa vê. Além disso, um problema nesse número para a cobrança de todas as empresas da base ao mesmo tempo.

O desenho certo é cada empresa cadastrada no ERP conectar o próprio número. Na D-API isso significa criar uma conexão por empresa (ou por filial) pela API, com o CNPJ ou o id interno no sessionId e no metadata. Cada conexão roda isolada e com IP próprio, então o número de uma distribuidora que teve problema não afeta a padaria que usa o mesmo ERP. Esse é o modelo descrito em API de WhatsApp para SaaS, com cobrança por conexão e não por mensagem, o que combina com o volume irregular de fechamento de mês.

Roteiro de implementação no ERP

Cadastro: na tela de parâmetros da empresa, adicione "Conectar WhatsApp". O ERP cria a conexão por API e mostra o QR Code para o responsável escanear.
Telefone confiável: padronize o celular do cadastro de clientes no formato internacional, como 5511999999999. É aqui que a maioria dos envios falha.
Primeiro gatilho: comece por um documento só, normalmente o boleto, com opção de desligar por empresa.
Log por documento: guarde o commandId junto com a nota ou o título, para o suporte responder "foi enviado às 14h02" sem abrir chamado.
Status da conexão: escute connection.status e mostre um alerta no painel quando o número de uma empresa desconectar, antes que ela descubra pelo cliente.
Resposta do cliente final: encaminhe o messages.received para o usuário responsável no ERP, ou para um atendimento, se a empresa tiver.

Cuidados com volume e com documento fiscal

Espalhe o fechamento: centenas de boletos no mesmo minuto por um número recém-conectado é um padrão que costuma levar a restrição. Use uma fila com ritmo por conexão e consulte a rota /api/v1/limits da conexão para ver as cotas de mensagens.
Link com prazo: PDF fiscal tem dados do comprador. Gere a URL assinada no momento do envio e deixe expirar logo depois.
Opt-out por contato: cliente que pediu para receber só por e-mail precisa de uma flag no cadastro que o ERP respeite.

A cobrança recorrente tem nuances próprias, tratadas em cobrança pelo WhatsApp, e os avisos de status de pedido em notificações transacionais. Para colocar isso no ar com a sua base, os 14 dias grátis falando com o time comercial incluem suporte de implementação.

Perguntas frequentes

O ERP pode mandar a nota fiscal em PDF pelo WhatsApp?

Pode. A rota de documento aceita uma URL pública ou o arquivo em base64, com nome e tipo do arquivo. O cliente final recebe o PDF da DANFE como anexo, igual a um arquivo enviado pelo celular.

Qual número aparece para o cliente final: o do ERP ou o da empresa?

O da empresa que usa o ERP. Cada empresa conecta o próprio número e as mensagens saem com o nome dela. O ERP só orquestra o envio, o que evita que o cliente final estranhe um remetente desconhecido.

Como enviar centenas de boletos no fechamento do mês sem travar o ERP?

Use o envio assíncrono. Com async igual a true a API devolve um commandId na hora, e o resultado é consultado depois ou chega pelo evento command.result. O job de faturamento não fica esperando cada envio.

Uma empresa com várias filiais precisa de vários números?

Só se cada filial atende separado. Muitas empresas usam um número central para cobrança e documentos fiscais e números por filial para vendas. No ERP, isso vira uma conexão por número, ligada ao cadastro da filial.

Preciso da API oficial para mandar boleto?

Não é obrigatório. Na API não oficial o envio é livre, basta o número conectado. Na oficial, a primeira mensagem para o cliente precisa ser um template aprovado pela Meta. Na D-API as duas usam as mesmas rotas de envio.