manual de integración
TRANSCRIPT
fwd-logistica
Mex. T. +52 (81) 1968 5060 USA T. +1 (956) 704 9040
www.fwdlogistica.com FwdLogistica fwdlogistica
Manual de IntegraciónFwd Logística con Prestadores AVL/GPS
fwd-logistica
Mex. T. +52 (81) 1968 5060 USA T. +1 (956) 704 9040
www.fwdlogistica.com FwdLogistica fwdlogistica
Introducción
Este documento es un manual práctico en donde se describe paso a paso el proceso de cómo realizar la integración del rastreo satelital con Fwd Logística, esta integración se realiza por medio de servicios web proporcionados por Fwd Logística.
En Fwd Logística trabajamos todos los días para brindar el mejor servicio a nuestros clientes y mejorar la relación con nuestros proveedores. Realizar esta integración de rastreo satelital proporciona beneficios a nuestros proveedores, como la capacidad de cubrir rutas de clientes selectos y obtener notificaciones en tiempo real del seguimiento de las unidades que se encuentran en ruta, las notificaciones tienen el objetivo principal de brindar información relevante respecto al seguimiento satelital de la unidad, las notificaciones enviadas propor-cionan información sobre inicio/finalización de rastreos, entradas/salidas de ubicaciones importantes como son origen, destino y otros puntos intermedios de la ruta.
fwd-logistica
Mex. T. +52 (81) 1968 5060 USA T. +1 (956) 704 9040
www.fwdlogistica.com FwdLogistica fwdlogistica
Objetivo
Orientar al equipo de desarrollo de Prestadores AVL/GPS u otros equipos de desarrollo encargados de la integración de rastreo satelital sobre el proceso correcto de integración con los servicios web de Fwd Logística.
Tecnología de Integración
Fwd Logística ofrece una infraestructura eficiente, segura y fácil de implementar, para mejo-rar la experiencia de la integración con Prestadores AVL/GPS u otros equipos de desarrollo encargados de la integración GPS, dicha infraestructura utiliza tecnología de tipo API REST y es capaz de recibir información en formato JSON y XML para el contenido de la petición.
fwd-logistica
Mex. T. +52 (81) 1968 5060 USA T. +1 (956) 704 9040
www.fwdlogistica.com FwdLogistica fwdlogistica
Integración de ubicación satelital
Antes de iniciar el desarrollo de esta integración es necesario que el equipo de desarrollo encargado de la misma tenga el contexto adecuado de cómo y cuándo se deben de reportar eventos de rastreo satelital a Fwd Logística.
Proceso de compra venta de fletes.1. Nuestros proveedores reportan sus unidades disponibles por medio de nuestra plataforma
web de proveedores.2. Fwd Logística se encarga de buscar cargas para las unidades disponibles de nuestros
proveedores.3. Cuando se encuentran cargas ideales para las unidades disponibles de nuestros proveedo-
res, entonces nuestro equipo de se comunica con el proveedor para acordar y establecer los detalles de la compra venta del servicio de flete, los detalles son los siguientes:
• Número de servicio (folio de embarque)• Origen (lugar de recolección de carga)• Fecha y hora de recolección de carga• Destino (lugar de descarga)• Fecha y hora de descarga• Información sobre el vehículo que realizará el servicio de flete (número de placas del
tracto y del remolque)• Información sobre el chofer (nombre completo y número celular de contacto)
4. Se realiza el servicio de flete (Se requiere el rastreo de la unidad durante este paso)5. Cuando el servicio de flete se ha completado comienza el proceso administrativo para rea-
lizar los pagos correspondientes.
fwd-logistica
Mex. T. +52 (81) 1968 5060 USA T. +1 (956) 704 9040
www.fwdlogistica.com FwdLogistica fwdlogistica
Requerimientos funcionales de la integración
Se requiere un proceso automático que sea capaz de reportar eventos de posicionamiento sa-telital directamente al servicio web de Fwd Logística. La forma óptima de realizar este proceso se desglosa en dos requerimientos.
Requerimiento 1: Liberar un nuevo servicio web para uso exclusivo de Fwd Logística, en este servicio web se pretende iniciar y detener el rastreo de las unidades del proveedor. Se inicia/detiene el rastreo de una sola unidad por solicitud.
Requerimiento 2: Reportar eventos de posicionamiento satelital con una frecuencia mínima de 5 minutos. Solo reportar a las unidades solicitadas por Fwd Logística.
Con el conjunto de los 2 requerimientos se pretende que Fwd Logística inicie automática-mente el rastreo satelital de la unidad en ruta 15 minutos antes de su hora acordada de reco-lección de carga, posteriormente obtener el posicionamiento satelital de dicha unidad durante todo su trayecto del origen al destino y finalmente detener el rastreo de manera automática cuando la unidad llegue a su destino.
Implementación de requerimiento 1Iniciar/detener rastreos
Se requiere liberar un servicio web para uso exclusivo de Fwd Logística, este servicio debe de tener la funcionalidad de iniciar y detener el rastreo satelital de las unidades, o si lo prefiere es posible liberar 2 servicios donde el primer servicio sea específicamente para iniciar rastreos y el segundo servicio sea para detener el rastreo de las unidades.
El servicio solicitado debe de recibir como mínimo 2 parámetros que se describen a continuación:
• Número de servicio (folio de embarque, es una cadena de caracteres alfanuméricos)• Número de placas de la unidad por rastrear
Los datos anteriormente mencionados serán enviados y recibidos por medio de una peti-ción tipo POST.
fwd-logistica
Mex. T. +52 (81) 1968 5060 USA T. +1 (956) 704 9040
www.fwdlogistica.com FwdLogistica fwdlogistica
Para iniciar el rastreo satelital se enviará el número de servicio ej. 0001MX y el número de placas del vehículo ej. TESTGPS.
Para detener el rastreo satelital se enviará el número de placas del vehículo ej. TESTGPS y el número de servicio con un valor 0 (cero)
<form id=“formulario-servicio-unidad”><input type=“text” name=“strNumeroServicio” placeholder=“Número de servicio”><input type=“text” name=“strNumeroPlaca” placeholder=“Número de placas”> <button type=“button” onclick=“iniciarDetenerRastreos()”>Enviar</button></form>
<div id=“contenedor-log”></div>
function iniciarDetenerRastreos () { $.ajax({ type: "POST", url: "dominio.com/ruta", data: $("#formulario-servicio-unidad").serialize(), async: true, beforeSend: function () { $("#contenedor-log").html("<div>Enviando solicitud...<div>"); }, success: function (response, textStatus, xhr) { console.log(response, textStatus, xhr); $("#contenedor-log") .append(`<div>[Success ${xhr.status}] ${xhr.responseText}<div>`); }, error: function (xhr, textStatus) { console.log(textStatus, xhr); $("#contenedor-log") .append(`<div>[Error ${xhr.status}] ${xhr.responseText}<div>`); } }); }
Ejemplo de petición para iniciar/detener el rastreo satelital
fwd-logistica
Mex. T. +52 (81) 1968 5060 USA T. +1 (956) 704 9040
www.fwdlogistica.com FwdLogistica fwdlogistica
Implementación de requerimiento 2Reportar eventos de posicionamiento satelital a Fwd Logística
Se requiere liberar un proceso automático que envíe la última ubicación satelital de las unida-des solicitadas por Fwd Logística, este proceso debe ejecutarse con una frecuencia mínima de 5 minutos.
Requisitos para enviar eventos de rastreo a la API de Fwd Logística
Este proceso consta de 2 pasos:
• Obtener token de autenticación (token válido por 24 horas).• Enviar el posicionamiento satelital de las unidades solicitadas por Fwd Logística.
Para consumir los servicios de la API es necesario contar con un usuario activo y su res-pectiva contraseña, estos datos de autenticación son proporcionados por el personal admi-nistrativo de Fwd Logística. Si aún no cuentas con un usuario y contraseña, puedes utilizar la siguiente clave de autenticación que es únicamente para pruebas y por ende no guardará información sobre los eventos enviados con dichas claves.
• Usuario: prueba • Contraseña: password
Las direcciones URL de la API se encuentran al final del documento.
fwd-logistica
Mex. T. +52 (81) 1968 5060 USA T. +1 (956) 704 9040
www.fwdlogistica.com FwdLogistica fwdlogistica
Procedimiento de integración
Paso 1: Obtener token de autenticaciónEl primer paso es obtener un token de autenticación que servirá para enviar los eventos a Fwd Logística. El token es una cadena alfanumérica que tiene una vigencia de 24 horas, una vez se haya terminado la vigencia del token es recomendable solicitar uno nuevo, en caso de intentar enviar eventos con un token vencido o no válido la API responderá con un status de error.
Descripción de parámetros de autenticación
Para obtener un token de autenticación es necesario hacer una solicitud tipo POST al servicio https://sru029yrw1.execute-api.us-east-2.amazonaws.com/produccion/proveedores/token y enviar los parámetros strUsuario y strPassword en formato JSON. La API nos res-ponderá con un nuevo token y su fecha límite de vigencia.
Parámetro Tipo Descripción
strUsuario String email de usuario proporcionado para consumo de la APIstrPassword String Contraseña enviada por email para consumo de la API
Imagen 1. Ejemplo de solicitud de token desde postman.
fwd-logistica
Mex. T. +52 (81) 1968 5060 USA T. +1 (956) 704 9040
www.fwdlogistica.com FwdLogistica fwdlogistica
Los parámetros deben estar encapsulados en un objeto el cual contiene el token de auten-ticación y un arreglo de eventos por reportar, se debe de enviar este objeto en formato JSON mediante una solicitud tipo POST al servicio https://sru029yrw1.execute-api.us-east-2.amazo-naws.com/produccion/proveedores/tracking/evento, el servicio nos responderá con un status 200 para confirmar que la solicitud ha sido procesada correctamente como se visualiza en la imagen 2.
Paso 2. Enviar eventos de posicionamiento satelitalEl segundo y último paso para la integración es enviar la información de posicionamiento sa-telital a Fwd Logística. La información de posicionamiento debe estar codificada en formato JSON y contener como mínimo los parámetros obligatorios que se describen en la siguiente tabla de descripción de parámetros.
Parámetro Tipo Descripción ObligatoriostrCodigo String Código del evento SidatFechaHora String Fecha en formato UTC Si {año}-{mes}-{día}T{hora}:{min}:{seg}.{ms} Ej. 2020-08-27T10:32:33.000dblLatitud Double Latitud de ubicación SidblLongitud Double Longitud de ubicación SistrNumeroPlaca String Número de placas del vehículo SistrNumeroServicio String Folio del embarque ej. 0001MX SistrNumeroSerie String Número de serie del dispositivo de rastreo No satelitaldblVelocidad Double Velocidad actual del vehículo NodblAltitud Double Altitud de ubicación NodblKilometraje Double Total de kilómetros recorridos por el vehículo NointNivelBateria Integer Nivel de batería de 0 a 100 NostrOrientacion String Orientación cardinal. Ej. Norte, Sur, etc... NostrDireccion String Dirección conocida de la ubicación No actual del vehículobitEncendido Integer Representación de estado actual del vehículo No 0 para apagado y 1 para encendido
Descripción de parámetros
fwd-logistica
Mex. T. +52 (81) 1968 5060 USA T. +1 (956) 704 9040
www.fwdlogistica.com FwdLogistica fwdlogistica
Para realizar pruebas con el usuario genérico se recomienda utilizar la siguiente API ht-tps://sru029yrw1.execute-api.us-east-2.amazonaws.com/produccion/proveedores/tracking/evento/prueba
Imagen 2. Ejemplo de envío de posicionamiento satelital.
fwd-logistica
Mex. T. +52 (81) 1968 5060 USA T. +1 (956) 704 9040
www.fwdlogistica.com FwdLogistica fwdlogistica
Colecciones postman
La API recibe peticiones POST con un Content-Type: application/json o application/xml A continuación, se comparten links con colecciones postman, cada colección contiene las ru-tas y ejemplos para el consumo de la API, por lo cual se recomienda instalar postman y hacer pruebas iniciales desde esta aplicación.
Postman JSON: https://www.getpostman.com/collections/5126312cad535f11b4c0
Postman XML: https://www.getpostman.com/collections/159d1c6175ecd452b0eb
Si tienes dudas o comentarios respecto a la integración comunícate con nosotros a través del email [email protected] en donde te atenderemos con gusto.