Pular para o conteúdo
apiwpp

Notificações de pedido pelo WhatsApp para e-commerce

Confirmação, pagamento, envio e rastreio pelo WhatsApp: templates com variáveis, id do pedido como clientRef, boleto em PDF e status de entrega no webhook.

Equipe apiwpp · 13 min de leitura

O cliente fechou a compra e agora quer saber três coisas: se o pedido entrou, se o pagamento foi aprovado e quando a encomenda chega. O e-mail de confirmação cai na aba de promoções, o SMS parece golpe e a página "Meus pedidos" ninguém abre. O WhatsApp é o canal que ele já lê, e é por isso que tanta loja quer mandar a notificação de pedido por lá.

O desafio técnico é menor do que parece, mas tem armadilhas conhecidas: a mesma confirmação enviada duas vezes porque o job de checkout rodou de novo, o boleto que não chega porque o link era interno, a Black Friday que empilha centenas de mensagens num número recém-conectado. Este guia mostra como montar esse fluxo com a apiwpp, do evento do pedido até o status de entrega voltando para o seu painel.

As mensagens que o cliente espera receber

Uma notificação de pedido funciona quando responde a uma pergunta que o cliente já tem. Por isso o conjunto certo é curto e acompanha a vida do pedido:

MomentoMensagemAnexo possível
Pedido criadoConfirmação com número do pedido e totalBoleto em PDF, se for o meio de pagamento
Pagamento aprovadoAviso de que o pedido segue para separaçãoNota fiscal em PDF, quando emitida
Pedido enviadoTransportadora e código de rastreioNenhum: o link de rastreio basta
Pedido entregueConfirmação e canal de atendimentoNenhum
Carrinho abandonadoUm único lembrete, só para quem aceitou receberNenhum

Duas regras valem para todas elas. A primeira: cada mensagem precisa carregar o número do pedido, para o cliente reconhecer do que se trata sem abrir o site. A segunda: menos é mais. Se o pagamento por PIX é aprovado segundos depois da criação do pedido, junte confirmação e aprovação numa mensagem só em vez de mandar duas seguidas.

A recuperação de carrinho merece cuidado à parte. Ela é uma mensagem de venda, não de serviço, e só deve ir para quem marcou no checkout que aceita receber mensagens pelo WhatsApp. Um lembrete, não uma sequência. Quem recebe mensagem que não pediu costuma fazer denúncia, e denúncias são um dos motivos que levam o WhatsApp a restringir um número (o post sobre como evitar o bloqueio do número explica o resto).

A jornada de um pedido e a mensagem que acompanha cada etapa, do checkout à entrega.

Opt-in e saída, do jeito que a LGPD pede

Coloque no checkout uma caixa, desmarcada por padrão, com um texto claro: "Quero receber atualizações do meu pedido pelo WhatsApp". Guarde a data do consentimento junto do cliente. Ofereça a saída em toda mensagem que não seja estritamente sobre um pedido em andamento, algo como "responda SAIR para não receber mais". As respostas chegam ao seu sistema pelo webhook message.incoming, e o seu código marca o cliente como descadastrado. A apiwpp entrega a mensagem e o evento; guardar e respeitar o consentimento é responsabilidade da loja.

Templates com variáveis: o texto fica num lugar só

Montar a mensagem por concatenação dentro do código do checkout espalha o texto por vários serviços e torna qualquer ajuste de copy um deploy. Os templates da apiwpp resolvem isso: você salva o texto uma vez, com variáveis entre chaves duplas, e cada envio passa só o nome do template e os valores.

Crie os templates no número da loja com POST /connections/{id}/templates:

curl -s -X POST "https://api.apiwpp.com/connections/$ID/templates" \
  -H "Authorization: Bearer $APIWPP_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name": "pedido_confirmado", "body": "Olá, {{nome}}! Recebemos o pedido {{pedido}}, no valor de {{total}}. Avisaremos aqui quando ele for enviado."}'

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 a entrega: {{rastreio}}"}'

Na hora de enviar, o corpo leva template e variables no lugar de message:

{
  "to": "5511988887777",
  "template": "pedido_enviado",
  "variables": {
    "nome": "Ana",
    "pedido": "#1234",
    "transportadora": "Transportadora Exemplo",
    "rastreio": "https://loja.example.com/rastreio/1234"
  },
  "clientRef": "pedido-1234-enviado"
}

Se faltar alguma variável, a API responde 400 com a lista em missingVariables, e nada entra na fila. Isso é útil: um pedido sem código de rastreio falha de forma visível no seu log, em vez de chegar ao cliente com um buraco no meio da frase.

