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.
Antes de começar
Seção intitulada “Antes de começar”- Uma conexão de WhatsApp ativa e a permissão
catalog_managementconcedida ao app da Meta (sem ela,403commerce_permission_missing). - Chave com
commercepara catálogos, produtos, configurações e pagamento manual,sendpara as mensagens ereadpara ler. No painel, Vendas. - Valores sempre em centavos (
amount_minor, inteiro).R$ 12,90=1290.
Catálogo e produtos
Seção intitulada “Catálogo e produtos”| 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.
Mostrar produtos
Seção intitulada “Mostrar produtos”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.
Receber o carrinho
Seção intitulada “Receber o carrinho”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}.
Cobrar com Pix
Seção intitulada “Cobrar com Pix”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: 100em todos os valores eaction.name: "review_and_pay";subtotal= soma dequantidade × (sale_amount ?? amount)etotal=subtotal + tax + shipping − discount; não bate →422order_totals_mismatch;reference_idúnico na conexão, de 1 a 35 caracteres (letras, números,_,.,-); repetido →409order_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(urihttps) eboleto(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.
Conciliar o pagamento
Seção intitulada “Conciliar o pagamento”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:
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.
Andamento do pedido
Seção intitulada “Andamento do pedido”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 → completedcart_received | pending | processing → canceledTransição fora desse caminho → 409 order_invalid_transition.
Eventos
Seção intitulada “Eventos”| 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 } }) |