Cuando configuras una automatización para Rondas Interna (por ejemplo "Al marcar un punto", "Al marcar un punto con fraude de umbral", "Al completar una ronda", "Al vencimiento de una ronda", etc.), el flujo recibe datos de la ronda y, según el tipo de acción, también métricas de cumplimiento. En este artículo se explica qué información llega y qué nombres de campo usar en el diseñador del flujo.

Visión general

El flujo recibe un único objeto llamado my_info, con esta estructura:

{
  "my_info": {
    "meta": { ... },
    "data": {
      "subject": { ... },
      "ronda": { ... },
      "ronda_marcaciones": [ ... ],
      "ronda_cumplimiento": { ... }
    }
  }
}

• meta: Metadatos del evento: identificador único del evento, fecha y hora, cuenta, módulo, acción, entity_id (cuando aplica) e identificador del flujo.
• data.subject: Tipo de registro ("ronda") e identificadores: form_id, local_id (en eventos por marcación de un punto), record_id y, en eventos de ronda completa, id_ronda.
• data.ronda: Cabecera de la ronda: identificador, fechas, estado, sede, cliente, zona, ciudad, turno/jornada. Puede ser null si la ronda no se puede resolver.
• data.ronda_marcaciones: Lista de puntos de la ronda (cada uno con hora programada, hora marcada, umbrales e indicadores de fraude). Siempre es un array (puede estar vacío).
• data.ronda_cumplimiento: Solo en eventos de ronda completa (vencimiento, completar ronda, terminar incompleta, superar hora de inicio, fraude desplazamiento a nivel ronda). Incluye total de puntos, puntos marcados, cumplimiento real y fraude por tipo. En eventos por marcación de un punto no se envía.

Cuando el evento es por una marcación concreta (un punto marcado) y el sistema puede recuperar el registro de ese envío, data puede incluir además los mismos bloques que en eventos de formularios (respuestas, fechas en formato legible, sucursal, etc.) para usar el contenido de esa marcación en el flujo.

Las fechas y horas que reciba el flujo estarán en formato estándar y, cuando aplique, en la zona horaria de tu cuenta.

Estructura general (qué verás en el diseñador)

En el diseñador del flujo verás esta misma jerarquía: my_info → meta y data; dentro de data, subject, ronda, ronda_marcaciones y, si aplica, ronda_cumplimiento. Los nombres de campo que se listan abajo son los que usarás al conectar los datos entrantes.

Dos tipos de eventos de ronda

Hay dos formas en que puede dispararse un evento de ronda interna:

1. Por una marcación concreta: cuando se marca un punto de la ronda (con o sin fraude de umbral, geocerca, altitud, desplazamiento o tag no conocido). El flujo recibe meta, data.subject, data.ronda, data.ronda_marcaciones y, cuando el sistema puede recuperarlo, los datos del registro de esa marcación (en los mismos campos que en eventos de formularios). No recibe data.ronda_cumplimiento.
2. Por la ronda completa: cuando ocurre algo a nivel de toda la ronda (vencimiento, completar ronda, terminar ronda incompleta, superar la hora de inicio o fraude de desplazamiento en variante de ronda completa). El flujo recibe meta, data.subject (con id_ronda), data.ronda, data.ronda_marcaciones y data.ronda_cumplimiento (métricas de cumplimiento).

Contenido de meta

En todos los casos meta incluye:

• event_id: identificador único de esta ejecución del evento (para trazabilidad).
• occurred_at: fecha y hora del evento (si la aplicación la envía).
• id_account: identificador de tu cuenta (tenant).
• module: módulo que disparó la automatización (rondas_interna).
• action: acción concreta (por ejemplo marcar_punto, completar_ronda, vencimiento_ronda, etc.).
• entity_id: identificador asociado al evento cuando aplica; puede ser null.
• flow_id: identificador del flujo que se está ejecutando.

Contenido de data.subject

data.subject incluye:

• type: tipo de registro; para rondas internas será "ronda".
• form_id: identificador del formulario de la marcación (en eventos por marcación de un punto).
• local_id: identificador local del registro de esa marcación (en eventos por marcación).
• record_id: identificador de la ronda o del registro, según el caso.
• id_ronda: en eventos de ronda completa, identificador de la ronda (string). En eventos por marcación puede no estar presente.

Contenido de data.ronda

Cuando el sistema puede identificar la ronda asociada al evento, data.ronda contiene la cabecera de la ronda. Los campos que no existan pueden llegar vacíos o nulos.

