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) yproperties(detalles). Opcionales:occurred_at,external_idybackfill. - 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.
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.nameactualiza el nombre del cliente.customer.attributesguarda 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 comoskippedconno_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.
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.
id de inmediato.
customer.matched_bydice qué identificador encontró al cliente. Cuando el evento creó al cliente, llegacreated: trueymatched_byse omite.flowslista los flows activos que escuchan ese nombre. Una lista vacía significa que ningún flow está escuchando.warningsaparece solo cuando hay algo que avisar. Un aviso nunca sustituye a un error.duplicate: trueaparece 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 traerflows[].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 disparadorcustom.<nombre_del_evento>. Crea el flow con POST /v1/flows, con
platform: "custom" y el nombre del evento en event:
trigger.filterses opcional y acepta hasta 10 filtros. El flow solo se inicia cuando todos coinciden con las propiedades del evento.propertyes la ruta de la propiedad, comotracking.carrieroitems[0].sku.- Una propiedad ausente o de otro tipo simplemente no pasa el filtro. El flow
aparece como
skippedconfilter_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.
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_variableen 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 confield: "event.<ruta>". La propiedad se compara como el tipo del valor dado:
número, booleano o texto, y lista con includes.
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 llegapayment_confirmed.
- Un evento que llega antes también cuenta. Todo lo que el flow escucha se
registra cuando empieza la ejecución. Si
payment_confirmedllega 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_onvincula 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 cuyoorder_numberes igual al del evento que inició el flow, para que un cliente con dos pedidos abiertos no tenga los dos terminados por un pago.10293y"10293"son el mismo valor. Solo funciona en flows iniciados por un evento personalizado; si el evento inicial no tiene la propiedad, nada coincide.filtersfuncionan 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 debackfillnunca 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.
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 conevents:writeno puede validar. - Cuando el envío crearía al cliente, la respuesta trae
"customer": { "would_create": true }. - El
iddel 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.
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.
resultstiene el mismo orden y el mismo tamaño queevents. Cadaeventllega completo, como en la respuesta dePOST /v1/events.- El
paramde cada error empieza por la posición del evento:events[2].name. - El
200no significa que todo fue aceptado. Revisafailedy reenvía solo los elementos constatus: "error"después de corregirlos. - El lote entero solo se rechaza (
422) cuandoeventsestá 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.
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
eventdeGET /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[].skuincluyeCAM-01,totalmayor que 100). Se combina con las demás condiciones por Y y O. Los eventos de prueba nunca cuentan; los debackfillsí. “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[].pathusa puntos para objetos y[]para elementos de una lista.typeesstring,number,boolean,date,listuobject.- 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.
natureesutilityomarketing. 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 permisoevents: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
403conmissing_scope. - La respuesta del envío trae únicamente
customer.id.customer.matched_byycustomer.createdse omiten. - Los avisos de identidad (
ambiguous_identifier,identifier_conflict,identifier_mismatch) se omiten. Solo aparecepayload_mismatch.
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
skippedconreason: "test_mode". - Queda separado. El evento se guarda con
livemode: false. Los eventos, los tipos de evento y la unicidad delexternal_idestá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.consentsolo 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.
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.