# 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

- Uma conexão de WhatsApp ativa e a permissão `catalog_management` concedida ao app da Meta (sem ela, `403` [`commerce_permission_missing`](/errors#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`.

## 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 |

```json
{
  "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

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`](/errors#catalog_not_linked). Templates com catálogo ou vários produtos usam o formato da Meta, como qualquer [template](/start/concepts/).

## 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

Mande um `order_details` com `payment_type: "br"`:

```json
{
  "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`](/errors#order_totals_mismatch);
- `reference_id` único na conexão, de 1 a 35 caracteres (letras, números, `_`, `.`, `-`); repetido → `409` [`order_reference_taken`](/errors#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`.

## 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:

```bash
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

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

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

Transição fora desse caminho → `409` [`order_invalid_transition`](/errors#order_invalid_transition).

## 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 } }`) |
