Guía de integración de Turvo

TrackFlo lee su espacio de trabajo de Turvo mediante la Turvo Public API y recibe cambios casi en tiempo real a través de Turvo webhooks. Todo lo que su equipo hace en una carga en TrackFlo se escribe nuevamente en el mismo envío en Turvo, de modo que ambos sistemas muestran una única historia.

Lo que lee TrackFlo

• Envíos con estados activos, desde Covered hasta Route complete, actualizados según un calendario como respaldo de los webhooks.

• Detalles completos del envío: órdenes del cliente y del transportista, la ruta con las citas, las horas de llegada y salida, el equipo, las etiquetas y los conductores asignados.

• Freight de los artículos de la orden del cliente: el nombre, la cantidad de piezas y el peso de cada artículo, sumados en los totales de la orden. Solo se cuentan como piezas las cantidades registradas en una unidad Piece. Un artículo contado en pallets o en otra unidad de manipulación aporta su peso, pero no una cantidad de piezas.

• Documentos de comprobante de entrega que sus usuarios adjuntan en Turvo, cuando la suscripción de documentos está habilitada (más abajo).

Lo que escribe TrackFlo

• Cambios de estado con una marca de tiempo y una ubicación, vinculados a la parada a la que corresponden. Las notas llevan el sufijo (via TrackFlo) para que ambos sistemas puedan distinguirlas de las notas propias de Turvo.

• Llegadas y salidas de las paradas en la ruta del envío.

• Datos del conductor y de seguimiento: nombre y teléfono del conductor, camión y remolque, y una invitación a la aplicación Turvo Driver.

• Comprobante de entrega cargado como un documento Proof of delivery.

Lo que configura su administrador de Turvo

1. Un usuario de API con acceso a Public API

Cree un usuario de Turvo para TrackFlo y comparta con nosotros su nombre de usuario, contraseña y clave de API. El acceso a Public API es un permiso concedido por espacio de trabajo, independiente del inicio de sesión. Si falta, el usuario puede iniciar sesión, pero todas las lecturas fallan con el error 109, "Client is unauthorized to access Public API". Solicite a Turvo que habilite Public API para el usuario en cada espacio de trabajo que quiera conectar. Sandbox y producción son espacios de trabajo independientes, con permisos y credenciales separados.

2. Una suscripción a un webhook

En su espacio de trabajo de Turvo, añada una suscripción a un webhook que apunte al endpoint de TrackFlo de su tenant:

https://<tenant>-integration-webhooks.trackflo.tech/webhook-ingest

TrackFlo le proporciona el nombre de host exacto y un bearer token para la suscripción. Turvo debe enviarlo en el encabezado Authorization: Bearer <token>. Las solicitudes con cualquier otro valor se rechazan con 403.

Suscríbase a estos eventos:

La suscripción de Documents es opcional. Sin ella, TrackFlo sigue cargando los POD en Turvo, pero los documentos que su equipo adjunte en Turvo no aparecerán en TrackFlo. Se configura por espacio de trabajo, por lo que una suscripción creada en el sandbox no se transfiere a producción.

Aspectos que debe conocer

• Turvo nos confirma nuestras propias escrituras. Un estado enviado desde TrackFlo vuelve segundos después como un webhook. TrackFlo reconoce sus propias notas por el sufijo (via TrackFlo) y no las duplica.

• Las listas de envíos filtradas solo incluyen envíos recientes. El endpoint de lista de Turvo, cuando se filtra por estado, devuelve los envíos creados aproximadamente en los últimos cuatro o cinco meses. La carga activa siempre se encuentra dentro de ese periodo. Los envíos de prueba muy antiguos del sandbox no, por lo que un sandbox lleno de datos obsoletos puede parecer vacío para la sincronización programada, aunque los envíos individuales se sigan leyendo correctamente por su id.

• El estado es una secuencia. TrackFlo envía Covered, Dispatched, At pickup, Picked up, En route, At delivery, Delivered y Route complete. Las etapas de facturación son responsabilidad de su equipo de contabilidad y nunca se establecen desde TrackFlo.

• Los cambios de transportista se gestionan. Cuando se reemplaza un transportista en un envío, Turvo conserva la orden del transportista anterior marcada como eliminada. TrackFlo sigue la orden activa.

• Las etiquetas pueden mostrarse en TrackFlo como grupos de visibilidad. Infórmenos cómo utiliza su equipo las etiquetas para que las asignemos de la manera que espera.