> ## 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 personalizados

> Envía a Bevits lo que ocurre en tu sistema y usa esos eventos para iniciar flows.

Un evento es un hecho: esta persona hizo esto, en este momento, con estos
detalles. Envía un `POST` y Bevits guarda el evento, lo vincula a un cliente e
inicia los flows que escuchan ese nombre.

```bash theme={null}
curl https://api.bevits.com/v1/events \
  -H "Authorization: Bearer $BEVITS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_shipped",
    "customer": { "email": "ana@exemplo.com.br" },
    "properties": { "tracking_code": "BR123", "carrier": "Correios" }
  }'
```

* **URL:** `POST https://api.bevits.com/v1/events`
* **Formato:** `name` (qué ocurrió), `customer` (a quién) y `properties`
  (detalles). Opcionales: `occurred_at`, `external_id` y `backfill`.
* **Cómo se vincula al cliente:** envía los identificadores que tengas
  (`external_id`, `tax_id`, `email`, `phone`). El primero que coincida, en ese
  orden, decide. Si ninguno coincide, se crea el cliente. La respuesta dice qué
  cliente fue y por cuál identificador.

No se registra nada antes: ni el evento, ni las propiedades, ni el cliente.

> [!NOTE]
>
> La clave necesita el permiso `write` o `events:write`. Consulta
> [Clave solo de envío](#clave-solo-de-envío).

## Envío completo

```json theme={null}
{
  "name": "order_shipped",
  "customer": {
    "external_id": "u_8842",
    "email": "ana@exemplo.com.br",
    "phone": "+5511988887777",
    "tax_id": "123.456.789-09",
    "name": "Ana Souza",
    "attributes": { "plano": "premium" }
  },
  "properties": {
    "order_number": "10293",
    "tracking": { "code": "BR123", "carrier": "Correios" },
    "items": [{ "sku": "CAM-01", "name": "Camiseta", "quantity": 2 }]
  },
  "occurred_at": "2026-11-18T14:03:00-03:00",
  "external_id": "ship_10293",
  "backfill": false
}
```

| Campo | Obligatorio | Regla |
| - | - | - |
| `name` | sí | Letras minúsculas, números y guiones bajos, empezando por una letra (`^[a-z][a-z0-9_]*$`). Hasta 64 caracteres. |
| `customer` | sí | Al menos un identificador: `id`, `external_id`, `tax_id`, `email` o `phone`. |
| `properties` | no | Objeto JSON libre. Consulta [Propiedades y límites](#propiedades-y-límites). |
| `occurred_at` | no | ISO 8601 con offset. Por defecto: el momento de la recepción. |
| `external_id` | no | ID del hecho en tu sistema, hasta 255 caracteres. Consulta [Repetir con seguridad](#repetir-con-seguridad). |
| `backfill` | no | `true` guarda el evento sin disparar flows. Por defecto `false`. |

Los campos desconocidos se rechazan con `unknown_field`, en lugar de
ignorarse. Un `customerId` en lugar de `customer.id` falla en la primera
llamada.

El nombre es estricto para que `Order Shipped`, `order shipped` y
`order_shipped` no se conviertan en tres eventos distintos. Un nombre inválido
falla en la primera llamada y sugiere el correcto:

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "invalid_event_name",
    "message": "Event names use lowercase letters, digits and underscores, start with a letter and have at most 64 characters. Did you mean \"order_shipped\"?",
    "param": "name",
    "suggestion": "order_shipped",
    "request_id": "req_07f6cdc3c20249d6afcd90b4"
  }
}
```

```bash cURL theme={null}
curl https://api.bevits.com/v1/events \
  -H "Authorization: Bearer $BEVITS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_shipped",
    "customer": {
      "external_id": "u_8842",
      "email": "ana@exemplo.com.br",
      "phone": "+5511988887777"
    },
    "properties": {
      "order_number": "10293",
      "tracking": { "code": "BR123", "carrier": "Correios" }
    },
    "occurred_at": "2026-11-18T14:03:00-03:00",
    "external_id": "ship_10293"
  }'
```

```javascript Node.js theme={null}
const response = await fetch("https://api.bevits.com/v1/events", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BEVITS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "order_shipped",
    customer: {
      external_id: "u_8842",
      email: "ana@exemplo.com.br",
      phone: "+5511988887777",
    },
    properties: {
      order_number: "10293",
      tracking: { code: "BR123", carrier: "Correios" },
    },
    occurred_at: "2026-11-18T14:03:00-03:00",
    external_id: "ship_10293",
  }),
});

const body = await response.json();

if (!response.ok) {
  // error.code dice el motivo, error.param dice el campo.
  throw new Error(`${body.error.code ?? body.error.type}: ${body.error.message}`);
}

// 201: evento nuevo. 200: el external_id ya existía (body.duplicate === true).
console.log(body.id, body.customer, body.flows);
```

```python Python theme={null}
import os
import requests

response = requests.post(
    "https://api.bevits.com/v1/events",
    headers={"Authorization": f"Bearer {os.environ['BEVITS_API_KEY']}"},
    json={
        "name": "order_shipped",
        "customer": {
            "external_id": "u_8842",
            "email": "ana@exemplo.com.br",
            "phone": "+5511988887777",
        },
        "properties": {
            "order_number": "10293",
            "tracking": {"code": "BR123", "carrier": "Correios"},
        },
        "occurred_at": "2026-11-18T14:03:00-03:00",
        "external_id": "ship_10293",
    },
    timeout=30,
)
body = response.json()

