Ir al contenido

Eventos recomendados

Los eventos recomendados se basan en un marco que envía eventos personalizados estandarizados con esquemas JSON definidos. Cuando envías un evento recomendado, Braze lo valida contra su esquema en la ingesta y aplica un procesamiento especializado, como cálculos automáticos de campos o gestión del carrito, que los eventos personalizados genéricos no reciben. Para ciertos conjuntos de eventos de la industria, Braze también admite un tratamiento especial, como acciones desencadenantes basadas en acciones dedicadas para Campaigns y Canvas.

Los eventos recomendados de comercio electrónico cubren seis pasos del recorrido de compra: product_viewed, cart_updated, checkout_started, order_placed, order_cancelled y order_refunded. Cuando envías correctamente estos eventos, Braze valida los datos y los pone a disposición de un conjunto cada vez mayor de características de la plataforma.

Estas características incluyen plantillas de Canvas para flujos de navegación abandonada, carrito abandonado, pago abandonado y confirmación de pedido; informes de comercio electrónico; y campos calculados del perfil de usuario para Ingresos totales, Pedidos totales y Reembolsos totales. También puedes crear Segments con filtrado de propiedades de producto anidadas mediante extensiones de segmento, personalizar mensajes de carrito abandonado con la etiqueta de Liquid {% shopping_cart %} y alimentar capacidades de BrazeAITM como Predictive Events, Predictive Churn y recomendaciones de artículos, entre otras capacidades.

Como estos eventos siguen un esquema definido, cada característica compatible puede leer los datos estructurados sin necesidad de mapeado de propiedades personalizado ni configuración por característica de tu parte.

Cómo funcionan los eventos de comercio electrónico

Los eventos de comercio electrónico son eventos personalizados con nombres y esquemas de propiedades predefinidos. Los envías mediante el Braze SDK, el endpoint de la REST API /users/track, la ingesta de datos en la nube (CDI) o la importación de CSV, y Braze valida cada evento con su esquema durante la ingesta. Cuando la validación se supera, Braze aplica automáticamente un posprocesamiento específico para ese tipo de evento, como calcular los campos de ingresos y gestionar el estado del carrito en los perfiles de usuario.

Los eventos de comercio electrónico funcionan en todos los lugares donde funcionan otros eventos personalizados: desencadenantes y filtros de eventos personalizados realizados, informes de eventos personalizados y más. Sin embargo, su validación de esquema desbloquea capacidades adicionales, como:

  • Acciones desencadenantes “Realiza un pedido” en Campaigns, Canvas, pasos de Rutas de Acción, desencadenantes de mensajes dentro de la aplicación y eliminación de tarjetas de contenido
  • Campos calculados de comercio electrónico en el perfil de usuario (Ingresos totales, Pedidos totales, Reembolsos totales)
  • Gestión del estado del carrito para flujos de carrito abandonado
  • Datos más completos para características de BrazeAITM como Predictive Events, Predictive Churn y recomendaciones de artículos

También puedes hacer referencia a los eventos de comercio electrónico por su nombre en cualquier lugar de la plataforma que admita eventos personalizados. Por ejemplo, puedes desencadenar una campaña basada en acciones con eventos ecommerce.product_viewed, crear un Segment que filtre por eventos ecommerce.checkout_started o exportar eventos ecommerce.order_placed a través de Currents.

Nomenclatura de eventos

Los nombres de los eventos son exactos, distinguen entre mayúsculas y minúsculas, y están delimitados por puntos. Usa siempre el formato canónico. Si el nombre de un evento no coincide exactamente con uno de los seis nombres canónicos, Braze lo trata como un evento personalizado estándar y no se realiza ningún posprocesamiento de comercio electrónico.

No puedes personalizar ni cambiar el nombre de los eventos.

  • Correcto: ecommerce.order_placed
  • Incorrecto: order.placed, eCommerce_order_placed, Order_Placed

Esquemas de eventos

Los seis eventos recomendados de comercio electrónico se corresponden con las etapas del recorrido de compra. Activa cada evento en el momento en que el usuario completa la acción correspondiente.

