Ir al contenido

Guías

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.

  • Una conexión de WhatsApp activa y el permiso catalog_management concedido a la app de Meta (sin él, 403 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.
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
{
"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.

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. Las plantillas con catálogo o varios productos usan el formato de Meta, como cualquier plantilla.

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}.

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

{
"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;
  • reference_id único en la conexión, de 1 a 35 caracteres (letras, números, _, ., -); repetido → 409 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.

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:

Ventana de 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 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.

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

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

Una transición fuera de este camino → 409 order_invalid_transition.

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