A sua loja sabe, no instante exato, quando o pagamento foi aprovado e quando o pacote foi postado. Com a API do zapon, essa mudança de status vira uma mensagem no WhatsApp do cliente sem ninguém digitar — e a resposta dele volta por webhook, amarrada ao número do pedido.
Toda loja que cresce esbarra na mesma parede: o time para de vender e passa o dia respondendo "cadê meu pedido?". A informação existe — está no status do pagamento e no código de rastreio —, mas nunca chegou a quem comprou. Somam-se o carrinho abandonado, a compra que travou no meio do checkout, e o rastreio mandado por e-mail, que ninguém abre.
Uma API de WhatsApp inverte a direção: em vez de esperar a pergunta, a loja avisa. O zapon expõe uma API REST simples — header token, JSON entrando e saindo — que o back-end da loja chama quando o pedido muda de estado. Abaixo: os seis avisos do fluxo, os endpoints em cURL e Node, a armadilha da idempotência e a fronteira entre aviso transacional e marketing.
Porque entre pagar e receber existem cinco ou seis dias de silêncio, e silêncio depois de gastar dinheiro gera ansiedade. Ele não pergunta por chateação: pergunta porque não tem onde olhar. Cada aviso enviado no instante em que o status muda apaga uma dessas perguntas antes de ela nascer, e o que sobra na caixa de entrada passa a ser dúvida real.
Porque ele compete com promoções e boletos numa caixa que o cliente abre uma vez por dia, se abrir. O rastreio é a informação mais aguardada da compra e a que menos chega. E quando a entrega falha — endereço incompleto, ninguém no local —, descobrir no mesmo dia ou uma semana depois é a diferença entre resolver e receber o pacote de volta.
Três coisas: um número de WhatsApp da loja, uma conta no zapon com esse número conectado por QR Code ou código de pareamento, e um ponto no back-end que perceba a mudança de status do pedido. Não é preciso servidor dedicado, conta na Meta, aprovação de template nem aplicativo instalado num celular na loja.
token, credencial de todas as chamadas daquele número.É a diferença entre uma loja e uma agenda. Uma agenda pode varrer o dia seguinte às 18h. Um pedido não: o pagamento é aprovado às 3h da manhã, a nota sai às 11h47, a coleta acontece às 16h. Aviso que só sai na varredura da meia-noite chega velho, e aviso velho não elimina a pergunta. E nunca coloque a chamada ao WhatsApp no mesmo bloco que fecha a venda — se a mensagem falhar, o pedido não pode falhar junto. Enfileire.
Se ela tem notificação por webhook ou área de integrações, o gatilho já existe: aponte para o seu endpoint. Se é fechada e não notifica nada, sobra ler o estado por fora — consultar a API dela em intervalos curtos — e disparar a partir da diferença. É pior, mas funciona.
Seis avisos, cada um amarrado a uma mudança de estado: (1) pedido recebido, (2) pagamento aprovado, recusado ou pendente, (3) pedido separado e nota emitida, (4) enviado com código de rastreio, (5) saiu para entrega e entregue, (6) pós-venda. Cada um sai no instante em que o back-end registra a mudança, e o número do pedido viaja em todos eles.
Não é a mesma mensagem seis vezes: cada aviso responde a uma pergunta diferente, e só um deles pede ação.
A primeira mensagem confirma que a compra existe. Conteúdo mínimo: número do pedido, itens com quantidade, valor total, forma de pagamento e o que acontece a seguir. Esse último item é o que mais economiza atendimento — dizer "assim que o pagamento for aprovado, você recebe o aviso aqui" transforma a espera em algo previsto. Se a entrega falhar já aqui, você descobre hoje que o telefone do checkout está errado.
Este aviso muda a expectativa do cliente, e os três desfechos pedem textos distintos. Aprovado é curto: entrou na fila de separação e o prazo passou a contar. Pendente explica a espera pela compensação e o prazo dela. Recusado é o único dos seis que pede ação, e por isso o único que aponta um caminho para refazer o pagamento na própria loja. Nunca colete dados de cartão pela conversa nem mande link de pagamento fora do domínio da loja.
É o aviso que prova movimento: saiu do estoque e ganhou número de nota fiscal. Aqui existe um detalhe que vale a mensagem inteira — é a partir deste ponto que a loja não consegue mais alterar o endereço. Diga isso com todas as letras, junto do que fazer se o endereço estiver errado. Uma frase aqui evita a devolução que apareceria dez dias depois com frete pago duas vezes.
É o aviso que substitui o e-mail não lido e o mais aguardado de todos. Mande o código em linha própria, para o cliente copiar com um toque, e diga onde acompanhar e em quanto tempo o primeiro registro costuma aparecer — código recém-postado que ainda não consta gera exatamente a pergunta que você queria evitar. É também o ponto de enviar a imagem do comprovante de postagem.
Dois avisos curtos com funções distintas. O de saiu para entrega é logístico: alguém precisa estar no endereço hoje. O de entregue encerra o ciclo e desarma a dúvida de quem não estava em casa. A exceção é a entrega frustrada — ausente, endereço não localizado, recusa: esse estado não pode virar só mensagem automática, precisa gerar tarefa humana na loja.
Dias após a entrega, uma mensagem curta pede avaliação do produto e da experiência. Ainda é assunto da compra que a pessoa fez, então continua no terreno transacional. O retorno do carrinho abandonado é outra coisa: abordagem comercial para quem não comprou, tratada como fluxo próprio, com consentimento coletado no checkout. É a fronteira mais importante desta página, e ela tem uma seção só para si.
Quatro resolvem o fluxo inteiro: POST /chat/send/text para os avisos de status, POST /chat/send/image para a foto do produto ou o comprovante de postagem, POST /chat/send/buttons para rastrear, trocar ou chamar o atendimento em um toque, e POST /user/check para validar o telefone do checkout. São 49 endpoints publicados — 23 de /chat, 18 de /group e 8 de /user —, mas a operação de uma loja 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-o como senha da loja.
Um POST em /chat/send/text com dois campos: 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": "Loja Exemplo - pedido 10482 recebido.\n\n2x Camiseta linho areia (M)\n1x Bermuda sarja azul (42)\nTotal: R$ 289,90 - PIX\n\nAssim que o pagamento for aprovado, avisamos por aqui. O prazo de entrega comeca a contar a partir da aprovacao." }'
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 na linha do pedido, junto do status que motivou o envio. É esse par que impede a duplicata do próximo tópico.
Esta é a armadilha específica do e-commerce. A sua plataforma pode registrar o mesmo status mais de uma vez: reentrega de webhook, reprocessamento do gateway, operador que reabre e salva o pedido, retentativa depois de um tempo esgotado. Se o código envia toda vez que ouve o evento, o cliente recebe "pagamento aprovado" três vezes — e isso não parece atenção, parece defeito.
A solução é uma chave única de pedido + status: antes de enviar, registre a intenção; se o registro já existir, não envie.
// avisos.js — chamado pelo back-end da loja quando o pedido muda de estado 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 TEXTOS = { pago: (p) => `Pedido ${p.numero}: pagamento aprovado. Ja estamos separando.`, faturado: (p) => `Pedido ${p.numero}: nota emitida. A partir de agora o endereco nao pode mais ser alterado.`, enviado: (p) => `Pedido ${p.numero} enviado.\n\nCodigo de rastreio:\n${p.rastreio}`, entregue: (p) => `Pedido ${p.numero} entregue. Qualquer coisa, e so responder por aqui.` }; async function avisarStatus(pedido) { const montar = TEXTOS[pedido.status]; if (!montar) return; // status que nao vira mensagem if (pedido.cliente.optOut) return; // pediu para nao receber const chave = `${pedido.numero}:${pedido.status}`; // pedido + status = uma vez so if (!await reservarEnvio(chave)) return; // insercao unica; false = ja saiu try { const id = await enviarTexto(pedido.cliente.telefone, montar(pedido)); await confirmarEnvio(chave, id); // guarda o Id da mensagem } catch (e) { await liberarReserva(chave); // permite nova tentativa await filaDeFalhas(pedido.numero, pedido.status, String(e)); } await pausa(4000); // no faturamento em lote, nao dispare tudo no mesmo segundo }
Três detalhes separam a integração que dura da que quebra. O reservarEnvio é uma inserção com restrição de unicidade na chave pedido:status: evento repetido não envia de novo. O liberarReserva impede que uma falha de rede queime a única chance de avisar. E a pausa importa porque no e-commerce o disparo vem em rajada: o faturamento de fim de dia emite cem notas em um minuto, e cem mensagens no mesmo segundo não se parecem com uma loja atendendo.
O POST /chat/send/image aceita Image como URL pública ou data URI em base64, e um Caption. Duas aplicações rendem: a miniatura do produto na confirmação, que reduz o "comprei a cor certa?", e o comprovante de postagem no aviso de envio.
curl -X POST https://api.zapon.dev/chat/send/image \ -H "token: SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "Phone": "5511999999999", "Image": "https://cdn.lojaexemplo.com.br/postagem/10482.jpg", "Caption": "Pedido 10482 postado hoje. Rastreio: XX123456789BR" }'
O POST /chat/send/buttons envia botões de resposta rápida, com texto de até 20 caracteres. Cada botão carrega um id definido por você, e é ele que volta no webhook. Coloque o número do pedido dentro desse id: a resposta chega amarrada ao registro certo, sem depender de casar telefone com pedido — o que quebra assim que a mesma pessoa tem dois pedidos abertos, situação corriqueira em loja com recompra. 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": "Pedido 10482 entregue hoje as 14h20. Esta tudo certo com a sua compra?", "Footer": "Loja Exemplo", "Buttons": [ { "id": "p10482|ok", "text": "Recebi, tudo certo" }, { "id": "p10482|troca", "text": "Quero trocar" }, { "id": "p10482|humano", "text": "Falar com alguem" } ] }
Telefone de checkout é campo digitado com pressa, no celular: falta o nono dígito, sobra o zero da operadora, entra o fixo da empresa. Descobrir isso na hora do rastreio é tarde. O POST /user/check recebe uma lista e diz quais números têm conta no WhatsApp.
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": "" } ] } }
Ao todo são 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 —, mais reação, "digitando", marcar como lido e histórico. Fora do quarteto principal, os que mais rendem numa loja são documento, para a nota fiscal em PDF, e enquete, para a pesquisa do pós-venda.
Cada conexão tem o seu webhook: você cadastra no painel a URL do seu sistema e escolhe os eventos. A partir daí, toda mensagem que chega ao número da loja é entregue 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 número do pedido dentro.
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 seu sistema. A API não sabe o que é um pedido; sabe que uma mensagem chegou.
O corpo traz o tipo do evento e a mensagem completa. Assim chega quem digitou o número do pedido:
{
"type": "Message",
"event": {
"Info": {
"ID": "3EB0C767D26A1B5F7C83",
"Chat": "[email protected]",
"Sender": "[email protected]",
"IsFromMe": false, "IsGroup": false,
"PushName": "Marcos Ribeiro",
"Timestamp": "2026-03-11T18:04:22-03:00"
},
"Message": { "conversation": "10482" }
}
}
// quando ele toca num botao, muda so o bloco Message:
"Message": { "buttonsResponseMessage": {
"selectedButtonID": "p10482|troca",
"Response": { "SelectedDisplayText": "Quero trocar" }
} }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 da loja envia também gera evento, com IsFromMe igual a true: ignore, ou o atendente respondendo um cliente dispara a sua automação.
Responda 200 antes de processar, descarte o que não interessa, deduplique por Info.ID, encontre o pedido pelo id do botão e confirme ao cliente o que foi feito. O que a regra não reconhecer vira tarefa de gente — e isso é a maioria, o que está certo.
app.post("/whatsapp/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 a loja enviou, 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(); // o numero do pedido vem no id do botao; no texto, so se ele digitou const numero = botao ? botao.split("|")[0].replace("p", "") : (texto.match(/\b\d{5}\b/) ?? [])[0]; const pedido = numero ? await buscarPedido(numero) : await ultimoPedidoPorTelefone(telefone); if (!pedido) return filaDoAtendimento(telefone, texto); const acao = botao ? botao.split("|")[1] : /^(ok|recebi|chegou|tudo certo)$/.test(texto) ? "ok" : /(troca|trocar|devolver|devolucao)/.test(texto) ? "troca" : null; if (acao === "ok") { await marcarEntregaConfirmada(pedido.id); return enviarTexto(telefone, "Que bom. Obrigado pela compra!"); } if (acao === "troca") { await abrirChamado(pedido.id, "troca"); // vira tarefa de gente return enviarTexto(telefone, `Abrimos a solicitacao do pedido ${pedido.numero}. Respondemos por aqui ainda hoje.`); } return filaDoAtendimento(telefone, texto); // o resto e assunto de gente });
Não tente resolver por automação: troca envolve prazo, estado do produto e frete; devolução tem consequência fiscal; mudança de endereço depende de o pedido ainda não ter sido faturado. O papel da automação é reconhecer, registrar e sinalizar — abrir o chamado vinculado ao número do pedido e colocar a conversa numa fila que alguém olha. É assim que a segunda metade da dor se resolve: quando o "cadê meu pedido" some da caixa, a troca deixa de ficar soterrada.
Pode, desde que trate como o que é: abordagem comercial para quem não comprou, e não aviso sobre uma compra existente. Isso exige consentimento explícito coletado no checkout, com texto claro, registro de data e origem do aceite, e um caminho de descadastro em cada mensagem. Sem essas peças, não envie.
A distinção não é só jurídica, é operacional. Os seis avisos do fluxo são transacionais: o cliente comprou, deu o telefone para isso e espera receber. O carrinho abandonado é marketing: a pessoa não fechou nada. Quem trata os dois com o mesmo critério termina com um número denunciado por gente que não pediu contato.
Uma caixa de aceite não marcada por padrão, ao lado do campo de telefone, dizendo que a loja pode escrever no WhatsApp sobre a compra e sobre um carrinho não finalizado, e que dá para sair a qualquer momento. Grave o aceite com data, hora e origem. Sem aceite gravado, o carrinho não entra na régua.
optOut que toda rotina consulta antes de enviar. O pedido chega em qualquer palavra ("para", "não quero mais"), então alguém precisa olhar a fila de exceções todo dia.Dado de cartão, código de verificação, senha e qualquer link de pagamento que não seja do domínio da própria loja. A mensagem precisa de número do pedido, estado atual e próximo passo — nada além. Quanto menos a conversa se parecer com uma cobrança, mais difícil fica imitá-la.
Existe um golpe que se apoia exatamente neste fluxo: alguém se passa por atendente da loja, aborda o cliente com o número do pedido em mãos e pede uma taxa de liberação ou o código que acabou de chegar por SMS. A defesa é de linguagem, e começa pelo que a sua loja nunca faz.
A conversa fica no WhatsApp da loja: quem tem acesso ao aparelho ou aos aparelhos conectados vê o histórico de todos os pedidos. Merece o cuidado que se dá à senha do painel — bloqueio de tela e retirada dos aparelhos conectados quando alguém deixa a equipe.
R$ 27 por mês por número conectado, sem cobrança por mensagem: o valor não muda se a loja despachar 20 ou 2.000 pedidos no mês. O que existe é uma cota de 300 mensagens por dia por número — cerca de 9.000 por mês — para o WhatsApp não confundir a loja com um disparador de spam. O teste é de 14 dias sem cartão e só começa na primeira conexão — dá para criar a conta, integrar com o back-end e só depois conectar o número.
Essa previsibilidade é o que torna o fluxo de seis avisos possível. Com cobrança por mensagem, a conta cresceria junto com as vendas, e a reação natural seria cortar avisos — normalmente o de nota emitida e o de saiu para entrega, justamente os que mais evitam pergunta. Com mais de uma marca ou centro de distribuição, use uma conexão por número: o seu código 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 ler o QR Code de novo. E toda chamada que falhar precisa cair numa lista visível — foi o que a filaDeFalhas fez — com alguém olhando todo dia. Em loja, aviso que não saiu volta como pergunta no atendimento dois dias depois.
Funciona sempre que essa plataforma conseguir avisar o seu código quando o pedido muda de status, seja por webhook, evento interno ou consulta à API dela. O zapon é uma API REST comum: quem chama é o seu back-end. Se a plataforma é fechada, dá para comparar o estado dos pedidos em intervalos curtos e disparar a partir da diferença.
Pode, e é o aviso que mais rende. Quando o pedido ganha o código, o back-end chama POST /chat/send/text com o número do pedido e o código em linha própria, para o cliente copiar com um toque. Diga onde acompanhar e avise que o primeiro registro leva algumas horas para aparecer.
Pode, tratando como marketing e não como aviso de pedido: consentimento explícito no checkout, com caixa não marcada por padrão, registro de data e origem do aceite, e descadastro em cada mensagem. Uma tentativa algumas horas depois, no máximo duas em um dia, em horário civilizado. Sem aceite gravado, o carrinho não entra na régua.
Ter comprado não é o mesmo que ter autorizado receber oferta. O aviso sobre o pedido é esperado porque trata do serviço contratado; a promoção é outra finalidade e pede consentimento próprio. Mantenha os dois campos separados: quem saiu da lista de promoções continua tendo direito ao rastreio do pedido que pagou.
Use POST /user/check na confirmação do pedido, antes do primeiro envio: ele recebe uma lista de números e responde quais têm conta no WhatsApp. Os negativos viram tarefa do atendimento, que corrige o cadastro por outro canal. Descobrir no dia da compra é barato; descobrir no dia do rastreio é uma entrega que ninguém acompanhou.
A automação reconhece, registra e sinaliza — não decide. Ela abre o chamado vinculado ao número do pedido, responde que a solicitação existe e coloca a conversa numa fila que alguém olha. Troca envolve prazo, estado do produto e frete; devolução tem consequência fiscal. O atendente responde no próprio aplicativo.
R$ 27 por mês por número conectado, sem cobrança por mensagem, dentro de uma cota de 300 mensagens por dia por número (cerca de 9.000 por mês). O valor não muda com o volume de pedidos, o que permite manter os seis avisos sem que a conta cresça junto com as vendas, e a cota é a trava que mantém o número da loja fora do radar de bloqueio. 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 sobre pedidos que existem, mantenha o marketing separado e com aceite registrado, distribua os disparos em lote no tempo, respeite o descadastro e responda quem responde. O que dispara bloqueio é mensagem não solicitada em massa, não o uso de API.
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 o primeiro aviso de rastreio hoje.