No atacado não existe cliente anônimo: é o mesmo comprador, comprando quase o mesmo mix, no mesmo intervalo. Com a API do zapon, o seu ERP manda a sugestão de reposição antes de o pedido chegar, recebe a confirmação por webhook amarrada ao código do cliente e avisa crédito, faturamento, carga e vencimento sem o representante repetir status o dia inteiro.
Distribuidora e atacadista vendem para pessoa jurídica: o dono do mercadinho, o comprador da rede de cinco lojas, o encarregado de compras do restaurante. Cada um tem CNPJ, código no sistema, tabela negociada, condição de pagamento e um intervalo de compra que se repete há anos.
Mesmo assim o ciclo recomeça do zero. O representante liga, manda a tabela, espera o pedido em áudio, digita no sistema, confere limite, aguarda o faturamento — e depois passa o dia respondendo "quando chega a carga?" e "cadê a nota?". Uma API de WhatsApp tira essa repetição do humano. O zapon expõe uma API REST direta — header token, JSON entrando e saindo — que o seu ERP chama como chamaria qualquer serviço.
Porque nada do ciclo anterior é reaproveitado. A distribuidora sabe o que aquele CNPJ compra, com que frequência e em que volume, mas o processo ainda começa por uma ligação e termina num áudio que alguém digita à mão. O trabalho não está em vender: está em recomeçar a conversa e retransmitir o que o sistema já sabe.
São três perdas que a operação costuma tratar como uma só:
Porque a resposta está no sistema, mas o caminho até ela passa por gente. O comprador chama o representante, o representante chama a logística, alguém olha a tela, a resposta volta pelo mesmo caminho: quatro trocas de mensagem para transmitir um dado que o ERP já tinha às sete da manhã. Multiplique por trinta clientes na carteira e o vendedor virou painel de consulta.
Quatro coisas: um número que a empresa controle, uma conta no zapon com esse número conectado por QR Code ou código de pareamento, um sistema que saiba o histórico de compra e o status dos pedidos, e um cadastro que ligue cada telefone a um CNPJ e a um papel. Não é preciso servidor próprio, conta na Meta nem aprovação de template.
token diferente, webhook diferente.token da conexão é a credencial de todas as chamadas daquele número. Conecta-se pelo QR Code no painel (WhatsApp → Aparelhos conectados) ou por código de pareamento.Não, e trocar custa caro: a carteira responde para o número que conhece. Mantenha o número do comercial e conecte-o — a automação envia por ele e o que ela não trata fica visível na conversa para o representante responder no próprio aparelho. Use sempre um número da empresa: quando o vendedor sai, a carteira não pode sair junto com o aparelho.
Se faz chamada HTTP, chama a API nos eventos que já dispara. Se é fechado, leia os dados por fora — view no banco, relatório agendado, exportação da posição de pedidos — e dispare dali. A API precisa de telefone e conteúdo; a inteligência de mix, giro e crédito continua no seu sistema.
Sete etapas: (1) o sistema calcula a sugestão de reposição pelo histórico e manda antes de o pedido chegar; (2) o comprador confirma, ajusta ou chama o representante em um toque; (3) o pedido passa pela análise de crédito e o cliente recebe um aviso claro do estado; (4) faturado, ele recebe número da nota, valor, condição e vencimento, com o PDF anexo; (5) a carga é montada e roteirizada, e a data prevista é avisada; (6) na entrega, a divergência de conferência vira ocorrência com prazo; (7) o título vence e o ciclo reabre no intervalo médio daquele cliente.
Cada passo tem um dono diferente dentro da distribuidora — comercial, crédito, faturamento, logística, financeiro. É por isso que ele vaza: a informação troca de setor e ninguém é responsável por contar ao cliente.
O sistema já tem tudo: os últimos pedidos daquele código de cliente, os itens que se repetem, a quantidade média e o intervalo entre compras. A regra mais simples que funciona compara a data de hoje com a última compra; passado o intervalo médio, monta a sugestão com os itens do último pedido. Nada de catálogo inteiro — a sugestão precisa caber na tela e ser reconhecível: "os mesmos 8 itens de 14/08, R$ 4.230,00". É o passo que inverte o jogo: em vez de esperar o pedido, a distribuidora chega antes.
Com botões: repetir o último pedido, ajustar quantidades ou falar com o representante. O id de cada botão é definido por você e volta no webhook — então coloque nele o código do cliente e o número do pedido sugerido. A confirmação chega amarrada ao registro certo, sem interpretar texto e sem depender do telefone, que pode ser o do comprador num dia e o do dono no outro.
Este é o passo que só o B2B tem, e o mais delicado de escrever. O pedido trava por limite, título em aberto ou bloqueio cadastral, e o motivo é assunto comercial — não pode ser despejado numa conversa que talvez esteja aberta no balcão da loja. A mensagem automática diz o estado, não o diagnóstico: "Pedido 8842 recebido e em análise no financeiro." Se travou, o texto convida a falar com quem resolve, e o motivo fica para essa conversa.
Emitida a nota, o cliente precisa de quatro dados: número da nota, valor total, condição de pagamento e vencimento. O PDF vai junto, como documento — o setor de compras arquiva a nota antes de a carga sair e consegue lançar a entrada. Esse envio substitui o e-mail que ninguém abre e a ligação cobrando a nota.
No momento em que a rota fecha, não quando o caminhão sai. O cliente precisa de antecedência para ter alguém no recebimento: mercadinho com um funcionário só não recebe carga a qualquer hora, e restaurante não recebe no meio do almoço. A mensagem traz a data prevista, a janela aproximada e a nota daquela viagem. Se a rota mudar, o mesmo gatilho dispara de novo.
Na doca, duas informações precisam voltar: quem recebeu e se bateu. Volume a menos, embalagem avariada ou item trocado não podem virar discussão na conversa: viram ocorrência com número e prazo, aberta pelo seu sistema no recebimento do evento, com resposta imediata dizendo o protocolo e quando haverá retorno. A foto da avaria chega na mesma conversa e fica anexada à ocorrência.
Duas rotinas de setores diferentes. O financeiro dispara o lembrete de vencimento com número da nota, valor e data — antes do vencimento, porque a função é evitar o esquecimento, não cobrar. E o comercial reabre o ciclo: o cálculo do passo 1 volta a rodar quando o intervalo médio daquele cliente se completa. O representante entra só onde faz diferença: negociar mix, preço e volume.
Quatro cobrem o ciclo: POST /chat/send/buttons para a sugestão com confirmação em um toque, POST /chat/send/text para os avisos de crédito, faturamento, carga e vencimento, POST /chat/send/image para comprovantes digitalizados e POST /user/check para saber quais telefones do cadastro têm WhatsApp. Todos na base https://api.zapon.dev, com o header token. São 49 endpoints publicados — 23 de /chat, 18 de /group e 8 de /user —, mas o ciclo do pedido vive nesses quatro.
A autenticação é um header só, token: não é Authorization, não é Bearer, não há OAuth. Trate-o como senha do cofre — quem tem o token do comercial fala com a carteira inteira em nome da distribuidora.
São três ou quatro botões, de rótulo curto. O que carrega informação é o id, invisível para o cliente: nele vão o código do cliente e o número do pedido sugerido. 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: TOKEN_DO_COMERCIAL { "Phone": "5511999999999", "Body": "Mercado Exemplo, faz 21 dias do último pedido.\n\nSugestão com os mesmos itens de 14/08:\n• Arroz tipo 1, 5kg — 30 fardos\n• Óleo de soja 900ml — 20 caixas\n• Açúcar refinado 1kg — 25 fardos\n\nTotal: R$ 4.230,00 · 28/35/42 dias", "Footer": "Distribuidora Exemplo — Rodrigo, seu representante", "Buttons": [ { "id": "c10432|pd8842|repetir", "text": "Repetir pedido" }, { "id": "c10432|pd8842|ajustar", "text": "Ajustar itens" }, { "id": "c10432|pd8842|falar", "text": "Falar com o rep" } ] }
Repare no rodapé: o nome do representante aparece em toda mensagem automática, e o terceiro botão existe para dar saída humana a quem não quer confirmar nada agora. É o que impede o comprador de sentir que passou a falar com uma máquina.
Um POST em /chat/send/text com dois campos: Phone, em formato internacional só com dígitos, e Body.
curl -X POST https://api.zapon.dev/chat/send/text \ -H "token: TOKEN_DO_FATURAMENTO" \ -H "Content-Type: application/json" \ -d '{ "Phone": "5511999999999", "Body": "Pedido 8842 faturado.\n\nNota fiscal: 154.220\nValor: R$ 4.230,00\nCondição: 28/35/42 dias\nVencimentos: 12/09, 19/09 e 26/09\n\nO PDF da nota segue na próxima mensagem. A previsão de entrega chega assim que a carga for roteirizada." }'
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"
}
}Guarde esse Id na tabela do pedido: é a prova de qual aviso saiu e o que impede a rotina de faturar duas vezes na tela do cliente. São 13 formas de envio ao todo — texto, imagem, áudio, vídeo, documento, sticker, localização, contato, enquete, lista, botões, template e edição de mensagem já enviada —, mais reação, "digitando", marcar como lido e histórico. O documento é o que leva a nota em PDF logo depois do aviso; a lista rende quando a sugestão passa de três opções; a localização ajuda o motorista a achar a doca de um cliente novo.
É o pedido mais comum depois da entrega: o cliente perdeu o canhoto e o financeiro dele precisa do documento para lançar. Com o canhoto digitalizado, /chat/send/image resolve — aceita o arquivo em data URI base64 ou uma URL, e a Caption identifica a nota.
curl -X POST https://api.zapon.dev/chat/send/image \ -H "token: TOKEN_DA_LOGISTICA" \ -H "Content-Type: application/json" \ -d '{ "Phone": "5511999999999", "Image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA…", "Caption": "Canhoto da nota 154.220, entregue em 05/09, recebido por Marcos." }'
Uma rotina agendada varre os clientes cujo intervalo médio venceu, monta a sugestão e chama a API com pausa entre um envio e outro. Três detalhes separam o fluxo que dura do que quebra na primeira semana: pular quem pediu para não receber e quem já tem pedido em aberto, não repetir o que já saiu hoje, e registrar a falha numa lista que alguém olha todo dia.
// reposicao.js — roda dias úteis às 9h const API = "https://api.zapon.dev"; const TOKEN = process.env.ZAPON_TOKEN_COMERCIAL; async function enviarBotoes(phone, sug) { const r = await fetch(`${API}/chat/send/buttons`, { method: "POST", headers: { "token": TOKEN, "Content-Type": "application/json" }, body: JSON.stringify({ Phone: phone, Body: sug.texto, Footer: sug.representante, Buttons: [ { id: `${sug.cliente}|${sug.numero}|repetir`, text: "Repetir pedido" }, { id: `${sug.cliente}|${sug.numero}|ajustar`, text: "Ajustar itens" }, { id: `${sug.cliente}|${sug.numero}|falar`, text: "Falar com o rep" } ] }) }); 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)); for (const cli of await clientesNoIntervaloDeCompra()) { if (cli.optOut || cli.pedidoEmAberto || cli.bloqueado) continue; if (await jaSugeridoHoje(cli.codigo)) continue; // rodar 2x não duplica try { const sug = await montarSugestao(cli.codigo); // último pedido + giro const id = await enviarBotoes(cli.telefoneComprador, sug); await registrarEnvio(cli.codigo, "sugestao", sug.numero, id); } catch (e) { await registrarFalha(cli.codigo, "sugestao", String(e)); // vira tarefa do rep } await pausa(4000); // carteira inteira no mesmo segundo não parece gente }
Cadastro de atacado é antigo: tem telefone fixo da loja, número do dono que saiu da empresa e dígito faltando. O POST /user/check recebe uma lista e diz quais números têm conta — rode antes do primeiro disparo e depois de toda importação de base.
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 o seu webhook: você cadastra no painel a URL do sistema e escolhe os eventos. A partir daí, toda mensagem recebida naquele número chega como 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, com o código do cliente e o número do pedido dentro. Não há polling nem consulta periódica.
O ciclo tem três partes que não se misturam: o webhook entrega o evento, a sua regra interpreta e a ação acontece no ERP. A API não sabe o que é um pedido nem o que é limite de crédito; sabe que uma mensagem chegou naquele número.
O corpo traz o tipo do evento e a mensagem completa. Assim chega quem respondeu "1" em texto, e assim chega quem tocou no botão de repetir o pedido:
{
"type": "Message",
"event": {
"Info": {
"ID": "3EB0C767D26A1B5F7C83",
"Chat": "[email protected]",
"Sender": "[email protected]",
"IsFromMe": false, "IsGroup": false,
"PushName": "Mercado Exemplo",
"Timestamp": "2026-03-11T18:04:22-03:00"
},
"Message": { "conversation": "1" }
}
}
// quando ele toca num botão, muda só o bloco Message:
"Message": { "buttonsResponseMessage": {
"selectedButtonID": "c10432|pd8842|repetir",
"Response": { "SelectedDisplayText": "Repetir pedido" }
} }Duas observações que economizam horas: 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 representante respondendo um cliente aciona a sua automação.
Responda 200 antes de processar, descarte o que não interessa, identifique cliente e pedido pelo id do botão, decida pela intenção e confirme ao comprador o que foi feito — é essa última parte que evita o "mandei e não sei se entrou".
app.post("/whatsapp/comercial", 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 rep envia, e grupos, fora if (await jaProcessado(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 [cod, ped, acao] = botao ? botao.split("|") : []; const cliente = cod ? await clientePorCodigo(cod) : await clientePorTelefone(telefone); if (!cliente) return filaDoRepresentante(telefone, texto); if (acao === "repetir") { const p = await gravarPedido(cliente.codigo, ped); return enviarTexto(telefone, `Pedido ${p.numero} registrado, R$ ${p.total}. Segue para análise no financeiro.`); } if (acao === "ajustar" || acao === "falar") { await avisarRepresentante(cliente, acao); // gente resolve daqui return enviarTexto(telefone, "Certo. O Rodrigo te chama em seguida."); } if (/avaria|faltou|volume a menos|divergência/.test(texto)) { const oc = await abrirOcorrencia(cliente.codigo, texto); return enviarTexto(telefone, `Ocorrência ${oc.numero} aberta. Retorno em até ${oc.prazoHoras}h.`); } return filaDoRepresentante(telefone, texto); // o resto é assunto de gente });
Ele vai escrever muito: "tem o azeite de 500 promocional?", "consigo 42 dias nesse?", "manda o boleto do mês passado". Não tente responder tudo automaticamente — preço e prazo são do representante, e é aí que ele ganha o cliente. O que a regra não reconhece vira pendência numa lista que uma pessoa trata, e a conversa já está no WhatsApp da distribuidora.
Mensagem sobre um pedido que aquele cliente fez — crédito, nota, carga, vencimento — é esperada: existe relação comercial e o telefone foi dado para isso. Sugestão de reposição do mix dele está no mesmo terreno. Já disparo de oferta para base fria, lista comprada ou CNPJ que nunca comprou exige consentimento e um caminho fácil de saída. Misturar as duas coisas no mesmo número é o erro que transforma o canal do comercial num número denunciado.
optOut do exemplo em Node.Depende do assunto, e é por isso que o cadastro precisa de papel, não só de telefone. Sugestão de reposição vai para o comprador; aviso de carga roteirizada vai para quem recebe na doca, que muitas vezes nem trabalha no escritório; lembrete de vencimento vai para quem paga. Mandar tudo para o telefone principal do CNPJ é o mesmo que mandar para ninguém: o dono não confere carga e o conferente não decide compra.
Na prática o cadastro ganha uma tabela simples: CNPJ, telefone, papel (comprador, financeiro, recebimento, decisor) e se aquele número aceita receber. Cada rotina escolhe o papel antes de escolher o texto. Quando um papel não tem telefone, a mensagem cai no comprador com um pedido de repasse — mas isso é remendo; vale pedir o número do conferente na primeira entrega.
Vale, por motivo operacional antes de técnico. Cada conexão é um número com token e webhook próprios: o retorno do comprador cai no sistema do comercial, a divergência de conferência no da logística, a dúvida de boleto no do financeiro. Ninguém filtra mensagem dos outros, e o cliente aprende para qual número escrever o quê.
Não. A API tem 18 endpoints de grupo e eles são úteis na distribuidora — grupo da rota com os motoristas, grupo da equipe de vendas, grupo do armazém. Isso é comunicação interna: saída de carga, mudança de rota, escala. Confirmação de pedido, valor, condição e nota são conversa individual, com registro, porque precisam ficar amarradas a um CNPJ e a um número de pedido. Em grupo não se sabe quem confirmou, e um cliente vê o que o outro escreveu — por isso o receptor do exemplo descarta IsGroup logo na entrada.
Preço negociado fora da tabela, percentual de desconto especial, limite de crédito e motivo de bloqueio. A conversa fica no aparelho dos dois lados e outra pessoa pode ler: o dono vê o desconto que o comprador conseguiu, o comprador de outra loja vê a condição da rede vizinha. Valor total e condição padrão do pedido, sim; a régua comercial que sustenta aquele preço, não.
Ele perde o trabalho de repetir status, que ninguém quer fazer. O desenho todo assume isso: o nome dele no rodapé das mensagens automáticas, um dos três botões só para chamá-lo, e tudo que a regra não reconhece virando tarefa dele. A automação cobre o previsível; o imprevisível, onde a margem se decide, continua com quem sabe negociar.
R$ 27 por mês por número conectado, sem cobrança por mensagem. Comercial, logística e financeiro em conexões separadas custam R$ 81 por mês, e o valor não muda se a operação mandar 200 ou 8.000 mensagens. Cada número tem cota de 300 mensagens por dia — cerca de 9.000 por mês —, limite que impede a operação de virar disparo em massa e derrubar a conexão. 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 o ERP e só depois conectar o número.
Essa previsibilidade é o que torna o ciclo completo viável no atacado: são sete mensagens por pedido, e com cobrança por mensagem o custo cresceria junto com o faturamento até alguém cortar o aviso de carga — justo o que evita a ligação do cliente. O seu sistema escolhe de qual número a mensagem sai trocando um header.
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, 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 um envio falhar, registre numa lista visível — foi o que o registrarFalha fez — e faça alguém olhar essa lista todo dia. Sugestão que não saiu precisa virar tarefa, não silêncio.
Dá, e é o maior ganho desta operação. O seu sistema monta a sugestão com os itens e as quantidades do último pedido daquele código de cliente e envia com botões. O id de cada botão carrega o código do cliente e o número do pedido sugerido, então o toque volta pelo webhook já amarrado ao registro certo.
Se o ERP faz chamada HTTP, ele chama a API nos eventos que já dispara: pedido gravado, crédito liberado, nota emitida, carga roteirizada, título a vencer. Se é fechado, leia os dados por fora, com view no banco ou relatório agendado, e dispare por uma ferramenta de automação. A API só precisa de telefone e conteúdo.
Pode. O aviso vai por POST /chat/send/text, com número da nota, valor, condição de pagamento e vencimentos. O PDF segue em seguida pelo envio de documento, que é uma das 13 formas de envio da API, e chega na mesma conversa em que o pedido foi confirmado.
Diz o estado, nunca o motivo. Algo como "pedido 8842 em análise no financeiro" e um convite para falar com o representante. Limite, título em aberto e bloqueio cadastral são assunto comercial e podem ser lidos por outra pessoa na loja do cliente; o diagnóstico fica para a conversa com quem pode resolver.
Pode, e é o arranjo recomendado. Cada conexão é um número, com token próprio e webhook próprio, então o retorno de cada equipe cai no sistema certo sem filtro. Também separa o risco: se um número cair, os outros continuam operando. São R$ 27 por mês por número conectado.
Não, se o fluxo for desenhado assim. O nome dele aparece no rodapé das mensagens automáticas, um dos três botões existe só para chamá-lo e tudo que a regra não reconhece vira tarefa dele. A automação assume o repetitivo e devolve tempo para negociar mix, preço e volume.
O conferente responde pelo mesmo canal e o seu sistema abre uma ocorrência no recebimento do evento, devolvendo na hora o número do protocolo e o prazo de retorno. A foto da avaria chega na mesma conversa e fica anexada. O objetivo é tirar a divergência da discussão informal.
R$ 27 por mês por número conectado, sem cobrança por mensagem — três números custam R$ 81 por mês, cada um com a sua cota de 300 mensagens por dia (cerca de 9.000 por mês), limite que existe para proteger cada conexão contra bloqueio. 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 escrever a integração antes.
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 mande a primeira sugestão de reposição ainda esta semana.