Manual de integración
Fwd Logística con
Introducción
Este documento es un manual práctico en donde se describe paso a paso el proceso a realizar para llevar a cabo 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. Esta integración de rastreo satelital proporciona ciertos beneficios a nuestros proveedores, como la capacidad de cubrir rutas de clientes más selectos y obtener notificaciones de alerta en la aplicación móvil sobre las unidades que Fwd Logística tiene en rastreo activo, las notificaciones tienen el objetivo de brindar información respecto a la ruta en curso de cada unidad como son entradas y salidas del origen, destino y puntos intermedios existentes en la ruta.
Objetivo
Informar y 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 mejorar 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.
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.
1. Fwd Logística publica múltiples rutas disponibles por cubrir a través de la app de proveedores.
2. El proveedor hace match con alguna ruta que pueda cubrir en la fecha solicitada.
3. Fwd Logística valida el match del proveedor.
4. Si el match es aceptado se genera un nuevo número de servicio (ej. 0001MX) como identificador del servicio proporcionado por Fwd Logística.
5. Fwd Logística envía un email al proveedor con toda la información necesaria de la ruta por cubrir, a continuación, un ejemplo de los datos que se envían:
• Lugar de origen
• Lugar de destino
• Fecha para recoger la carga
• Número de servicio
• Tipo de vehículo requerido
• Etc.
6. El proveedor asigna un vehículo que cumple con los requerimientos solicitados y comparte su número de placas con Fwd Logística.
7. Fwd Logística registra el número de placas en el sistema e inicia el rastreo satelital.
8. Fwd Logística detiene automáticamente el rastreo satelital cuando el vehículo llega a su destino.
Requerimientos funcionales
Para la integración se solicitan dos requerimientos funcionales los cuales ayudan a tener un buen control sobre el rastreo satelital.
Requerimiento 1: Servicio web para consumo de Fwd Logística en donde se realicen las solicitudes para iniciar o detener el rastreo satelital de las unidades acordadas con el proveedor.
Requerimiento 2: Reportar por cada 5 minutos los eventos de rastreo satelital de las unidades solicitadas por Fwd Logística.
Implementación de requerimiento 1
Vincular vehículo y número de servicio Fwd Logística
Se requiere un servicio web capaz de recibir datos de un formulario que se envía por medio de un AJAX tipo POST, el formulario contiene por lo menos los
parámetros strNumeroServicio y strNumeroPlaca como se muestra a continuación.
El formulario es enviado desde un Ajax y se espera una respuesta con status code 200 en caso de guardar correctamente la solicitud y un status code diferente de 200 para errores y validaciones.
<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="enviarServicioUnidad()">Enviar</button> </form>
<div id="contenedor-log"></div>
function enviarServicioUnidad () {
$.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>`); }
}); }
Para vincular un vehículo con un número de servicio, Fwd Logística enviará por medio del Ajax el número de placas del vehículo y el número de servicio correspondiente, solo se deben de reportar las ubicaciones de los vehículos que tienen un número de servicio asignado.
Para desvincular un vehículo del número de servicio, Fwd Logística enviará una nueva petición con el número de servicio en cero, cuando un vehículo no tiene número de servicio asignado no se debe de reportar su ubicación ante Fwd Logística.
Para la seguridad de la petición post es posible agregar parámetros de autenticación en el header o body del request, estos datos deben ser acordados entre el equipo de desarrollo del proveedor y el equipo de desarrollo de Fwd Logística.
Implementación de requerimiento 2
Reportar ubicaciones de vehículos a Fwd Logística
Requisitos para enviar eventos de rastreo a la API de Fwd Logística
Para consumir los servicios de la API es necesario contar con un usuario activo y su respectiva contraseña, estos datos de autenticación son proporcionados por el personal administrativo 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 URL de la API se encuentran al final del documento.
Procedimiento de integración
Paso 1: Obtener token de autenticación
El 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 error.
Descripción de atributos
Atributo Tipo Descripción
strUsuario String email de usuario proporcionado para consumo
de la API
strPassword String Contraseña enviada por email para consumo
Para obtener un token de autenticación es necesario hacer una solicitud tipo POST y enviando los parámetros en formato JSON como se presenta en el siguiente ejemplo de solicitud de token realizada desde postman:
Paso 2. Enviar evento
El segundo y último paso para la integración es enviar la información de ubicaciones a Fwd logística. La información de las ubicaciones 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 atributos.
Descripción de atributos
Atributo Tipo Descripción
strCodigo String Código del evento Obligatorio
datFechaHora String Fecha en formato UTC Obligatorio
dblLatitud Double Latitud de ubicación Obligatorio
dblLongitud Double Longitud de ubicación Obligatorio
strNumeroPlaca String Número de placas del vehículo Obligatorio
strNumeroServicio String Identificador del rastreo proporcionado por
Fwd, ej: 0001MX
Obligatorio
strNumeroSerie String Número de serie del dispositivo de rastreo
satelital
Opcional
dblVelocidad Double Velocidad actual del vehículo Opcional
dblAltitud Double Altitud de ubicación Opcional
dblKilometraje Double Total de kilómetros recorridos por el
vehículo
Opcional
intNivelBateria Integer Porcentaje de batería de 0 a 100 Opcional
strOrientacion String Orientación cardinal Opcional
strDireccion String Dirección conocida de la ubicación actual
del vehículo
Opcional
bitEncendido Integer Representación de estado actual del
vehículo 0 para apagado y 1 para encendido
Opcional
Los parámetros deben estar encapsulados en un objeto el cual contiene un token y un arreglo de eventos por reportar y luego ser enviados a la API por medio del método POST.
A continuación, se presenta un ejemplo de consumo de la API para enviar y guardar los eventos.
El servicio nos responde con un status code 200 si los datos han sido guardados correctamente y en caso contrario nos devuelve un status code 500, a continuación, un ejemplo de respuesta.
Rutas de la API
La API recibe peticiones POST con un Type:application/json o Content-Type:application/xml
A continuación, se comparten links con colecciones postman, cada colección contiene las rutas 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
