Detalles y estado de pedidos de WhatsApp

**Nota:** Order Details solo está disponible para **cuentas de pago de Brasil** y todos los valores se expresan en **BRL**.

Descripción general

WhatsApp Order Details permite que una empresa envíe a un cliente una solicitud de pago y un pedido detallado con su valor total y una o varias opciones de pago brasileñas, todo dentro de una conversación de WhatsApp. El cliente puede pagar sin salir de WhatsApp, por ejemplo, copiando un código Pix dinámico en su aplicación bancaria o abriendo un enlace de pago. Después, la empresa puede informar el avance del pedido mediante un mensaje de Order Status.

TODO_IMAGE[imagen de la interfaz]: revisar imagen desde Confluence.

En OneChat, la función se ofrece mediante dos pasos del flow:

• **WhatsApp Order Details:** envía el mensaje del pedido o factura junto con las opciones de pago.
• **WhatsApp Order Status:** envía un mensaje de seguimiento que actualiza el estado del pedido y del pago, por ejemplo, en proceso, enviado o pagado.

TODO_IMAGE[Pasos WhatsApp Order Details y WhatsApp Order Status del flow]: revisar imagen desde Confluence.

_Los dos pasos tal como aparecen en Flow Builder, cada uno con una rama “If send WhatsApp failed”._

Ambas son funciones de **plantillas de mensajes** de WhatsApp. Por lo tanto, debes crear la plantilla correspondiente en OneChat y obtener la aprobación de Meta antes de enviar mensajes.

Cómo funciona

1. El cliente conversa con la empresa y elige qué desea comprar.

2. La empresa envía un mensaje de **WhatsApp Order Details** con el detalle del pedido, el total en BRL y las opciones de pago.

TODO_IMAGE[imagen de la interfaz]: revisar imagen desde Confluence.

3. El cliente paga. Si usa Pix, copia el código y realiza el pago en su aplicación bancaria; si usa un enlace de pago, el checkout se abre en el navegador; y si usa boleto, copia el código correspondiente.

4. La empresa envía un mensaje de **WhatsApp Order Status** para actualizar el estado del pedido, por ejemplo, a “processing”, y el estado del pago.

TODO_IMAGE[imagen de la interfaz]: revisar imagen desde Confluence.

Cada pedido incluye un **ID de referencia** único, que el cliente ve como “Nº da cobrança”. WhatsApp **no** concilia los pagos. Tu proveedor de servicios de pago (PSP) confirma el pago y tú debes asociarlo con el pedido mediante este ID de referencia.

Requisitos

Antes de usar Order Details necesitas:

• **Un número brasileño de WhatsApp Business** conectado a tu workspace de OneChat.
• **Una plantilla aprobada de Order Details**. Consulta “Crear la plantilla de Order Details”. Meta no permite agregar opciones de pago al crear la plantilla; estas se incorporan únicamente al enviar el mensaje.
• Para realizar pruebas, **un segundo número brasileño** que reciba los mensajes. No es posible entregar mensajes a números de línea fija. Consulta “Limitaciones y problemas conocidos”.

Crear la plantilla de Order Details

Los mensajes de Order Details se envían desde una plantilla aprobada. Para crearla en OneChat:

1. Abre el administrador de plantillas del canal de WhatsApp y selecciona **Add New Template**.

2. Completa los campos de la plantilla:

• **Name**: obligatorio, con un máximo de 200 caracteres. Debe escribirse en inglés, en minúsculas y con guiones bajos; por ejemplo, test_order_details.
• **Category / Type**: obligatorio. Selecciona UTILITY o MARKETING.
• **Language**: obligatorio. El idioma del cuerpo y del pie de página debe coincidir con esta selección; por ejemplo, Portuguese (BR).

3. En **Interactive component**, selecciona **Order details**. Aparecerá la etiqueta “Brazil only”, que confirma que la plantilla utiliza pagos brasileños en BRL. Las otras opciones, Buttons y Call permission request, corresponden a tipos de plantilla diferentes.

4. Selecciona el tipo de **Header**: None, Text, Image o Document. Elige **Document** para adjuntar un **PDF**, como una factura o un boleto, en el encabezado.

5. Escribe el **Body**, que es obligatorio y admite hasta 1.000 caracteres. Usa el control de variables </> para insertar datos como el nombre del cliente, el valor y la fecha de vencimiento.

6. Opcionalmente, agrega un **Footer** de hasta 60 caracteres.

7. Selecciona **Send to review**. La plantilla se enviará a Meta para su clasificación y revisión. Cuando se apruebe, su estado cambiará a **Active** y podrás utilizarla para enviar mensajes.

TODO_IMAGE[imagen de la interfaz]: revisar imagen desde Confluence.

