Pular para o conteúdo

Guias

Vendas no WhatsApp

Catálogo, produtos, carrinho e cobrança com Pix, link de pagamento ou boleto: como montar, mandar e conciliar um pedido.

O WhatsApp vende em três passos: o contato vê o catálogo, monta um carrinho e você manda a cobrança (order_details) com Pix, link de pagamento ou boleto. O Messajo guarda cada pedido, calcula os totais e avisa por evento.

  • Uma conexão de WhatsApp ativa e a permissão catalog_management concedida ao app da Meta (sem ela, 403 commerce_permission_missing).
  • Chave com commerce para catálogos, produtos, configurações e pagamento manual, send para as mensagens e read para ler. No painel, Vendas.
  • Valores sempre em centavos (amount_minor, inteiro). R$ 12,90 = 1290.
Chamada O que faz
POST /v1/catalogs cria um catálogo no portfólio e liga à conta de mensagens ({ connection_id, name })
POST /v1/catalogs/link · POST /v1/catalogs/{id}/unlink liga um catálogo que já existe (catalog_external_id) ou desliga
POST /v1/catalogs/{id}/sync relê os produtos da Meta (também roda todo dia)
GET · PUT /v1/connections/{id}/commerce-settings is_cart_enabled (carrinho) e is_catalog_visible (ícone da loja)
GET · POST /v1/catalogs/{id}/products lista e cria produtos
GET · PATCH · DELETE /v1/products/{id} lê, altera e apaga
{
"retailer_id": "bolo-cenoura",
"name": "Bolo de cenoura",
"amount_minor": 4500,
"sale_amount_minor": 3900,
"currency": "BRL",
"availability": "in stock",
"image_url": "https://loja.suaempresa.com/img/bolo.jpg"
}

O retailer_id é o seu código do produto: é ele que vai nas mensagens e volta no carrinho.

Pelo POST /v1/messages, com type: "interactive":

interactive.type O que mostra
product um produto (action.catalog_id + product_retailer_id)
product_list até 30 produtos em até 10 seções, com header de texto
catalog_message o catálogo inteiro, com um produto de capa (thumbnail_product_retailer_id)

Um catálogo que não está ligado à conta → 409 catalog_not_linked. Templates com catálogo ou vários produtos usam o formato da Meta, como qualquer template.

O contato manda o carrinho e chegam message.received (conteúdo order) e order.received, com o pedido em cart_received, os itens e os totais calculados pelos preços do carrinho. Leia depois com GET /v1/orders ou GET /v1/orders/{id}.

Mande um order_details com payment_type: "br":

{
"connection_id": "conn_...",
"to": "5511999990001",
"type": "interactive",
"interactive": {
"type": "order_details",
"body": { "text": "Seu pedido" },
"action": {
"name": "review_and_pay",
"parameters": {
"reference_id": "pedido-1042",
"type": "digital-goods",
"payment_type": "br",
"currency": "BRL",
"total_amount": { "value": 3900, "offset": 100 },
"payment_settings": [
{
"type": "pix_dynamic_code",
"pix_dynamic_code": {
"code": "00020101021226…6304ABCD",
"merchant_name": "Doceria Exemplo",
"key": "39580525000189",
"key_type": "CNPJ"
}
}
],
"order": {
"status": "pending",
"items": [{ "retailer_id": "bolo-cenoura", "name": "Bolo de cenoura", "amount": { "value": 3900, "offset": 100 }, "quantity": 1 }],
"subtotal": { "value": 3900, "offset": 100 }
}
}
}
}
}

O Messajo confere antes de chamar a Meta:

  • currency: "BRL", offset: 100 em todos os valores e action.name: "review_and_pay";
  • subtotal = soma de quantidade × (sale_amount ?? amount) e total = subtotal + tax + shipping − discount; não bate → 422 order_totals_mismatch;
  • reference_id único na conexão, de 1 a 35 caracteres (letras, números, _, ., -); repetido → 409 order_reference_taken;
  • de 1 a 3 formas de pagamento, sem repetir tipo: pix_dynamic_code (o código copia-e-cola do seu PSP, nome, chave e tipo da chave), payment_link (uri https) e boleto (digitable_line);
  • até 100 itens.

Requisitos do Pix: o código dinâmico vem do seu PSP (banco ou gateway), com o valor do pedido; a chave tem que ser da mesma conta. A Meta só mostra o código ao contato.

Depois do envio, o pedido fica pending com payment_status: pending e sai order.updated. Com o parâmetro expiration da Meta, o pedido vencido vira payment_status: expired.

O Pix fora da plataforma não tem webhook de pagamento: a Meta não sabe se o contato pagou. Concilie no seu PSP pelo reference_id (use o mesmo id na cobrança do PSP) e avise o Messajo:

Janela do terminal
curl https://api.messajo.com/v1/orders/ord_.../payment \
-H "Authorization: Bearer $MESSAJO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "status": "captured", "notify": true }'

notify: true manda ao contato um order_status processing (com message opcional) e a resposta traz notification_message_id. No painel, o pedido tem Marcar como pago. Link de pagamento e cartão com webhook da Meta atualizam sozinhos e geram payment.updated.

Mande order_status (action.name: "review_order") para avisar o contato: processing, partially_shipped, shipped, completed ou canceled.

cart_received → pending → processing → partially_shipped → shipped → completed
cart_received | pending | processing → canceled

Transição fora desse caminho → 409 order_invalid_transition.

Tipo Quando
order.received chegou um carrinho
order.updated cobrança enviada, status mudou, pagamento marcado ou vencido
payment.updated a Meta avisou o pagamento ({ order: { id, reference_id }, payment: { status, method, transaction } })