Um ponto que confunde quem vem da API oficial: esses templates não passam por aprovação da Meta. São mensagens salvas da sua conta, que você cria e altera quando quiser. Isso dá agilidade, mas também deixa com você a responsabilidade de manter o texto curto, útil e sem cara de propaganda. A diferença entre os dois modelos está no guia API oficial ou não oficial do WhatsApp, e a página de templates de mensagem resume o recurso.

clientRef é o id do pedido: a mesma confirmação nunca sai duas vezes

O cenário clássico: o gateway de pagamento chama o seu webhook, o seu código envia a confirmação, a resposta da apiwpp demora, o seu cliente HTTP estoura o timeout e o job é reprocessado. Sem proteção, a cliente recebe "Recebemos o pedido #1234" duas vezes e fica em dúvida se pagou duas vezes.

O campo clientRef resolve. Ele é o seu identificador do envio, com até 200 caracteres. A primeira requisição com um clientRef numa conexão entra na fila e responde 202. Uma repetição com o mesmo valor, na mesma conexão, responde 200 com o job original e "duplicate": true, sem enfileirar nada:

{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 1, "duplicate": true }

Monte o clientRef a partir do pedido e da etapa: pedido-1234-confirmado, pedido-1234-pago, pedido-1234-enviado. Só o id do pedido não basta, porque aí a mensagem de envio seria tratada como repetição da confirmação. O valor fica reservado por 7 dias, prazo de sobra para qualquer retentativa.

Aqui está a função de envio completa em Node.js (18 ou mais recente, com o fetch nativo), pronta para ser chamada pelo worker que escuta os eventos do pedido:

const API = 'https://api.apiwpp.com'

export async function notifyOrder({ order, step, template, variables }) {
  const response = await fetch(`${API}/connections/${process.env.APIWPP_CONNECTION_ID}/send`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.APIWPP_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      to: order.customerPhone, // só dígitos, com país e DDD: 5511988887777
      template,
      variables,
      clientRef: `pedido-${order.id}-${step}`,
    }),
  })

  if (response.status === 202 || response.status === 200) {
    // 200 com duplicate: true = esta etapa já estava na fila; nada a fazer
    return response.json()
  }

  if (response.status === 429) {
    const retryAfter = Number(response.headers.get('Retry-After') ?? 60)
    const error = new Error('apiwpp: tente de novo mais tarde')
    error.retryAfterSeconds = retryAfter
    throw error // o seu job agenda uma nova tentativa, com o mesmo clientRef
  }

  // 400: conexão fora do ar, variável faltando ou corpo inválido. Não adianta repetir igual.
  const body = await response.json().catch(() => ({}))
  throw new Error(`apiwpp ${response.status}: ${body.error ?? 'erro desconhecido'}`)
}
await notifyOrder({
  order: { id: 1234, customerPhone: '5511988887777' },
  step: 'confirmado',
  template: 'pedido_confirmado',
  variables: { nome: 'Ana', pedido: '#1234', total: 'R$ 189,90' },
})

Repare que a retentativa usa o mesmo clientRef. Esse é o ponto: repetir é seguro. Já um reenvio de propósito, depois de o envio ter falhado de vez, precisa de um valor novo (pedido-1234-confirmado-2), senão a API só responde duplicate. O post sobre mensagens duplicadas e idempotência detalha os casos de borda, e a integração completa em Node.js está na página de integração com Node.js.

O to vai só com dígitos, código do país e DDD. Antes de enviar, a apiwpp pergunta ao WhatsApp em qual endereço aquele número está registrado, então contas antigas sem o nono dígito recebem normalmente. Um número que não tem WhatsApp falha na hora com not_on_whatsapp. Se quiser validar o telefone já no cadastro, POST /connections/{id}/contacts/check confere até 100 números de uma vez.

Boleto e nota fiscal em PDF, por URL https

