Eventos

Evento es cada ocurrencia enviada a la plataforma a través del endpoint POST /events.

Mientras el tipo de evento define el contrato, el evento representa el dato real ocurrido en la operación (por ejemplo: un intento de pago, una autenticación o una actualización de registro).

Todo evento pertenece a un tipo de evento

Para enviar un evento, es obligatorio indicar en el atributo type qué tipo de evento representa.

Este valor debe ser el ID de un tipo de evento previamente configurado y activo en la cuenta.

Si el tipo de evento no existe o está inactivo, la API rechaza el envío.

Estructura mínima de envío

En el envío a POST /events, los campos principales son:

• type: ID del tipo de evento;
• id: identificador único del evento;
• attributes: datos del evento según los campos configurados en el tipo;
• timestamp (opcional): fecha y hora de la ocurrencia. Si no se indica, la plataforma utiliza el horario de recepción;
• rule.name (opcional): nombre de la regla que se ejecutará sobre este evento. Sin este atributo, se aplica la regla predeterminada del tipo de evento, si la hay.

Los nombres de campo que comienzan con _ o % están reservados por la plataforma, y el envío se rechaza si alguno de ellos aparece en attributes.

Herencia entre eventos con el mismo id

Varios envíos pueden compartir el mismo id, representando la misma ocurrencia en etapas diferentes: la creación de un pedido y, minutos después, su resultado. Un envío posterior no necesita repetir todo lo que ya fue informado.

Cada campo del tipo de evento define si participa de esa herencia, mediante la configuración Herencia. Cuando está activada, un envío que omite el campo recibe el valor dejado por el envío anterior; cuando está desactivada, el campo vale solo para el envío que lo trajo.

Lo que se hereda es el evento tal como quedó grabado, incluidos los campos completados por una regla durante el procesamiento, y no solo lo que el cliente envió. Los valores heredados valen en todas partes: en el evento grabado, en las condiciones de la regla y en los análisis.

Enviar el campo con el valor null limpia el valor heredado, y los envíos siguientes no lo recuperan. Omitir el campo mantiene la herencia.

La herencia tiene un plazo, configurado en el tipo de evento. Pasado ese plazo sin nuevos envíos con el mismo id, los valores acumulados se descartan y un envío posterior vale exactamente por lo que traiga.

Cómo funciona la validación

La validación del evento sigue las configuraciones del tipo de evento:

• los campos obligatorios deben enviarse;
• los tipos de datos deben estar en el formato esperado;
• los campos desconocidos pueden ignorarse o rechazarse, según la configuración del tipo de evento.

Esto garantiza consistencia en la ingestión y evita que eventos fuera del contrato afecten métricas y monitoreos.

Qué devuelve la respuesta

La respuesta trae el id del evento y todos los campos del tipo de evento, incluidos los que fueron completados por una regla durante el procesamiento. Un evento enviado con tres campos puede volver con cinco, si una regla enriqueció los otros dos.

Los campos reservados de la plataforma se graban en el evento, pero no aparecen en la respuesta.

Ejemplo práctico

1. Registre un tipo de evento con ID transaction.
2. Defina los campos esperados, como amount y status.
3. Envíe un evento a POST /events con type: transaction.
4. La plataforma valida el payload, ejecuta la regla del tipo de evento (si la hay) y procesa el evento para su uso en análisis, métricas y monitoreos.