_Creación de una plantilla de Order Details en OneChat: categoría Marketing o Utility, idioma Portuguese (BR) y componente interactivo Order details._

| **Regla del encabezado:** El **tipo de encabezado no puede cambiarse después de crear la plantilla**. Meta solo permite editar posteriormente plantillas creadas con un encabezado de **imagen o documento**. Si existe la posibilidad de que necesites modificar la plantilla, créala desde el principio con uno de esos encabezados. |

| --- |

| **Nota:** La vista previa durante la creación, que muestra un único botón “Review and pay”, **no** representa exactamente el mensaje final. Los métodos de pago y sus botones no forman parte de la plantilla; se agregan al enviar el mensaje y Meta define sus etiquetas. |

Enviar el mensaje con WhatsApp Order Details

Agrega un paso **WhatsApp Order Details** al flow y selecciona la plantilla aprobada. Al configurar el paso debes definir:

• **Payment method:** método de pago brasileño que ofrecerás: código Pix dinámico, boleto, enlace de pago o tarjeta. Consulta “Métodos de pago”.
• **Item Type:** por ejemplo, Digital goods.
• **Item Name:** artículo que aparecerá en la tarjeta del pedido; por ejemplo, Invoice payment.
• **Total Amount:** valor total en BRL; por ejemplo, 500.00.
• **Reference ID:** identificador único del cobro o pedido, que el cliente verá como “Nº da cobrança”.
• **Body variables:** valores de las variables definidas en la plantilla, como nombre, valor y fecha de vencimiento. Si el encabezado es un documento, también debes proporcionar la **URL del PDF** y un **nombre de archivo**.

Cada valor puede establecerse como **predeterminado en la plantilla** o enviarse como **valor en tiempo de ejecución**, por ejemplo, desde un campo de usuario o desde la salida de un paso anterior.

Si el mensaje no puede enviarse, la rama **“If send WhatsApp failed”** dirige al contacto al siguiente paso que hayas seleccionado. Consulta “Gestión de errores y solución de problemas”.

Actualizar el pedido con WhatsApp Order Status

Agrega un paso **WhatsApp Order Status** para enviar una actualización de un pedido existente. Debes configurar:

• **Body:** texto del mensaje, con un máximo de 1.024 caracteres. Puedes incluir mediante variables el estado del pedido y del pago.
• **Footer:** opcional, con un máximo de 60 caracteres.
• **Order Status** y **Payment Status:** valores estructurados que controlan el estado del pedido en WhatsApp. Los valores permitidos aparecen a continuación.

| **Estado del pedido (order_status)** | **Estado del pago (payment_status)** |

| --- | --- |

| pending, processing, partially_shipped, shipped, completed, canceled | pending, captured, failed |

Métodos de pago

Order Details admite los siguientes métodos de pago brasileños. Meta genera y localiza las etiquetas de los botones, por lo que **no pueden personalizarse**:

• **Código Pix dinámico:** botón “Copiar código Pix”. Debes proporcionar code, merchant_name, key y key_type, por ejemplo, CNPJ. Meta crea automáticamente el botón para copiar.
• **Boleto:** botón “Copiar código do boleto”.
• **Enlace de pago:** botón “Abrir link de pagamento”.
• **Tarjeta Visa o Mastercard:** se muestra en la fila “Pagar com”.

Cuando configuras más de una opción de pago, el cliente ve las opciones principales como botones directos y las restantes agrupadas bajo **“Mais formas de pagar”**, es decir, más formas de pago. Los botones exactos dependen del método y son controlados por Meta.

Lo que ve el cliente

El mensaje de Order Details aparece como una tarjeta con el valor total, una fila “Pagar com” con los iconos de los métodos disponibles, el texto del cuerpo y los botones de pago. Un mensaje independiente de Order Status muestra el estado actual del pedido y del pago.

TODO_IMAGE[Mensaje de Order Details mostrado en WhatsApp]: revisar imagen desde Confluence.

_Ejemplo: mensaje de Order Details por R$ 100,00 con Pix, boleto, Visa y Mastercard; botones “Copiar código Pix”, “Abrir link de pagamento” y “Mais formas de pagar”; y una actualización posterior de Order Status._

Limitaciones y problemas conocidos