Diagrama del recorrido del usuario a través de los seis eventos recomendados de comercio electrónico: product_viewed, cart_updated, checkout_started, order_placed, order_cancelled y order_refunded.

Para el registro del lado del cliente, ecommerce.product_viewed, ecommerce.cart_updated, ecommerce.checkout_started y ecommerce.order_placed usan las API de eventos de comercio electrónico del SDK cuando están disponibles, mientras que ecommerce.order_cancelled y ecommerce.order_refunded usan logCustomEvent.

Los eventos de reembolso y cancelación suelen enviarse desde tu servidor a través de la REST API de Braze, porque normalmente dependen de que se complete una lógica del lado del servidor, como tu flujo de reembolsos. Para ver ejemplos de implementación específicos de cada plataforma, consulta Registrar eventos de comercio electrónico mediante el Braze SDK.

Se desencadena cuando un usuario ve la página de detalles de un producto. Este evento es compatible con las notificaciones de reposición de stock y las notificaciones de bajada de precio de los catálogos de Braze.

Implementación del lado del cliente

Usa las API de eventos de comercio electrónico del SDK cuando estén disponibles. Para ver ejemplos de implementación específicos de cada plataforma, consulta Registrar eventos de comercio electrónico mediante el Braze SDK.

Propiedades del evento

Nombre de la propiedad Tipo de datos Obligatorio Descripción
product_id Cadena Sí Identificador único del producto (por ejemplo, SKU o ID del artículo).
product_name Cadena Sí Nombre visible del producto.
variant_id Cadena Sí Identificador de la variante del producto (por ejemplo, shirt_medium_blue).
image_url Cadena No URL de la imagen del producto.
product_url Cadena No URL de la página del producto para obtener más detalles.
price Flotante Sí Precio unitario de la variante en el momento de la visualización.
currency Cadena Sí Código ISO 4217 de tres letras (por ejemplo, USD o EUR).
source Cadena Sí Origen del evento (por ejemplo, web, ios o android).
type Matriz de cadenas No Obligatorio para usar las características de desencadenantes de catálogo de Braze para alertas de reposición de stock y bajada de precio. Valores aceptados: "price_drop", "back_in_stock"
metadata Objeto No Pares clave-valor flexibles (por ejemplo, category o brand).

Ejemplo de REST API




{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.product_viewed",
      "time": "2026-04-28T14:22:11Z",
      "properties": {
        "product_id": "SKU-RUN-4821",
        "product_name": "Ultraboost Running Shoe",
        "variant_id": "UB-BLK-11",
        "image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
        "product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
        "price": 189.99,
        "currency": "USD",
        "source": "web",
        "type": ["price_drop", "back_in_stock"],
        "metadata": {
          "category": "Running Shoes",
          "brand": "Shoe Brand"
        }
      }
    }
  ]
}

Se desencadena cada vez que cambia el contenido del carrito de un usuario.

Implementación del lado del cliente

Usa las API de eventos de comercio electrónico del SDK cuando estén disponibles. Para ver ejemplos de implementación específicos de cada plataforma, consulta Registrar eventos de comercio electrónico mediante el Braze SDK.

Puedes enviar este evento de una de estas dos formas:

  • Sustitución completa del carrito: Omite action o establece action en replace. Incluye el conjunto completo de líneas de pedido en products con cantidades absolutas (unidades totales por variante en el carrito). Debes incluir total_value.
  • Actualizaciones incrementales del carrito: Establece action en add o remove. Incluye solo las líneas de pedido que hayan cambiado. Cada quantity es el número de unidades que se añaden o eliminan, no la cantidad total en el carrito. Para add, Braze aumenta la cantidad de la línea o añade una línea nueva. Para remove, Braze reduce la cantidad de la línea y la elimina cuando la cantidad llega a 0. total_value es opcional para add y remove.

