# Ventas en WhatsApp

> Catálogo, productos, carrito y cobro con Pix, enlace de pago o boleto: cómo armar, enviar y conciliar un pedido.

WhatsApp vende en tres pasos: el contacto ve el **catálogo**, arma un **carrito** y tú envías el **cobro** (`order_details`) con Pix, enlace de pago o boleto. Messajo guarda cada pedido, calcula los totales y avisa por evento.

## Antes de empezar

- Una conexión de WhatsApp activa y el permiso `catalog_management` concedido a la app de Meta (sin él, `403` [`commerce_permission_missing`](/es/errors#commerce_permission_missing)).
- Clave con `commerce` para catálogos, productos, configuración y pago manual, `send` para los mensajes y `read` para leer. En el panel, **Ventas**.
- Valores siempre en **centavos** (`amount_minor`, entero). `R$ 12,90` = `1290`.

## Catálogo y productos

| Llamada | Qué hace |
|---|---|
| `POST /v1/catalogs` | crea un catálogo en el portafolio y lo vincula a la cuenta de mensajería (`{ connection_id, name }`) |
| `POST /v1/catalogs/link` · `POST /v1/catalogs/{id}/unlink` | vincula un catálogo que ya existe (`catalog_external_id`) o lo desvincula |
| `POST /v1/catalogs/{id}/sync` | vuelve a leer los productos de Meta (también corre a diario) |
| `GET` · `PUT /v1/connections/{id}/commerce-settings` | `is_cart_enabled` (carrito) e `is_catalog_visible` (ícono de la tienda) |
| `GET` · `POST /v1/catalogs/{id}/products` | lista y crea productos |
| `GET` · `PATCH` · `DELETE /v1/products/{id}` | lee, cambia y borra |

```json
{
  "retailer_id": "torta-zanahoria",
  "name": "Torta de zanahoria",
  "amount_minor": 4500,
  "sale_amount_minor": 3900,
  "currency": "BRL",
  "availability": "in stock",
  "image_url": "https://tienda.tuempresa.com/img/torta.jpg"
}
```

El `retailer_id` es tu código del producto: es el que va en los mensajes y vuelve en el carrito.

## Mostrar productos

Por el `POST /v1/messages`, con `type: "interactive"`:

| `interactive.type` | Qué muestra |
|---|---|
| `product` | un producto (`action.catalog_id` + `product_retailer_id`) |
| `product_list` | hasta 30 productos en hasta 10 secciones, con encabezado de texto |
| `catalog_message` | el catálogo entero, con un producto de portada (`thumbnail_product_retailer_id`) |

Un catálogo que no está vinculado a la cuenta → `409` [`catalog_not_linked`](/es/errors#catalog_not_linked). Las plantillas con catálogo o varios productos usan el formato de Meta, como cualquier [plantilla](/es/start/concepts/).

## Recibir el carrito

El contacto envía el carrito y llegan `message.received` (contenido `order`) y `order.received`, con el pedido en `cart_received`, los ítems y los totales calculados con los precios del carrito. Léelo después con `GET /v1/orders` o `GET /v1/orders/{id}`.

## Cobrar con Pix

Envía un `order_details` con `payment_type: "br"`:

```json
{
  "connection_id": "conn_...",
  "to": "5511999990001",
  "type": "interactive",
  "interactive": {
    "type": "order_details",
    "body": { "text": "Tu 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": "Pastelería Ejemplo",
              "key": "39580525000189",
              "key_type": "CNPJ"
            }
          }
        ],
        "order": {
          "status": "pending",
          "items": [{ "retailer_id": "torta-zanahoria", "name": "Torta de zanahoria", "amount": { "value": 3900, "offset": 100 }, "quantity": 1 }],
          "subtotal": { "value": 3900, "offset": 100 }
        }
      }
    }
  }
}
```

Messajo revisa antes de llamar a Meta:

- `currency: "BRL"`, `offset: 100` en todos los valores y `action.name: "review_and_pay"`;
- `subtotal` = suma de `cantidad × (sale_amount ?? amount)` y `total` = `subtotal + tax + shipping − discount`; si no coincide → `422` [`order_totals_mismatch`](/es/errors#order_totals_mismatch);
- `reference_id` único en la conexión, de 1 a 35 caracteres (letras, números, `_`, `.`, `-`); repetido → `409` [`order_reference_taken`](/es/errors#order_reference_taken);
- de 1 a 3 formas de pago, sin repetir tipo: `pix_dynamic_code` (el código copia y pega de tu PSP, nombre, clave y tipo de clave), `payment_link` (`uri` https) y `boleto` (`digitable_line`);
- hasta 100 ítems.

Requisitos de Pix: el código dinámico viene de **tu** PSP (banco o pasarela), con el valor del pedido; la clave tiene que ser de la misma cuenta. Meta solo muestra el código al contacto.

Después del envío, el pedido queda `pending` con `payment_status: pending` y sale `order.updated`. Con el parámetro `expiration` de Meta, el pedido vencido pasa a `payment_status: expired`.

## Conciliar el pago

El Pix fuera de la plataforma **no** tiene webhook de pago: Meta no sabe si el contacto pagó. Concilia en tu PSP por el `reference_id` (usa el mismo id en el cobro del PSP) y avisa a 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` envía al contacto un `order_status` `processing` (con `message` opcional) y la respuesta trae `notification_message_id`. En el panel, el pedido tiene **Marcar como pagado**. El enlace de pago y la tarjeta con webhook de Meta se actualizan solos y generan `payment.updated`.

## Avance del pedido

Envía `order_status` (`action.name: "review_order"`) para avisar al contacto: `processing`, `partially_shipped`, `shipped`, `completed` o `canceled`.

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

Una transición fuera de este camino → `409` [`order_invalid_transition`](/es/errors#order_invalid_transition).

## Eventos

| Tipo | Cuándo |
|---|---|
| `order.received` | llegó un carrito |
| `order.updated` | cobro enviado, cambió el estado, pago marcado o vencido |
| `payment.updated` | Meta avisó el pago (`{ order: { id, reference_id }, payment: { status, method, transaction } }`) |
