Campos
Registre los campos de un tipo de evento para definir el contrato de datos aceptado en POST /events. Los campos determinan qué valida la plataforma en el envío, qué ignora y qué queda disponible para métricas y monitoreos.
Configuraciones de un campo
Al registrar un campo en el panel de administración, usted define:
| Configuración | Qué 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 trata 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
Un campo asume uno de estos tipos de dato, elegido en la creación:
| Tipo de dato | Qué almacena | Tipo de propiedad |
|---|---|---|
| Texto | texto libre, con tamaño máximo configurable | dimensión o medición |
| Lista | un valor entre los elementos registrados | dimensión o medición |
| Número entero | número sin decimales | medición |
| Número decimal | número con precisión y escala fijas, indicado para valores monetarios | medición |
| Número en coma flotante | número fraccionario sin precisión fija, como un score o una tasa | medición |
| Booleano | verdadero o falso | medición |
| Fecha y hora | un instante en formato ISO 8601, comparable por período | medición |
Observaciones importantes
- El campo de texto tiene Tamaño máximo en bytes, de 1 a 1024, con valor predeterminado de 48. Los valores mayores son rechazados, o cortados cuando Truncar automáticamente está activado.
- El campo de lista acepta hasta 100 elementos registrados, y rechaza cualquier valor fuera de ellos. El truncamiento no se aplica: un valor cortado dejaría de corresponder al elemento.
- En un campo decimal, la precisión llega hasta 12 dígitos y la escala hasta 4 decimales, ambas fijas después de la creación.
- En un campo en coma flotante, los Decimales valen solo para la visualización y pueden modificarse después.
Sugerencias de elementos
En el registro de los elementos de un campo de lista, la plataforma presenta los valores recibidos que aún no tienen un elemento correspondiente, considerando el mes en curso y el anterior. La selección de un valor abre la fila de nuevo elemento ya completada, restando informar la etiqueta.
La sugerencia deja de mostrarse cuando el elemento se registra. La sugerencia vuelve si el elemento se elimina mientras el campo siga recibiendo el valor. Los campos sensibles no generan sugerencias.
Apariencia del elemento
Cada elemento de un campo de lista acepta una marca visual, presentada en la columna de icono de la relación de elementos: un color, un icono del catálogo, o el logo de una marca, localizado por el nombre o por la dirección del sitio. La marca distingue los elementos de un vistazo, por ejemplo los emisores o los medios de pago de un campo. La marca es opcional y no participa de la validación del valor recibido. La cuenta usa el mismo recurso.
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.
La elección existe solo en los campos de texto y de lista. Los demás tipos de dato son siempre medición, conforme la tabla anterior.
El tipo de propiedad determina qué métricas y monitoreos pueden configurarse sobre el campo después.
Herencia
Un campo con Herencia activada es heredado por envíos posteriores que usen el mismo id y no informen el campo. Active la herencia en los campos que describen la entidad y llegan solo en el primer envío, como el cliente o el establecimiento. Deje la herencia desactivada en 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
El panel puede presentar un campo 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 | número entero | el nombre del emisor, en lugar del identificador |
| Proveedor del ASN | número entero | el nombre del proveedor, en lugar del número |
| Duración | número 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, entre milisegundos, segundos y minutos. Sin la unidad, 3500 tanto puede ser tres segundos y medio como casi una hora. El valor predeterminado es milisegundos, la unidad de los campos de permanencia.
Rastrear permanencia
Marque un campo discreto (lista o booleano) como rastreable. La plataforma pasa a registrar el tiempo que cada entidad permanece 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, la plataforma aprovisiona dos campos derivados. Los campos derivados funcionan 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 en 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: tiempo máximo que una entidad puede permanecer en un valor antes de dejar de ser rastreada. Configure el plazo del 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. Reactivar el rastreo 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.
Validación en el envío de eventos
En la recepción de eventos vía POST /events, la plataforma aplica el contrato de campos 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. Planifique esas configuraciones en el momento de la creación:
- el ID del campo no puede modificarse después del registro;
- el tipo de dato 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 elementos de campo del tipo lista se gestionan después de que el campo se crea;
- 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. El nombre y la descripción de esos campos aceptan cambios, para que aparezcan en el panel con la terminología de su operación.
La eliminación de un campo puede fallar si está en uso por métricas, por ejemplo en dimensiones o agregaciones.