O pedido chega solto no WhatsApp — "me vê 2kg de tomate, um frango inteiro, 6 ovos e o que tiver de banana madura". Com a API do zapon, o seu sistema registra a lista, devolve o número do pedido, aprova por botão a troca do item que faltou na gôndola e avisa a janela de entrega, recebendo cada resposta por webhook.
Mercado de bairro que entrega não perde dinheiro no preço da mercadoria: perde na exceção. A lista veio em texto ou em áudio, alguém imprimiu, o separador saiu com o carrinho pelo corredor — e aí aparecem os dois problemas que só existem nesta operação. O item da marca pedida acabou. E a peça de queijo que ia ter meio quilo veio com 620 gramas.
Cada dúvida dessas vira uma ligação, com o carrinho parado no meio do corredor. Depois vem a terceira: o cliente pediu entrega para as 18h, não sabe se o carro saiu, e liga. Uma API de WhatsApp resolve as três no canal em que o pedido nasceu. O zapon expõe uma API REST direta — header token, JSON de ida e de volta — que o seu sistema de pedidos ou um fluxo de automação chama por HTTP. Abaixo: o fluxo em sete passos, os endpoints em cURL e Node, o evento que chega quando o cliente aprova a troca e o que fazer com ele.
Porque a lista de compras é o pedido de varejo que muda depois de aceito. Roupa e eletrônico têm código: ou tem estoque, ou não tem. Mercearia tem marca alternativa, fruta madura demais e produto vendido por quilo — coisas que só aparecem com o separador de frente para a gôndola. Sem um canal que devolva a decisão do cliente em segundos, cada exceção vira uma ligação.
São três buracos diferentes, e cada um tem solução própria:
Porque a informação fica na cabeça de quem leu. A lista está numa conversa, o número do pedido num caderno, a aprovação da troca num áudio que só o dono ouviu. Quando o cliente reclama de item errado, não há registro de quem aprovou o quê. Com a API no meio, cada envio volta com um identificador e cada resposta cai no seu sistema como um evento com telefone, horário e conteúdo.
Três coisas: um número de WhatsApp que a loja controla, uma conta no zapon com esse número conectado por QR Code ou código de pareamento, e um sistema que guarde os pedidos com um número próprio. Não precisa de servidor próprio, de conta na Meta nem de aprovação de template.
token, credencial de todas as chamadas daquele número.P4187 —, a resposta que chega três minutos depois não gruda em lugar nenhum.Não. O caixa registra a venda; a conversa acontece antes, na separação. Se o seu retaguarda expõe os itens e o total, leia dali. Se é fechado, mantenha o pedido de delivery em outro lugar — sistema próprio, planilha, ferramenta no-code — e lance no caixa só o total já conferido.
Sete etapas: (1) a lista chega e o webhook a entrega ao seu sistema, que devolve um número de pedido; (2) o cliente confere os itens digitados e escolhe a janela de entrega em botões; (3) o separador monta o carrinho; (4) faltou um item, a alternativa vai por mensagem e o cliente aprova, troca ou remove em um toque; (5) o pedido fecha com o peso real e o valor final; (6) sai para entrega, com janela, entregador e valor a pagar; (7) entrega confirmada, e o que deu errado vira ocorrência para uma pessoa resolver.
Cada passo resolve uma dúvida diferente, e três deles esperam resposta.
O cliente manda a lista do jeito dele: texto, foto do papel da geladeira ou áudio de quarenta segundos. O webhook entrega a mensagem ao seu sistema, que faz uma coisa só — registra o pedido daquele telefone e devolve o número. Não tente interpretar a lista aqui: "o que tiver de banana madura" não é linha de pedido, é instrução para uma pessoa. O que a automação garante é que ninguém perde o pedido na conversa.
Quem digitou devolve os itens por escrito, com quantidade e preço estimado, e pergunta a janela em botões: manhã, tarde ou noite. Três opções, no máximo — é o teto do recurso e também o teto do que alguém decide sem pensar. O id de cada botão carrega o número do pedido, então a resposta chega amarrada ao registro certo.
O separador percorre o corredor com a lista conferida. Aqui o cliente não precisa de mensagem: mandar "estamos separando" a cada três itens só treina a pessoa a ignorar o seu número. O sistema marca o pedido como em separação, e as mensagens voltam quando aparece uma exceção.
É o passo central desta operação. O separador registra a falta, o sistema envia a alternativa — o nome, ou a foto do produto na prateleira — e oferece três saídas em botão: levar, remover o item ou falar com alguém. A resposta volta pelo webhook e entra no pedido antes de o carrinho seguir. É aqui que o tempo pesa, e a seção sobre substituição trata da regra para quem não responde.
Frios, carne e hortifruti só têm valor depois da balança. O fechamento manda o que mudou: o item, o peso real, o valor dele e o total conferido. Quem recebe esse aviso antes da entrega não discute na porta; quem descobre o valor quando o entregador estende a maquininha, discute.
Uma mensagem curta com três informações: a janela confirmada, quem está entregando e quanto será pago na porta, com a forma de pagamento combinada. É o aviso que dispensa a ligação de "já saiu?" — a mais frequente da operação, e a mais cara, porque chega no pico da separação.
Entregou, confirma. E abre caminho para o que não deu certo: item faltando na sacola, produto trocado, fruta machucada. Isso não pode ser resposta automática: vira ocorrência ligada ao número do pedido, numa lista que alguém do mercado resolve com crédito, troca ou devolução. A automação sinaliza; quem decide é gente.
Quatro resolvem o fluxo: POST /chat/send/text para número de pedido, fechamento e aviso de saída; POST /chat/send/buttons para janela e substituição; POST /chat/send/image para a foto da alternativa na gôndola; e POST /user/check para limpar telefones antigos do cadastro. Todos na base https://api.zapon.dev, com header token. São 49 endpoints publicados — 23 de /chat, 18 de /group e 8 de /user —, mas o delivery vive nesses quatro.
A autenticação é um header só, token, copiado da conexão no painel: não é Bearer, não há OAuth. Trate como a senha do caixa — quem tem o token manda mensagem em nome da loja.
Um POST em /chat/send/text com Phone, o número em formato internacional só com dígitos, e Body. Mande o número do pedido e nada mais: promessa de horário aqui é promessa que a separação ainda não pode cumprir.
curl -X POST https://api.zapon.dev/chat/send/text \ -H "token: SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "Phone": "5511999999999", "Body": "Recebemos sua lista, dona Marta. Pedido P4187.\n\nEstamos digitando os itens e já mandamos aqui a conferência com os valores e as janelas de entrega de hoje.\n\nSe lembrou de algo, é só mandar por aqui antes da conferência." }'
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 junto do pedido: é ele que prova qual aviso saiu e impede que uma rotina rodada duas vezes mande o mesmo fechamento duas vezes.
O /chat/send/buttons envia botões de resposta rápida, cada um com rótulo curto e um id definido por você. Coloque o número do pedido dentro do id: a resposta volta identificada, sem interpretar texto. 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 P4187 conferido: 18 itens, R$ 214,30 (frios e hortifruti ainda vão para a balança). Qual janela fica melhor hoje?", "Footer": "Mercado Exemplo — entregas até as 20h", "Buttons": [ { "id": "P4187|janela|manha", "text": "Manhã 8h-12h" }, { "id": "P4187|janela|tarde", "text": "Tarde 12h-17h" }, { "id": "P4187|janela|noite", "text": "Noite 17h-20h" } ] }
Marca descrita por escrito não resolve. O POST /chat/send/image leva a foto da gôndola com legenda em Caption, e o cliente decide vendo o rótulo, o tamanho e a etiqueta de preço. A imagem vai como data URI em base64 ou como URL acessível.
curl -X POST https://api.zapon.dev/chat/send/image \ -H "token: SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "Phone": "5511999999999", "Image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ…", "Caption": "Pedido P4187: acabou o café que você pediu. Este é o que temos na prateleira agora, R$ 1,80 a mais." }'
Mesma estrutura da janela, outro conteúdo — e agora com pressa, porque tem gente parada esperando. Mande a foto e emende os botões: uma pergunta, um produto, três saídas.
{
"Phone": "5511999999999",
"Body": "Levo o Café Exemplo Extraforte 500g no lugar do Tradicional, por R$ 1,80 a mais?",
"Footer": "Sem resposta em 10 min, seguimos sem o item",
"Buttons": [
{ "id": "P4187|troca|sim", "text": "Pode levar" },
{ "id": "P4187|troca|nao", "text": "Tira do pedido" },
{ "id": "P4187|troca|fala", "text": "Quero falar" }
]
}O Footer não é enfeite: é a regra da casa, escrita na hora em que ela importa.
Quando a rota do turno fecha, sai um aviso por pedido. O cuidado está nos detalhes: pular quem cancelou, guardar o identificador do envio e não despejar a rota inteira no mesmo segundo.
// rota.js — roda quando o entregador fecha o carro 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)); for (const p of await pedidosDaRota(turno)) { if (p.status !== "fechado") continue; // cancelado e pendente ficam fora if (await jaAvisado(p.id, "saiu_entrega")) continue; try { const id = await enviarTexto(p.telefone, `Pedido ${p.codigo} saiu para entrega, na janela ${p.janela}.\n\n` + `Entregador: ${p.entregador}. Total conferido na balança: R$ ${p.total}.\n` + `Pagamento combinado: ${p.pagamento}.`); await registrarEnvio(p.id, "saiu_entrega", id); // guarda o Id do envio } catch (e) { await registrarFalha(p.id, "saiu_entrega", String(e)); // vira tarefa do balcão } await pausa(4000); // a rota inteira no mesmo segundo não parece gente }
Cadastro de mercado guarda telefone fixo antigo, número sem o nono dígito e celular de quem mudou de cidade. O POST /user/check recebe uma lista e responde quais têm conta no WhatsApp — rode antes do primeiro disparo.
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": "" } ] } }
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. Fora dos quatro principais, os úteis num mercado são localização, quando o entregador não acha a rua, e lista, para oferecer mais de três alternativas num menu.
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, com o número do pedido dentro. Não há nada para ficar consultando.
São três partes separadas: o webhook entrega o evento, a sua regra interpreta e a ação acontece no pedido. A API não sabe o que é uma sacola; sabe que uma mensagem chegou.
O corpo traz o tipo do evento e a mensagem completa — primeiro quem respondeu por escrito, depois quem tocou no botão da substituição:
{
"type": "Message",
"event": {
"Info": {
"ID": "3EB0C767D26A1B5F7C83",
"Chat": "[email protected]",
"Sender": "[email protected]",
"IsFromMe": false, "IsGroup": false,
"PushName": "Marta Ribeiro",
"Timestamp": "2026-03-11T18:04:22-03:00"
},
"Message": { "conversation": "pode levar sim" }
}
}
// quando ela toca no botão, muda só o bloco Message:
"Message": { "buttonsResponseMessage": {
"selectedButtonID": "P4187|troca|sim",
"Response": { "SelectedDisplayText": "Pode levar" }
} }Três detalhes economizam horas. O corpo pode chegar como JSON puro ou como formulário codificado, com o JSON dentro de um campo — aceite os dois. O que o próprio número envia também gera evento, com IsFromMe igual a true: ignore, ou o atendente respondendo um cliente aciona a sua automação. E o mesmo evento pode chegar duas vezes: deduplique por Info.ID, ou a troca é aprovada em dobro.
Responda 200 antes de processar, descarte o que não interessa, ache o pedido pelo id do botão e confirme ao cliente o que foi feito — é essa última linha que evita o "respondi e não sei se chegou" com o separador ainda parado.
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 mandou, 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 ?? ""; if (ev?.Message?.audioMessage) return filaDaLoja(telefone, "audio"); if (!botao) return filaDaLoja(telefone, "texto"); // lista nova ou dúvida: é de gente const [codigo, assunto, opcao] = botao.split("|"); const pedido = await buscarPedido(codigo); if (!pedido) return filaDaLoja(telefone, botao); if (assunto === "troca" && opcao === "sim") { await aprovarSubstituicao(pedido.id); // libera o separador return enviarTexto(telefone, `Anotado, ${pedido.codigo}: levamos o substituto.`); } if (assunto === "troca" && opcao === "nao") { await removerItem(pedido.id); // e recalcula o total return enviarTexto(telefone, "Item retirado. O valor sai do total do pedido."); } if (assunto === "janela") { const ok = await reservarJanela(pedido.id, opcao); return enviarTexto(telefone, ok ? `Entrega marcada para a janela da ${opcao}.` : `A ${opcao} lotou. Já te mando as janelas que ainda têm vaga.`); } return filaDaLoja(telefone, botao); // o resto é assunto de gente });
O webhook entrega o evento de áudio e o seu sistema fica sabendo na hora que chegou um pedido novo — isso a API resolve. O que ela não faz é transcrever: converter fala em texto é serviço de outro tipo de ferramenta, e mesmo o melhor deles erra em "meio quilo de mussarela fatiada fina" e em nome de marca regional. Seja honesto com a operação: alguém do mercado ouve e digita a lista. O ganho é o áudio não se perder na conversa, abrir um pedido e entrar numa fila com hora de chegada.
Você precisa de uma regra padrão decidida antes, não improvisada no corredor: por exemplo, sem resposta em 10 minutos, o pedido segue sem o item e sem cobrança por ele. A regra vai escrita na própria mensagem, o relógio começa quando o envio é confirmado e uma rotina de minuto em minuto fecha as pendências vencidas. Assim o separador nunca fica parado por decisão que não veio.
Todo o resto do fluxo tolera espera. Este passo não: tem uma pessoa e um carrinho bloqueados. Três disciplinas fazem a diferença:
Guarde no pedido o que foi oferecido, o que voltou e a hora. O id do botão já traz pedido e intenção; some o Id do envio e o horário do evento e você tem a linha do tempo inteira. Quando o cliente disser "eu não autorizei esse café", a resposta é registro, não memória.
Avisando duas vezes, com a mesma palavra. Na conferência da lista, o total sai marcado como estimado, com a observação de que frios e hortifruti vão para a balança. No fechamento, sai o valor conferido, item por item do que foi pesado. Cobrança só surpreende quem não foi avisado: quem leu "estimado" na primeira mensagem entende que 620 gramas de queijo custam mais que 500.
Escreva o peso e o valor daquele item, não só o total novo. "Queijo mussarela: 620 g — R$ 27,90" é conferível. "Total atualizado: R$ 231,40" é um número que caiu do céu, e número que cai do céu vira ligação.
Porque a loja não controla trânsito, elevador de prédio nem o cliente que não está em casa. Janela é uma promessa que a operação cumpre; horário exato é a que ela quebra. Como cada janela tem capacidade — número de rotas e tamanho do carro —, a escolha do cliente precisa virar reserva no seu sistema, não anotação.
Nunca deixe a resposta cair no vazio. Quando a reserva falha, o mesmo evento devolve na hora uma mensagem dizendo que aquela janela encheu e oferecendo as que ainda têm vaga — foi o que a função reservarJanela fez ao retornar falso. Quem escolheu "tarde" e ficou dez minutos sem retorno liga.
São duas coisas diferentes no mesmo canal. Mensagem sobre um pedido — número, substituição, valor, entrega — é transacional: o cliente deu o telefone para isso e espera o aviso. Encarte de ofertas é marketing e exige consentimento próprio, pedido de forma clara, com registro e com um jeito de sair que funcione. Tratar as duas como a mesma lista é o erro que transforma o número do mercado num número denunciado.
R$ 27 por mês por número conectado, sem cobrança por mensagem. Um pedido gasta de cinco a oito mensagens entre conferência, substituições, fechamento e entrega, e o valor não muda se a loja dobrar o movimento do sábado. O que precisa caber é a cota diária: 300 mensagens por número conectado, algo entre 35 e 60 pedidos por dia num único número — teto que existe para o WhatsApp não bloquear a loja por excesso de envio. O teste é de 14 dias sem cartão e a contagem só começa na primeira conexão.
É essa previsibilidade que torna o fluxo viável no varejo alimentar, onde a margem por pedido é fina. Com cobrança por mensagem, a conta cresceria justamente nos pedidos mais trabalhosos — os de três substituições — e alguém acabaria cortando a pergunta que evita a devolução na porta.
É uma conexão por número, e o normal é um número por loja: estoque, janela e entregador são de cada unidade. Cada conexão tem o seu token, então o seu sistema escolhe de qual loja a mensagem sai trocando o header — o resto do código é o mesmo. Cada número conectado tem a sua assinatura mensal.
O painel mostra o estado de cada conexão e atualiza a cada 10 segundos enquanto a página está aberta. Como ninguém vai olhar a tela no pico da separação, 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 abrir essa lista todo dia.
Dá. Toda mensagem que chega no número conectado é entregue ao seu sistema por webhook, seja texto, foto do papel ou áudio, e o cliente recebe na hora o número do pedido. A leitura da lista continua sendo de uma pessoa: "o que tiver de banana madura" não é uma linha de pedido.
Pelo endpoint de botões. O sistema manda o nome ou a foto da alternativa e três opções: levar o substituto, remover o item ou falar com alguém. O identificador do botão carrega o número do pedido, então a resposta chega amarrada ao registro certo. Tenha uma regra padrão, escrita na mensagem, para quem não responde no prazo.
Não. O webhook entrega o evento de áudio e avisa o seu sistema de que chegou um pedido novo, mas converter fala em texto é serviço de outro tipo de ferramenta. Na prática, alguém do mercado ouve e digita. O ganho é que o áudio não se perde: abre um pedido e entra numa fila com hora de chegada.
São dois envios. Na conferência da lista, botões com as janelas do dia e a reserva feita no seu sistema quando a resposta chega. Quando a rota fecha, um texto com a janela confirmada, o nome de quem entrega e o valor a ser pago na porta. É esse segundo aviso que substitui a ligação de "já saiu?".
O total só fecha depois da balança, e o cliente precisa saber disso antes. Na conferência, mande o total como estimado e diga que frios e hortifruti serão pesados. No fechamento, mande o valor conferido com o peso item por item. Valor que aparece só na maquininha, na porta, vira discussão.
Aviso sobre um pedido é transacional e esperado. Encarte de ofertas é marketing e precisa de consentimento próprio, com registro e descadastro que funcione em todas as rotinas. Peça o opt-in numa mensagem separada depois da entrega e respeite quem disser não.
A conversa acontece antes do caixa, na separação, então não é preciso integrar com o PDV. Se o seu retaguarda expõe os itens e o total, leia dali e dispare. Se é fechado, mantenha o pedido de delivery em outro lugar e lance no caixa o total já conferido. A API precisa de telefone e texto.
R$ 27 por mês por número conectado, sem cobrança por mensagem, com cota de 300 mensagens por dia em cada número. Uma rede costuma usar um número por loja, porque estoque, janela e entregador são de cada unidade, então são tantas assinaturas quantos números conectados. O teste é de 14 dias sem cartão e só começa na primeira conexão.
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 aprovação de substituição hoje.