WhatsApp API no e-commerce: pedidos, entrega, carrinho e pós-venda

Atualizado em 20/10/2026

No e-commerce, a API oficial do WhatsApp serve para avisar o cliente em cada etapa do pedido e para trazer de volta quem abandonou o carrinho. Confirmação de pedido, pagamento aprovado, envio com rastreio, entrega e pesquisa sobre um pedido específico usam templates de utilidade, desde que não tenham conteúdo promocional. Lembrete de carrinho abandonado, cupom e recomendação de produto são marketing, mesmo quando o cliente pediu para ser lembrado.

Este guia mostra qual mensagem enviar em cada evento da loja, qual categoria de template usar, quanto custa e como ligar os eventos da plataforma da loja à API, com exemplo em Node.js.

Mapa de mensagens: evento da loja, mensagem e categoria

A categoria do template define o preço e as regras de envio. A Meta revisa a categoria na aprovação e pode mudá-la depois, então o texto precisa corresponder ao que você declarou. As regras abaixo seguem as diretrizes de categorização de templates.

Evento da loja	Mensagem	Categoria	Observação
Pedido criado	Confirmação com número e resumo do pedido	Utilidade	Sem cupom nem sugestão de produto
Pagamento pendente	Aviso de pagamento pendente do pedido	Utilidade	Só dados do pedido; com oferta, vira marketing
Pagamento aprovado	Confirmação do pagamento	Utilidade	Pode trazer prazo estimado de envio
Pedido enviado	Código de rastreio e previsão de entrega	Utilidade	Botão com link de rastreio dinâmico
Atraso ou falta de estoque	Aviso de atraso, opção de cancelar com reembolso	Utilidade	A Meta cita esse caso como exemplo de utilidade
Pedido entregue	Confirmação de entrega e canal para problemas	Utilidade	Pesquisa ligada ao pedido também é utilidade
Reembolso processado	Valor e prazo do estorno	Utilidade	Sem oferta de nova compra
Carrinho abandonado	Lembrete dos itens deixados no carrinho	Marketing	Marketing mesmo se o cliente pediu o lembrete
Recompra ou produto relacionado	Sugestão com base na última compra	Marketing	Exige opt-in de marketing
Cupom de agradecimento	Desconto na próxima compra	Marketing	Conteúdo promocional

Duas regras da Meta explicam a tabela. Um template só é utilidade se for não promocional e, ao mesmo tempo, específico do usuário (pedido, conta, transação) ou essencial para ele. E templates com conteúdo misto, como uma atualização de pedido com promoção, são considerados marketing.

Confirmação de pedido

É a primeira mensagem que o cliente recebe e a que mais gera confiança no canal. Mantenha só o essencial: número do pedido, valor, forma de pagamento e quando ele terá a próxima notícia.

Criação do template pela Vectalk, que usa o mesmo formato da Meta e resolve o WABA pelo token de instância:

curl -X POST https://apis.vectalk.com.br/api/templates \
  -H "Authorization: Bearer SEU_TOKEN_DE_INSTANCIA" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pedido_confirmado",
    "language": "pt_BR",
    "category": "UTILITY",
    "components": [
      { "type": "HEADER", "format": "TEXT", "text": "Pedido confirmado" },
      {
        "type": "BODY",
        "text": "Olá, {{1}}! Recebemos seu pedido {{2}} no valor de {{3}}. Avisaremos por aqui quando ele for enviado.",
        "example": { "body_text": [["Ana", "#10482", "R$ 189,90"]] }
      },
      { "type": "FOOTER", "text": "Loja Exemplo" }
    ]
  }'

O template fica PENDING até a aprovação da Meta. Confira o caminho exato e os exemplos na documentação de criação de templates.

Status de entrega

Rastreio é o caso mais natural de utilidade: a Meta lista “seu pacote está a caminho, o código de rastreio é X e a previsão de entrega é Y” entre os exemplos de gestão de pedidos. Um botão de URL com parte dinâmica leva o cliente direto à página de rastreio do pedido:

{
  "messaging_product": "whatsapp",
  "to": "5584999999999",
  "type": "template",
  "template": {
    "name": "pedido_enviado",
    "language": { "code": "pt_BR" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "#10482" },
          { "type": "text", "text": "24/10" }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [{ "type": "text", "text": "10482" }]
      }
    ]
  }
}

Não mande uma mensagem para cada evento da transportadora. Escolha os marcos que importam para o cliente (enviado, saiu para entrega, entregue, problema na entrega) e ignore os eventos internos de triagem.

Recuperação de carrinho

O lembrete de carrinho abandonado aparece nas diretrizes da Meta como exemplo de retargeting, que é marketing “mesmo se solicitado pelo usuário”. Isso traz três consequências:

