TrackFlo
Comience aquí

Primeros pasos con la Integration API

Actualizado hoy

Necesita una API key, el tenant slug y una asignación de estados, todos proporcionados por TrackFlo durante la incorporación. Después, envíe un transportista, una carga, sus tramos, sus paradas y sus actualizaciones, en ese orden.

Lo que necesita

  1. Una API key y su tenant slug (company_permalink), ambos proporcionados por TrackFlo durante la incorporación. La clave se muestra una sola vez; guárdela en un almacén de secretos.

  2. Una asignación de estados acordada con TrackFlo: qué estados de su TMS significan planificado, en tránsito, entregado, etc. Envíe los estados exactamente con los nombres que utiliza su TMS; TrackFlo los asigna.

  3. La URL base: https://integration-api.trackflo.tech

Los cinco endpoints

Orden

Endpoint

Uno por cada…

1

POST /api/v1/carriers/upsert

transportista

2

POST /api/v1/loads/upsert

pedido / BOL

3

POST /api/v1/loadlegs/upsert

ruta / movimiento de una carga

4

POST /api/v1/stops/upsert

recogida o entrega de un tramo

5

POST /api/v1/loadupdates/upsert

llamada de seguimiento, señal GPS o comentario de estado

Envíelos en ese orden la primera vez para que todas las referencias ya existan. Después, envíe lo que haya cambiado.

Cada objeto se identifica mediante un native_system_*_permalink que usted construye como <your id>-<company_permalink>. Para el tenant acme, el pedido 1083452 se convierte en 1083452-acme. Si vuelve a enviar el mismo permalink, el registro se actualiza. Las actualizaciones de carga son la excepción: solo se añaden y no se pueden modificar; si se repite un permalink, se responde con status: duplicate y se deja sin cambios.

Su primera solicitud

curl -X POST https://integration-api.trackflo.tech/api/v1/loads/upsert \
  -H "X-API-Key: $TRACKFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Trackflo-Ingest-Source: pull" \
  -d '{
    "company_permalink": "acme",
    "native_system_load_permalink": "1083452-acme",
    "native_system_load_id": "1083452",
    "native_system_load_status": "Available",
    "customer_name": "Example Foods",
    "origin_stop_id": "5001",
    "origin_stop_id_permalink": "5001-acme",
    "destination_stop_id": "5002",
    "destination_stop_id_permalink": "5002-acme"
  }'

Una llamada correcta devuelve 200:

{ "status": "processed", "message": "Load processed", "permalink": "1083452-acme" }

Dos datos que conviene enviar siempre

  • Trackflo-Ingest-Source encabezado: pull para el sondeo programado, webhook para los envíos basados en eventos. TrackFlo supervisa el estado de cada ruta por separado, por lo que detecta un sondeador detenido incluso mientras los webhooks siguen fluyendo.

  • sync_run_time parámetro de consulta (cargas, tramos, paradas): la hora UTC en formato ISO-8601 en la que comenzó la ejecución de su sincronización. Si el registro cambió en TrackFlo después de ese momento (por una edición de un usuario o un webhook más reciente), la actualización responde status: skipped en lugar de sobrescribir los datos más recientes. Envíelo en cada actualización por lotes.

Lectura de la referencia

Cada campo de la referencia de la API comienza su descripción con su nivel de importancia (x-trackflo-importance en la especificación):

  • obligatorio: la API rechaza la solicitud si falta.

  • recomendado: una función de TrackFlo depende de él (la descripción indica cuál).

  • opcional: se almacena y se muestra; nada depende de él.

Las descripciones de los campos se están completando; si falta alguna, el nombre del campo sigue el modelo de datos de TrackFlo en Modelo de datos.

¿Te fue útil?
¿Te fue útil?