O escritório já sabe o que falta em cada cliente para fechar a competência. Falta a cobrança sair sozinha. Com a API do zapon, o seu sistema pede o documento no primeiro dia útil, lembra antes do corte, recebe o arquivo do cliente por webhook e dá baixa na pendência — sem ninguém reenviar o mesmo e-mail pela terceira vez.
O trabalho do departamento fiscal não começa quando a competência abre: começa quando o último cliente manda as notas. Enquanto o escritório espera o extrato bancário de um, a folha de outro e as notas de entrada de um terceiro, o fechamento inteiro fica represado em quem entregou por último.
Cobrar documento é um problema de canal. O e-mail some na caixa do cliente; o telefone não liga para duzentas empresas por competência. Uma API de WhatsApp permite que quem cobra seja o sistema que já mantém a lista de pendências, não uma pessoa copiando texto. O zapon expõe uma API REST direta — header token, JSON entrando e saindo — que o seu sistema contábil ou a sua ferramenta de automação chamam por HTTP. A seguir: o ciclo do mês, os endpoints em cURL e Node, o evento que chega quando o cliente devolve o arquivo e o que fazer com ele.
Porque a cobrança chega genérica e sem lista. Uma circular igual para todos não diz ao sócio o que falta na empresa dele, então ele adia. Quando a mensagem nomeia os três itens pendentes daquele CNPJ — notas de saída, extrato bancário e o relatório de ponto —, ela deixa de ser aviso e vira tarefa com começo e fim.
Três sintomas aparecem sempre juntos:
Para prazo curto, sim — a leitura é imediata e a resposta cabe num toque. O e-mail continua sendo o lugar do anexo pesado e do que precisa ficar arquivado formalmente. O arranjo que funciona usa os dois: pacote da competência por e-mail, prazo e devolução rápida pelo WhatsApp.
Três peças: um número de WhatsApp do escritório, uma conexão no zapon com esse número lido por QR Code ou código de pareamento, e alguma fonte que saiba a lista de pendências por cliente na competência aberta. Não é preciso servidor próprio, conta na Meta, aprovação de template nem aplicativo instalado no celular de ninguém.
token, credencial de todas as chamadas daquele número. Separar fiscal e pessoal em dois números significa duas conexões.Não, e trocar costuma piorar: o cliente responde para o número que tem salvo como o do escritório, e o que a automação não trata fica visível na conversa para um analista responder. O que muda é a disciplina interna — quem acessa aquele WhatsApp passa a ver a conversa de todos os clientes.
Dá, desde que os dados saiam de alguma forma: relatório de pendências, exportação, consulta ao banco ou a planilha do próprio departamento. A API precisa de duas informações por envio — telefone e texto. Onde elas nascem é problema seu, não dela.
Cinco etapas: (1) no primeiro dia útil, cada cliente recebe a lista do que falta na empresa dele; (2) o lembrete escalona dentro do mês até o corte interno do escritório; (3) o cliente responde mandando o arquivo, que chega ao seu sistema pelo webhook; (4) o sistema confirma o recebimento citando o nome do arquivo e marca aquele item como entregue; (5) quando a guia ou a folha fica pronta, ela sai em PDF e o envio fica registrado ao lado da obrigação.
Cada etapa tem função distinta — não é a mesma cobrança repetida quatro vezes em tom mais duro.
Ela abre a competência para aquele cliente e é a única do ciclo que enumera: nome da empresa, mês de referência e a lista exata do que falta naquele CNPJ — notas de entrada, notas de saída, extrato bancário, movimento de folha, admissões e rescisões. Uma circular igual para todos economiza cinco minutos de quem escreve e custa uma semana de cobrança depois, porque o cliente que já mandou metade não sabe qual metade ainda falta. A lista sai do sistema, item a item, por cliente.
O escalonamento é interno e previsível: no dia 1 o escritório pede, no dia 3 lembra quem não devolveu nada, no dia 5 avisa que aquele é o corte para entrar no lote da competência. Duas cautelas separam o lembrete útil do lembrete que gera problema. A primeira: o prazo citado é o prazo do escritório, a data interna a partir da qual o departamento não garante o processamento — e o texto precisa dizer isso com essas palavras. A segunda: prazo de órgão público muda, e prazo escrito à mão dentro de um texto envelhece sem ninguém perceber. Se o seu sistema controla a data-limite de uma obrigação acessória, a mensagem lê essa data do registro; se não controla, não cita data de órgão nenhum — fala do corte do escritório e chama o cliente para falar com o responsável.
O cliente responde na própria conversa anexando o documento — a foto da nota, o PDF do extrato, a planilha de ponto. Essa mensagem vira um evento entregue no webhook da conexão, e o bloco Message chega com documentMessage, que traz fileName, mimetype e o caption digitado junto. O receptor registra a entrada, guarda o arquivo onde o escritório arquiva os documentos daquele cliente e marca o item da lista como entregue. É esse passo que transforma cobrança em controle: sem ele, o documento chega ao WhatsApp e a pendência continua aberta.
Porque é a confirmação que encerra o "eu já mandei". Quando a resposta devolve o nome do arquivo recebido, o cliente sabe que chegou e o escritório tem registro. Sem ela, o cliente supõe que chegou, o analista supõe que não veio, e alguém descobre a divergência no dia do fechamento. A confirmação também expõe o erro na hora certa: quem mandou notas de janeiro quando faltava fevereiro lê o nome de volta e corrige no mesmo minuto.
O ciclo fecha na direção contrária: agora é o escritório que entrega. A guia do DAS, o demonstrativo de folha ou o relatório da competência saem em PDF por /chat/send/document, com um texto curto dizendo do que se trata. O identificador devolvido pela API fica guardado ao lado da obrigação, e é ele que responde "vocês mandaram?" com data e hora, em vez de com memória.
Quatro resolvem o ciclo: POST /chat/send/text para a solicitação e os lembretes, POST /chat/send/buttons para a resposta em um toque, POST /chat/send/document para a guia em PDF e POST /user/check para conferir quais telefones do cadastro têm WhatsApp antes do primeiro disparo. Todos usam a base https://api.zapon.dev e o header token. São 49 endpoints publicados — 23 de /chat, 18 de /group e 8 de /user —, mas a cobrança de documento vive nesses quatro.
A autenticação é um header único, token, copiado da conexão no painel: não é Authorization, não é Bearer, não há OAuth. Trate esse valor como senha do escritório — quem o tiver escreve em nome do escritório para a carteira inteira.
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 já montado com a lista daquele cliente.
curl -X POST https://api.zapon.dev/chat/send/text \ -H "token: SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "Phone": "5511999999999", "Body": "Bom dia, Marcelo. Abrimos a competência 02/2026 da Marcenaria Vitória.\n\nFalta chegar até aqui:\n- notas de entrada de fevereiro\n- notas de saída de fevereiro\n- extrato bancário do mês\n- movimento de folha (admissões e rescisões)\n\nPode responder por aqui mesmo, anexando os arquivos. Nosso corte interno é dia 5." }'
A resposta traz o identificador da mensagem no WhatsApp:
{
"code": 200,
"success": true,
"data": {
"Details": "Sent",
"Id": "90B2F8B13FAC8A9CF6B06E99C7834DC5",
"Timestamp": "2026-03-01T09:12:08-03:00"
}
}Grave esse Id junto da pendência: ele prova qual cobrança saiu e impede que a rotina do dia seguinte repita a mesma mensagem.
O padrão é uma rotina agendada de manhã que percorre os clientes com pendência aberta e decide, por cliente, se hoje é dia de pedir, de lembrar ou de não falar nada. Em Node:
// pendencias.js — roda todo dia útil às 8h30 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 pausa = (ms) => new Promise((r) => setTimeout(r, ms)); const diaUtil = await ordinalDoDiaUtil(); // 1, 2, 3… dentro da competência for (const cli of await clientesComPendencia()) { if (cli.optOut || cli.faltantes.length === 0) continue; if (![1, 3, 5].includes(diaUtil)) continue; if (await jaCobradoHoje(cli.id)) continue; // uma cobrança por dia, no máximo const lista = cli.faltantes.map((i) => `- ${i.descricao}`).join("\n"); try { const id = await enviarTexto(cli.responsavel.telefone, `${cli.responsavel.nome}, ainda falta chegar da ${cli.razaoCurta}:\n\n${lista}\n\n` + `Nosso corte interno da competência ${cli.competencia} é dia ${cli.corte}.`); await registrarCobranca(cli.id, diaUtil, id); } catch (e) { await registrarFalha(cli.id, diaUtil, String(e)); // vira tarefa de alguém } await pausa(4000); // a carteira inteira não sai no mesmo segundo }
Quatro detalhes desse laço evitam os problemas clássicos. O faltantes.length impede cobrar quem já entregou tudo — o erro que mais irrita cliente adimplente. O jaCobradoHoje garante que rodar a rotina duas vezes não gera duas mensagens. O registrarFalha transforma envio que não saiu em tarefa visível. E a pausa evita despejar a carteira no mesmo instante, comportamento que não se parece com um escritório trabalhando.
O /chat/send/buttons envia botões de resposta rápida. Cada botão carrega um id definido por você, que volta no webhook quando o cliente toca. Embuta ali o identificador da pendência: a resposta chega amarrada ao registro certo, sem casar telefone nem interpretar texto livre. 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": "Marcelo, ainda faltam as notas de saída e o extrato de fevereiro da Marcenaria Vitória. Como fica?", "Footer": "Departamento fiscal", "Buttons": [ { "id": "cmp2602-4471|enviado", "text": "Já enviei" }, { "id": "cmp2602-4471|hoje", "text": "Envio hoje" }, { "id": "cmp2602-4471|humano", "text": "Falar com vocês" } ] }
O rótulo cabe em poucas palavras, por natureza do WhatsApp. "Já enviei" merece tratamento próprio: em geral significa que o arquivo foi por e-mail ou para outro analista, então a ação certa é abrir uma conferência, não dar baixa no item.
O /chat/send/document recebe o arquivo em Document, como data URI em base64, mais FileName e um Caption opcional. O nome do arquivo é o que o cliente vê e o que ele vai procurar daqui a três meses — escreva-o pensando nisso.
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,JVBERi0xLjQKJc…", "FileName": "guia-das-marcenaria-vitoria-02-2026.pdf", "Caption": "Marcelo, segue a guia da competência 02/2026. A data de pagamento está no próprio documento." }'
Fora desses quatro endpoints, o zapon oferece 13 formas de envio — texto, imagem, áudio, vídeo, documento, sticker, localização, contato, enquete, lista, botões, template e edição de mensagem já enviada —, além de reação, indicador de "digitando", marcação de lido e histórico. Para escritório contábil, a que mais aparece depois do documento é a lista, quando o cliente precisa escolher entre vários itens pendentes.
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. Quando o cliente anexa um arquivo, o bloco Message chega com documentMessage — nome do arquivo, tipo e a legenda que ele digitou. Não existe polling nem caixa para alguém ficar conferindo.
O ciclo tem três partes que não se confundem: o webhook entrega o evento, a sua regra decide a que pendência ele pertence e a ação acontece no seu sistema. A API não sabe o que é uma competência; sabe que chegou uma mensagem com um anexo.
O corpo traz o tipo do evento e a mensagem completa. Assim chega o cliente que respondeu anexando o extrato:
{
"type": "Message",
"event": {
"Info": {
"ID": "3EB0C767D26A1B5F7C83",
"Chat": "[email protected]",
"Sender": "[email protected]",
"IsFromMe": false, "IsGroup": false,
"PushName": "Marcelo Ferraz",
"Timestamp": "2026-03-11T18:04:22-03:00"
},
"Message": { "documentMessage": {
"fileName": "extrato-fevereiro-2026.pdf",
"mimetype": "application/pdf",
"caption": "segue o extrato que faltava"
} }
}
}
// quando ele toca num botão, muda só o bloco Message:
"Message": { "buttonsResponseMessage": {
"selectedButtonID": "cmp2602-4471|hoje",
"Response": { "SelectedDisplayText": "Envio hoje" }
} }Duas observações poupam 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; ignore, ou o analista respondendo pelo aparelho dispara a sua automação.
Descarte o que não interessa, deduplique pelo Info.ID, identifique o cliente pelo telefone, registre o arquivo e responda citando o nome recebido.
app.post("/contabil/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 escritório enviou, fora if (await jaProcessado(info.ID)) return; // o mesmo evento pode chegar 2x const telefone = String(info.Chat || "").split("@")[0]; const cliente = await clientePorTelefone(telefone); if (!cliente) return filaDoAtendimento(telefone, ev); const doc = ev?.Message?.documentMessage; if (doc) { const registro = await arquivarRecebido(cliente.id, { nome: doc.fileName, tipo: doc.mimetype, obs: doc.caption || "" }); await marcarItemEntregue(cliente.id, registro.id); // baixa na lista return enviarTexto(telefone, `Recebemos "${doc.fileName}". Já está com o departamento fiscal.`); } const botao = ev?.Message?.buttonsResponseMessage?.selectedButtonID ?? ""; if (botao) { const [pendencia, acao] = botao.split("|"); if (acao === "hoje") { await adiarCobranca(pendencia, 1); return enviarTexto(telefone, "Combinado. Ficamos no aguardo hoje."); } if (acao === "enviado") { await abrirConferencia(pendencia); // alguém confere, não dá baixa return enviarTexto(telefone, "Vamos conferir e te confirmamos ainda hoje."); } } return filaDoAtendimento(telefone, ev); // o resto é assunto de gente });
Ele vai responder: "esse DAS é o do mês passado?", "posso pagar dia 25?", "meu pró-labore mudou?". Não tente responder isso automaticamente — o que a regra não reconhece vira pendência para um analista. A conversa já está no WhatsApp do escritório, e a pessoa responde no próprio aplicativo; o papel da automação é sinalizar que aquela conversa espera retorno. Em matéria contábil isso vale em dobro: valor, enquadramento e interpretação de regime são resposta de profissional, não de fluxo automático.
Comunicação sobre o serviço contratado — pedir documento, avisar de guia pronta, confirmar recebimento — é esperada: o cliente contratou o escritório e deu o telefone para isso. Divulgação de novo serviço, convite para evento e oferta de consultoria pedem consentimento registrado e descadastro fácil. Misturar as duas coisas no mesmo canal é o que transforma um número de trabalho em número denunciado.
optOut no exemplo em Node. O pedido chega em qualquer redação, então alguém revisa a fila de exceções todo dia.Valor de imposto a pagar, faturamento do cliente, salário de funcionário, senha do certificado digital e qualquer credencial de acesso. A mensagem existe para avisar que há um documento disponível e dizer como acessá-lo — o valor mora dentro do PDF ou do sistema, não na notificação que aparece na tela de bloqueio do celular.
Escreva imaginando que a mensagem será lida por outra pessoa, porque frequentemente será: o celular do sócio fica na mesa e a tela acende com a prévia inteira antes de qualquer senha. "Sua guia da competência 02/2026 está disponível" é seguro. "Sua guia de R$ 14.320 venceu" é o mesmo aviso com um dado a mais que ninguém pediu para expor.
Porque ali o dado não é do seu cliente: é do funcionário dele. Salário, desconto, rescisão, admissão e ponto são dados de terceiros que o escritório trata a serviço do empregador. Isso muda a régua — nada de citar nome de funcionário com valor no corpo da mensagem, nada de mandar demonstrativo para outro contato que não o responsável definido pelo cliente, nada de repassar arquivo de folha para grupo. Para tratar uma rescisão específica, avise que existe um documento e conduza a conversa para onde o escritório já protege esse tipo de arquivo.
Todo mundo que tem acesso ao aparelho conectado. Se o número do fiscal está aberto num tablet da recepção, a recepção lê os documentos de todos os clientes. Vale o cuidado que se dá à senha do sistema contábil: bloqueio de tela, revisão dos aparelhos conectados e desconexão imediata quando alguém deixa a equipe. E o texto que você guardar no seu banco passa a fazer parte do que precisa ser protegido — a disciplina da LGPD aqui é prática: minimizar o que se escreve, registrar consentimento quando o assunto for divulgação e proteger o que se armazena.
R$ 27 por mês por número conectado, sem cobrança por mensagem: o valor não muda se o escritório tem 30 ou 300 clientes na carteira. O que há é uma cota de 300 mensagens por dia por número, folgada para a cobrança de documento do fechamento mensal e útil como freio contra o volume que o WhatsApp interpreta como robô. O teste é de 14 dias sem cartão e a contagem só começa na primeira conexão — dá para criar a conta, escrever a integração com calma e só depois ler o QR Code.
É essa previsibilidade que torna o ciclo viável. A cobrança escalonada gasta três ou quatro mensagens por cliente por competência, mais a confirmação de cada arquivo e a entrega da guia; com cobrança por mensagem, o custo cresceria junto com a carteira até alguém cortar justamente o lembrete que faz o fluxo funcionar. Separando fiscal, pessoal e contábil em números distintos, é uma conexão por número, e o sistema escolhe de qual departamento 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 olhar a tela no dia 5, 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 toda falha de envio deve cair numa lista revisada diariamente — foi o papel do registrarFalha. Cobrança que não saiu precisa virar tarefa, não silêncio descoberto no fechamento.
Funciona sempre que esse sistema conseguir fazer uma chamada HTTP ou exportar a lista de pendências por cliente. Se ele tem área de integrações ou banco acessível, a rotina lê dali e chama a API direto. Se é fechado, use um relatório exportado ou a planilha do departamento como fonte e dispare com uma ferramenta de automação no meio.
Depende de quem responde. Um número só simplifica para o cliente e concentra o histórico, mas mistura fiscal, pessoal e contábil na mesma conversa. Números separados deixam claro com quem o cliente está falando e permitem escalas diferentes por departamento — o custo é uma conexão por número. Escritórios com departamento pessoal grande costumam separar pelo menos esse.
Ela não julga qualidade de imagem. Registre a entrada, marque o item como recebido em conferência e deixe a validação com uma pessoa; quando o analista recusa o arquivo, o sistema devolve uma mensagem pedindo reenvio e dizendo o que ficou ilegível. Vale orientar na abertura da competência que PDF entra melhor do que foto de tela.
Isso é combinado entre escritório e cliente e precisa estar escrito no contrato de honorários ou na comunicação de abertura da competência, não presumido. O que a integração garante é registro: quem enviou, qual arquivo, com que nome e em que horário. Muitos escritórios aceitam o canal e mantêm o arquivamento definitivo no próprio sistema, para onde o receptor copia o documento assim que ele chega.
R$ 27 por mês por número conectado, sem cobrança por mensagem, com cota diária de 300 mensagens por número. Cabe a rotina de pedir nota, avisar prazo e confirmar recebimento de uma carteira inteira, e o teto protege o número do escritório de ser bloqueado em dia de fechamento. O teste é de 14 dias sem cartão e só começa a contar quando você conecta o primeiro número, então dá para desenvolver a integração antes de iniciar a contagem.
Pode — em qualquer API, inclusive na oficial da Meta. O risco não é eliminável, é gerenciável: fale apenas com clientes da carteira, mantenha volume e ritmo compatíveis com o tamanho do escritório 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. Os dois canais fazem coisas diferentes: o e-mail é o lugar do material completo e do que precisa ficar formalmente arquivado; o WhatsApp é onde o prazo é lido no mesmo dia e a devolução acontece em um toque. O arranjo comum é mandar o pacote da competência por e-mail e usar o WhatsApp para a lista do que falta, o lembrete até o corte e a confirmação de recebimento.
Essa resposta não é reconhecida pela regra automática e vai para a fila de atendimento, com a conversa visível para o analista responsável. É intencional: valor de tributo, enquadramento e data de pagamento dependem de conferência e são resposta de profissional. A automação sinaliza que aquela conversa espera retorno; quem responde é gente.
14 dias grátis, sem cartão — a contagem só começa quando você conectar o número. Crie a conta, ligue a lista de pendências na API e mande a primeira solicitação da competência hoje.