Modelo de datos: cargas, tramos, paradas, actualizaciones y transportistas

Una carga en TrackFlo se compone de cinco objetos, cada uno con su propio endpoint de upsert y enlace permanente.

Carrier ──┐
          │  assigned to
Load ─────┴─► Load leg ─┬─► Stop (pickup)
 (order)     (route)    ├─► Stop (delivery)
                        └─► Load update, Load update, … (append-only)

• Una carga tiene uno o más tramos (load_leg_sequence, basado en 1). La mayoría de las cargas de brokerage tienen exactamente uno.

• Un tramo tiene dos o más paradas (stop_sequence, basado en 1). Tanto la carga como el tramo indican su primera recogida y su entrega final (origin_stop_id, destination_stop_id y sus enlaces permanentes).

• Las actualizaciones de carga se asocian a un tramo. TrackFlo obtiene de ellas la última ubicación, la ETA y el comentario del tramo; usted no debe escribir esos campos de "última actualización".

• Las marcas de tiempo vienen en pares: *_utc y *_local. Envíe ambas; TrackFlo muestra la hora local a los usuarios y realiza los cálculos con UTC. La única excepción es planned_appointment_utc, que no tiene un equivalente _local. Consulte la sección Marcas de tiempo más abajo.

• Una cita fija es una ventana de ancho cero: envíe la misma hora en earliest_appointment_time_* y latest_appointment_time_*. Una parada sin hora de cierre de la cita no se muestra en el panel.

• Un tramo marcado con no_contact_load: true no recibe comunicaciones automáticas (SMS, voz, WhatsApp, correo electrónico al transportista, MacroPoint), y el panel muestra un icono de no contactar para que los rastreadores no llamen. Envíelo cuando su TMS marque el movimiento o su pedido como no contactar.

Citas y ETA

Una parada incluye dos tipos de cita, y una actualización de carga puede indicar para qué parada corresponde su ETA.

• La cita actual es earliest_appointment_time_* / latest_appointment_time_*. Actualícela cada vez que se reprograme la cita.

• El plan original es planned_appointment_utc en la parada. Siga enviando la primera hora planificada después de una reprogramación. TrackFlo compara la ETA de la parada con ella y genera Planned ETA Drift cuando la ETA se retrasa con respecto al plan más allá del umbral de desviación de ETA de la empresa. Esa excepción sigue generándose después de una reprogramación, cuando deja de recibirse la ETA posterior a la cita. Una parada sin planned_appointment_utc nunca genera esta excepción. Si su TMS planifica solo por fecha, envíe las 12:00 en la hora local de la parada, convertida a UTC.

• La parada a la que corresponde una ETA se indica en eta_stop_permalink de la actualización de carga (el native_system_stop_permalink de la parada). Sin este valor, TrackFlo supone que se trata de la siguiente parada a la que aún no se ha llegado. Con este valor, la ETA se almacena en la parada indicada y actualiza la ETA del tramo en el panel solo cuando esa parada es la siguiente a la que aún no se ha llegado. Por lo tanto, un TMS que envíe una ETA para cada parada puede enviarlas todas.

Mercancía

La mercancía de una carga se incluye en commodity, un objeto por pedido:

{
  "description": "Frozen poultry",
  "pieces": 24,
  "weight": 37000,
  "weight_unit": "LB",
  "items": [
    { "description": "Frozen poultry", "pieces": 20, "weight": 30000, "weight_unit": "LB" },
    { "description": "Dry ice",        "pieces": 4,  "weight": 7000,  "weight_unit": "LB" }
  ]
}

• El nivel superior es el total del pedido y es lo que muestra TrackFlo. Si su TMS conserva la mercancía únicamente por línea, sume las líneas en los totales y envíe las líneas como items. Si solo conserva los totales, omita items.

• pieces cuenta únicamente las piezas. Una cantidad que su TMS registre en palés, bolsas u otras unidades de manipulación no es un recuento de piezas, por lo que debe omitir pieces en lugar de enviarlo. 0 es válido para mercancía a granel.

• weight necesita una weight_unit. Envíe la unidad que utiliza su TMS (LB, KG, …). TrackFlo nunca supone una unidad. Se rechaza un peso sin unidad, por lo que debe omitirlo si su TMS no proporciona ninguna.

• Los números son números JSON. Envíe 37000, no "37000.0".

• El objeto completo se reemplaza en cada upsert. Envíe el objeto completo cada vez; null lo borra. Se aceptan y almacenan otras claves.

Marcas de tiempo

ISO-8601; es suficiente una precisión de segundos.

TrackFlo almacena las marcas de tiempo sin zona horaria. Esto tiene una consecuencia importante: un desplazamiento distinto de cero no se convierte. Si se envía 2026-09-06T10:37:00-05:00 en un campo _utc, se almacena como 10:37 y se interpreta como las 10:37 UTC, cinco horas antes. Convierta la hora a UTC antes de enviarla y nunca incluya un desplazamiento en un valor _local.

Una actualización de carga cuyo load_update_utc_timestamp esté más de 15 minutos en el futuro se almacena, pero se ignora cuando TrackFlo obtiene la última ubicación, la ETA y el comentario del tramo; de lo contrario, las fechas futuras erróneas bloquearían las actualizaciones reales hasta que el reloj se pusiera al día.