Precisa de opt-in de marketing. O consentimento para receber avisos do pedido não cobre ofertas. Peça os dois separadamente no checkout.
Está sujeito ao limite por usuário. A Meta pode deixar de entregar templates de marketing para quem já recebeu muitos, com erro 131049. Parte dos lembretes não vai chegar, e isso é esperado.
Custa mais. Para destinatários no Brasil, marketing custa R$ 0,3217 por mensagem entregue, contra R$ 0,0350 de utilidade.

Não tente passar o lembrete de carrinho como utilidade. Quando a Meta detecta uma empresa classificando marketing como utilidade de forma recorrente, as restrições escalam: aviso, limite de volume de utilidade por no mínimo 7 dias, conversão de todos os templates de utilidade da conta em marketing por 7 dias (30 em reincidência) e, se o problema se espalhar, a mesma restrição em todo o portfólio por 30 dias.

Para o carrinho, um único lembrete algumas horas depois do abandono, com o link do carrinho e um botão de saída, costuma ser suficiente. O guia de disparo em massa pela API oficial cobre opt-in, opt-out e limites de marketing em detalhe.

Pós-venda

O pós-venda mistura as duas categorias, e o texto decide qual se aplica:

Pesquisa sobre o pedido. “Entregamos seu pedido #10482. Teve algum problema?” é utilidade. A Meta exige que a pesquisa seja específica de um pedido ou interação; uma pesquisa genérica não é aprovada como utilidade.
Troca e devolução. Confirmação de recebimento do item devolvido e do reembolso é utilidade.
Recompra, avaliação com cupom, lançamento. Tudo isso é marketing.

Quando o cliente responde, abre-se a janela de 24 horas e o atendimento pode seguir com mensagens livres. Desde 1º de outubro de 2026, templates de utilidade enviados dentro dessa janela passaram a ser cobrados normalmente, e as respostas livres têm franquia de 1.000 mensagens de serviço por número por mês (página de preços). Veja janela de 24 horas do WhatsApp.

Quanto custa notificar um pedido

Mensagem	Categoria	Tarifa Meta por entregue (Brasil)
Confirmação, pagamento, envio, entrega	Utilidade	R$ 0,0350
Carrinho abandonado, recompra, cupom	Marketing	R$ 0,3217
Resposta livre no atendimento	Serviço	Grátis até 1.000 por número no mês; depois R$ 0,0350

Uma loja que envia quatro avisos de utilidade por pedido paga cerca de R$ 0,14 por pedido à Meta, sem contar faixas de volume. Utilidade tem desconto progressivo por volume mensal no portfólio; marketing não tem. Os detalhes estão em preço da API do WhatsApp no Brasil, e as tarifas oficiais na tabela do WhatsApp Business.

Opt-in no checkout

O checkout é o melhor lugar para pedir consentimento, porque o cliente já está informando o telefone. A Meta pede que o opt-in deixe claro que a pessoa aceita receber comunicações e de qual empresa, e recomenda opt-ins separados por categoria de mensagem (Get opt-in for WhatsApp). Para uma loja, isso vira duas caixas de seleção independentes:

Avisos do pedido: “Quero receber pela Loja Exemplo, no WhatsApp, avisos sobre meus pedidos (confirmação, pagamento, envio e entrega).”
Ofertas: “Quero receber ofertas e novidades da Loja Exemplo por WhatsApp. Posso cancelar quando quiser.”

Deixe as duas desmarcadas, para que cada uma seja uma escolha ativa do cliente. Guarde data, hora, origem e o texto aceito para cada uma. Quem desmarcar ofertas continua recebendo os avisos do pedido, e quem pedir para sair de tudo precisa parar de receber as duas categorias, como exige a política da Meta.

Integração com os eventos da loja

A maioria das plataformas de e-commerce envia webhooks quando um pedido muda de status. A integração com o WhatsApp é um serviço que traduz esses eventos em templates:

Plataforma da loja ──webhook──▶ seu serviço ──▶ fila ──▶ worker
                                                        │
                       mapeia evento ▶ template ▶ POST /api/messages (Vectalk)
                                                        │
Vectalk ──webhook de status──▶ seu serviço (entregue, lida, falha)

Princípios que evitam os problemas mais comuns:

Idempotência. Plataformas reenviam webhooks. Use o par pedido e evento como chave e não envie o mesmo aviso duas vezes.
Consentimento por categoria. Guarde opt-in de pedidos e de marketing separados e consulte antes de cada envio.
Telefone normalizado. A API espera o número no formato internacional sem o “+”, como 5584999999999. Valide no checkout.
Registro do ID da mensagem. Guarde o wamid devolvido pela API junto do pedido para cruzar com os status e com o atendimento.

Exemplo em Node.js

