Campos
Los campos de evento son los atributos definidos en el tipo de evento que forman el contrato de datos aceptado en POST /events.
Son estos campos los que determinan qué se validará en el envío, qué se ignorará y qué podrá usarse para generar métricas y monitoreos.
Qué se puede configurar en un campo
Al registrar un campo en el panel de administración, usted define:
- ID del campo: identificador usado en el payload de la API;
- nombre y descripción: etiquetas mostradas en el panel;
- tipo de dato: formato esperado para el valor;
- tipo de propiedad: cómo se tratará el campo en el modelado;
- obligatoriedad: si el campo debe estar presente en cada evento;
- herencia: si el campo es heredado por envíos posteriores con el mismo
id; - visualización: cómo se presenta el valor en el panel;
- estado: si el campo está activo o inactivo.
El formulario agrupa esas configuraciones en Comportamiento (obligatoriedad, sensibilidad, herencia y estado), Formato (precisión, visualización y límites de tamaño) y Permanencia.
Tipos de dato disponibles
La plataforma permite los siguientes tipos de campo:
- texto;
- lista (valores predefinidos);
- número entero;
- número decimal;
- número en coma flotante;
- booleano.
Observaciones importantes
- El campo de texto acepta hasta 128 caracteres.
- Los campos de tipo lista permiten registrar ítems permitidos para validación.
- En campos decimales, la precisión y la escala se definen en la creación.
Tipo de propiedad: dimensión o medición
Cada campo también recibe un tipo de propiedad:
- dimensión: representa una característica del evento usada para segmentación;
- medición: representa un valor variable usado en consolidaciones.
Esta elección impacta cómo las métricas y los monitoreos pueden configurarse más adelante.
Herencia
Un campo con Herencia activada es heredado por envíos posteriores que usen el mismo id y no informen el campo. Actívela para los campos que describen la entidad y llegan solo en el primer envío, como el cliente o el establecimiento; déjela desactivada para los campos que valen únicamente para el envío que los trajo, como la etapa o el código de respuesta de ese intento.
Desactivar la herencia pasa a valer en el envío siguiente, incluso para los valores ya acumulados. El mecanismo completo está descrito en Herencia entre eventos con el mismo id.
Visualización del valor
Un campo puede presentarse en el panel de forma diferente al valor almacenado. La visualización es solo visual: el valor grabado, los filtros y las comparaciones en las reglas siguen usando el valor original.
| Visualización | Se aplica a | Resultado |
|---|---|---|
| Valor original | cualquier campo | el valor tal como fue recibido |
| País (ISO 3166) | texto | el nombre del país y la bandera, en lugar del código |
| Emisor de la tarjeta | entero | el nombre del emisor, en lugar del identificador |
| Proveedor del ASN | entero | el nombre del proveedor, en lugar del número |
| Duración | entero | tiempo legible, como 3,5s o 2d 1h |
La visualización de duración tiene una configuración propia, la unidad de tiempo en que se almacena el valor: milisegundos, segundos o minutos. Sin ella no hay forma de saber si 3500 son tres segundos y medio o casi una hora. El valor predeterminado es milisegundos, la unidad de los campos de permanencia.
Rastrear permanencia
Un campo discreto (lista o booleano) puede marcarse como rastreable. A partir de ahí, la plataforma registra cuánto tiempo permanece cada entidad en cada valor de ese campo: la duración de un pedido en pendiente, el tiempo transcurrido de un registro en bloqueo.
Al activar el rastreo, se aprovisionan automáticamente dos campos derivados que pasan a estar disponibles como cualquier otro campo del tipo de evento, incluso en métricas, filtros y reglas:
| Campo derivado | Tipo de propiedad | Contenido |
|---|---|---|
<campo> anterior | dimensión | valor en que estaba la entidad antes del cambio |
Tiempo en <campo> anterior | medición | duración de la permanencia cerrada por ese cambio |
Dos configuraciones acompañan al rastreo:
- Dimensiones de segmentación: campos discretos por los cuales pueden segmentarse las medidas en abierto, como el proveedor o el establecimiento. Solo esos campos pueden usarse como dimensión en una métrica de permanencia en abierto.
- Retención de la permanencia: cuánto tiempo puede permanecer una entidad en un valor antes de dejar de ser rastreada. Configure el plazo de su proceso: una entidad que lo supera fue abandonada, no está retenida, y contabilizarla distorsiona las medidas en abierto. En blanco, rigen 90 días, que también es el techo.
Un tipo de evento acepta como máximo 2 campos rastreables. Desactivar el rastreo interrumpe el registro y preserva los campos derivados y las métricas construidas sobre ellos; reactivarlo reaprovecha los mismos campos.
El rastreo vale a partir del momento en que se activa y no reprocesa el historial. Lo mismo se aplica a una dimensión de segmentación añadida después: las entidades ya abiertas siguen sin ella hasta que cambien de valor.
Reglas de validación en el envío de eventos
Al recibir eventos a través de POST /events, el contrato de campos se aplica con las siguientes reglas:
- los campos obligatorios ausentes causan rechazo;
- los valores fuera del tipo esperado causan rechazo;
- los campos inactivos pueden permanecer en el payload, pero sus valores son ignorados;
- los campos desconocidos pueden ignorarse o rechazarse, según la configuración del tipo de evento.
Buenas prácticas para modelar campos
- Defina IDs estables y semánticos desde el principio.
- Comience con un conjunto reducido de campos esenciales.
- Use campos de lista cuando haya un conjunto controlado de valores.
- Evite crear campos redundantes para el mismo concepto.
- Revise periódicamente los campos sin uso.
Restricciones y ciclo de vida
Algunas configuraciones son estructurales y deben planificarse en el momento de la creación:
- el ID del campo no puede modificarse después del registro;
- el tipo de propiedad no puede modificarse después del registro;
- en campos decimales, la precisión y la escala quedan fijas después de la creación;
- los ítems de campo del tipo lista se gestionan después de que se crea el campo;
- el tipo de evento tiene un límite de hasta 100 campos.
Los campos gestionados por la plataforma, como los aprovisionados por el rastreo de permanencia o por las reglas, no pueden eliminarse, pero su nombre y su descripción sí pueden cambiarse, para que aparezcan en el panel con la terminología de su operación.
Al eliminar un campo, la operación puede fallar si está en uso por métricas (por ejemplo, en dimensiones o agregaciones).