Crear endpoints de escritura en TrackFlo

Cree cinco endpoints HTTPS en su TMS y escribiremos en TrackFlo, en la carga correspondiente, el trabajo de seguimiento de su equipo: llamadas de seguimiento, llegadas y salidas de paradas, cambios de estado, datos del conductor y del equipo, y documentos. Este artículo explica qué comparten los cinco: autenticación, formato de solicitud, cómo responder, reintentos y pruebas. El artículo de cada endpoint enumera todos los campos que incluye.

Use esto si su TMS no es uno de los que conectamos de forma predeterminada. Para McLeod, Turvo, Mastery, Tai y Revenova, escribimos mediante la API propia del TMS y usted no tiene que crear nada; consulte Cómo conecta TrackFlo con su TMS.

Los cinco endpoints

Las rutas son sugerencias; cualquier URL HTTPS funciona. Envíenos la URL de cada endpoint que cree. Puede crearlos en cualquier orden; las actualizaciones de un endpoint que aún no haya creado solo permanecerán 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 API que emita para TrackFlo, una para el entorno de pruebas y otra para producción. Envíela mediante un administrador de contraseñas o un enlace de un solo uso, en lugar de por correo electrónico. 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, de modo que puede buscar los registros con sus propias claves.

• Un entorno de pruebas, si dispone de uno. Probamos allí todos los endpoints antes de que su equipo dependa de ellos.

Autenticación

Cada solicitud incluye la clave API que emitió para TrackFlo:

Authorization: Bearer <the key you issued to TrackFlo>

• Rechace las solicitudes que no incluyan una clave válida con 401.

• Permita el acceso a través de su firewall únicamente desde nuestra dirección IP.

HTTPS, la clave y la lista de direcciones IP permitidas son todas las comprobaciones necesarias. No firmamos las solicitudes, por lo que no hay ningún encabezado de firma que verificar.

Cuando se rote una clave, acordaremos con usted una fecha para el cambio. Acepte tanto la clave anterior como la nueva hasta que confirmemos el cambio. Si nuestra dirección IP cambia, se lo comunicaremos antes de cambiarla.

Formato de la solicitud

Todas las solicitudes son POST con un cuerpo JSON en UTF-8 y estos encabezados:

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

El cuerpo incluye los campos compartidos que aparecen 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

Las horas se envían en pares, como en Integration API, con ambas versiones siempre que conozcamos 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 del reloj en la parada o ubicación, sin desplazamiento horario; 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 recibe respuesta, lo consideramos un error y reintentamos.

Envíe los errores con este formato e incluya un message de menos de 100 caracteres para que se muestre completo:

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

Reintentos y duplicados

Reintentamos una solicitud fallida hasta 3 veces, esperando más tiempo en cada ocasión, durante unos 10 minutos. Cada reintento lleva el mismo event_id.

Si falla el último intento, la actualización tampoco se guarda en TrackFlo, por lo que TrackFlo nunca muestra un cambio que no esté registrado en su TMS. La persona que hizo la actualización recibe un correo electrónico con el nombre de la carga y su message; podrá volver a ingresarla cuando se resuelva el problema. Se avisará a nuestro equipo de todos los errores. Los documentos son la excepción: un POD permanece en la carga en TrackFlo.

• Guarde event_id y rechace las repeticiones. Es posible que una solicitud cuyo tiempo de espera se agotó se haya guardado de todos modos 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 dé por sentado que las solicitudes llegarán en orden. Dos actualizaciones de una misma carga pueden llegar desordenadas, sobre todo si se reintentó una de ellas. Ordénelas por la hora del evento de cada endpoint (load_update_utc_timestamp, arrived_date_time_utc, status_date_time_utc, entered_at_utc).

No nos reenvíe nuestras propias actualizaciones

Si su TMS también envía actualizaciones de carga a TrackFlo a través de 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 por ese texto.

Una acción puede llegar a más de un endpoint. Por ejemplo, una llegada al punto de recogida envía un evento de parada, un cambio de estado y una actualización de carga que la registra. El artículo de cada endpoint indica qué incluye.

Pruebas y puesta en marcha

1. Cree los endpoints en el entorno de pruebas, permita nuestra dirección IP y envíenos sus URL y una clave para el entorno de pruebas.

2. Enviaremos cada tipo de evento a una carga de prueba en su TMS de pruebas y confirmaremos con usted que se registró donde su equipo espera.

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

4. Las próximas actualizaciones que su equipo haga en TrackFlo se escribirán en su TMS.