• **El tipo de encabezado es permanente.** No puedes cambiarlo después de crear la plantilla. Meta solo permite editar plantillas creadas con un encabezado de imagen o documento.
• **Meta define las etiquetas de los botones.** El texto de los botones de pago, como “Copiar código Pix”, no puede personalizarse. Meta lo genera y localiza según el idioma de la plantilla. Un texto personalizado no supera la validación de la API de Meta.
• **El encabezado PDF solo funciona en plantillas.** Se admite un encabezado PDF o de documento en las _plantillas_ de Order Details, pero no en mensajes interactivos de Order Details.
• **Descarga del PDF en dispositivos móviles.** Durante las pruebas, un PDF adjunto en el encabezado no pudo descargarse desde la aplicación de WhatsApp para Android, pero sí desde WhatsApp Desktop y WhatsApp Web. Parecía ser un problema de Meta; verifica el comportamiento en tu propia cuenta.
• **No se entrega a números de línea fija.** Los mensajes no llegan a líneas fijas; sí funcionan con un número estándar de WhatsApp Business. Los intentos no entregados devuelven el error 131026 de Meta, “Message undeliverable”.
• **Los métodos de pago no se definen al crear la plantilla.** Solo pueden agregarse al enviar el mensaje, por lo que la vista previa del constructor difiere del mensaje final.

Gestión de errores y solución de problemas

• **Rama “If send WhatsApp failed”.** Ambos pasos incluyen esta rama. Conéctala a una acción alternativa, como notificar a un agente, reintentar o enviar otro mensaje, para evitar que el contacto quede sin continuidad cuando falle el envío.
• **Error 131026, “Message undeliverable”.** Suele aparecer al enviar a una línea fija o a un número que no puede recibir el mensaje. Confirma que el destinatario tenga WhatsApp habilitado y que no sea una línea fija.
• **Mensajes entrantes duplicados.** Si los mensajes se duplican después de conectar el número, ve a Facebook > Settings & Privacy > Business Integrations y elimina la integración duplicada llamada “onechat”. Conserva la integración de la aplicación del chatbot.
• **Avisos ocasionales de “send failed” al probar plantillas.** Durante la validación de una plantilla nueva pueden aparecer avisos ocasionales antes de que quede completamente activa.

Referencia técnica de la API

La mayoría de los usuarios configura la función mediante los pasos de OneChat y no necesita utilizar directamente la API. A continuación se resumen las estructuras de Meta y OneChat para casos avanzados.

Estructura de la plantilla en Meta

• category: UTILITY o MARKETING.
• display_format: ORDER_DETAILS.
• Formato de HEADER: TEXT, IMAGE o DOCUMENT.
• Componentes: HEADER, BODY, FOOTER y un bloque BUTTONS con un único botón de tipo ORDER_DETAILS.

Valores monetarios

Los valores monetarios utilizan un par value + offset; el importe real es value ÷ offset. Por ejemplo, { "value": 55700, "offset": 100 } equivale a **R$ 557.00**.

Ejemplo de payload de envío: Pix dinámico con encabezado de texto

| { "messaging_product": "whatsapp", "recipient_type": "individual", "to": "<RECIPIENT_PHONE_NUMBER>", "type": "template", "template": { "name": "<TEMPLATE_NAME>", "language": { "policy": "deterministic", "code": "pt_BR" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "<CUSTOMER_NAME>" }, { "type": "text", "text": "<REFERENCE_ID>" } ] }, { "type": "button", "sub_type": "order_details", "index": 0, "parameters": [ { "type": "action", "action": { "order_details": { "reference_id": "<REFERENCE_ID>", "type": "digital-goods", "payment_type": "br", "payment_settings": [ { "type": "pix_dynamic_code", "pix_dynamic_code": { "code": "<DYNAMIC_PIX_COPY_PASTE_CODE>", "merchant_name": "<MERCHANT_NAME>", "key": "<PIX_KEY>", "key_type": "CNPJ" } } ], "currency": "BRL", "total_amount": { "value": 55700, "offset": 100 }, "order": { "status": "pending", "items": [ { "retailer_id": "<ITEM_ID>", "name": "<ITEM_NAME>", "amount": { "value": 55700, "offset": 100 }, "quantity": 1 } ], "subtotal": { "value": 55700, "offset": 100 }, "tax": { "value": 0, "offset": 100 } } } } } ] } ] } } |

| --- |

Endpoint de envío de OneChat

Define el nombre y el idioma de la plantilla junto con sus parámetros. Después, envía la plantilla aprobada a un suscriptor:

| POST /api/subscriber/send-whatsapp-template-by-user-id |

| --- |

Referencias

• Meta: enviar un mensaje de plantilla de detalles de pedido para Brasil (https://developers.facebook.com/documentation/business-messaging/whatsapp/payments/payments-br/orderdetailstemplate/)
• Meta: descripción general de Payments API para Brasil (https://developers.facebook.com/documentation/business-messaging/whatsapp/payments/payments-br/overview/)
• Meta: carga de archivos multimedia en Graph API para encabezados de documentos o imágenes (https://developers.facebook.com/docs/graph-api/guides/upload)