• id_ronda: identificador de la ronda.
• date_time: fecha y hora programada de la ronda.
• estado_ronda: estado de la ronda (por ejemplo Completa, Incompleta).
• start_at: fecha y hora de inicio real de la ronda (si existe).
• end_at: fecha y hora de fin (programada o real).
• done_at: fecha y hora en que se finalizó la ronda (si aplica).
• id_account_customer_point: identificador de la sede (punto).
• id_account_customer: identificador del cliente.
• id_turno_jornada: identificador del turno/jornada.
• id_account: identificador de la cuenta.
• customer_point_name: nombre de la sede.
• customer_point_address: dirección de la sede (o coordenadas si se guardaron así).
• customer_name: nombre del cliente.
• customer_code: código del cliente.
• customer_identification: identificación del cliente.
• geo_zone_name: nombre de la zona.
• geo_zone_code: código de la zona (si existe).
• geo_city_name: nombre de la ciudad.
• geo_city_code: código de la ciudad (si existe).
• turno_jornada_name: nombre del turno/jornada (por ejemplo Diurno, Nocturno).

Si la ronda no se puede resolver, data.ronda puede ser null.

Contenido de data.ronda_marcaciones

data.ronda_marcaciones es una lista de puntos de esa ronda. Cada elemento es un objeto con:

• id_account_customer_subpoint_planeacion_tag: identificador del punto en la planeación de la ronda.
• id_ronda: identificador de la ronda.
• id_account_customer_subpoint_tag: identificador del subpunto/tag.
• start_at: hora programada de inicio de ese punto.
• done_at: hora en que se marcó el punto (si ya se marcó; si no, puede ser null).
• tolerance_meters: umbral de distancia permitida (metros) para considerar el punto cumplido.
• cheat_tolerance_meters: si hubo fraude por umbral (se excedió la distancia); si no aplica, null.
• cheat_position_meters: si hubo fraude por geocerca (incumplimiento de la geocerca); si no aplica, null.
• cheat_proximity_meters: si hubo fraude por desplazamiento; si no aplica, null.
• cheat_altitude_meters: si hubo fraude por altitud; si no aplica, null.
• tolerance_meters_altitude: umbral de altitud permitida (metros), si aplica.
• id_survey_solution_subpoint_tag: identificador del subpunto en la solución (si aplica).
• alert_failure_at: fecha/hora en que se generó alerta por no haber marcado ese punto a tiempo (si aplica).

Así el flujo puede saber qué puntos se marcaron, cuáles no y cuáles tuvieron fraude (umbral, geocerca, desplazamiento o altitud).

Contenido de data.ronda_cumplimiento (solo eventos de ronda completa)

Cuando el evento es de ronda completa, data.ronda_cumplimiento está presente. En eventos por marcación de un punto no se envía este bloque.

• total_puntos: total de puntos de la ronda.
• puntos_marcados: cuántos puntos tienen ya una marcación (aunque haya fraude).
• puntos_marcados_sin_fraude: cuántos se marcaron correctamente (sin ningún tipo de fraude).
• cumplimiento_real: porcentaje que representa los puntos marcados sin fraude sobre el total (por ejemplo 0, 50, 100).
• fraude_umbral: objeto con cantidad y porcentaje (puntos con fraude de umbral sobre los marcados).
• fraude_geocerca: objeto con cantidad y porcentaje (fraude por geocerca).
• fraude_desplazamiento: objeto con cantidad y porcentaje (fraude por desplazamiento).
• fraude_altitud: objeto con cantidad y porcentaje (fraude por altitud).

Ejemplo de uso en el flujo: si cumplimiento_real es 0 y fraude_umbral.cantidad es mayor que 0, puedes interpretar que la ronda se marcó pero todos los puntos marcados tuvieron fraude de umbral.

Datos del registro de la marcación (eventos por marcación)

Cuando el evento se dispara por una marcación concreta (un punto marcado) y el sistema puede recuperar el registro de ese envío, data incluye además los mismos bloques que en eventos de formularios: form_id, local_id, fechas en formato legible, sucursal por nombre, simplified, index_map, answers, etc. Así puedes usar en el flujo el contenido concreto de esa marcación (respuestas, usuario que marcó, etc.) sin acceder a otras pantallas.

Resumen rápido

• Estructura: my_info con meta y data; en data tienes subject, ronda, ronda_marcaciones y, solo en eventos de ronda completa, ronda_cumplimiento. Usa los nombres de campo indicados arriba en el diseñador del flujo.
• Evento por marcación de un punto: recibes meta, data.subject (con form_id, local_id), data.ronda, data.ronda_marcaciones y, cuando se puede recuperar, los datos del registro (como en formularios). No recibes data.ronda_cumplimiento.
• Evento por ronda completa: recibes meta, data.subject (con id_ronda), data.ronda, data.ronda_marcaciones y data.ronda_cumplimiento (total_puntos, puntos_marcados, cumplimiento_real, fraude por tipo).
• Los indicadores de fraude en cada elemento de ronda_marcaciones (cheat_tolerance_meters, cheat_position_meters, cheat_proximity_meters, cheat_altitude_meters) permiten saber si ese punto se marcó correctamente o con incumplimiento.