O PDF não vai no corpo da requisição: a apiwpp baixa o arquivo de uma URL https pública e envia como documento. Endereços privados ou internos (um http://10.0.0.5/boletos/... da sua rede, por exemplo) são recusados, por segurança. O tipo document exige o mimetype, e o fileName define o nome que o cliente vê no WhatsApp:

{
  "to": "5511988887777",
  "media": {
    "type": "document",
    "url": "https://arquivos.loja.example.com/boletos/1234.pdf",
    "mimetype": "application/pdf",
    "fileName": "boleto-pedido-1234.pdf",
    "caption": "Ana, segue o boleto do pedido #1234. O pedido é liberado assim que o pagamento for compensado."
  },
  "clientRef": "pedido-1234-boleto"
}

Três cuidados práticos:

  • Use a legenda. O texto em caption substitui uma mensagem separada. Menos mensagens para a mesma pessoa significa menos espera na fila, porque há um intervalo mínimo de 30 segundos entre duas mensagens para o mesmo destinatário.
  • Dê validade ao link. O arquivo é baixado quando o envio sai da fila, não no momento da requisição. Se você usa links assinados com prazo, dê uma validade que cubra o tempo de fila, que pode ser de minutos num pico.
  • Não exponha o que não deve. Um boleto tem dados pessoais. Prefira URLs com um token longo e aleatório a caminhos previsíveis como /boletos/1234.pdf.

Imagem, vídeo e áudio seguem o mesmo formato, trocando o type. O tutorial como enviar PDF, imagem, áudio e vídeo pela API cobre cada tipo, e a página de envio de mídia lista os campos.

Acompanhe entrega e leitura pelo webhook

O 202 do envio quer dizer "entrou na fila", não "o cliente recebeu". O resultado chega depois, pelo webhook do projeto. Para notificações de pedido, dois eventos importam:

EventoO que dizO que a loja faz
message.deliveryO status mudou: sent, delivered, read ou failed, com o messageId e o seu clientRefAtualiza a linha da notificação no pedido
message.send_failedUm envio com clientRef não vai acontecer, com o motivo em reasonMarca a notificação como falha e avisa por outro canal

Como o clientRef carrega o id do pedido e a etapa, ligar o evento ao pedido é uma linha de código. Um exemplo de processamento, depois de verificar a assinatura HMAC do webhook como mostra o guia de webhooks do WhatsApp:

export async function handleApiwppEvent(event, db) {
  const { type, data } = event

  if (type === 'message.delivery' && data.clientRef?.startsWith('pedido-')) {
    // Status repetido ou fora de ordem não pode regredir: read > delivered > sent
    await db.orderNotifications.advanceStatus(data.clientRef, data.status, data.messageId)
    return
  }

  if (type === 'message.send_failed') {
    // reason: attempts_exhausted, lease_expired, not_on_whatsapp ou reachout_timelocked
    await db.orderNotifications.markFailed(data.clientRef, data.reason)
    return
  }

  // Ignore os tipos que você não usa: a lista de eventos só cresce
}

Dois detalhes evitam dor de cabeça. A entrega do webhook é pelo menos uma vez, então o mesmo status pode chegar duas vezes: grave de forma idempotente e nunca deixe um delivered sobrescrever um read. E a associação entre clientRef e messageId vale por 72 horas; um status que chega depois disso pode vir com clientRef: null, por isso guarde também o messageId na primeira vez que ele aparecer.

O read só chega quando o cliente mantém a confirmação de leitura ativada no WhatsApp. Trate a ausência dele como "não sabemos", não como "não leu". Já o delivered é um bom sinal para a equipe de atendimento: se o cliente liga dizendo que não recebeu o código de rastreio, o painel do pedido mostra se a mensagem chegou ao aparelho dele.

O histórico de notificações dentro do pedido, alimentado pelos eventos message.delivery.

Todos os eventos, o formato do envelope e a política de novas tentativas estão na página de webhooks assinados.

Picos de venda, fila e clientes novos

Aqui está a parte que as lojas descobrem na primeira Black Friday. A apiwpp envia pela fila de cada número, num ritmo que imita uma pessoa e protege o número de bloqueios. Os padrões por número são 3 envios por minuto, 60 por hora e 200 por dia, com intervalo aleatório de 3 a 8 segundos entre dois envios. Não há cobrança por mensagem: o preço é por número, e as mensagens são ilimitadas dentro desses limites (os valores estão em preços).

Na prática, isso quer dizer que 150 pedidos numa hora não viram 150 mensagens na mesma hora. O POST /send responde na hora com position (o lugar na fila) e scheduledAt (quando o envio está previsto, em milissegundos unix), e a mensagem sai no horário dela. Três decisões ajudam:

  1. Priorize o que importa. Confirmação e envio com rastreio são as mensagens que o cliente espera. "Seu pedido está em separação" pode ficar de fora num pico.
  2. Cancele o que perdeu o sentido. Se o pedido foi cancelado antes de a confirmação sair, DELETE /connections/{id}/queue/{jobId} tira o envio da fila. Guarde o jobId da resposta para isso.
  3. Acompanhe a fila. GET /connections/{id}/queue mostra quantos envios aguardam, os limites em vigor e o uso atual. Um alerta interno quando a fila passa de um tamanho que você define evita surpresas.

O teto de destinatários novos

Existe um segundo limite, e ele pesa mais para e-commerce do que para outros usos: por padrão, cada número fala com até 100 destinatários novos a cada 24 horas. Destinatário novo é quem não trocou mensagem com o número nos últimos 28 dias desde o pareamento atual. Quem compra pela primeira vez na sua loja quase sempre é um destinatário novo.

Passado o teto, o envio responde na hora, sem enfileirar nada:

{ "error": "new_recipient_cap_reached", "message": "This number already reached 100 new recipients …" }

com status 429 e o cabeçalho Retry-After dizendo em quantos segundos abre uma vaga. A função notifyOrder acima já trata esse caso: o job agenda a nova tentativa com o mesmo clientRef. Contatos conhecidos nunca são barrados por esse teto.

O jeito mais natural de transformar o comprador em contato conhecido é deixar que ele comece a conversa. Na página de "pedido concluído", um botão "Acompanhar pelo WhatsApp" que abre uma conversa com o número da loja, com uma mensagem pronta como "Quero acompanhar o pedido #1234", faz o cliente escrever primeiro. A partir daí ele é um contato conhecido, a sua loja recebe o message.incoming e ainda ganha uma confirmação explícita de que ele quer ser avisado por ali.

Um número recém-conectado tem limites ainda menores nos primeiros 14 dias, no aquecimento de número: até 6 horas depois do pareamento, são 5 envios por hora, 20 por dia e 5 destinatários novos. Conecte o número da loja com antecedência, nunca na véspera de uma campanha. A fila com ritmo anti-bloqueio resume todas as regras. Nenhum desses cuidados garante que um número nunca será restringido pelo WhatsApp; eles reduzem o risco.

LITE ou PRO para uma loja

Tudo o que este guia mostrou, envio de texto, templates, PDF, webhooks, clientRef, fila e aquecimento, está no plano LITE. O PRO acrescenta as operações sobre mensagens já enviadas, e uma delas é bem útil em loja: editar uma mensagem enviada pela API até 15 minutos depois do envio. Mandou o código de rastreio errado? Dá para corrigir a mesma mensagem em vez de mandar uma segunda com "desconsidere a anterior". O PRO também permite apagar para todos, marcar como lida e mostrar presença, além do IP dedicado como adicional por número. A comparação completa está em preços.

Como começar hoje

  1. Defina as mensagens: confirmação, pagamento aprovado (ou junto da confirmação), envio com rastreio e entrega. Escreva cada uma com o número do pedido.
  2. Adicione a caixa de consentimento no checkout e o botão "Acompanhar pelo WhatsApp" na página de pedido concluído.
  3. Crie um projeto, uma chave com o escopo messages:send e conecte o número da loja com antecedência, para o aquecimento correr antes do próximo pico.
  4. Salve os templates com POST /connections/{id}/templates e envie com clientRef no formato pedido-<id>-<etapa>.
  5. Configure o webhook do projeto e grave message.delivery e message.send_failed no histórico do pedido.
  6. Crie sua conta na apiwpp e faça o fluxo completo com um pedido de teste no seu próprio celular.

Perguntas frequentes

Posso mandar notificação de pedido para qualquer cliente que comprou?

Pode mandar para quem comprou e informou o WhatsApp no pedido, porque a mensagem é sobre uma compra que ele fez. Ainda assim, peça o consentimento no checkout e ofereça a saída, como pede a LGPD. Mensagens de venda, como a recuperação de carrinho, devem ir só para quem aceitou recebê-las.

Como evito que o cliente receba a mesma confirmação duas vezes?

Envie sempre com um clientRef formado pelo id do pedido e pela etapa, como pedido-1234-confirmado. Uma repetição com o mesmo valor, na mesma conexão, responde 200 com "duplicate": true e não enfileira nada. O valor fica reservado por 7 dias.

Dá para enviar o boleto ou a nota fiscal em PDF?

Sim. Envie um media do tipo document com a URL https pública do arquivo, o mimetype application/pdf, o fileName e uma legenda. Endereços internos da sua rede são recusados, e o link precisa continuar válido até o envio sair da fila.

Por que a notificação não sai no mesmo segundo do pedido?

Porque cada número envia por uma fila com ritmo de pessoa: por padrão, 3 envios por minuto, 60 por hora e 200 por dia, com 3 a 8 segundos entre dois envios. A resposta do envio traz scheduledAt com o horário previsto. Isso protege o número, mas também quer dizer que a apiwpp não serve para mensagens que precisam chegar em segundos garantidos.

Como sei se o cliente recebeu e leu a mensagem?

O webhook message.delivery chega a cada mudança de status (sent, delivered, read ou failed), com o messageId e o seu clientRef. O read depende de o cliente manter a confirmação de leitura ativada no WhatsApp. Se o envio não vai acontecer, chega message.send_failed com o motivo.

O que acontece quando muitos clientes novos compram no mesmo dia?

Por padrão, cada número fala com até 100 destinatários novos a cada 24 horas, e menos durante o aquecimento. Passado esse teto, o envio responde 429 new_recipient_cap_reached com Retry-After, e o seu sistema tenta de novo depois. Clientes que já escreveram para o número são contatos conhecidos e não são barrados.


Leia também:

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.