if not response.ok:
    # error.code dice el motivo, error.param dice el campo.
    error = body["error"]
    raise RuntimeError(f"{error.get('code', error['type'])}: {error['message']}")

# 201: evento nuevo. 200: el external_id ya existía (body["duplicate"] es True).
print(body["id"], body["customer"], body["flows"])
```

## Cómo se vincula el evento al cliente

**La regla:** los identificadores se prueban en este orden, `id`,
`external_id`, `tax_id`, `email`, `phone`, y el primero que pertenezca a un
cliente activo decide. Si ninguno pertenece, el cliente se crea con todo lo que
se envió.

| Identificador | Qué es | Cómo se compara |
| - | - | - |
| `id` | ID del cliente en Bevits (`cus_…`) | Exacto. |
| `external_id` | ID del cliente en tu sistema | Texto exacto, hasta 255 caracteres. |
| `tax_id` | CPF o CNPJ (documentos fiscales de Brasil) | Solo los dígitos. Debe ser un documento válido. |
| `email` | Email | En minúsculas, sin espacios en los extremos. |
| `phone` | Teléfono | E.164 (`+5511988887777`). Sin código de país, se asume el país de la tienda. |

`external_id` y `tax_id` son identificadores **fuertes**: identifican a una
persona. `email` y `phone` son **débiles**: pueden compartirse o cambiar de
dueño. Cada identificador pertenece a un único cliente, y eso es lo que hace
que el resultado sea predecible.

Un evento nunca fusiona dos clientes. Cuando algo no cuadra, la API mantiene lo
que ya existía y avisa en `warnings`:

| Situación | Qué ocurre | Aviso |
| - | - | - |
| Ningún identificador coincide | El cliente se crea con todo lo que se envió. La respuesta trae `customer.created: true`. | |
| El cliente encontrado todavía no tiene uno de los identificadores enviados | El identificador se guarda en él. | |
| Varios clientes activos tienen el mismo documento, email o teléfono (duplicados antiguos) | Coincide con el más antiguo. La elección queda fija para las próximas llamadas. | `ambiguous_identifier` |
| El email o teléfono es de un cliente que tiene un `external_id` o `tax_id` distinto del enviado | Ese identificador no se usa para coincidir: es otra persona con el mismo contacto. La búsqueda sigue con el siguiente. Si ninguno coincide, se crea un cliente nuevo. Este guarda el contacto, pero el email o teléfono sigue identificando al dueño original. | `identifier_conflict` |
| Coincidió por `id`, `external_id` o `tax_id`, y el email o teléfono enviado es distinto del actual | El contacto se reemplaza. El cliente deja de encontrarse por el valor antiguo. | |
| Coincidió por `email` o `phone`, y el otro contacto enviado es distinto del actual | Se mantiene el contacto actual. | `identifier_mismatch` |
| El `external_id` o `tax_id` enviado es distinto del que el cliente encontrado ya tiene | No se sobrescribe nada. | `identifier_mismatch` |
| Uno de los otros identificadores enviados pertenece a otro cliente | El evento queda con el cliente encontrado. No se mueve nada de un cliente al otro. | `identifier_conflict` |
| `customer.id` no existe | `404` con `customer_not_found`. Los demás identificadores no se prueban. | |
| Los identificadores solo pertenecen a un cliente eliminado | Un cliente eliminado nunca coincide y nunca se reactiva por un evento. Se crea un cliente nuevo. | |

Cada aviso trae `code`, `message` y `param` (por ejemplo `customer.email`).

### Datos del cliente en la misma llamada

* `customer.name` actualiza el nombre del cliente.
* `customer.attributes` guarda atributos del cliente. Solo cambian las claves
  enviadas. Los valores pueden ser texto (hasta 256 caracteres), número o
  booleano, y las claves tienen hasta 64 caracteres.
* Un atributo que todavía no existe se crea con el tipo inferido del valor:
  texto, número, booleano o fecha (texto en ISO 8601).
* Un valor que no cabe en el tipo de un atributo existente rechaza el evento
  con `attribute_type_mismatch`. No se guarda nada.
* Un cliente solo con `external_id`, sin email ni teléfono, es válido. El
  evento se guarda, y un flow que no puede alcanzarlo por ningún canal aparece
  como `skipped` con `no_contact_channel`.

## Repetir con seguridad

`external_id` es el ID del hecho en tu sistema, como `ship_10293`. Es único por
nombre de evento durante **90 días**. Reenviar el mismo `name` y `external_id`
en ese período responde `200` con el evento original y `duplicate: true`.

* **No ocurre nada de nuevo.** El reenvío no dispara flows y no toca al
  cliente: los atributos y los identificadores no se vuelven a aplicar.
* **Cuerpo distinto en el reenvío.** El primer envío sigue valiendo, y la
  respuesta trae el aviso `payload_mismatch`. No es un upsert.
* **Sin `external_id`.** Cada llamada es un evento nuevo. La API nunca
  deduplica por su cuenta.

El header `Idempotency-Key` también se acepta en los envíos (`POST /v1/events`
y `POST /v1/events/bulk`). Durante 24 horas, repetir la misma clave con el
mismo cuerpo devuelve la respuesta guardada, con el header
`Idempotent-Replayed: true`. La misma clave con otro cuerpo responde
`409 conflict`.

Usa los dos: `external_id` protege el hecho, `Idempotency-Key` protege la
solicitud. En el lote, `Idempotency-Key` es lo que impide que un timeout
duplique los elementos sin `external_id`.

```bash theme={null}
curl https://api.bevits.com/v1/events \
  -H "Authorization: Bearer $BEVITS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-ship-10293" \
  -d '{
    "name": "order_shipped",
    "customer": { "external_id": "u_8842" },
    "external_id": "ship_10293"
  }'