Para desencadenar mensajería a partir de este evento, usa el desencadenante Perform Cart Updated Event en Canvas y Campaigns. Este desencadenante incluye un tratamiento especial para evitar que el carrito avance por el embudo de compra.

Propiedades del evento

Propiedad Tipo de datos Obligatorio Descripción
cart_id Cadena Sí Identificador único del carrito. Se comparte entre los eventos de carrito, pago y pedido para el mapeado del carrito del usuario.
action Cadena No add (aumenta la cantidad o añade una línea), remove (reduce la cantidad; la línea se elimina al llegar a 0) o replace (sustitución completa del carrito, igual que omitir action).
total_value Flotante Condicional Obligatorio cuando se omite action o es replace. Opcional cuando action es add o remove.
subtotal_value Flotante No Valor subtotal del carrito (tras descuentos, antes de impuestos y envío).
tax Flotante No Total de impuestos aplicados al carrito.
shipping Flotante No Coste total de envío del carrito.
currency Cadena Sí Código ISO 4217 de tres letras.
products Matriz Sí Líneas de pedido de esta actualización. Para la sustitución completa (sin action o con replace), incluye el carrito completo con cantidades absolutas. Para add o remove, incluye solo las líneas que hayan cambiado; consulta las propiedades del producto.
source Cadena Sí Origen del evento.
metadata Objeto No Pares clave-valor flexibles para datos adicionales a nivel de evento.

Propiedades del producto (products[])

Propiedad Tipo de datos Obligatorio Descripción
product_id Cadena Sí Identificador único del producto.
product_name Cadena Sí Nombre visible del producto.
variant_id Cadena Sí Identificador de la variante.
image_url Cadena No URL de la imagen del producto.
product_url Cadena No URL de la página del producto.
quantity Entero Sí Para la sustitución completa (sin action o con replace), unidades de esta línea en el carrito. Para add o remove, cuántas unidades se añaden o eliminan.
price Flotante Sí Precio unitario de la variante.
metadata Objeto No Pares clave-valor flexibles (por ejemplo, color o size).

Se desencadena cuando el usuario inicia el flujo de pago (por ejemplo, selecciona “Pagar” o llega a la página de pago).

Implementación del lado del cliente

Usa las API de eventos de comercio electrónico del SDK cuando estén disponibles. Para ver ejemplos de implementación específicos de cada plataforma, consulta Registrar eventos de comercio electrónico mediante el Braze SDK.

Propiedades del evento

Propiedad Tipo Obligatorio Descripción
checkout_id Cadena Sí Identificador único de la sesión de pago.
cart_id Cadena No Identificador del carrito. Se comparte entre los eventos de carrito, pago y pedido para el mapeado del carrito del usuario.
total_value Flotante Sí Valor monetario total del pago.
subtotal_value Flotante No Valor subtotal (tras descuentos, antes de impuestos y envío).
tax Flotante No Total de impuestos aplicados al pago.
shipping Flotante No Coste total de envío.
currency Cadena Sí Código ISO 4217 de tres letras.
products Matriz Sí Artículos que se están pagando. Consulta la subtabla de propiedades del producto.
source Cadena Sí Origen del evento.
metadata Objeto No Pares clave-valor flexibles. Subpropiedad reconocida: checkout_url (cadena)

Propiedades del producto (products[])

Propiedad Tipo de datos Obligatorio Descripción
product_id Cadena Sí Identificador único del producto.
product_name Cadena Sí Nombre visible del producto.
variant_id Cadena Sí Identificador de la variante.
image_url Cadena No URL de la imagen del producto.
product_url Cadena No URL de la página del producto.
quantity Entero Sí Número de unidades en el carrito.
price Flotante Sí Precio unitario de la variante.
metadata Objeto No Pares clave-valor flexibles (por ejemplo, color o talla).

Ejemplo de REST API




