WhatsApp para e-commerce: pedido, pagamento e rastreio via API
Integre sua loja ao WhatsApp pela API: confirmação de pedido, boleto em PDF e rastreio com templates, clientRef por pedido e status de entrega por webhook.
Atualizado em
Quem compra numa loja virtual quer saber três coisas: se o pedido foi recebido, se o pagamento foi aprovado e quando a encomenda chega. O e-mail com essas respostas muitas vezes cai no spam ou fica sem ser aberto. O WhatsApp é o canal que o cliente já olha várias vezes por dia.
Com a apiwpp, a sua loja envia essas mensagens a partir do próprio sistema, por HTTP, usando um número de WhatsApp da loja conectado como aparelho. Este caso de uso mostra o desenho: quais mensagens enviar, como montar cada uma com templates, como nunca mandar a mesma confirmação duas vezes e como saber se a mensagem chegou.
As mensagens que o cliente espera receber
As notificações que funcionam melhor são as que o cliente está esperando, porque acabou de comprar:
| Momento | Mensagem | O que vai junto |
|---|---|---|
| Pedido criado | Confirmação com número e valor | Link para acompanhar o pedido |
| Aguardando pagamento | Boleto ou código PIX | Boleto em PDF, por URL |
| Pagamento aprovado | Confirmação do pagamento | Nota fiscal em PDF, se já emitida |
| Pedido enviado | Transportadora e código de rastreio | Link de rastreio |
| Carrinho abandonado | Lembrete curto, só para quem deu opt-in | Link de volta ao carrinho |
A recuperação de carrinho merece cuidado: envie só para quem autorizou mensagens pelo WhatsApp, uma vez, e com um jeito fácil de parar de receber. É o tipo de mensagem que, mal usada, vira denúncia.
Templates com variáveis para cada etapa
Em vez de montar o texto no código, salve uma mensagem por etapa como template, com variáveis entre chaves duplas:
curl -s -X POST "https://api.apiwpp.com/connections/$ID/templates" \
-H "Authorization: Bearer $APIWPP_KEY" \
-H 'Content-Type: application/json' \
-d '{"name": "pedido_enviado", "body": "{{nome}}, o pedido {{pedido}} saiu com a {{transportadora}}. Acompanhe: {{rastreio}}"}'
No envio, o corpo leva template e variables. Se faltar alguma variável, a API responde 400 com a lista em missingVariables e nada entra na fila, então um pedido sem código de rastreio falha de forma visível no seu log. Esses templates são mensagens salvas da sua conta: não passam por aprovação da Meta, e você altera o texto quando quiser. O recurso está descrito em templates de mensagem.
clientRef é o id do pedido
O cenário clássico: o gateway de pagamento chama o seu sistema, a notificação é enviada, a resposta demora, o seu cliente HTTP estoura o tempo e o job é reprocessado. Sem proteção, o cliente recebe a confirmação duas vezes.
O campo clientRef resolve. Monte o valor com o pedido e a etapa, como pedido-1234-enviado. A primeira requisição entra na fila e responde 202; uma repetição com o mesmo clientRef, na mesma conexão, responde 200 com o job original e "duplicate": true, sem enfileirar nada. O valor fica reservado por 7 dias:
{
"to": "5511988887777",
"template": "pedido_enviado",
"variables": {
"nome": "Ana",
"pedido": "#1234",
"transportadora": "Transportadora Exemplo",
"rastreio": "https://loja.example.com/rastreio/1234"
},
"clientRef": "pedido-1234-enviado"
}
O to vai só com dígitos, com país e DDD. Antes de enviar, a apiwpp pergunta ao WhatsApp em qual endereço o número está registrado, então contas antigas sem o nono dígito recebem normalmente, e um número sem WhatsApp falha na hora com not_on_whatsapp. Veja idempotência com clientRef.
Boleto e nota fiscal em PDF
O arquivo não vai no corpo da requisição: a apiwpp baixa o PDF de uma URL https pública e envia como documento. Endereços privados ou internos são recusados, por segurança. O tipo document exige o mimetype, e o fileName é o nome que o cliente vê:
{
"to": "5511988887777",
"media": {
"type": "document",
"url": "https://arquivos.loja.example.com/boletos/a8f3c1.pdf",
"mimetype": "application/pdf",
"fileName": "boleto-pedido-1234.pdf",
"caption": "Ana, segue o boleto do pedido #1234."
},
"clientRef": "pedido-1234-boleto"
}
Use a legenda em vez de uma segunda mensagem, e dê ao link uma validade que cubra o tempo de fila: o arquivo é baixado quando o envio sai, não no momento da requisição. Imagem, vídeo e áudio seguem o mesmo formato; veja envio de mídia.
Entrega e leitura pelo webhook
O 202 do envio quer dizer "entrou na fila", não "o cliente recebeu". O resultado chega depois, no webhook do projeto:
message.deliverytraz o status (sent,delivered,readoufailed), omessageIde o seuclientRef. Como oclientRefcarrega o pedido e a etapa, ligar o evento ao pedido é uma consulta.message.send_failedavisa que um envio comclientRefnão vai acontecer, com o motivo (por exemplonot_on_whatsapp).
O read só chega quando o cliente mantém a confirmação de leitura ativada no WhatsApp: trate a ausência como "não sabemos", não como "não leu". A entrega do webhook é pelo menos uma vez, então grave os status de forma idempotente e nunca deixe um delivered sobrescrever um read. Todos os eventos estão em webhooks assinados.
Picos de venda e a fila do número
Cada número envia por uma fila com ritmo que protege o número. Os padrões são 3 envios por minuto, 60 por hora e 200 por dia, com intervalo aleatório de 3 a 8 segundos, e no máximo 100 destinatários novos a cada 24 horas. Quem compra pela primeira vez quase sempre é um destinatário novo, e passado o teto o envio responde 429 new_recipient_cap_reached com o cabeçalho Retry-After, sem enfileirar nada.
Num pico, 150 pedidos numa hora não viram 150 mensagens na mesma hora: o envio responde com position e scheduledAt, e a mensagem sai no horário dela. Priorize confirmação e rastreio, cancele com DELETE /connections/{id}/queue/{jobId} o que perdeu o sentido e, se o volume passar dos limites de um número, distribua entre números diferentes, cada um com a própria fila. O preço é por número, com mensagens ilimitadas dentro dos limites; os valores estão em preços. A fila anti-bloqueio explica cada limite.
O passo a passo completo, com a função de envio em Node.js e o tratamento de cada evento, está no post notificações de pedido pelo WhatsApp.
Perguntas frequentes
Os templates precisam ser aprovados pela Meta?
Não. Na apiwpp, templates são mensagens salvas da sua conta, com variáveis, e não passam por aprovação. A contrapartida é que o cuidado com o conteúdo fica com você: mensagens curtas, úteis e para quem espera recebê-las.
Como evito enviar a mesma confirmação de pedido duas vezes?
Use um clientRef com o id do pedido e a etapa, como pedido-1234-confirmado. Repetir a requisição com o mesmo valor devolve o job original com "duplicate": true, sem enfileirar outra mensagem.
Consigo saber se o cliente leu a mensagem?
O evento message.delivery informa sent, delivered, read ou failed. O read depende de o cliente manter a confirmação de leitura ativada no WhatsApp, então a ausência dele não significa que a mensagem não foi lida.
Posso usar a apiwpp para campanhas de marketing para toda a base?
Não é para isso. A fila limita o ritmo e os destinatários novos por dia justamente para reduzir o risco de bloqueio. Ela serve para conversar com quem comprou ou autorizou as mensagens, e nenhuma ferramenta garante que um número nunca será restringido.
Outros casos de uso
Todos: Casos de uso →Mande pelo WhatsApp os avisos que o seu sistema já gera para quem é cliente (conta, serviço, pedido, alerta), com templates, envios sem duplicidade e a confirmação de entrega e leitura no seu webhook.
Envie o aviso de vencimento, a segunda via do boleto e a confirmação de pagamento a quem já é seu cliente, a partir do seu sistema financeiro, sem risco de mandar a mesma cobrança duas vezes.
Cada mensagem que chega no número da empresa vira um evento no seu sistema: abra o ticket, distribua para a equipe e responda pela API, com texto, mídia, reações e o indicador de digitando.