Numa assinatura, quase nenhuma perda começa com uma decisão: começa com um cartão vencido que ninguém percebeu. Com a API do zapon, o seu sistema avisa a cobrança recusada no mesmo dia, anuncia a renovação antes de ela acontecer, oferece pausa como alternativa honesta ao cancelamento e facilita a retomada — recebendo cada resposta por webhook.
Quem opera recorrência sabe que existem dois tipos de saída. A voluntária, quando a pessoa decide que não quer mais — e essa merece respeito, não obstáculo. E a involuntária, quando a cobrança falha por cartão vencido, limite indisponível ou banco que negou a transação, e o assinante nem fica sabendo. A segunda é a maior parte do volume, e é inteiramente evitável com um aviso escrito no dia certo.
É esse aviso que uma API de WhatsApp torna barato. O zapon expõe uma API REST direta — header token, JSON entrando e saindo — que o seu sistema de assinaturas chama quando um evento de cobrança acontece, como chamaria qualquer serviço. A seguir: os quatro momentos da recorrência, os endpoints em cURL e Node, o evento que chega quando o assinante responde e uma regra que atravessa a página inteira — nada aqui serve para dificultar a saída de ninguém.
Porque o cartão que paga a recorrência é justamente aquele que a pessoa não olha. Ele vence, é reemitido por perda ou fraude, muda de número — e a cobrança do mês seguinte é recusada sem que ninguém do outro lado perceba. O assinante só descobre quando a caixa não chega ou quando o acesso trava, e a essa altura ele já teve a experiência ruim antes de ter a chance de resolver.
São quatro momentos onde a recorrência vaza, cada um com uma resposta diferente:
Porque ele compete com dezenas de mensagens automáticas na mesma caixa e costuma parar em promoções — sem contar que muito assinante nem lembra qual e-mail usou para assinar. A mensagem no aparelho é lida, e o assunto é objetivamente útil para quem recebe: sem ela, a pessoa perde o serviço por um motivo que levaria dois minutos para resolver. É o raro caso em que o aviso do fornecedor é um favor ao cliente.
Três peças: um número de WhatsApp do clube, uma conexão no zapon com esse número lido por QR Code ou código de pareamento, e um sistema de assinaturas que dispare um evento quando a cobrança falha, quando o ciclo está para renovar e quando o assinante muda de situação. Não é preciso servidor próprio, conta na Meta, aprovação de template nem aplicativo instalado em aparelho nenhum.
token, credencial de todas as chamadas daquele número. Operação com mais de uma marca costuma manter uma conexão para cada, com webhooks separados.Serve, e o desenho muda pouco. Academia, software, mensalidade de curso, manutenção mensal e clube de produto físico compartilham o mesmo esqueleto: um ciclo, uma cobrança, uma entrega e uma saída. O que muda é o que a mensagem cita — o número da caixa do mês num clube, a data de corte do acesso num serviço digital, a próxima visita numa manutenção.
Cinco etapas: (1) a cobrança recusada gera aviso no mesmo dia, com o motivo em linguagem simples e o caminho para atualizar o pagamento na área do assinante; (2) alguns dias antes da renovação, um aviso informa a data, o valor e como cancelar antes; (3) quem sinaliza saída recebe a pausa como uma alternativa oferecida uma única vez, ao lado do cancelamento imediato; (4) quem pausou recebe um aviso simples quando o período acaba; (5) toda resposta volta por webhook e muda a situação da assinatura no seu sistema.
Comece pelo primeiro. O aviso de cobrança recusada é o único dos quatro que devolve receita já na primeira semana e que o assinante agradece.
No mesmo dia da tentativa, com três informações e nada mais: que a cobrança do ciclo não passou, o que costuma causar isso (cartão vencido, limite indisponível, dados desatualizados) e onde atualizar o meio de pagamento — a área do assinante, acessada pelo caminho de sempre. Diga também até quando o serviço continua disponível, para que a pessoa saiba quanto tempo tem.
Uma regra inegociável: a mensagem nunca pede número de cartão, código de segurança ou dado bancário, e nunca oferece um link de pagamento que não seja o mesmo endereço que o assinante já conhece. Cobrança por mensagem é o formato preferido de quem aplica golpe; um clube que segue esse roteiro treina o próprio cliente a cair no golpe do próximo. Escreva uma frase fixa dizendo que dados de pagamento só são atualizados dentro da conta.
Sobre insistência: duas mensagens no ciclo bastam — a do dia da falha e uma antes do encerramento. Uma cobrança recusada não vira paga porque o clube mandou seis lembretes; vira bloqueio de número.
Este aviso assusta quem opera assinatura, e não deveria. Ele diz: "sua assinatura renova em 12/04, no valor combinado, e a caixa de abril sai no dia 15". Quem estava satisfeito não faz nada e fica satisfeito por saber. Quem tinha esquecido não é cobrado de surpresa — e uma cobrança surpresa é o que produz contestação junto ao banco, avaliação ruim e o pior tipo de saída, aquela com ressentimento.
Em assinatura anual ou semestral, o aviso prévio é ainda mais importante, porque o valor é maior e o intervalo desde a última cobrança é longo. Informe a data, o valor, o que acontece se nada for feito e onde cancelar caso a pessoa queira. Escrever "onde cancelar" no mesmo aviso é o que separa transparência de aviso decorativo.
A pausa é útil porque muita saída é temporária. Ela vira armadilha quando substitui o cancelamento. A regra que resolve isso é uma só: a pausa e o cancelamento aparecem lado a lado, na mesma mensagem, com o mesmo destaque — e o cancelamento é executado na hora, sem etapa extra, sem ligação, sem "um consultor vai falar com você".
Os três botões que cumprem isso: Pausar 1 mês, Cancelar e Falar com alguém. Quem toca em cancelar tem a assinatura encerrada e recebe a confirmação por escrito, com a data do encerramento e o que acontece com o que já foi pago. Nada de perguntar "tem certeza?" três vezes, nada de contra-oferta automática, nada de desconto de última hora que a pessoa não pediu — e a pausa é oferecida uma vez, não a cada tentativa de sair.
Perto do fim do período de pausa, uma mensagem informativa: a pausa termina em tal data e a assinatura volta a ser cobrada a partir dali; se a pessoa preferir, pode estender ou encerrar. Isso é o oposto de reativar alguém sem avisar — e é o que evita a cobrança surpresa depois de meses sem uso.
Para quem cancelou de vez, o convite de retorno tem regras próprias: só com consentimento para receber esse tipo de mensagem, com um motivo verdadeiro (a nova temporada do clube, o produto que a pessoa tinha pedido), uma única tentativa e a saída explícita no texto. Quem cancelou e não respondeu ao convite não recebe um segundo.
O webhook entrega, a sua regra interpreta e a ação acontece no seu sistema de assinaturas: a pausa é registrada com data de início e fim, o cancelamento é efetivado imediatamente, o pedido de contato vira tarefa nominal e o descadastro grava um campo que todas as rotinas consultam. O que a regra não reconhecer vira pendência com telefone, número da assinatura e o texto do assinante.
Quatro dão conta: POST /chat/send/text para os avisos, POST /chat/send/buttons para pausa, cancelamento e contato, POST /chat/send/document para comprovantes e notas em PDF, e POST /user/check para conferir quais telefones da base de assinantes têm WhatsApp. Todos na base https://api.zapon.dev, com o header token. São 49 endpoints publicados, todos com schema — a recorrência vive nesses quatro.
A autenticação é um header só, token, copiado da conexão no painel: não é Authorization, não é Bearer, não há OAuth. Trate como credencial de sistema — quem tem o token escreve em nome do clube.
Um POST em /chat/send/text com dois campos obrigatórios: Phone, o número em formato internacional só com dígitos, e Body, o texto.
curl -X POST https://api.zapon.dev/chat/send/text \ -H "token: SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "Phone": "5511999999999", "Body": "Oi, Bruna. A cobrança da sua assinatura deste mês não passou no cartão cadastrado.\n\nNa maioria das vezes é cartão vencido ou limite indisponível no momento da tentativa.\n\nPara resolver, atualize o cartão na área do assinante, no mesmo endereço de sempre. Sua assinatura segue ativa até 18/04.\n\nNunca pedimos número de cartão por mensagem: a atualização é feita dentro da sua conta." }'
A resposta traz o identificador da mensagem dentro do WhatsApp:
{
"code": 200,
"success": true,
"data": {
"Details": "Sent",
"Id": "90B2F8B13FAC8A9CF6B06E99C7834DC5",
"Timestamp": "2026-04-11T10:05:33-03:00"
}
}Guarde esse Id junto do ciclo de cobrança. Ele prova qual aviso saiu e quando, e impede que uma nova tentativa de cobrança no mesmo dia dispare a segunda mensagem idêntica — o erro que transforma um aviso útil em incômodo.
O /chat/send/buttons envia botões de resposta rápida, com rótulo curto — o WhatsApp corta texto longo, então até vinte caracteres é a regra prática. Cada botão carrega um id definido por você: coloque o número da assinatura ali dentro e a resposta volta amarrada ao registro certo. Além da resposta rápida, o mesmo endpoint monta botão que abre um link ("type": "cta_url"), botão que abre o discador ("type": "cta_call") e botão que copia um código ("type": "copy") — e os tipos convivem na mesma mensagem. O toque em resposta rápida volta no webhook; os outros três agem no aparelho de quem recebe.
POST https://api.zapon.dev/chat/send/buttons token: SEU_TOKEN { "Phone": "5511999999999", "Body": "Bruna, entendi que você quer interromper a assinatura 5512.\n\nSe for algo passageiro, dá para pausar por um mês e voltar depois. Se preferir encerrar agora, também resolvo por aqui — sem etapa extra.", "Footer": "Clube Exemplo", "Buttons": [ { "id": "as5512|pausar", "text": "Pausar 1 mês" }, { "id": "as5512|cancelar", "text": "Cancelar" }, { "id": "as5512|falar", "text": "Falar com alguém" } ] }
Repare na ordem e no peso: cancelar não está escondido atrás de "outras opções", não exige justificativa e não vem seguido de contra-oferta. É a diferença entre oferecer uma alternativa e criar um labirinto — e a segunda opção custa caro em reputação, além de gerar a pior espécie de assinante, o que fica sem querer.
O /chat/send/document recebe o arquivo em data URI base64, o nome com que ele aparece na conversa e uma legenda opcional. Nome de arquivo é parte da mensagem: recibo-assinatura-abril-2026.pdf se explica sozinho meses depois; documento.pdf não.
curl -X POST https://api.zapon.dev/chat/send/document \ -H "token: SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "Phone": "5511999999999", "Document": "data:application/pdf;base64,JVBERi0xLjQKJcfs…", "FileName": "recibo-assinatura-abril-2026.pdf", "Caption": "Recibo do ciclo de abril da assinatura 5512. O próximo ciclo renova em 12/05, e você pode pausar ou cancelar na área do assinante quando quiser." }'
O padrão é uma rotina agendada que roda uma vez por dia, busca os ciclos que renovam dali a alguns dias e chama a API. Em Node:
// renovacoes.js — roda todo dia às 10h const API = "https://api.zapon.dev"; const TOKEN = process.env.ZAPON_TOKEN; async function enviarTexto(phone, body) { const r = await fetch(`${API}/chat/send/text`, { method: "POST", headers: { "token": TOKEN, "Content-Type": "application/json" }, body: JSON.stringify({ Phone: phone, Body: body }) }); const json = await r.json(); if (!r.ok || !json.success) throw new Error(json.error || `HTTP ${r.status}`); return json.data.Id; } const intervalo = (ms) => new Promise((r) => setTimeout(r, ms)); for (const a of await assinaturasQueRenovamEm(3)) { if (a.situacao !== "ativa") continue; // pausada ou cancelada: fora if (a.assinante.semAvisos || a.avisoCiclo) continue; // um aviso por ciclo try { const id = await enviarTexto(a.assinante.telefone, `${a.assinante.nome}, sua assinatura ${a.numero} renova em ${a.dataRenovacao}, ` + `no valor de ${a.valorFormatado}.\n\n` + `Não precisa fazer nada para continuar. Se quiser pausar ou cancelar antes disso, ` + `é na área do assinante, em Minha assinatura — ou responda por aqui que eu resolvo.`); await marcarAviso(a.numero, a.cicloAtual, id); } catch (e) { await registrarFalha(a.numero, "aviso_renovacao", String(e)); // vira tarefa do suporte } await intervalo(4000); // a base inteira no mesmo segundo não parece gente }
Três detalhes desse laço importam. Os continue impedem aviso de assinatura pausada e de quem pediu para não receber mensagem. O marcarAviso amarra o aviso ao ciclo, então rodar a rotina duas vezes não duplica a mensagem. E o intervalo entre envios mantém um ritmo compatível com uma operação de verdade.
Base de assinatura antiga guarda telefone digitado errado no cadastro e número que a pessoa trocou desde então. O POST /user/check recebe uma lista e diz quais têm conta no WhatsApp — serve para saber quem precisa ser avisado por outro canal quando a cobrança falhar.
curl -X POST https://api.zapon.dev/user/check \ -H "token: SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "Phone": ["5511999999999", "5511888888888"] }' // resposta { "code": 200, "success": true, "data": { "Users": [ { "Query": "5511999999999", "IsInWhatsapp": true, "JID": "[email protected]" }, { "Query": "5511888888888", "IsInWhatsapp": false, "JID": "" } ] } }
Cada conexão tem um webhook próprio: você cadastra no painel a URL do seu sistema e escolhe os eventos. A partir daí, toda mensagem recebida naquele número vira um POST nessa URL, com o conteúdo inteiro no corpo — telefone, identificador, horário, texto e, quando é resposta de botão, o id que você definiu. É assim que "pausar por um mês" vira uma pausa registrada, com data de início e de fim, sem ninguém abrir o painel.
São três partes que não se confundem: o webhook entrega o evento, a sua regra interpreta e a ação acontece no seu sistema. A API não sabe o que é ciclo nem o que é pausa; sabe que uma mensagem chegou naquele número.
O corpo traz o tipo do evento e a mensagem completa. Assim chega quem escreveu "quero cancelar":
{
"type": "Message",
"event": {
"Info": {
"ID": "3EB0C767D26A1B5F7C83",
"Chat": "[email protected]",
"Sender": "[email protected]",
"IsFromMe": false, "IsGroup": false,
"PushName": "Bruna Tavares",
"Timestamp": "2026-04-11T19:27:14-03:00"
},
"Message": { "conversation": "quero cancelar" }
}
}
// tocando num botão, muda só o bloco Message:
"Message": { "buttonsResponseMessage": {
"selectedButtonID": "as5512|pausar",
"Response": { "SelectedDisplayText": "Pausar 1 mês" }
} }Duas observações economizam horas de depuração. O corpo pode chegar como JSON puro ou como formulário codificado com o JSON dentro de um campo — aceite os dois. E o que o próprio número envia também gera evento, com IsFromMe igual a true: se não ignorar, o suporte respondendo um assinante no aparelho aciona a sua automação.
Descarte o que não interessa, encontre a assinatura, execute o que a pessoa pediu — inclusive o cancelamento — e confirme por escrito o que foi feito.
app.post("/zapon/eventos", express.json(), async (req, res) => { res.sendStatus(200); // responda primeiro, processe depois const ev = req.body?.event ?? req.body, info = ev?.Info ?? {}; if (info.IsFromMe || info.IsGroup) return; // o que o clube enviou, e grupos, fora if (await jaTratado(info.ID)) return; // o mesmo evento pode chegar 2x const telefone = String(info.Chat || "").split("@")[0]; const botao = ev?.Message?.buttonsResponseMessage?.selectedButtonID ?? ""; const texto = (ev?.Message?.conversation ?? ev?.Message?.extendedTextMessage?.text ?? "").trim().toLowerCase(); const ass = botao ? await buscarAssinatura(botao.split("|")[0].replace("as", "")) : await assinaturaPorTelefone(telefone); if (!ass) return filaDoSuporte(telefone, texto); const acao = botao ? botao.split("|")[1] : /^(cancelar|quero cancelar|nao quero mais)$/.test(texto) ? "cancelar" : /^(pausar|quero pausar)$/.test(texto) ? "pausar" : null; if (acao === "cancelar") { const fim = await cancelarAgora(ass.id); // executa; nada de "tem certeza?" return enviarTexto(telefone, `Assinatura cancelada. Você tem acesso até ${fim}, e não haverá nova cobrança.`); } if (acao === "pausar") { const volta = await pausarPorUmMes(ass.id); return enviarTexto(telefone, `Pausado. Nada é cobrado até ${volta}, e aviso alguns dias antes de voltar.`); } if (acao === "falar") { await abrirTicket(ass.id, "contato pedido pelo assinante"); return enviarTexto(telefone, "Certo, alguém do suporte fala com você hoje."); } return filaDoSuporte(telefone, texto); // o resto é assunto de gente });
A linha do cancelarAgora é a mais importante da página. Cancelamento pedido por escrito é cancelamento executado — não é abertura de negociação, não é encaminhamento para uma equipe de retenção e não é motivo para deixar de responder.
Ele vai escrever — "a caixa de março não chegou", "veio quebrado", "não era isso que eu escolhi". Nada disso deve virar resposta automática: cada caso depende do que aconteceu no envio, e resposta genérica em reclamação piora o problema. Essas mensagens viram pendência nominal do suporte, com telefone, número da assinatura e o texto original. O papel da automação é apontar a conversa que espera uma pessoa.
Seguindo quatro regras: o cancelamento aparece na mesma mensagem que a pausa, com o mesmo destaque; ele é executado imediatamente, sem etapa adicional; a pausa é oferecida uma única vez, não a cada tentativa de saída; e nenhuma mensagem usa culpa, urgência falsa ou desconto surpresa para demover a pessoa. Se sair for mais difícil do que entrar, o desenho está errado.
Vale listar o que não entra em nenhuma das mensagens deste fluxo, por mais que a métrica do mês peça:
semAvisos do exemplo, e revise a fila de exceções todo dia.R$ 27 por mês por número conectado, sem cobrança por mensagem: o valor não muda entre 200 e 6.000 mensagens no mês. O que existe é uma cota de 300 mensagens por dia por número — espaço de sobra para a régua de renovação de um clube e uma trava que impede o pico de disparos que faz o WhatsApp derrubar o número. O teste é de 14 dias sem cartão e só começa a contar na primeira conexão — dá para criar a conta, ligar os eventos do seu sistema de assinaturas com calma e conectar o número quando a rotina estiver pronta.
Em recorrência, essa previsibilidade tem um efeito direto no desenho do fluxo: nenhum aviso precisa ser cortado por custo unitário. Se cada mensagem tivesse preço, o primeiro corte seria o aviso prévio de renovação — o que menos "converte" e o que mais evita contestação e reclamação pública. Com valor fixo por número, a decisão volta a ser o que é melhor para o assinante. Com mais de uma marca, é uma conexão para cada, e o seu sistema escolhe de qual número a mensagem sai trocando o header token.
O painel mostra o estado de cada conexão e atualiza a cada 10 segundos enquanto a página está aberta. Para não depender de alguém olhando a tela, assine os eventos de conexão no webhook: Disconnected avisa a queda e LoggedOut avisa que o número precisa reler o QR Code. E quando uma chamada de envio falhar, registre numa lista visível — foi o papel do registrarFalha — e faça alguém conferir essa lista todo dia. Aviso de cobrança recusada que não saiu vira assinatura perdida sem que ninguém tenha decidido nada.
Funciona sempre que esse sistema conseguir chamar uma URL quando um evento de cobrança acontece, ou expor esses eventos de alguma forma. Falha na tentativa, renovação próxima, pausa e cancelamento são os gatilhos; a partir deles, uma rotina sua monta o texto e chama a API. Se o sistema é fechado, leia os dados por relatório e dispare com uma ferramenta de automação no meio.
Duas, no máximo: no dia da falha e uma antes do encerramento do acesso. Cobrança recusada quase sempre é problema técnico do cartão, e quem quer resolver resolve com um aviso. Repetir seis vezes não recupera pagamento — gera bloqueio do número e denúncia.
Nunca. Nem número, nem código de segurança, nem validade, nem dado bancário. A atualização acontece dentro da conta do assinante, no endereço que ele já conhece, e a mensagem deve dizer isso explicitamente. Pedir dado de pagamento por mensagem é o roteiro do golpe e treina o cliente a cair no próximo.
Aumenta o cancelamento consciente e reduz a cobrança contestada, a reclamação pública e o assinante que fica insatisfeito porque foi cobrado de surpresa. Quem cancela ao ser avisado ia cancelar de qualquer forma, e provavelmente com mais atrito. Transparência também é o que faz alguém voltar depois.
Colocando os dois na mesma mensagem, com o mesmo destaque, e executando o cancelamento na hora em que ele é pedido — sem confirmação repetida, sem exigir ligação, sem contra-oferta automática. A pausa é oferecida uma única vez; se a pessoa preferir sair, ela sai e recebe a confirmação por escrito.
R$ 27 por mês por número conectado, sem cobrança por mensagem. Cada número envia até 300 mensagens por dia, cota pensada para caber a régua de renovação e de cartão recusado de um clube inteiro sem expor o número ao bloqueio por volume. O teste é de 14 dias sem cartão e só começa a contar quando você conecta o primeiro número.
Pode — em qualquer API, inclusive na oficial da Meta. O risco não é eliminável, é gerenciável: fale de contratos que a pessoa tem, mantenha a régua curta, não misture aviso de cobrança com divulgação e pare de enviar para quem pediu para sair. O que dispara bloqueio é mensagem não solicitada em massa, não o uso de API.
Não. O número é conectado por QR Code ou código de pareamento, sem fila de aprovação, sem cadastro de template e sem custo por mensagem. Em compensação, a boa conduta do número é responsabilidade do clube.
14 dias grátis, sem cartão — a contagem só começa quando você conectar o número. Crie a conta, leia o QR Code e avise a primeira cobrança recusada hoje.