```

## Propiedades y límites

`properties` es un objeto JSON libre y es todo tuyo: no hay claves reservadas.
Los valores pueden ser texto, número, booleano, fecha (texto en ISO 8601),
lista y objeto. No hay un esquema que registrar. El tipo de cada propiedad se
infiere de los eventos recibidos y aparece en
[Tipos de evento](#tipos-de-evento).

Lo que no cabe se rechaza con `422` y un `error.code`. No se trunca nada.

| Límite | Valor | `error.code` |
| - | - | - |
| Tamaño del evento | 64 KB | `event_too_large` |
| Claves en `properties`, contando las anidadas | 200 | `too_many_properties` |
| Profundidad de `properties` | 5 niveles | `properties_too_deep` |
| Elementos por lista | 100 | `array_too_long` |
| Nombres de evento activos por tienda | 500 | `too_many_event_names` |
| Eventos por lote | 100 | |
| Tamaño del lote | 1 MB | `batch_too_large` |

El límite de nombres existe para detectar pronto el error de poner datos en el
nombre, como `order_10293_shipped`. El nombre dice qué ocurrió; los IDs y los
valores van en `properties`. Los tipos de evento archivados no cuentan para el
límite, y un evento con un nombre archivado se rechaza con
`event_type_archived`.

## Tiempo

`occurred_at` dice cuándo ocurrió el hecho. Sin él, vale el momento de la
recepción.

| `occurred_at` | Resultado |
| - | - |
| Más de 5 minutos en el futuro | `422` con `occurred_at_in_future`. |
| Más antiguo que 13 meses | `422` con `occurred_at_too_old`. |
| Más antiguo que 72 horas | El evento se guarda, pero no dispara flows: `flows[].reason` es `stale`. |
| Cualquier valor aceptado, con `backfill: true` | El evento se guarda, pero no dispara flows: `flows[].reason` es `backfill`. |

Usa `backfill: true` para importar historial. La regla de las 72 horas protege
contra una cola reprocesada que descargue mensajes antiguos sobre tus clientes.

## Qué dice la respuesta

`201 Created` cuando el evento es nuevo. `200 OK` con el evento original cuando
el `external_id` ya existía.

```json theme={null}
{
  "object": "event",
  "id": "evt_01jd2v9k3m8q4r5s6t7u8v9w0x",
  "name": "order_shipped",
  "external_id": "ship_10293",
  "occurred_at": "2026-11-18T17:03:00.000Z",
  "received_at": "2026-11-18T17:03:01.000Z",
  "customer": {
    "id": "cus_ckabc123",
    "matched_by": "external_id",
    "created": false
  },
  "flows": [
    { "id": "flw_ckdef456", "name": "Pedido enviado", "status": "queued" },
    {
      "id": "flw_ckghi789",
      "name": "Entrega expressa",
      "status": "skipped",
      "reason": "filter_not_matched"
    }
  ],
  "properties": {
    "order_number": "10293",
    "tracking": { "code": "BR123", "carrier": "Correios" }
  },
  "backfill": false,
  "livemode": true
}
```

Una respuesta de éxito es una promesa: el evento está guardado, vinculado a un
cliente y puede leerse por su `id` de inmediato.

* `customer.matched_by` dice qué identificador encontró al cliente. Cuando el
  evento creó al cliente, llega `created: true` y `matched_by` se omite.
* `flows` lista los flows **activos** que escuchan ese nombre. Una lista vacía
  significa que ningún flow está escuchando.
* `warnings` aparece solo cuando hay algo que avisar. Un aviso nunca sustituye
  a un error.
* `duplicate: true` aparece cuando la llamada devolvió un evento que ya
  existía.

### `flows[].status` y `flows[].reason`

| `status` | Significado |
| - | - |
| `queued` | El inicio del flow se encoló. Es lo que informa la respuesta del envío. |
| `started` | El flow se inició para el cliente. Aparece al consultar el evento después. |
| `skipped` | El flow no se inició. `reason` dice por qué. |

| `reason` | Cuándo se decide | Significado |
| - | - | - |
| `test_mode` | En el envío | El evento se envió con una clave de prueba. |
| `backfill` | En el envío | El evento llegó con `backfill: true`. |
| `stale` | En el envío | `occurred_at` tiene más de 72 horas. |
| `filter_not_matched` | En el envío | Las propiedades no pasaron los filtros del disparador. |
| `no_contact_channel` | Después | El cliente no tiene el contacto (email o teléfono) de ningún canal que usa el flow. |
| `no_consent` | Después | El cliente tiene el contacto, pero no aceptó recibir mensajes de esta naturaleza por ningún canal que usa el flow ([quién recibe](#quién-recibe-los-mensajes-del-flow)). |
| `flow_inactive` | Después | El flow se desactivó antes de iniciarse. |
| `flow_error` | En el envío o después | El flow tiene un disparador o pasos que no se pueden leer, por eso no se inició. Abre el flow en Bevits y publícalo de nuevo. |
| `dispatch_failed` | Después | Bevits no pudo iniciar el flow, incluso reintentando durante 72 horas. No se envió ningún mensaje por este evento. |

Para saber qué ocurrió con un flow `queued`,
[consulta el evento](#leer-un-evento).

### Avisos de un flow

Un flow iniciado puede traer `flows[].warnings`: lo que no pudo hacer y tú
puedes corregir en el envío. El campo solo aparece cuando hay algo que avisar.

| `flows[].warnings[].code` | Significado |
| - | - |
| `missing_variable` | Se omitió un mensaje del flow (e-mail, SMS o WhatsApp) porque una variable de la plantilla no tenía valor ni texto alternativo. `param` indica la propiedad que faltó, como `properties.tracking.code`. |

### Avisos

| `warnings[].code` | Significado |
| - | - |
| `ambiguous_identifier` | Varios clientes tenían el mismo identificador. Se usó el más antiguo. |
| `identifier_conflict` | Un identificador enviado pertenece a otro cliente y quedó con él. |
| `identifier_mismatch` | El cliente ya tenía un valor distinto para ese identificador, y se mantuvo. |
| `payload_mismatch` | Ya existía un evento con el mismo `name` y `external_id` y otro cuerpo. El primero sigue valiendo. |

## Disparar un flow con el evento

Un flow escucha un evento personalizado mediante el disparador
`custom.<nombre_del_evento>`. Crea el flow con `POST /v1/flows`, con
`platform: "custom"` y el nombre del evento en `event`:

```json theme={null}
{
  "name": "Pedido enviado pelos Correios",
  "trigger": {
    "platform": "custom",
    "event": "order_shipped",
    "filters": [
      { "property": "tracking.carrier", "operator": "equals", "value": "Correios" }
    ]
  },
  "start": "avisar",
  "nodes": [
    { "key": "avisar", "type": "send_whatsapp", "template_id": "wtp_…" }
  ]
}
```

* `trigger.filters` es opcional y acepta hasta 10 filtros. El flow solo se
  inicia cuando todos coinciden con las propiedades del evento. `property` es
  la ruta de la propiedad, como `tracking.carrier` o `items[0].sku`.
* Una propiedad ausente o de otro tipo simplemente no pasa el filtro. El flow
  aparece como `skipped` con `filter_not_matched`.
* Los mensajes usan las propiedades del evento como [variables](#variables), y
  los bloques de condición las comparan con `field: "event.<ruta>"`
  ([condiciones](#condiciones)).
* El flow se crea como borrador. Solo recibe eventos después de activarse
  (`POST /v1/flows/{flow_id}/activate`).
* El flow puede crearse antes de que llegue el primer evento con ese nombre.

En el panel, el mismo disparador está en **API de eventos → Evento
personalizado**, en el bloque de disparador del flow: elige un evento ya
recibido o escribe el nombre, y agrega filtros por las propiedades. Las recetas
**Pedido enviado** y **Pix generado** crean flows listos para `order_shipped` y
`pix_generated`.

### Variables

Los mensajes del flow (email, SMS y WhatsApp) leen las propiedades del evento
como variables:

| Variable | Qué lee |
| - | - |
| `{{event.tracking.code}}` | Una propiedad, a cualquier profundidad. |
| `{{event.items[0].name}}` | Un elemento de una lista, por su posición. |
| `{{event.carrier \| default: "Correios"}}` | El texto alternativo, usado cuando la propiedad no llegó o está vacía. Las comillas simples también sirven. |

* Una variable sin valor ni texto alternativo hace que el mensaje se omita, en
  cualquier canal (email, SMS y WhatsApp), para que el cliente nunca reciba la
  variable tal como se escribió. El evento registra `missing_variable` en el
  flow ([avisos de un flow](#avisos-de-un-flow)). En las plantillas oficiales
  de WhatsApp, usa una variable dinámica para dar un texto alternativo.
* Una lista o un objeto entero se escribe como JSON. En el email, el bloque de
  artículos del pedido muestra `items[]` cuando los artículos siguen el formato
  del [catálogo](https://docs.bevits.com/es/api-reference/recommended-events.md) (`name`, `quantity`,
  `price_in_cents`, `image_url`, `url`).
* En el editor, las propiedades ya recibidas aparecen en el grupo **Evento** del
  selector de variables.

### Condiciones

Un bloque de condición compara una propiedad del evento con
`field: "event.<ruta>"`. La propiedad se compara como el tipo del valor dado:
número, booleano o texto, y lista con `includes`.

```json theme={null}
{
  "key": "express",
  "type": "condition",
  "field": "event.shipping.express",
  "operator": "equals",
  "value": true,
  "if_true": "avisar"
}
```

Las propiedades no tienen esquema: una propiedad de otro tipo no se puede
comparar, la condición es falsa y la ejecución registra el motivo. En el
editor, el bloque de condición ofrece el grupo **Evento**, con las propiedades
ya recibidas y el tipo de cada una.

### Esperar y terminar por un evento

Un flow también puede **escuchar** eventos del mismo cliente mientras se
ejecuta. Son dos usos del mismo mecanismo:

* **Esperar evento**: un bloque que pausa la ejecución hasta que llega el
  evento, con un tiempo máximo de hasta 90 días. Tiene dos salidas: *llegó*
  (`if_arrived`) y *tiempo agotado* (`if_timed_out`).
* **Terminar cuando llegue**: en el disparador, eventos que terminan la
  ejecución en cuanto llegan (`trigger.exit_on`, hasta 5). Por ejemplo, el
  recordatorio de un Pix termina cuando llega `payment_confirmed`.

```json theme={null}
{
  "name": "Pix con recordatorio",
  "trigger": {
    "platform": "custom",
    "event": "pix_generated",
    "exit_on": [{ "event": "order_cancelled", "match_on": "order_number" }]
  },
  "start": "codigo",
  "nodes": [
    { "key": "codigo", "type": "send_whatsapp", "template_id": "wtp_…", "next": "pago" },
    {
      "key": "pago",
      "type": "wait_for_event",
      "event": "payment_confirmed",
      "match_on": "order_number",
      "timeout_amount": 15,
      "timeout_unit": "minutes",
      "if_arrived": "gracias",
      "if_timed_out": "recordatorio"
    },
    { "key": "gracias", "type": "send_email", "template_id": "etp_…" },
    { "key": "recordatorio", "type": "send_whatsapp", "template_id": "wtp_…" }
  ]
}
```

* **Un evento que llega antes también cuenta.** Todo lo que el flow escucha se
  registra cuando empieza la ejecución. Si `payment_confirmed` llega antes de
  que la ejecución alcance el bloque de espera (o incluso antes de que empiece
  el flow), el bloque sigue al instante por *llegó*, y una regla de salida
  termina la ejecución antes del primer envío.
* **`match_on` vincula el evento al pedido correcto.** Sin él, cuenta cualquier
  evento con ese nombre del mismo cliente. Con `"match_on": "order_number"`,
  solo cuenta el evento cuyo `order_number` es igual al del evento que inició
  el flow, para que un cliente con dos pedidos abiertos no tenga los dos
  terminados por un pago. `10293` y `"10293"` son el mismo valor. Solo funciona
  en flows iniciados por un evento personalizado; si el evento inicial no tiene
  la propiedad, nada coincide.
* **`filters`** funcionan como los del disparador: solo cuenta el evento que
  pasa todos.
* **Terminar es cancelar.** La ejecución se cancela y no sale ningún envío
  posterior: cada envío comprueba la cancelación antes de salir.
* Los eventos de prueba (`bvt_test_`) y de `backfill` nunca cuentan: uno no
  ocurre de verdad y el otro es historial importado.
* El bloque de espera cuenta el tiempo máximo desde que la ejecución llega a
  él.
* Los bloques siguientes leen el evento recibido como
  `{{events.<nombre>.<ruta>}}`, por ejemplo
  `{{events.payment_confirmed.payment_method}}`. Si se agota el tiempo, esas
  variables no tienen valor: usa un texto alternativo
  (`{{events.payment_confirmed.payment_method | default: "Pix"}}`).
* Los flows de Instagram no esperan ni terminan por eventos.

En el panel, el bloque **Esperar evento** está en la barra lateral del editor,
y las reglas de salida están en el bloque disparador, en **Terminar cuando
llegue**. La receta **Pix generado** ya trae un recordatorio que se detiene
cuando llega `payment_confirmed` del mismo `order_number`.

## Validar sin guardar

`POST /v1/events/validate` recibe el mismo cuerpo y devuelve lo que devolvería
`POST /v1/events`, sin guardar nada y sin modificar clientes. Úsalo durante el
desarrollo para ver qué cliente coincidiría, qué flows se encolarían y qué
avisos aparecerían.

```bash theme={null}
curl https://api.bevits.com/v1/events/validate \
  -H "Authorization: Bearer $BEVITS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_shipped",
    "customer": { "email": "novo@exemplo.com.br" }
  }'