{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.checkout_started",
      "time": "2026-04-28T14:30:05Z",
      "properties": {
        "checkout_id": "chk_88291",
        "cart_id": "cart_abc123",
        "total_value": 234.96,
        "subtotal_value": 219.97,
        "tax": 9.0,
        "shipping": 5.99,
        "currency": "USD",
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
            "product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11"
            }
          },
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "image_url": "https://cdn.example.com/socks/soc-wht-l.jpg",
            "product_url": "https://www.example.com/products/performance-running-socks?variant=SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "checkout_url": "https://www.example.com/checkout/chk_88291",
          "checkout_type": "express"
        }
      }
    }
  ]
}

Se desencadena cuando un pedido se completa correctamente o se confirma el pago.

Implementación del lado del cliente

Usa las API de eventos de comercio electrónico del SDK cuando estén disponibles. Para ver ejemplos de implementación específicos de cada plataforma, consulta Registrar eventos de comercio electrónico mediante el Braze SDK.

Propiedades del evento

Propiedad Tipo de datos Obligatorio Descripción
order_id Cadena Sí Identificador único del pedido.
cart_id Cadena No Identificador del carrito. Se comparte entre los eventos de carrito, pago y pedido para el mapeado del carrito del usuario.
total_value Flotante Sí Valor monetario total del pedido.
subtotal_value Flotante No Valor subtotal (tras descuentos, antes de impuestos y envío).
tax Flotante No Total de impuestos aplicados al pedido.
shipping Flotante No Coste total de envío.
currency Cadena Sí Código ISO 4217 de tres letras.
total_discounts Flotante No Importe total de los descuentos aplicados al pedido.
discounts Matriz No Lista detallada de los descuentos aplicados.
products Matriz Sí Artículos del pedido. Consulta la subtabla de propiedades del producto.
source Cadena Sí Origen del evento.
metadata Objeto No Pares clave-valor flexibles. Subpropiedad reconocida: order_status_url (cadena)

Propiedades del producto (products[])

Propiedad Tipo de datos Obligatorio Descripción
product_id Cadena Sí Identificador único del producto.
product_name Cadena Sí Nombre visible del producto.
variant_id Cadena Sí Identificador de la variante.
image_url Cadena No URL de la imagen del producto.
product_url Cadena No URL de la página del producto.
quantity Entero Sí Número de unidades en el carrito.
price Flotante Sí Precio unitario de la variante.
metadata Objeto No Pares clave-valor flexibles (por ejemplo, color o size).

Ejemplo de REST API




{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_placed",
      "time": "2026-04-28T14:35:42Z",
      "properties": {
        "order_id": "ord_77821",
        "cart_id": "cart_abc123",
        "total_value": 224.96,
        "subtotal_value": 209.97,
        "tax": 9.0,
        "shipping": 5.99,
        "currency": "USD",
        "total_discounts": 10.0,
        "discounts": [
          {
            "code": "SPRING10",
            "amount": 10.0,
            "type": "percentage"
          }
        ],
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "image_url": "https://cdn.example.com/shoes/ub-blk-11.jpg",
            "product_url": "https://www.example.com/products/ultraboost-running-shoe?variant=UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11"
            }
          },
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "image_url": "https://cdn.example.com/socks/soc-wht-l.jpg",
            "product_url": "https://www.example.com/products/performance-running-socks?variant=SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "order_status_url": "https://www.example.com/orders/ord_77821/status"
        }
      }
    }
  ]
}

Se desencadena cuando se cancela un pedido.

Implementación del lado del cliente

Usa logCustomEvent. Para ver ejemplos de implementación específicos de cada plataforma, consulta Registrar eventos de comercio electrónico mediante el Braze SDK.

Propiedades del evento

Propiedad Tipo Obligatorio Descripción
order_id Cadena Sí Identificador único del pedido.
total_value Flotante Sí Valor monetario total del pedido que se cancela. Debe ser ≥ 0: envía el importe absoluto; Braze se encarga de la reducción.
subtotal_value Flotante No Valor subtotal (tras descuentos, antes de impuestos y envío).
tax Flotante No Total de impuestos aplicados al pedido.
shipping Flotante No Coste total de envío.
currency Cadena Sí Código ISO 4217 de tres letras.
total_discounts Flotante No Importe total de los descuentos aplicados al pedido.
discounts Matriz No Lista detallada de los descuentos aplicados.
cancel_reason Cadena Sí Motivo por el que se canceló el pedido.
products Matriz Sí Artículos del pedido cancelado. Consulta la subtabla de propiedades del producto.
source Cadena Sí Origen del evento.
metadata Objeto No Pares clave-valor flexibles. Subpropiedad reconocida: order_status_url (cadena)

