Cobrança e envio de boletos pelo WhatsApp
Aviso de vencimento, segunda via e confirmação de pagamento pelo WhatsApp, com boleto em PDF, clientRef contra cobrança duplicada e fila que protege o número.
Atualizado em
Boa parte da inadimplência não é falta de dinheiro: é esquecimento. O boleto chegou por e-mail, caiu na aba de promoções e ninguém viu. O WhatsApp é o canal que o cliente abre várias vezes por dia, e por isso um aviso curto de vencimento com o boleto em anexo costuma resolver o que três e-mails não resolveram.
Com a apiwpp, o seu sistema financeiro (ERP, plataforma de assinaturas, planilha com um script) chama a API e a mensagem sai do número da sua empresa. Esta página mostra o fluxo de uma régua de cobrança para quem já é seu cliente, os cuidados para nunca cobrar duas vezes e o tom que evita denúncias.
As mensagens de uma régua de cobrança
Uma régua simples tem poucos momentos, todos ligados a um evento do seu sistema:
| Momento | Mensagem | Anexo |
|---|---|---|
| Alguns dias antes do vencimento | Aviso de que o boleto vence em tal data, com o valor | Boleto em PDF ou link de pagamento |
| No dia do vencimento | Lembrete curto, com o código ou o link | Opcional |
| Depois do vencimento | Oferta de segunda via, com a nova data | Novo boleto em PDF |
| Pagamento confirmado | Agradecimento e confirmação | Recibo, se houver |
A última linha é a mais esquecida e a mais importante para o relacionamento: o cliente que pagou quer saber que o pagamento foi reconhecido, e uma confirmação evita que ele receba o lembrete seguinte por engano.
Para textos que se repetem, salve cada mensagem como um template com variáveis: o sistema envia só o nome do template e os valores ({{nome}}, {{valor}}, {{vencimento}}), e ajustar a redação não exige publicar código. Se faltar uma variável, a API responde 400 com a lista em missingVariables e nada é enfileirado, então ninguém recebe um aviso com o valor em branco.
Enviar o boleto em PDF ou o link de pagamento
O boleto vai como documento, a partir de uma URL https pública que o seu sistema já gera. O tipo document exige o mimetype, e você escolhe o nome do arquivo que o cliente vê e uma legenda:
curl -s -X POST "https://api.apiwpp.com/connections/$CONNECTION_ID/send" \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"to": "5511988887777",
"media": {
"type": "document",
"url": "https://financeiro.suaempresa.com.br/boletos/7781.pdf",
"mimetype": "application/pdf",
"fileName": "boleto-7781.pdf",
"caption": "Olá, Maria! Seu boleto de R$ 189,90 vence em 10/10. Qualquer dúvida, é só responder."
},
"clientRef": "fatura-7781-aviso-vencimento"
}'
A resposta é 202 com jobId, scheduledAt e position: a mensagem entrou na fila do número e sai no ritmo que o protege. A apiwpp baixa o arquivo com segurança e recusa endereços privados ou internos, então o PDF precisa estar numa URL acessível pela internet. Se preferir mandar só um link de pagamento, use uma mensagem de texto comum com o link. Os detalhes de cada tipo de mídia estão em envio de mídia.
A apiwpp não gera boletos nem processa pagamentos: ela entrega a mensagem. O boleto, o PIX ou o link continuam vindo do seu banco ou da sua plataforma de pagamentos.
Idempotência: nunca cobrar duas vezes
Cobrança duplicada é o erro que mais irrita um cliente em dia. Ela costuma nascer de um problema técnico comum: a requisição expira por timeout, o job da sua fila tenta de novo e a mensagem sai duas vezes.
O campo clientRef resolve isso. Ele é o seu identificador daquele envio, com até 200 caracteres. A primeira requisição com um clientRef enfileira a mensagem; uma repetição com o mesmo valor, na mesma conexão, responde 200 com o job original e "duplicate": true, sem enfileirar nada. O clientRef fica reservado por 7 dias.
Monte o valor a partir da fatura e do momento da régua, como fatura-7781-aviso-vencimento, fatura-7781-segunda-via e fatura-7781-pago. Assim, cada etapa sai uma vez só, por mais que o seu job seja reprocessado. Se uma etapa falhar de verdade e você quiser mandar de novo de propósito, use outro valor, como fatura-7781-segunda-via-2. O funcionamento completo está em idempotência com clientRef.
O mesmo clientRef volta nos webhooks message.delivery (com os status sent, delivered, read e failed) e message.send_failed. Com ele, o seu sistema registra na própria fatura que o aviso foi entregue ou lido, e sabe quando um envio não vai acontecer, por exemplo porque o número não está no WhatsApp (not_on_whatsapp). Nesse caso, a régua pode cair para o e-mail.
Ritmo de envio e volume do mês
Cobrança costuma se concentrar em poucos dias do mês, e é aí que o ritmo importa. Cada número tem uma fila anti-bloqueio com limites padrão de 3 mensagens por minuto, 60 por hora e 200 por dia, um intervalo aleatório de 3 a 8 segundos entre envios e pelo menos 30 segundos entre duas mensagens para o mesmo destinatário.
Há também um teto de 100 destinatários novos por 24 horas. Destinatário novo é quem não trocou mensagem com o número nos últimos 28 dias desde o pareamento atual. Um cliente que só recebe uma mensagem por mês pode contar como novo a cada ciclo. Passando do teto, a API responde 429 new_recipient_cap_reached com o cabeçalho Retry-After, e nada é enfileirado: o seu sistema espera e tenta de novo.
Na prática, isso significa planejar a régua para o volume da sua base:
- Comece os avisos alguns dias antes do vencimento, espalhando os envios, em vez de disparar tudo na manhã do dia 10.
- Use
scheduledAteGET /connections/{id}/queuepara acompanhar quando cada mensagem vai sair e quanto do limite do dia já foi usado. - Números recém-conectados passam por um aquecimento de 14 dias com limites menores; não comece uma régua grande num número conectado ontem.
Os planos são cobrados por número, com mensagens ilimitadas dentro desses limites. Os valores estão em preços.
Tom e frequência que evitam denúncias
O WhatsApp restringe números que recebem muitas denúncias, e cobrança é o tipo de mensagem que mais gera irritação quando é mal feita. A fila reduz o risco, mas não garante que um número nunca será restrito. Algumas regras de bom senso:
- Só para quem é cliente e informou o número para esse fim. Lista comprada ou cobrança de dívida cedida para quem nunca falou com você é o caminho mais curto para a denúncia; veja o guia sobre disparo em massa.
- Mensagem curta, com nome, valor, data e o documento. Nada de caixa-alta, ameaça ou linguagem de cobrança agressiva.
- Poucos lembretes. Três mensagens por fatura já é uma régua completa; não repita o aviso todos os dias.
- Horário comercial. Programe a régua para sair em dias úteis, em horário razoável.
- Um canal de resposta. Deixe claro que o cliente pode responder a mensagem; as respostas chegam ao seu sistema pelo webhook
message.incoming, como mostra o caso de atendimento e suporte.
No Brasil, o Código de Defesa do Consumidor (art. 42) proíbe expor o consumidor inadimplente ao ridículo ou submetê-lo a constrangimento ou ameaça na cobrança. Isto não é aconselhamento jurídico: revise a sua régua com quem cuida do jurídico da empresa.
Para outros avisos que o seu sistema manda automaticamente, como alertas de conta e de serviço, veja notificações transacionais. O guia como evitar o bloqueio do número detalha o que faz o WhatsApp restringir um número.
Perguntas frequentes
Posso enviar o boleto em PDF pela API?
Sim. Envie como mídia do tipo document, a partir de uma URL https pública, com mimetype igual a application/pdf, o nome do arquivo e uma legenda. A apiwpp não aceita o arquivo no corpo da requisição: ela baixa o PDF da URL que você informar.
Como evito mandar a mesma cobrança duas vezes?
Envie sempre um clientRef montado com o número da fatura e a etapa da régua. Se o seu sistema repetir a requisição, a API responde com o job original e "duplicate": true, sem enfileirar outra mensagem. A reserva vale por 7 dias.
A apiwpp gera o boleto ou confirma o pagamento?
Não. A apiwpp envia e recebe mensagens de WhatsApp. O boleto, o PIX e a confirmação de pagamento vêm do seu banco ou da sua plataforma de pagamentos; o seu sistema chama a apiwpp quando esses eventos acontecem.
Quantas cobranças consigo enviar por dia com um número?
No padrão, a fila de cada número envia até 200 mensagens por dia, 60 por hora e 3 por minuto, com um teto de 100 destinatários novos a cada 24 horas. Números recém-conectados têm limites menores durante os 14 dias de aquecimento. Planeje a régua para espalhar os envios ao longo dos dias antes do vencimento.
Outros casos de uso
Todos: Casos de uso →Mande pelo WhatsApp os avisos que o seu sistema já gera para quem é cliente (conta, serviço, pedido, alerta), com templates, envios sem duplicidade e a confirmação de entrega e leitura no seu webhook.
Envie confirmação de pedido, boleto ou nota em PDF e código de rastreio no canal que o cliente lê, com templates, clientRef por pedido e status de entrega e leitura no webhook.
Cada mensagem que chega no número da empresa vira um evento no seu sistema: abra o ticket, distribua para a equipe e responda pela API, com texto, mídia, reações e o indicador de digitando.