Cree endpoints de escritura de datos para TrackFlo

Cree cinco endpoints HTTPS en su TMS y escribiremos en él la información de seguimiento de su equipo en TrackFlo para la carga correspondiente: llamadas de seguimiento, 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 la solicitud, 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. Para McLeod, Turvo, Mastery, Tai y Revenova, escribimos mediante la propia API del TMS y usted no tiene que desarrollar 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 desarrolle. Puede desarrollarlos en cualquier orden; las actualizaciones de los endpoints que aún no haya desarrollado solo estarán disponibles 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 el firewall.

• Una clave de API que usted emita para TrackFlo. La guardamos 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 empiece a depender de él.

Autenticación

Cada solicitud incluye dos encabezados: su clave, para que sepa que quien realiza la llamada tiene autorización, y nuestra firma, para que sepa que el cuerpo no se modificó después de que lo enviamos.

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

• Authorization: rechace la solicitud con 401 si falta la clave o es incorrecta.

• X-TrackFlo-Signature: t es la hora Unix en que firmamos. v1 es el HMAC-SHA256 hexadecimal de <t>.<raw request body>, calculado con el secreto de firma que le proporcionamos durante la incorporación. Vuelva a calcularlo con 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 en más de 5 minutos de la hora de su reloj.

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 rota una clave o un secreto, acordamos con usted una fecha para el cambio. Acepte tanto la clave anterior como la nueva hasta que confirmemos el cambio. Durante la rotación de un secreto de firma, el encabezado contiene dos valores v1; acepte la solicitud si alguno de ellos coincide.

Formato de la solicitud

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

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

El cuerpo contiene los campos compartidos que aparecen a continuación, además de 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 ambos valores cuando conocemos la zona horaria de la ubicación.

• _utc: 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; por ejemplo, 2026-10-24T10:37:00. La zona horaria se indica en el campo *_iana_timezone del endpoint.

Cómo responder

Responda en un plazo de 30 segundos. Si no recibimos respuesta, lo consideramos un error y volvemos a intentarlo.

Envíe los errores con esta estructura:

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

Reintentos y duplicados

Volvemos a intentar una solicitud fallida hasta 5 veces, esperando más tiempo en cada intento, durante unos 25 minutos en total. Todos los reintentos llevan el mismo event_id. Si el último intento falla, la persona que hizo 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ía un duplicado. Responda a la repetición 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, especialmente si se volvió a intentar una de ellas. 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 propias 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 criterio.

Pruebas y puesta en marcha

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

2. Enviamos cada tipo de evento a una carga de prueba en su TMS de pruebas y verificamos 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 de su equipo en TrackFlo se escribirán en su TMS.