Propiedades del producto (products[])

Propiedad Tipo de datos Obligatorio Descripción
product_id Cadena Sí Identificador único del producto.
product_name Cadena Sí Nombre visible del producto.
variant_id Cadena Sí Identificador de la variante.
image_url Cadena No URL de la imagen del producto.
product_url Cadena No URL de la página del producto.
quantity Entero Sí Número de unidades en el carrito.
price Flotante Sí Precio unitario de la variante.
metadata Objeto No Pares clave-valor flexibles (por ejemplo, color o size).

Ejemplo de REST API




{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_cancelled",
      "time": "2026-04-28T16:10:00Z",
      "properties": {
        "order_id": "ord_77821",
        "total_value": 224.96,
        "subtotal_value": 209.97,
        "tax": 9.0,
        "shipping": 5.99,
        "currency": "USD",
        "total_discounts": 10.0,
        "cancel_reason": "customer_request",
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11"
            }
          },
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "order_status_url": "https://www.example.com/orders/ord_77821/status"
        }
      }
    }
  ]
}

Se desencadena cuando se emite un reembolso total o parcial.

Implementación del lado del cliente

Usa logCustomEvent. Para ver ejemplos de implementación específicos de cada plataforma, consulta Registrar eventos de comercio electrónico mediante el Braze SDK.

Propiedades del evento

Propiedad Tipo de datos Obligatorio Descripción
order_id Cadena Sí Identificador único del pedido original.
total_value Flotante Sí Valor monetario total del reembolso. Debe ser ≥ 0: envía el importe absoluto; Braze se encarga del incremento de total_refunds.
currency Cadena Sí Código ISO 4217 de tres letras.
total_discounts Flotante No Importe total de los descuentos aplicados originalmente.
discounts Matriz No Lista detallada de descuentos.
products Matriz Sí Artículos que se reembolsan. Consulta la subtabla de propiedades del producto.
source Cadena Sí Origen del evento.
metadata Objeto No Pares clave-valor flexibles. Subpropiedad reconocida: order_status_url (cadena).

Propiedades del producto (products[])

Propiedad Tipo de datos Obligatorio Descripción
product_id Cadena Sí Identificador único del producto.
product_name Cadena Sí Nombre visible del producto.
variant_id Cadena Sí Identificador de la variante.
image_url Cadena No URL de la imagen del producto.
product_url Cadena No URL de la página del producto.
quantity Entero Sí Número de unidades en el carrito.
price Flotante Sí Precio unitario de la variante.
metadata Objeto No Pares clave-valor flexibles (por ejemplo, color o size).

Ejemplos de REST API




{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_refunded",
      "time": "2026-04-29T10:05:00Z",
      "properties": {
        "order_id": "ord_77821",
        "total_value": 189.99,
        "currency": "USD",
        "total_discounts": 0,
        "products": [
          {
            "product_id": "SKU-RUN-4821",
            "product_name": "Ultraboost Running Shoe",
            "variant_id": "UB-BLK-11",
            "quantity": 1,
            "price": 189.99,
            "metadata": {
              "color": "Core Black",
              "size": "11",
              "refund_reason": "size_mismatch"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "order_status_url": "https://www.example.com/orders/ord_77821/status"
        }
      }
    }
  ]
}






