Tipos de evento
El tipo de evento es la estructura que define el contrato de datos de un evento en la plataforma.
En la práctica, describe cómo debe estructurarse un evento, qué datos son relevantes para el análisis y cómo esos datos pueden monitorearse a lo largo del tiempo.
Por ejemplo, puede configurar tipos de evento para transacción financiera (transaction), autenticación de usuario (user_authentication) o hitos logísticos de entrega (logistics_delivery_event).
Diferencia entre tipo de evento y evento
- tipo de evento: es el modelo de datos y las reglas de validación.
- evento: es la ocurrencia real enviada a la API, siguiendo el modelo del tipo de evento.
Todo evento siempre pertenece a un tipo de evento previamente configurado.
En la API POST /events, esto ocurre a través del atributo type del evento, que debe indicar el ID del tipo de evento registrado. Si el tipo indicado no existe o está inactivo, el envío es rechazado.
Qué resuelve el tipo de evento
Con el tipo de evento, la integración deja de depender de endpoints rígidos por dominio específico (como pagos) y pasa a seguir un modelo más flexible:
- usted define el tipo de evento según su contexto de negocio;
- envía eventos estandarizados al endpoint
POST /events; - evoluciona el modelo con menor acoplamiento entre producto e integración.
Componentes principales
Un tipo de evento normalmente incluye:
- campos: estructura del evento (por ejemplo: identificadores, valores, estado y atributos de contexto);
- métricas: agregaciones e indicadores derivados de los eventos recibidos;
- monitoreos: reglas y vistas para el seguimiento operacional, riesgo y rendimiento.
Esta combinación permite modelar diferentes flujos de negocio sin crear un endpoint específico para cada nuevo caso de uso.
Campos
Los campos definen el contrato de datos del tipo de evento. Consulte Campos para más detalles sobre configuración, tipos de dato y reglas de validación.
Relación con la API /events
Una vez que se define un tipo de evento, cada ocurrencia se envía a POST /events siguiendo el contrato correspondiente.
Este patrón favorece:
- estandarización de la ingestión de datos;
- evolución continua del modelado;
- reutilización de métricas y monitoreos entre escenarios.
Buenas prácticas
- Use nombres claros y estables para los tipos de evento.
- Evite tipos demasiado genéricos, sin semántica de negocio.
- Trate los cambios de contrato con versionado planificado.
- Documente la obligatoriedad y el formato de cada campo para el equipo de integración.