Eventos

Envíe a POST /events cada ocurrencia real de la operación: un intento de pago, una autenticación, una actualización de registro. El tipo de evento define el contrato; el evento lleva el dato ocurrido.

Vínculo con el tipo de evento

Todo evento informa en el atributo type qué tipo de evento representa. El atributo es obligatorio.

El valor de type debe ser el ID de un tipo de evento ya 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. Sin ese atributo, la plataforma usa el horario de la recepción;
• rule.name (opcional): nombre de la regla que se ejecutará sobre este evento. Sin ese atributo, vale la regla predeterminada del tipo de evento, si la hay.

Los nombres de campo que comienzan con _ o % están reservados por la plataforma. La API rechaza el envío 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. Con la herencia activada, un envío que omite el campo recibe el valor dejado por el envío anterior. Con la herencia desactivada, el campo vale solo para el envío que lo trajo.

La herencia lleva el evento tal como quedó grabado, no solo lo que el cliente envió. Los campos completados por una regla durante el procesamiento también se heredan. 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, la plataforma descarta los valores acumulados y un envío posterior vale exactamente por lo que traiga.

Validación del envío

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.

La validación garantiza consistencia en la ingestión e impide que eventos fuera del contrato afecten métricas y monitoreos.

Respuesta del envío

La respuesta presenta el id del evento y todos los campos del tipo de evento. Los campos completados por una regla durante el procesamiento también aparecen en la respuesta. Un evento enviado con tres campos puede retornar con cinco, si una regla enriqueció los otros dos.

La plataforma graba los campos reservados en el evento, pero no los presenta en la respuesta.

Ejemplo práctico

1. Usted registra un tipo de evento con ID transaction.
2. Define los campos esperados, como amount y status.
3. Envía 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.