Cree endpoints para devolver datos a TrackFlo

Cree cinco endpoints HTTPS en su TMS y nosotros enviaremos al envío correcto el trabajo de seguimiento que realiza su equipo en TrackFlo: llamadas de comprobación, llegadas y salidas de paradas, cambios de estado, datos del conductor y del equipo, y documentos. Este artículo explica qué tienen en común los cinco endpoints: autenticación, formato de las solicitudes, cómo responder, reintentos y pruebas. El artículo de cada endpoint enumera todos los campos que incluye.

Use esta opción si su TMS no es uno de los sistemas a los que nos conectamos de forma predeterminada. En el caso de McLeod, Turvo, Mastery, Tai y Revenova, escribimos mediante la API propia del TMS y usted no tiene que crear nada; consulte Cómo se conecta TrackFlo a su TMS.

Los cinco endpoints

Las rutas son sugerencias; puede usar cualquier URL HTTPS. Envíenos la URL de cada endpoint que cree. Puede crearlos en cualquier orden, y las actualizaciones de un endpoint que aún no haya creado permanecerán solo en TrackFlo.

Antes de empezar

• Solo HTTPS, TLS 1.2 o posterior. Nos conectamos desde una dirección IP fija, que le proporcionaremos durante la incorporación para que pueda permitirla en su firewall.

• Una clave de API que usted emita para TrackFlo. La almacenamos cifrada en AWS Secrets Manager.

• Los identificadores que ya nos envía. Cada solicitud identifica la carga, el tramo y la parada mediante los identificadores que su TMS envió a Integration API, para que pueda buscar los registros con sus propias claves.

• Un entorno de pruebas, si dispone de uno. Probamos allí cada endpoint antes de que su equipo dependa de él.

Autenticación

Cada solicitud incluye dos encabezados: su clave, para que pueda comprobar que la solicitud proviene de un remitente autorizado, y nuestra firma, para que pueda comprobar que el cuerpo no se modificó después de que lo enviáramos.

Authorization: Bearer <the key you issued to TrackFlo>
X-TrackFlo-Signature: t=1792675200,v1=5f2b1c...

• Authorization: rechace las solicitudes que no incluyan una clave válida con 401.

• X-TrackFlo-Signature: t es la hora Unix en la que generamos la firma. v1 es el HMAC-SHA256 en formato hexadecimal de <t>.<raw request body>, cuya clave es el secreto de firma que le proporcionamos durante la incorporación. Vuelva a calcularlo a partir de los bytes sin procesar antes de analizar el JSON, compare los valores en tiempo constante y rechace la solicitud con 401 si no coinciden o si t difiere de la hora de su reloj en más de 5 minutos.

import hashlib, hmac, time

def verify_trackflo_signature(raw_body: bytes, header: str, secret: str) -> bool:
    pairs = [part.split("=", 1) for part in header.split(",")]
    timestamp = next(value for key, value in pairs if key == "t")
    if abs(time.time() - int(timestamp)) > 300:
        return False
    signed = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, value) for key, value in pairs if key == "v1")

Cuando se cambia una clave o un secreto, acordamos con usted una fecha para hacer el cambio. Acepte la clave anterior y la nueva hasta que confirmemos el cambio. Mientras se cambia un secreto de firma, el encabezado incluye dos valores v1; acepte la solicitud si alguno de ellos coincide.

Formato de las solicitudes

Cada solicitud es un POST con un cuerpo JSON codificado en UTF-8 y los siguientes encabezados:

Content-Type: application/json
Idempotency-Key: 6f1d2c0e-8a43-4f0b-9a57-2b8d3e1c4f90

El cuerpo incluye los campos comunes que se indican a continuación y los campos propios del endpoint.

{
  "event_id": "6f1d2c0e-8a43-4f0b-9a57-2b8d3e1c4f90",
  "event_type": "load_update",
  "native_system_load_id": "1089520",
  "native_system_load_leg_id": "2330158",
  "entered_by_name": "Jordan Ellis",
  "entered_by_email": "[email protected]",
  "entered_by_tms_user_id": "JELLIS",
  "entered_at_utc": "2026-10-24T15:42:10Z",
  "trackflo_load_url": "https://app.trackflo.tech/public_load_details/4b6e…"
}

Marcas de tiempo

Enviamos los mismos pares de marcas de tiempo que usa Integration API, siempre con ambos valores cuando conocemos la zona horaria de la ubicación.

• _utc: fecha y hora en formato ISO-8601 en UTC con una Z, por ejemplo, 2026-10-24T15:37:00Z.

• _local: la hora local de la parada o ubicación, sin desplazamiento de zona horaria; por ejemplo, 2026-10-24T10:37:00. La zona horaria se especifica en el campo *_iana_timezone del endpoint.

Cómo responder

Responda en un plazo de 30 segundos. Si no recibe respuesta, consideramos que se produjo un error y volvemos a intentarlo.

Envíe los errores con este formato:

{ "error": "stop_not_found", "message": "Stop 88213 is not on movement 2330158." }

Reintentos y duplicados

Reintentamos las solicitudes fallidas hasta 5 veces, con tiempos de espera cada vez mayores, durante unos 25 minutos. Cada reintento incluye el mismo event_id. Si el último intento falla, la persona que realizó la actualización recibe un correo electrónico y una notificación en TrackFlo, y la actualización permanece guardada en TrackFlo.

• Guarde event_id y rechace las repeticiones. Es posible que una solicitud cuyo tiempo de espera se agotó se haya guardado en su sistema, por lo que el reintento será un duplicado. Responda al reintento con 409 o con el mismo 2xx que la primera vez.

• No dependa del orden de llegada. Dos actualizaciones de la misma carga pueden llegar desordenadas, sobre todo si una de ellas se reintentó. Ordénelas según la hora del evento de cada endpoint (load_update_utc_timestamp, arrived_date_time_utc, status_date_time_utc, entered_at_utc).

No nos vuelva a enviar nuestras actualizaciones

Si su TMS también envía actualizaciones de carga a TrackFlo mediante Integration API, omita los registros creados por estos endpoints. De lo contrario, cada actualización aparecerá dos veces en la cronología de la carga. Los comentarios que escribimos terminan en (via TrackFlo), así que también puede filtrarlos con ese texto.

Pruebas y puesta en marcha

1. Cree los endpoints en el entorno de pruebas y envíenos sus URL y una clave de ese entorno. Nosotros le enviaremos el secreto de firma.

2. Enviaremos cada tipo de evento a una carga de prueba en su TMS de pruebas y comprobaremos con usted que se haya registrado donde su equipo espera.

3. Envíenos las URL y la clave de producción.

4. Las próximas actualizaciones que su equipo registre en TrackFlo se enviarán a su TMS.