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 del envío a realizar
- Actualización del 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:
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 |
|---|---|
| delivery | scheduled |
En este escenario, la ruta debe ser generada por el operador logístico que se está integrando.
2. Obtener datos del shipping
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 del shipping, pueden utilizarse la siguiente API:
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 |
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 utilizando la siguiente API:
| Status a notificar | Descripcion |
|---|---|
| started | Inicio el recorrido al punto de entrega |
| arrived | Es cuando se llego al punto de entrega |
| delivered | Se entrego en pedido |
| notDelivered | No se pudo entregar el pedido |
| partiallyDelivered | Se entrego parcialmente el pedido |
| cancelled | Se cancelo en envío |
| returnedToSeller | Es cuando se deberá devolver el pedido a la tienda |
Updated 5 days ago