```

* Exige el permiso `read`. Una clave solo con `events:write` no puede validar.
* Cuando el envío crearía al cliente, la respuesta trae
  `"customer": { "would_create": true }`.
* El `id` del evento devuelto es provisional: no existe un evento que consultar
  después.
* Los errores son los mismos que en el envío.

## Envío por lote

`POST /v1/events/bulk` acepta hasta 100 eventos y 1 MB por llamada. Cada
elemento tiene el mismo formato que `POST /v1/events`.

```bash cURL theme={null}
curl https://api.bevits.com/v1/events/bulk \
  -H "Authorization: Bearer $BEVITS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: stock-CAM-01-2026-11-18" \
  -d '{
    "events": [
      {
        "name": "back_in_stock",
        "customer": { "email": "ana@exemplo.com.br" },
        "properties": { "product": { "sku": "CAM-01", "name": "Camiseta" } },
        "external_id": "stock_CAM-01_u_8842"
      },
      {
        "name": "back_in_stock",
        "customer": { "email": "bruno@exemplo.com.br" },
        "properties": { "product": { "sku": "CAM-01", "name": "Camiseta" } },
        "external_id": "stock_CAM-01_u_9120"
      }
    ]
  }'
```

```javascript Node.js theme={null}
const events = interested.map((customer) => ({
  name: "back_in_stock",
  customer: { email: customer.email },
  properties: { product: { sku: "CAM-01", name: "Camiseta" } },
  external_id: `stock_CAM-01_${customer.id}`,
}));

