Pular para o conteúdo
apiwpp
Caso de uso

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:

MomentoMensagemAnexo
Alguns dias antes do vencimentoAviso de que o boleto vence em tal data, com o valorBoleto em PDF ou link de pagamento
No dia do vencimentoLembrete curto, com o código ou o linkOpcional
Depois do vencimentoOferta de segunda via, com a nova dataNovo boleto em PDF
Pagamento confirmadoAgradecimento e confirmaçãoRecibo, 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.

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:

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:

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.

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.

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.