{
  "events": [
    {
      "external_id": "user_98765",
      "name": "ecommerce.order_refunded",
      "time": "2026-05-02T11:08:30Z",
      "properties": {
        "order_id": "ORD-20260428-7891",
        "total_value": 29.98,
        "currency": "USD",
        "products": [
          {
            "product_id": "SKU-SOC-1102",
            "product_name": "Performance Running Socks",
            "variant_id": "SOC-WHT-L",
            "image_url": "https://cdn.example.com/socks/soc-wht-l.jpg",
            "product_url": "https://www.example.com/products/performance-running-socks?variant=SOC-WHT-L",
            "quantity": 2,
            "price": 14.99,
            "metadata": {
              "color": "White",
              "size": "L"
            }
          }
        ],
        "source": "web",
        "metadata": {
          "refund_method": "store_credit",
          "initiated_by": "customer"
        }
      }
    }
  ]
}

Posprocesamiento de eventos de comercio electrónico

Cuando envías un evento de comercio electrónico, Braze lo valida con el esquema esperado para ese nombre de evento.

La siguiente tabla resume lo que Braze hace automáticamente con cada evento cuando se supera la validación. Para saber qué ocurre cuando la validación falla, consulta Validación de eventos y solución de problemas.

Evento Lo que Braze hace automáticamente
ecommerce.order_placed Incrementa Ingresos totales en total_value y Pedidos totales en 1 en el perfil de usuario.
ecommerce.order_cancelled Reduce Pedidos totales en 1.
ecommerce.order_refunded Reduce Ingresos totales en total_value e incrementa Valor total de reembolsos.
ecommerce.cart_updated Crea o actualiza el objeto de mapeado de carritos en el perfil de usuario (cargas útiles con el carrito completo o actualizaciones incrementales del carrito con el parámetro opcional action: add, remove o replace). El carrito caduca tras 30 días sin actualizaciones.
ecommerce.product_viewed Sin cambios en el perfil de usuario. Disponible para segmentación, desencadenantes y características de BrazeAITM (como las recomendaciones de artículos).
ecommerce.checkout_started Sin cambios en el perfil de usuario. Disponible para segmentación y desencadenantes (por ejemplo, flujos de pago abandonado).

Detalles de implementación

Puntos de datos y facturación

Los eventos de comercio electrónico no consumen puntos de datos. Puedes registrarlos sin ningún impacto en tu uso de puntos de datos.

Límite de tamaño de los eventos

Las propiedades del evento enviadas a /users/track tienen un límite de 102 400 bytes (100 KB) por evento. Para mensajes desencadenados de Campaign y Canvas, las trigger_properties enviadas a /campaigns/trigger/send y /canvas/trigger/send tienen un límite predeterminado más estricto de 51 200 bytes (50 KB).

Como práctica recomendada, envía solo la información del producto que necesites para desencadenar, personalizar o atribuir el evento. Almacena los detalles más completos del producto, como descripciones, listas completas de variantes, inventario o imágenes alternativas, en los catálogos de Braze. Haz referencia a estos detalles mediante product_id o variant_id al enviar mensajes. Usa el objeto metadata de forma selectiva para el contexto específico del pedido o del producto que vaya a usar la mensajería.

Gestión de divisas

Braze convierte automáticamente los valores en divisas distintas del USD a USD usando el tipo de cambio de la fecha en que se informa el evento. Este valor convertido es el que aparece en las métricas de ingresos.

Campo de origen

La propiedad de origen es una cadena obligatoria que identifica dónde se originó el evento. Por ejemplo, shopify, in-store POS o custom_api. Esto te ayuda a distinguir los orígenes de la integración al analizar datos en las exportaciones de Currents o al depurar problemas de validación.

Flexibilidad de los metadatos

Tanto el objeto de metadatos a nivel de evento como el de nivel de producto aceptan pares clave-valor arbitrarios, por lo que puedes adjuntar dimensiones personalizadas sin modificar el esquema principal. Algunos ejemplos comunes son order_status_url, gift_wrapped, loyalty_points_earned o warehouse_id. Estas propiedades están disponibles en la personalización con Liquid, en las exportaciones de Currents y en la segmentación mediante extensiones de segmento.

Validación de eventos y solución de problemas