const response = await fetch("https://api.bevits.com/v1/events/bulk", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BEVITS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "stock-CAM-01-2026-11-18",
  },
  body: JSON.stringify({ events }),
});

const batch = await response.json();

if (!response.ok) {
  throw new Error(`${batch.error.code ?? batch.error.type}: ${batch.error.message}`);
}

// results tiene el mismo orden que events.
batch.results.forEach((result, index) => {
  if (result.status === "error") {
    console.error(events[index].external_id, result.error.code, result.error.param);
  }
});
```

```python Python theme={null}
import os
import requests

events = [
    {
        "name": "back_in_stock",
        "customer": {"email": customer["email"]},
        "properties": {"product": {"sku": "CAM-01", "name": "Camiseta"}},
        "external_id": f"stock_CAM-01_{customer['id']}",
    }
    for customer in interested
]

response = requests.post(
    "https://api.bevits.com/v1/events/bulk",
    headers={
        "Authorization": f"Bearer {os.environ['BEVITS_API_KEY']}",
        "Idempotency-Key": "stock-CAM-01-2026-11-18",
    },
    json={"events": events},
    timeout=60,
)
batch = response.json()

if not response.ok:
    error = batch["error"]
    raise RuntimeError(f"{error.get('code', error['type'])}: {error['message']}")

