Saltar al contenido principal
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.
  • 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.
La clave necesita el permiso write o events:write. Consulta Clave solo de envío.

Envío completo

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:

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ó. 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: 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.

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. Lo que no cabe se rechaza con 422 y un error.code. No se trunca nada. 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. 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.
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

Para saber qué ocurrió con un flow queued, consulta el 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.

Avisos

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:
  • 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, y los bloques de condición las comparan con field: "event.<ruta>" (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:
  • 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). 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 (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.
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.
  • 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.
  • 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.
La respuesta es 200 con un resultado por evento:
  • 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.
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.
  • 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.
  • 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 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. 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. 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.
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 que lo inició y del consentimiento del cliente en cada canal:
  • 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. 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:

Próximos pasos

Eventos recomendados

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

Autenticación

Crea una clave solo de envío con el permiso events:write.