> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bevits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Eventos recomendados

> Nombres y propiedades sugeridos para los eventos más comunes de e-commerce.

La API acepta **cualquier nombre** de evento que siga el formato (letras
minúsculas, números y guiones bajos). Este catálogo es una convención, no una
regla: nada de lo que aparece aquí se valida, y puedes enviar eventos y
propiedades que no están en la lista.

Vale la pena seguir el catálogo por dos motivos:

* Los mismos nombres y propiedades en todos los eventos hacen que los flows y
  los mensajes sean predecibles: `{{event.order_number}}` funciona igual en
  `order_shipped` y en `order_delivered`.
* Un evento con un nombre del catálogo nace con la **naturaleza** indicada en
  la tabla (`utility` o `marketing`), devuelta en `GET /v1/event-types`.
* Algunos eventos tienen un flow listo en las recetas de Bevits: **Pedido
  enviado** para `order_shipped` (lee `tracking_code`, `tracking_url` y
  `carrier`), **Pix generado** para `pix_generated` (lee `pix_code` y
  `order_url`, recuerda al cliente 15 minutos después y se detiene cuando llega
  `payment_confirmed` con el mismo `order_number`) y **Puntos por vencer** para `points_expiring` (lee `points`).

Consulta cómo enviarlos en
[Eventos personalizados](https://docs.bevits.com/es/api-reference/custom-events.md).

## Propiedades comunes

Usa estas propiedades, con el mismo nombre, en todos los eventos en los que
tengan sentido:

| Propiedad | Contenido |
| - | - |
| `order_number` | Número del pedido, como lo ve el cliente. |
| `order_url` | Enlace al pedido. |
| `total_in_cents` | Valor total en centavos. |
| `currency` | Moneda, como `BRL`. |
| `items[]` | Artículos del pedido. Cada artículo: `sku`, `name`, `quantity`, `price_in_cents`, `image_url`, `url`. |

En los eventos sobre un producto, `product` es un objeto con `sku`, `name`,
`price_in_cents`, `image_url`, `url` y `category`.

```json theme={null}
{
  "name": "order_shipped",
  "customer": { "external_id": "u_8842", "email": "ana@exemplo.com.br" },
  "properties": {
    "order_number": "10293",
    "order_url": "https://loja.com/pedidos/10293",
    "total_in_cents": 15990,
    "currency": "BRL",
    "items": [
      {
        "sku": "CAM-01",
        "name": "Camiseta",
        "quantity": 2,
        "price_in_cents": 7995,
        "image_url": "https://cdn.loja.com/cam-01.png",
        "url": "https://loja.com/produtos/camiseta"
      }
    ],
    "tracking_code": "BR123",
    "tracking_url": "https://rastreio.exemplo.com.br/BR123",
    "carrier": "Correios",
    "estimated_delivery_date": "2026-11-22"
  },
  "external_id": "ship_10293"
}
```

## Catálogo

| Grupo | Evento | Propiedades recomendadas, además de las comunes | Naturaleza |
| - | - | - | - |
| Pedido | `order_placed` | | utilidad |
| | `order_cancelled` | `reason` | utilidad |
| Pago | `pix_generated` | `pix_code`, `expires_at` | utilidad |
| | `pix_expired` | | utilidad |
| | `boleto_generated` | `boleto_url`, `barcode`, `due_date` | utilidad |
| | `payment_confirmed` | `payment_method` | utilidad |
| | `payment_failed` | `payment_method`, `reason` | utilidad |
| | `refund_issued` | `amount_in_cents`, `reason` | utilidad |
| Logística | `order_invoiced` | `invoice_url`, `invoice_number` | utilidad |
| | `order_shipped` | `tracking_code`, `tracking_url`, `carrier`, `estimated_delivery_date` | utilidad |
| | `out_for_delivery` | `tracking_code`, `tracking_url` | utilidad |
| | `order_delivered` | `delivered_at` | utilidad |
| | `delivery_failed` | `reason`, `tracking_url` | utilidad |
| | `ready_for_pickup` | `pickup_location`, `pickup_deadline` | utilidad |
| Intención | `product_viewed` | `product` | marketing |
| | `search_performed` | `query`, `results_count` | marketing |
| | `product_added_to_cart` | `product`, `cart_url` | marketing |
| | `checkout_started` | `checkout_url` | marketing |
| | `wishlist_added` | `product` | marketing |
| Stock y precio | `back_in_stock` | `product` | marketing |
| | `price_dropped` | `product`, `previous_price_in_cents` | marketing |
| Posventa | `review_requested` | `review_url` | utilidad |
| | `review_submitted` | `rating`, `comment`, `product` | |
| | `return_requested` | `reason`, `return_url` | utilidad |
| | `exchange_requested` | `reason` | utilidad |
| | `nps_answered` | `score`, `comment` | |
| | `support_ticket_resolved` | `ticket_id`, `survey_url` | utilidad |
| Fidelización | `points_earned` | `points`, `balance` | marketing |
| | `points_expiring` | `points`, `expires_at` | marketing |
| | `tier_changed` | `previous_tier`, `tier` | marketing |
| | `cashback_available` | `amount_in_cents`, `expires_at` | marketing |
| | `cashback_expiring` | `amount_in_cents`, `expires_at` | marketing |
| | `coupon_issued` | `code`, `discount`, `expires_at` | marketing |
| Suscripción | `subscription_created` | `plan`, `next_charge_date` | utilidad |
| | `renewal_upcoming` | `plan`, `next_charge_date`, `amount_in_cents` | utilidad |
| | `subscription_renewed` | `plan`, `next_charge_date` | utilidad |
| | `subscription_payment_failed` | `plan`, `retry_date`, `update_payment_url` | utilidad |
| | `subscription_cancelled` | `plan`, `reason` | utilidad |
| Cuenta y captación | `account_created` | `source` | marketing |
| | `lead_captured` | `source`, `form_name` | marketing |
| Tienda física | `store_purchase` | `store_name` | utilidad |
| | `appointment_scheduled` | `scheduled_for`, `location` | utilidad |
| | `appointment_reminder` | `scheduled_for`, `location` | utilidad |

En la API, la naturaleza aparece como `utility` (utilidad) o `marketing`. Los
eventos sin naturaleza (`review_submitted`, `nps_answered`) normalmente no
generan un mensaje: sirven para registrar la respuesta del cliente.

Las fechas y horas van como texto en ISO 8601 (`2026-11-22` o
`2026-11-22T14:00:00-03:00`). Los valores monetarios van en centavos.

## Tres reglas

### 1. Naturaleza del evento

**Utilidad** es un evento sobre algo que el cliente ya hizo: un pedido, un
pago, una entrega. **Marketing** es un evento que se usa para vender, como
`back_in_stock` o `coupon_issued`, y el mensaje que genera exige el
consentimiento del cliente.

La naturaleza es una propiedad del tipo de evento. Los nombres del catálogo
nacen con la naturaleza de la tabla; un nombre fuera del catálogo nace sin
naturaleza y sigue la regla de marketing. La naturaleza se puede cambiar en
Configuración → Eventos. Un evento de utilidad alcanza a quien nunca aceptó
marketing, pero no a quien pidió darse de baja; en WhatsApp oficial, la
plantilla también debe ser de utilidad. Detalles en
[Quién recibe los mensajes del flow](https://docs.bevits.com/es/api-reference/custom-events.md#quién-recibe-los-mensajes-del-flow).

### 2. Los eventos de producto se envían por cliente

`back_in_stock` y `price_dropped` le ocurren a un producto, pero la API vincula
cada evento a un cliente. Envía un evento por cada cliente interesado, usando
el [envío por lote](https://docs.bevits.com/es/api-reference/custom-events.md#envío-por-lote).

### 3. Fuera del catálogo a propósito

El restablecimiento de contraseña y los códigos de verificación no están en el
catálogo. Son mensajes críticos en tiempo y no pertenecen a un flow de
marketing.

## Si tu tienda no tiene integración nativa

Las integraciones nativas de Bevits ya generan los eventos de pedido creado,
pagado, enviado y cancelado, de carrito abandonado y de cliente nuevo. Si
envías esos hechos por la API porque no usas una integración nativa, usa los
nombres del catálogo: `order_placed`, `payment_confirmed`, `order_shipped`,
`order_cancelled`, `checkout_started` y `account_created`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.