Cómo integrar un operador logístico a Janis
JANIS opera actualmente con operadores logísticos ya integrados de forma nativa, pero también es posible integrar un operador logístico hacia JANIS desde un sistema externo.
A partir de este tipo de integraciones, un operador puede ser notificado de los envíos pendientes a realizar, para luego informar su tracking ID, etiquetas y actualización de estados hacia JANIS.
Esta documentación se divide en 5 puntos:
- Configuración de webhooks
- Consulta de envíos pendientes a realizar
- Notificación de Id de tracking
- Notificación de etiqueta
- Actualización de estados
1. Configuración de Webhooks
El primer paso es la configuración de Webhooks. Los webhooks a configurar pueden ser 2:
1.A. Webhook de Shipping
Se debe suscribir la URL donde el webhook informará la creación de un nuevo shipping. Para esto es requerido configurar la entidad y el evento.
| Entity | Shipping |
|---|---|
| Event | created |
En este escenario, la ruta debe ser generada por el operador logístico que se está integrando.
1.B. Webhook de Rutas
En caso que además del Shipping, la ruta también deba ser generada por JANIS, se deberá configurar el webhook de ruta.
Para eso,también es requerido configurar la entidad y el evento correspondiente.
| Entity | Route |
|---|---|
| Events | created |
Una vez finalizada la configuración presionar "Save"
2. Obtener datos de la ruta
Con el paso 1 finalizado, desde el sistema externo ya se estarán recibiendo las nuevas rutas o shippings según correspondan.
Una vez recibidas las actualizaciones vía webhook, va a ser requerido consultar los datos de la ruta o shipping. Además, se puede obtener también información del pedido al que están asociados.
Para obtener todos los datos de la ruta o shipping notificados, pueden utilizarse las siguientes APIs:
Además, en caso de ser necesario, se puede hacer un Get al pedido para tener una información más detallada por medio de:
3. Actualizar el ID de Tracking del operador logístico
Una vez obtenidos los datos del despacho, debe insertarse en JANIS el identificador de tracking generado por el operador logístico para tener trazabilidad.
En la misma request se debe notificar un cambio de estado del shipping confirmando que el pedido ya fue ingreasdo en el operador logístico. Dicho estado es scheduled y junto al tracking ID se notifican en la API de actualización de shipping.
Se deben notificar los siguientes campos:
| id | Tracking id provisto por el operador logístico |
| link | Link para acceder al tracking del despacho |
| status | "scheduled" |
4. Actualización de etiqueta
En el caso que se requiera ingresar una etiqueta a un shipping, se debe invocar la API de creación de etiqueta.
Para la notificación de la etiqueta es necesario también informar el PackageID. Para poder consultar el PackageId debe hacerse un Get al listado de package filtrando por ID de Shipping
5. Actualización de estados
En esta etapa del proceso, el Shipping ya se encuentra en estado "Scheduled", teniendo así su respectivo ID de tracking y etiquetas.
El próximo paso es avanzar con el flujo de entrega. De esta forma, será requerido primero iniciar la ruta para luego avanzar el estado de los Shipping que la integren.
A continuación, se detalla la matriz de cambio de estados:
| Entidad | Status a notificar | API |
|---|---|---|
| Ruta | "started" | Notificar cuando inicia la ruta https://docs.janis.in/v2/service/delivery#operation/updateRouteTracking |
| Shipping | "started" | Notificar cuando inicia la ruta https://docs.janis.in/v2/service/delivery#operation/udpateShippingTracking |
| Shipping | "arrived" | Notificar cuando el Driver arribó a destino https://docs.janis.in/v2/service/delivery#operation/udpateShippingTracking |
| Shipping | "delivered" | Cuando se entrega el pedido https://docs.janis.in/v2/service/delivery#operation/udpateShippingTracking |
| Shipping | "notDelivered" | Cuando NO se entrega el pedido https://docs.janis.in/v2/service/delivery#operation/udpateShippingTracking |
| Ruta | "finished" | Cuando se finalizaron todos los Shippings que contenía la ruta https://docs.janis.in/v2/service/delivery#operation/updateRouteTracking |
En una cancelación se debe cancelar el shipping y la ruta (en ese orden):
| Entidad | Status a notificar | API |
|---|---|---|
| Shipping | "cancelled" | https://docs.janis.in/v2/service/delivery#operation/udpateShippingTracking |
| Ruta | "cancelled" | https://docs.janis.in/v2/service/delivery#operation/updateRouteTracking |
Updated about 1 year ago