Integrar Handy con tu sistema de ruteo

¿Sabías que Handy cuenta con la funcionalidad de ruteo optimizado integrado? conoce más haciendo click aquí. Si deseas integrar con tu sistema de ruteo actual, continúa leyendo este artículo

Puedes utilizar la API de Handy, para llevar la preventa capturada en la app móvil hacia tu sistema de ruteo, optimizar las rutas, y luego crear las rutas en Handy para ejecutar el reparto.

Esto asume que en tu sistema de ruteo manejas el catálogo de capacidad vehicular y restricciones de clientes.

Primero crea una cuenta gratuita en Handy aquí, y sigue la guía para obtener un token de API de Handy y probarlo.

La recomendación es que una vez al día, al final del día, leas la preventa de Handy desde la API, con este endpoint. Asegúrate de seguir las buenas prácticas de la guía de inicio de la API (manejar paginación, errores, autenticación, etc.)

Tenemos código de ejemplo para leer la preventa en C#, JavaScript y Java, en esta sección.

La recomendación es que al leer la preventa con la API, establezcas los parámetros de URL:
- Fechas start y end para sólo leer los pedidos del día en curso
- filterWithDate = "dateCreated" para usar la fecha de llegada al servidor y así asegurar que se toman todos los pedidos creados en ese día.
- salesType = "PRESALE" para sólo leer preventas y no devoluciones puras.

Al leer la preventa, cada una contendrá los siguientes campos de interés (se dejan fuera los campos completos, pues se pueden consultar en la referencia de la API):

{
    "id": 1,
    "latitude": 20.6760381,
    "longitude": -103.3618535,    
    "scheduledDateForDelivery": "2020-05-01T11:30:00Z",
    "items": [
      {
        "id": 1,     
        "quantity": 2,           
        "product": {
          "id": 1,        
          "code": "ACME-01-003",
          "quantity": 400,
          "description": "Do-it yourself tornado kit Acme",            
        },
        "isReturn": false,                  
      }
    ],
    "customer": {
      "id": 1,      
      "code": "C001",
      "description": "Customer number one",
      "zone": {
        "description": "Zone Guadalajara",
        "id": 1,
        "enabled": true
      },      
    }
  }

Los siguientes campos serán necesarios para optimizar las rutas:

ID: es el folio o identificador del pedido
Latitude y longitude: representan las coordenadas del punto de entrega
Items: contiene un registro por cada producto del pedido. Dentro del mismo, se puede tomar el código de producto como referencia y su cantidad. Es importante notar que los items que sean isReturn se deben ignorar pues son cambios físicos (devoluciones al cambio). También hay que considerar que un pedido puede contener más de 1 item por producto porque pueden venir en diferentes precios, por las promociones y descuentos. Para efectos del ruteo, se deben sumar las cantidades de un mismo producto, en un mismo pedido.
Customer: cuenta con un código identificador y con el ID del cliente en Handy. Puedes utilizar el que más te convenga. El código de cliente es editable en Handy.

Una vez que has llevado los datos a tu sistema de ruteo, y corras el proceso, por cada ruta, puedes mandar llamar la API de creación de rutas de Handy:

POST a /api/v2/user/userId/route
{
  "dateForDelivery": "04/03/2021",
  "comments": "Route to sell and delivery new products",
  "initialAmount": 1234.5,
  "salesOrders": [
    {
      "salesOrderId": 123,
      "items": [
        {
          "quantity": 30,
          "salesOrderItemId": 123
        }
      ]
    }
  ]
}

Puedes ver los ejemplos de respuesta en la documentación de la API aquí.

Puntos importantes:
Debes utilizar los ids de salesOrder y salesOrderItemId para realizar la asignación de las rutas
Debes especificar el ID de usuario repartidor al que se le asignará la ruta
La asignación de la fecha de reparto es en formato DD/MM/YYYY. Normalmente se asignan todos para el día siguiente.

Contáctanos si tienes dudas.

¿Sabías que Handy cuenta con la funcionalidad de ruteo optimizado integrado? conoce más haciendo click aquí. Si deseas integrar con tu sistema de ruteo actual, continúa leyendo este artículo

Actualizado el: 08/05/2024