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 que ocurrió en su 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.

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.

Ejemplo práctico

Registre un tipo de evento con ID transaction.
Defina los campos esperados, como amount y status.
Envíe un evento a POST /events con type: transaction.
La plataforma valida el payload y, si es correcto, procesa el evento para su uso en análisis, métricas y monitoreos.