Cuando envías un evento de comercio electrónico recomendado mediante /users/track o cualquier SDK de Braze, Braze valida la carga útil con el esquema JSON del evento durante su procesamiento. La validación se ejecuta automáticamente en cada evento cuyo nombre coincide exactamente con un evento recomendado (por ejemplo, ecommerce.order_placed o ecommerce.cart_updated).

Qué validamos

En cada evento cuyo nombre coincide con un evento recomendado de comercio electrónico, Braze comprueba lo siguiente:

Comprobación Ejemplo
Nombre del evento Debe ser exacto. Por ejemplo, ecommerce.cart_updated es correcto, pero no ecommerce.Cart_Updated, cartupdated ni cart_updated.
Propiedades obligatorias presentes order_placed requiere order_id, total_value, currency, products y source.
Tipos de datos correctos total_value debe ser un número; currency debe ser una cadena; products debe ser una matriz.
Sin propiedades adicionales de nivel superior Los campos personalizados dentro de properties provocan un error. Usa el objeto metadata en su lugar.
Restricciones de valores Los campos monetarios deben ser ≥ 0. currency debe ser una cadena ISO 4217 válida.
Campos por producto Cada elemento de products[] debe incluir product_id, product_name, variant_id, quantity y price.

Por qué validamos

Los eventos de comercio electrónico impulsan características que dependen de datos coherentes y predecibles, como el seguimiento de ingresos, la etiqueta de Liquid {% shopping_cart %}, el desencadenante de carrito abandonado y los informes. Cuando las cargas útiles se desvían del esquema, estas características generan imprecisiones silenciosas (totales de ingresos incorrectos, carritos que faltan, desencadenantes que no funcionan). La validación aplica el contrato desde el principio para que las características posteriores se comporten de forma predecible.

Cuando la validación se supera

El evento se procesa como un evento recomendado de comercio electrónico con todo el posprocesamiento asociado. Consulta Eventos recomendados de comercio electrónico para ver la lista completa de comportamientos que desencadena cada tipo de evento.

Verificar un evento correcto

Después de enviar un evento, puedes confirmar que se aceptó y se procesó correctamente de cualquiera de estas formas:

  • Registro de usuarios del evento: Abre el perfil del usuario en el panel y revisa su actividad. Los eventos recomendados aparecen con su carga útil completa de propiedades, así que puedes confirmar que el evento llegó y que los valores coinciden con lo que enviaste.
  • Informe de eventos personalizados: Ve a Análisis > Informe de eventos personalizados para ver los recuentos agregados de cada evento recomendado a lo largo del tiempo. Es útil para confirmar que el tráfico de producción fluye como se espera cuando tu integración está en vivo.
  • Usuarios de prueba: Marca un usuario de tu espacio de trabajo de desarrollo como usuario de prueba y, después, desencadena eventos desde tu integración para ese usuario. Los usuarios de prueba aparecen señalados en el panel, lo que facilita aislar e inspeccionar el comportamiento de extremo a extremo.

Cuando la validación falla

El evento no se procesa como evento recomendado. En concreto:

  • El evento se descarta por completo. Los eventos recomendados de comercio electrónico no válidos no llegan al perfil de usuario, no aparecen en Currents y no están disponibles para la segmentación.
  • Las características posteriores de los eventos recomendados no se ejecutan, entre ellas:
    • El seguimiento de ingresos (informes de ingresos, campos calculados del usuario como total_revenue)
    • Las actualizaciones del objeto de carrito en el perfil de usuario
    • Los desencadenantes Update Cart o Place Order en Canvas y Campaigns

La forma de notificar los errores depende de la ruta de ingesta:

  • REST API (/users/track): Cada evento no válido se notifica en la matriz de errores de la respuesta. Cada entrada te indica qué evento falló (índice) y por qué (tipo). El campo de mensaje de nivel superior sigue indicando “success”, lo que solo significa que tu solicitud llegó a Braze, no que todos los eventos fueran válidos. Comprueba siempre si hay una matriz de errores en la respuesta.
  • SDK de Braze: Las llamadas al SDK devuelven el control inmediatamente y la validación se ejecuta en segundo plano, por lo que los errores no se envían de vuelta a tu aplicación. Para enterarte de los errores de validación de eventos de comercio electrónico, presta atención al correo electrónico de resumen de errores (consulta Encontrar errores).