# results tiene el mismo orden que events.
for event, result in zip(events, batch["results"]):
    if result["status"] == "error":
        print(event["external_id"], result["error"].get("code"), result["error"].get("param"))
```

La respuesta es `200` con un resultado por evento:

```json theme={null}
{
  "object": "event_batch",
  "created": 1,
  "duplicate": 1,
  "failed": 1,
  "results": [
    { "status": "created", "event": { "object": "event", "id": "evt_…" } },
    { "status": "duplicate", "event": { "object": "event", "id": "evt_…", "duplicate": true } },
    {
      "status": "error",
      "error": {
        "type": "validation_error",
        "code": "invalid_tax_id",
        "message": "tax_id must be a valid CPF or CNPJ. For other documents, identify the customer by external_id.",
        "param": "events[2].customer.tax_id"
      }
    }
  ]
}
```

* **No es atómico.** Cada evento vale por sí mismo. Un evento inválido falla
  solo y los demás siguen.
* `results` tiene el mismo orden y el mismo tamaño que `events`. Cada `event`
  llega completo, como en la respuesta de `POST /v1/events`.
* El `param` de cada error empieza por la posición del evento:
  `events[2].name`.
* El `200` no significa que todo fue aceptado. Revisa `failed` y reenvía solo
  los elementos con `status: "error"` después de corregirlos.
* El lote entero solo se rechaza (`422`) cuando `events` está vacío, tiene más
  de 100 elementos o supera 1 MB (`batch_too_large`).
* **Orden:** los eventos se guardan en el orden enviado. El orden en que se
  ejecutan los flows de eventos distintos no está garantizado.

## Leer un evento

`GET /v1/events/{event_id}` devuelve el evento, el cliente al que se vinculó y
qué ocurrió con cada flow. Funciona justo después del envío.

```bash theme={null}
curl https://api.bevits.com/v1/events/evt_01jd2v9k3m8q4r5s6t7u8v9w0x \
  -H "Authorization: Bearer $BEVITS_API_KEY"
```

El cuerpo es el mismo objeto `event` del envío. En él, cada flow que estaba
`queued` pasa a `started` o a `skipped` con el motivo.

En el panel, **Configuración → Eventos** muestra los eventos recibidos en vivo,
con el cliente encontrado y el resultado de cada flow, y permite enviar un
evento de prueba. Ahí también un tipo de evento recibe etiqueta y naturaleza, o
se archiva.

Un evento puede leerse por ID durante los 13 meses de historial, con sus
`properties` y el resultado de cada flow. Después, la ruta responde `404`.

## Listar eventos

`GET /v1/events` lista los eventos de la tienda, del recibido más recientemente
al más antiguo. `GET /v1/customers/{customer_id}/events` es la línea de tiempo de
un cliente, incluidos los eventos de clientes que se fusionaron con él.

```bash theme={null}
curl "https://api.bevits.com/v1/events?name=order_shipped&occurred_after=2026-11-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $BEVITS_API_KEY"
```

```json theme={null}
{
  "data": [{ "object": "event", "id": "evt_01jd2v9k3m8q4r5s6t7u8v9w0x", "name": "order_shipped", "...": "..." }],
  "has_more": true
}
```

| Parámetro | Uso |
| - | - |
| `name` | Solo eventos con ese nombre. |
| `customer_id` | Solo eventos de ese cliente (`cus_…`), incluidos los de clientes fusionados con él. |
| `external_id` | El evento enviado con ese `external_id`. |
| `occurred_after` | Ocurrió en ese momento o después (ISO 8601 con offset). |
| `occurred_before` | Ocurrió antes de ese momento. |
| `limit` | De 1 a 100. Por defecto: 25. |
| `starting_after` | El `id` del último evento de la página anterior. |

* Cada ítem es el mismo objeto `event` de `GET /v1/events/{event_id}`.
* Un evento aparece en el listado en cuanto se acepta, sin esperar.
* El listado cubre los 13 meses de historial. Una clave de prueba lista los
  eventos de prueba; una de producción, los de producción.
* El historial vive en un almacenamiento analítico. Si no está disponible, los
  listados responden `503`; `GET /v1/events/{event_id}` sigue respondiendo para
  eventos recientes.

## En el panel

* **Configuración → Eventos → Llamadas rechazadas** muestra, durante 7 días,
  cada llamada que la API rechazó: el error, el campo, el `request_id`, la clave
  usada y el cuerpo exactamente como se envió. En un lote, cada evento
  rechazado aparece con su propio cuerpo. Después de 7 días el registro se
  borra.
* La pestaña **Eventos** del cliente, en el CRM, muestra su línea de tiempo.
  Propietarios y administradores pueden borrar ahí el historial de eventos de un
  cliente (protección de datos): las propiedades salen de Bevits en el momento y
  el historial se elimina en hasta un día. El cliente sigue en el CRM.
* **Segmentos por evento.** En el filtro de clientes, la condición **Evento
  personalizado** selecciona a quien hizo un evento al menos, como máximo o
  exactamente N veces, o nunca, en todo el historial, en los últimos N días o
  entre dos fechas, con hasta 5 filtros por propiedad (`items[].sku` incluye
  `CAM-01`, `total` mayor que 100). Se combina con las demás condiciones por Y y
  O. Los eventos de prueba nunca cuentan; los de `backfill` sí. "Nunca" vale
  dentro de los 13 meses de historial.

## Tipos de evento

`GET /v1/event-types` lista los nombres de evento que la tienda ya envió, con
las propiedades inferidas de los eventos recibidos.

```bash theme={null}
curl https://api.bevits.com/v1/event-types \
  -H "Authorization: Bearer $BEVITS_API_KEY"
