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.
Antes de empezar
Sección titulada «Antes de empezar»- Una conexión de WhatsApp activa y el permiso
catalog_managementconcedido a la app de Meta (sin él,403commerce_permission_missing). - Clave con
commercepara catálogos, productos, configuración y pago manual,sendpara los mensajes yreadpara leer. En el panel, Ventas. - Valores siempre en centavos (
amount_minor, entero).R$ 12,90=1290.
Catálogo y productos
Sección titulada «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 |
{ "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
Sección titulada «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. Las plantillas con catálogo o varios productos usan el formato de Meta, como cualquier plantilla.
Recibir el carrito
Sección titulada «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
Sección titulada «Cobrar con Pix»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: 100en todos los valores yaction.name: "review_and_pay";subtotal= suma decantidad × (sale_amount ?? amount)ytotal=subtotal + tax + shipping − discount; si no coincide →422order_totals_mismatch;reference_idúnico en la conexión, de 1 a 35 caracteres (letras, números,_,.,-); repetido →409order_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(urihttps) yboleto(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
Sección titulada «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:
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
Sección titulada «Avance del pedido»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 → completedcart_received | pending | processing → canceledUna transición fuera de este camino → 409 order_invalid_transition.
Eventos
Sección titulada «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 } }) |