Ejemplo de respuesta de error de la API

El endpoint /users/track devuelve errores a nivel de campo que indican qué propiedades fallaron y por qué. Ten en cuenta que el message de nivel superior puede devolver "success" porque el evento se aceptó en el proceso; la matriz errors te indica qué campos no superaron la validación del esquema. Consulta la siguiente respuesta de error como ejemplo.




{
 "message": "success",
 "errors": [{ "index": 0, "input_array": "purchases", "type": "'currency' must be an ISO 4217 currency" }]
}

Los errores también se clasifican internamente y se agregan para el correo electrónico de resumen de errores:

Tipo de error Significado Ejemplo
missing_property Falta un campo obligatorio. order_placed enviado sin order_id.
extra_property Se añadió un campo que el esquema no define. Un campo personalizado gift_wrapped en el nivel superior de properties en lugar de dentro de metadata.
unexpected_data_type Un campo tiene un tipo incorrecto. total_value: "29.99" (cadena) en lugar de 29.99 (número).

Encontrar errores

Braze envía por correo electrónico a los administradores de tu espacio de trabajo un resumen de los errores de validación de eventos recomendados para que puedas identificar y corregir problemas de integración sin supervisar manualmente cada evento.

El correo electrónico de resumen incluye:

  • Recuento total de errores: Los recuentos de errores del periodo del informe.
  • Errores por evento: Un desglose de cuántos eventos fallaron por cada tipo de evento recomendado (por ejemplo, ecommerce.cart_updated y ecommerce.order_placed). Úsalo para identificar qué eventos de tu integración necesitan atención primero.
  • Errores por origen: Una división entre API y SDK, para que puedas determinar qué integración está generando los errores.

Si no recibes estos correos electrónicos o quieres verificar la lista de destinatarios, ponte en contacto con el equipo de tu cuenta de Braze.

Diagnosticar y corregir errores

Cuando recibas un correo electrónico de resumen de errores:

  1. Identifica el evento y el origen que fallan. El correo electrónico separa los errores por nombre de evento y origen de integración (sdk frente a rest_api), para que puedas determinar qué integración necesita la corrección. Si tienes varios orígenes que envían el mismo evento (por ejemplo, el SDK de tu tienda online y un webhook del backend que envían cart_updated), abórdalos por separado.
  2. Compara tu carga útil con el esquema en Esquemas de eventos. La mayoría de los errores encajan en uno de estos tres patrones:
    • missing_property: Falta un campo obligatorio. Para solucionarlo, añade el campo obligatorio.
    • extra_property: Hay un campo personalizado en el nivel superior de properties. Para solucionarlo, mueve el campo personalizado dentro de metadata (a nivel de evento) o de products[].metadata (por producto).
    • unexpected_data_type: Un valor tiene un tipo incorrecto (por ejemplo, total_value enviado como cadena). Para solucionarlo, convierte el valor antes de enviarlo.
  3. Prueba la carga útil corregida en un espacio de trabajo de desarrollo antes de implementarla en producción. Envía un evento de prueba conocido para un usuario de prueba y, después, verifica el comportamiento esperado del evento recomendado en el perfil de ese usuario (por ejemplo, que el objeto de carrito se actualice, que los ingresos aumenten o que se active el desencadenante de carrito abandonado).
  4. Supervisa el siguiente correo electrónico de errores para confirmar que el recuento de errores de ese evento, origen y tipo baja a cero.

Para ver todos los requisitos de propiedades de cada evento, consulta Esquemas de eventos.

Documentación de la plataforma de interacción con el cliente de Braze.

Recursos
Legal
Empresa
© 2026 Braze, Inc. Todos los derechos reservados.
Verificación del estado de Braze
New Stuff!