```

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "event_type",
      "name": "order_shipped",
      "nature": "utility",
      "archived": false,
      "first_seen_at": "2026-11-18T17:03:01.000Z",
      "last_seen_at": "2026-11-18T19:40:12.000Z",
      "properties": [
        { "path": "order_number", "type": "string", "example": "10293" },
        { "path": "tracking", "type": "object" },
        { "path": "tracking.code", "type": "string", "example": "BR123" },
        { "path": "items", "type": "list" },
        { "path": "items[]", "type": "object" },
        { "path": "items[].quantity", "type": "number", "example": 2 }
      ]
    }
  ],
  "has_more": false
}
```

* `properties[].path` usa puntos para objetos y `[]` para elementos de una
  lista. `type` es `string`, `number`, `boolean`, `date`, `list` u `object`.
* Las propiedades son una ayuda, no una restricción: un evento con otro
  formato se sigue aceptando. Aparecen poco después de recibirse el evento.
* `nature` es `utility` o `marketing`. Los nombres del
  [catálogo de eventos recomendados](https://docs.bevits.com/es/api-reference/recommended-events.md)
  nacen con la naturaleza del catálogo; los demás nacen sin este campo.
* La lista llega completa, sin paginación. Los tipos archivados solo aparecen
  con `?include_archived=true`.

## Clave solo de envío

El permiso `events:write` puede existir solo en una clave. Es la clave indicada
para el backend que solo alimenta eventos: envía, y no puede leer la base de
clientes.

| Ruta | Permiso aceptado |
| - | - |
| `POST /v1/events` | `write` o `events:write` |
| `POST /v1/events/bulk` | `write` o `events:write` |
| `POST /v1/events/validate` | `read` |
| `GET /v1/events/{event_id}` | `read` |
| `GET /v1/events` | `read` |
| `GET /v1/customers/{customer_id}/events` | `read` |
| `GET /v1/event-types` | `read` |

Con una clave solo de envío:

* Cualquier otra ruta responde `403` con `missing_scope`.
* La respuesta del envío trae únicamente `customer.id`. `customer.matched_by` y
  `customer.created` se omiten.
* Los avisos de identidad (`ambiguous_identifier`, `identifier_conflict`,
  `identifier_mismatch`) se omiten. Solo aparece `payload_mismatch`.

Así, una clave filtrada no sirve para descubrir si un email o teléfono es de un
cliente de la tienda.

## Límites de solicitudes

Las rutas de envío tienen un límite propio, por segundo, separado del límite
general de 600 solicitudes por minuto.

| Ruta | Límite por clave API |
| - | - |
| `POST /v1/events` | 100 solicitudes por segundo |
| `POST /v1/events/validate` | 100 solicitudes por segundo |
| `POST /v1/events/bulk` | 2000 eventos por segundo, contados por evento |

Las respuestas traen `X-RateLimit-Limit`, `X-RateLimit-Remaining` y
`X-RateLimit-Reset`. Al recibir `429`, espera los segundos indicados en
`Retry-After`. Las rutas de lectura (`GET /v1/events`, `GET /v1/events/{event_id}`,
`GET /v1/customers/{customer_id}/events` y `GET /v1/event-types`) usan el límite
general.

## Modo de prueba

Con una clave de prueba (`bvt_test_…`), el evento pasa por toda la validación y
la resolución, pero no cambia nada en producción:

* **Nunca crea ni modifica clientes.** La respuesta devuelve el cliente que
  coincidiría, o `"customer": { "would_create": true }` cuando el envío crearía
  uno.
* **Nunca envía mensajes.** Los flows aparecen como `skipped` con
  `reason: "test_mode"`.
* **Queda separado.** El evento se guarda con `livemode: false`. Los eventos,
  los tipos de evento y la unicidad del `external_id` están separados entre
  prueba y producción, y cada clave solo lee los eventos de su modo. Los
  nombres vistos solo en prueba no cuentan para el límite de 500.

## Consentimiento al crear el cliente

* Un evento **nunca modifica** el opt-in o el opt-out de un cliente que ya
  existe.
* Un cliente creado por un evento nace **sin opt-in de marketing**, a menos que
  la llamada traiga `customer.consent`.
* `customer.consent` solo se lee cuando el evento crea al cliente.

```json theme={null}
{
  "name": "account_created",
  "customer": {
    "email": "ana@exemplo.com.br",
    "phone": "+5511988887777",
    "consent": { "email": true, "whatsapp": true }
  }
}
```

`consent.whatsapp` vale para WhatsApp y SMS. `consent.email` vale para email.

### Quién recibe los mensajes del flow

Lo que un flow puede enviar depende de la [naturaleza del
evento](https://docs.bevits.com/es/api-reference/recommended-events.md#1-naturaleza-del-evento) que lo
inició y del consentimiento del cliente en cada canal:

| Cliente | Evento de marketing | Evento de utilidad |
| - | - | - |
| Aceptó recibir mensajes | recibe | recibe |
| Nunca aceptó (incluido el creado sin `consent`) | no recibe | recibe |
| Pidió darse de baja | no recibe | no recibe |

* **Utilidad es sobre algo que el cliente hizo**, como el seguimiento de un
  pedido o el código de un Pix. Por eso alcanza a quien no aceptó marketing.
* **En WhatsApp oficial, la plantilla también debe ser de utilidad.** Un
  mensaje solo cuenta como utilidad cuando el evento es de utilidad y Meta
  aprobó la plantilla en la categoría de utilidad. Una plantilla de marketing
  sigue la regla de marketing, incluso en un flow iniciado por un evento de
  utilidad.
* **Los eventos sin naturaleza siguen la regla de marketing.** La naturaleza de
  cada tipo de evento se puede cambiar en Configuración → Eventos.
* **Email y WhatsApp son independientes.** `consent: { "email": true,
  "whatsapp": false }` recibe emails de marketing y solo WhatsApp y SMS de
  utilidad. Quien pidió darse de baja de todos los mensajes no recibe email.

Un flow que no alcanzaría al cliente por ningún canal aparece como `skipped`
con `no_consent`.

## Referencia de errores

Todo error sigue el sobre de la API. En los eventos, `error.code` nombra el
motivo, `error.param` trae la ruta completa del campo (`customer.email`,
`events[3].name`) y `error.suggestion`, cuando existe, trae un valor que sería
aceptado. Un evento rechazado no guarda nada y no toca a ningún cliente.

| HTTP | `error.code` | `error.param` | Significado |
| - | - | - | - |
| `422` | `invalid_event_name` | `name` | El nombre no sigue el formato. `suggestion` trae el nombre corregido, cuando hay uno. |
| `422` | `missing_customer_identifier` | `customer` | `customer` no tiene ningún identificador. |
| `422` | `unknown_field` | el campo | El cuerpo tiene un campo que la API no conoce. |
| `422` | `invalid_tax_id` | `customer.tax_id` | `tax_id` no es un CPF o CNPJ válido. Para otros documentos, usa `external_id`. |
| `422` | `invalid_phone` | `customer.phone` | El teléfono no es un número válido. |
| `422` | `attribute_type_mismatch` | `customer.attributes.<clave>` | El valor no cabe en el tipo del atributo que ya existe. |
| `422` | `event_too_large` | | El evento tiene más de 64 KB. |
| `422` | `too_many_properties` | `properties` | `properties` tiene más de 200 claves en total. |
| `422` | `properties_too_deep` | la ruta | `properties` tiene más de 5 niveles. |
| `422` | `array_too_long` | la ruta | Una lista tiene más de 100 elementos. |
| `422` | `occurred_at_in_future` | `occurred_at` | `occurred_at` está más de 5 minutos en el futuro. |
| `422` | `occurred_at_too_old` | `occurred_at` | `occurred_at` es más antiguo que 13 meses. |
| `422` | `too_many_event_names` | `name` | La tienda ya tiene 500 nombres de evento activos. |
| `422` | `event_type_archived` | `name` | El tipo de evento está archivado. |
| `422` | `batch_too_large` | `events` | El lote tiene más de 1 MB. |
| `404` | `customer_not_found` | `customer.id` | Ningún cliente activo tiene ese `id`. |
| `403` | `missing_scope` | `scope` | La clave no tiene el permiso que exige la ruta. |

Otros errores de validación, como un email mal formado o un `occurred_at` sin
offset, responden `422 validation_error` con `param` y sin `code`. Los demás
errores siguen los [fundamentos](https://docs.bevits.com/es/api-reference/fundamentals.md#errores):

| HTTP | `error.type` | Cuándo |
| - | - | - |
| `400` | `invalid_request` | El cuerpo no es un objeto JSON, o el `event_id` de la ruta es inválido. |
| `404` | `not_found` | El evento no existe, es de otro modo (prueba o producción) o ya pasó su plazo de lectura. |
| `409` | `conflict` | El `Idempotency-Key` ya se usó con otro cuerpo. |
| `429` | `rate_limited` | Se superó el límite por segundo. Espera `Retry-After`. |
| `503` | `service_unavailable` | El historial de eventos no está disponible. Inténtalo de nuevo en unos minutos; leer un evento reciente por ID sigue funcionando. |

## Próximos pasos

> [card] [Eventos recomendados](https://docs.bevits.com/es/api-reference/recommended-events.md)
>
> Nombres y propiedades sugeridos para los eventos más comunes de e-commerce.

> [card] [Autenticación](https://docs.bevits.com/es/api-reference/authentication.md)
>
> Crea una clave solo de envío con el permiso `events:write`.


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