O exemplo recebe eventos genéricos da loja e envia o template correspondente. Adapte os nomes dos eventos e o formato do corpo à sua plataforma.

import express from 'express';

const VECTALK = 'https://apis.vectalk.com.br/api/messages';
const TOKEN = process.env.VECTALK_TOKEN; // token de instância

// evento da loja -> template e parâmetros
const MAPA = {
  'pedido.criado': (p) => ({
    name: 'pedido_confirmado',
    body: [p.cliente.nome, `#${p.numero}`, p.totalFormatado],
  }),
  'pedido.pago': (p) => ({
    name: 'pagamento_aprovado',
    body: [p.cliente.nome, `#${p.numero}`],
  }),
  'pedido.enviado': (p) => ({
    name: 'pedido_enviado',
    body: [`#${p.numero}`, p.previsaoEntrega],
    botaoUrl: String(p.numero),
  }),
  'pedido.entregue': (p) => ({
    name: 'pedido_entregue',
    body: [p.cliente.nome, `#${p.numero}`],
  }),
};

const enviados = new Set(); // em produção: tabela com chave única (pedido, evento)

function montarTemplate({ name, body, botaoUrl }) {
  const components = [
    { type: 'body', parameters: body.map((text) => ({ type: 'text', text })) },
  ];
  if (botaoUrl) {
    components.push({
      type: 'button', sub_type: 'url', index: '0',
      parameters: [{ type: 'text', text: botaoUrl }],
    });
  }
  return { name, language: { code: 'pt_BR' }, components };
}

async function notificar(evento, pedido) {
  const regra = MAPA[evento];
  if (!regra || !pedido.cliente.optinPedidos) return;

  const chave = `${pedido.numero}:${evento}`;
  if (enviados.has(chave)) return;

  const r = await fetch(VECTALK, {
    method: 'POST',
    headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      messaging_product: 'whatsapp',
      to: pedido.cliente.whatsapp, // ex.: 5584999999999
      type: 'template',
      template: montarTemplate(regra(pedido)),
    }),
  });

  if (!r.ok) throw new Error(`Falha ao notificar ${chave}: ${await r.text()}`);
  const { messages } = await r.json();
  enviados.add(chave);
  return messages[0].id; // salve junto do pedido
}

const app = express();
app.use(express.json());

app.post('/loja/eventos', (req, res) => {
  res.sendStatus(200); // responde rápido; processa em seguida
  const { evento, pedido } = req.body;
  notificar(evento, pedido).catch((e) => console.error(e));
});

app.listen(3000);

Para produção, troque o Set por uma tabela com chave única e o processamento direto por uma fila com novas tentativas. Valide também a assinatura que a sua plataforma de e-commerce envia nos webhooks dela.

Lendo os status de volta

Os eventos de status chegam no webhook que você registrou na Vectalk, com o mesmo payload da Meta. Com eles, a loja sabe se o aviso foi entregue e lido, e pode acionar outro canal quando a mensagem falha. O artigo webhooks da API do WhatsApp mostra como estruturar esse receptor.

Perguntas frequentes

Posso colocar um cupom na confirmação do pedido?

Pode, mas o template passa a ser marketing. A Meta considera marketing qualquer template com conteúdo misto, como uma atualização de pedido com promoção. Mantenha avisos e ofertas em templates separados.

O cliente precisa autorizar os avisos de pedido?

Sim. A política da Meta exige opt-in antes de enviar mensagens. Um checkbox no checkout, separado do de ofertas, resolve os dois casos e mostra ao cliente o que ele vai receber.

Dá para mostrar produtos do catálogo no WhatsApp?

Sim. A API tem mensagens de produto único, multiproduto e catálogo, e há templates de marketing específicos para catálogo e carrossel de produtos. A Vectalk documenta o envio em mensagens de produto.

Quantos lembretes de carrinho posso mandar?

A Meta não fixa um número, mas aplica o limite por usuário de marketing e mede a qualidade pelos bloqueios e denúncias. Um lembrete por carrinho, com botão de saída, é um ponto de partida conservador.

Funciona com o número que a loja já usa no app?

Com coexistência, o mesmo número pode continuar no app WhatsApp Business enquanto os avisos automáticos saem pela API. Veja coexistência na API do WhatsApp.

Comece na Vectalk

Na Vectalk, a sua loja envia com os mesmos payloads da Meta e recebe os mesmos webhooks, com um token para todas as contas e coexistência com o app. O custo das mensagens vem na fatura da Vectalk, sem cartão cadastrado na Meta. Crie sua conta em apps.vectalk.com.br/register ou fale com o time pela página de contato.

Fontes oficiais consultadas em 20/10/2026: Categorização de templates, Templates de marketing, Limites por usuário de marketing, Preços, Tabela de preços no site do WhatsApp Business, Get opt-in for WhatsApp.