NAV
shell

Introducción

Este documento es la referencia oficial para la API de servicio web de OptimoRoute.

Nuestra API de servicio web se basa en HTTP

Los métodos para recuperar datos de nuestra API de servicio web (WS) requieren un método de solicitud HTTP GET.

Los métodos que envían, cambian o destruyen datos requieren un método de solicitud POST.

Los métodos de la API devolverán un error si no realizas tu solicitud con el método HTTP correcto.

Usamos JSON para el intercambio de datos estructurados

Nuestra API utiliza el formato JSON (JavaScript Object Notation).

Más información sobre JSON y cómo funciona se puede encontrar aquí: http://json.org/ y aquí: http://en.wikipedia.org/wiki/JSON.

Existen muchas librerías disponibles para convertir hacia y desde el formato JSON tanto para lenguajes de programación populares como más esotéricos.

Se requiere SSL

El uso de SSL (https) es necesario para evitar el paso de la clave de autenticación y potencialmente datos confidenciales en texto claro en la web.

Número limitado de solicitudes concurrentes

El número máximo de solicitudes concurrentes a la API de servicio web para una cuenta o para una dirección IP es limitado a 5.

Códigos de error generales

Los siguientes códigos de error son aplicables a todas las operaciones de la API:

Código de Error Descripción
AUTH_KEY_MISSING falta la clave de autenticación
AUTH_KEY_UNKNOWN se suministró una clave de autenticación incorrecta
MALFORMED_REQUEST algo está mal en la entrada
ERR_MISSING_MAND_FIELD falta uno de los campos obligatorios
ERR_INVALID_PARAM_FORMAT uno de los campos especificados no tiene un formato válido
ERR_TOO_MANY_CONNECTIONS hay demasiadas solicitudes concurrentes
ERR_INTERNAL ocurrió un error interno del servidor

También hay códigos de error específicos que se describen en la sección Códigos de Error y Advertencia de cada método.

Códigos de error con operaciones masivas

Para operaciones masivas, hay múltiples modos de falla. Por ejemplo, si se realiza una operación masiva en pedidos:

Permitir campos adicionales en los mensajes de respuesta

Es posible que se agreguen campos adicionales a los mensajes de respuesta JSON en el futuro, por lo que tu código cliente debería ignorar los campos adicionales.

Autenticación

El parámetro de clave de autenticación de la API de servicio web de OptimoRoute es requerido con todas las solicitudes a la API, además de todos los parámetros estándar.

Para habilitar la API y generar la clave de API por favor inicia sesión en la aplicación web de OptimoRoute. En la sección Administración selecciona Configuraciones -> WS API y habilita la API. La clave de API será generada para ti.

La API de servicio web también está disponible durante el periodo de prueba gratuita.

Objetos de Datos

Algunos puntos finales en la API comparten definiciones de objetos que se envían en la solicitud y la respuesta.

Objeto de Pedido

Ejemplo de Objeto de Pedido

{
  "orderNo": "ORD001",
  "id": "6671978a86b19d18c69cc934315cb100",
  "date": "2018-11-12",
  "duration": 60,
  "priority": "M",
  "type": "T",
  "load1": 1,
  "load2": 0,
  "load3": 0,
  "load4": 0,
  "assignedTo": {"externalId": "DRV001", "serial": "001"},
  "location": {
    "locationNo": "LOC001",
    "address": "393 Hanover St, Boston, MA 02113, USA",
    "locationName": "Green Cross Pharmacy North End",
    "latitude": 42.365142,
    "longitude": -71.052882,
    "checkInTime": 0,
    "notes": ""
  },
  "timeWindows": [{
      "twFrom": "11:00",
      "twTo": "17:00"
  }],
  "allowedWeekdays": ["mon", "tue", "wed", "thu", "fri"],
  "allowedDates": {},
  "allowedDateTimes": [{
      "from": "2019-12-10T07:39:00",
      "to": "2019-12-15T19:39:00"
  }],
  "skills": ["SK001"],
  "vehicleFeatures": [],
  "notes": "",
  "email": "john.doe@example.com",
  "phone": "",
  "customField1": "",
  "customField2": "",
  "customField3": "",
  "customField4": "",
  "customField5": "",
  "notificationPreference": "email"
}
Propiedad Tipo Descripción
id cadena El identificador único de solo lectura del pedido, asignado por OptimoRoute. Si esta propiedad se envía en solicitudes, se usará para encontrar el pedido para actualizar, eliminar o recuperar, tomando prioridad sobre orderNo.
orderNo cadena Un identificador de pedido especificado por el usuario, también mostrado en la aplicación web. Si id no se utiliza en las solicitudes de WS API, los pedidos se emparejan con este identificador, y se puede utilizar para actualizar, eliminar o recuperar pedidos.
relatedOrderNo cadena o null orderNo del pedido relacionado. Se usa para enlazar recogidas y entregas en situaciones donde las mercancías se transportan directamente de una ubicación de cliente a otra ubicación de cliente.
Al crear pedidos, la relación solo debe especificarse en el segundo pedido que se crea (el primer pedido ya debe existir en el sistema para que pueda referenciarse).
El valor predeterminado es null, lo que significa que el pedido no está relacionado con ninguna otra recogida/entrega.
relatedId cadena o null id del pedido relacionado. Ver relatedOrderNo arriba para detalles de pedidos relacionados.
date fecha (cadena) Fecha del pedido.
Formato YYYY-MM-DD, por ejemplo 2013-12-20.
location objeto de localización Ubicación de entrega/servicio. Ver Objeto de Localización.
type cadena enum Tipo de pedido: D (entrega), P (recoger) o T (tarea).
duration decimal El tiempo en minutos requerido para descargar las mercancías o realizar una tarea en la ubicación dada. Si no se especifica, los pedidos recién creados usarán el valor predeterminado configurado en OptimoRoute.
timeWindows lista de ventanas de tiempo Lista de ventanas de tiempo cuando el pedido puede ser atendido.
Cada ventana de tiempo es un objeto con campos twFrom y twTo. Ambos tiempos están en formato de reloj de 24 horas (militar), en el rango de 00:00 a 23:59.
twFrom especifica la hora más temprana permitida para comenzar el servicio (si el conductor llega demasiado temprano, se verá obligado a esperar). twTo especifica la fecha límite para terminar el servicio.
Ejemplo:
[{"twFrom": "10:00", "twTo": "14:00"}].
El valor predeterminado es [] significando sin ventanas de tiempo.
allowedWeekdays lista de cadenas Restringe los días de la semana cuando el pedido puede ser programado:
sun, mon, tue, wed, thu, fri, sat.
Por ejemplo, si el pedido puede ser programado el lunes o martes el valor debe ser:
["mon", "tue"].
Por defecto se permiten todos los días de la semana.
allowedDates objeto de rango de fechas Restringe las fechas en las que el pedido puede ser programado.
El rango de fechas se especifica como un objeto con campos from y to, por ejemplo:
{"from": "2018-06-01", "to": "2018-07-01"}
El valor predeterminado es un objeto vacío {} significando sin restricción.
allowedDateTimes lista de ventanas de datetime Lista de ventanas de datetime cuando el pedido puede ser atendido.
Cada objeto puede contener campos from y/o to, que son cadenas de datetime, o null. Las cadenas están en el formato YYYY-MM-DDTHH:MM:SS, por ejemplo 2020-01-30T15:54:02. El campo from define el tiempo más temprano para comenzar el servicio, y to define el tiempo más tardío para comenzar el servicio. Cuando solo se da un extremo de la restricción, el otro se asume como null, significando que no está restringido.
Ejemplo:
[{"from": "2019-12-26T00:00:00", "to": "2019-12-31T23:59:59"}].
El valor predeterminado es [] significando sin restricción.
assignedTo objeto o null Un objeto con propiedades de cadena serial o externalId que identifica de manera única al Conductor al que debe asignarse este Pedido. Ejemplo: {"serial": "102"} o {"externalId": "444"}. Establecer este campo fuerza que este Pedido sea servido por el Conductor especificado. Un valor null significa sin asignación, que es el valor predeterminado.
priority cadena Prioridad del pedido, por defecto M. Los valores pueden ser:
L – Baja
M – Media
H – Alta
C – Crítica
Los pedidos de alta prioridad se programan antes y tienen menos probabilidades de quedar sin programar si no se pueden atender todos los pedidos.
load1 decimal Los requerimientos de carga del pedido, es decir, cuántas unidades de carga (cantidad de cajas, kilogramos, libras, litros, etc.) deben ser entregadas.
El significado de esta entrada depende de la configuración proporcionada de restricciones de carga/capacidad.
El valor predeterminado es 0.
load2 decimal Ver load1.
load2 decimal Ver load1.
load3 decimal Ver load1.
vehicleFeatures lista de cadenas Las características de los vehículos utilizadas para diferenciar algunos Vehículos de otros. Las características requeridas del vehículo se definen como una lista de códigos de características del vehículo. El valor predeterminado es una lista vacía [].
skills lista de cadenas Las habilidades del conductor utilizadas para diferenciar algunos Conductores de otros. Las habilidades requeridas se definen como una lista de códigos de habilidades. El valor predeterminado es una lista vacía [].
notes cadena La nota opcional que acompañará las instrucciones del conductor. Las notas no afectan el proceso de optimización. Un texto de forma libre.
customField1 cadena Valor que se guardará en el campo personalizado #1, por defecto vacío.
customField2 cadena Valor que se guardará en el campo personalizado #2, por defecto vacío.
customField3 cadena Valor que se guardará en el campo personalizado #3, por defecto vacío.
customField4 cadena Valor que se guardará en el campo personalizado #4, por defecto vacío.
customField5 cadena Valor que se guardará en el campo personalizado #5, por defecto vacío.
customFields objeto de campos personalizados Un objeto que contiene campos personalizados. Ver Objeto de Campos Personalizados.
email cadena Correo electrónico del cliente. Si está habilitado, las notificaciones del pedido pueden ser enviadas a ese correo electrónico. Por defecto vacío.
phone cadena Número de teléfono del cliente. Por defecto vacío.
notificationPreference enum de cadena Define el método de entrega para notificaciones de seguimiento de pedidos para este pedido. Las notificaciones solo se enviarán si esta cuenta tiene seguimiento de pedidos configurado.
Valores permitidos:
dont_notify – no enviar notificaciones
email – enviar notificación a la dirección de correo electrónico especificada en el campo de correo electrónico
sms – enviar un mensaje de texto al número especificado en el campo de teléfono
both – enviar notificaciones por correo electrónico y sms
Por defecto es both.
barcode lista de objetos de código de barras
opcional
Lista de códigos de barras adjuntos al pedido.
Cada código de barras es un objeto con un campo barcode. El valor es una cadena arbitraria.
Ejemplo:
[{"barcode": "12345678"}].
Si no hay códigos de barras adjuntos al pedido, el resultado devolverá un arreglo vacío. Solo está presente si la función de Comprobante de Entrega está disponible.

Objeto de Localización

Ejemplo de Objeto de Localización con coordenadas GPS:

{
  "address": "1350 N High St, Columbus, OH 43201, USA",
  "latitude": 39.9892,
  "longitude": -83.0054,
  "locationName": "Colorado pharmacy 033",
  "locationNo": "COL033",
  "valid": true,
  "notes": "GATE CODE 4412",
  "checkInTime": 3
}
Propiedad Tipo / Predeterminado Descripción
locationNo cadena El identificador único para la ubicación dada.
locationName cadena Nombre de la ubicación.
address cadena La dirección completa incluyendo el país, por ejemplo 393 Hanover St, Boston, MA 02113, USA
latitude decimal Latitud de la ubicación.
longitude decimal Longitud de la ubicación.
valid booleano Propiedad de solo lectura, utilizada solo en respuestas. Si se encuentra en una solicitud será ignorada. Devuelve true cuando la ubicación es válida. Devuelve falso cuando la ubicación es inválida. Las ubicaciones inválidas son aquellas que no tienen latitud y longitud conocidas (por ejemplo, fueron creadas especificando una dirección que no pudo ser geocodificada).
Por defecto, al crear pedidos y ubicaciones el sistema no aceptará direcciones erróneas o incompletas y lanzará un error. El uso del indicador storeInvalid (de parámetros adicionales del objeto de localización en la solicitud de creación de pedido) evita lanzar un error y permite almacenar ubicaciones inválidas y pedidos relacionados en OptimoRoute. De esta manera las direcciones problemáticas pueden corregirse en OptimoRoute, sin embargo, los pedidos con ubicaciones inválidas no pueden formar parte de un plan hasta que esas ubicaciones sean corregidas.
Las ubicaciones inválidas tendrán las propiedades latitude y longitude presentes en la respuesta pero sus valores no deben ser considerados.
checkInTime entero Tiempo mínimo de espera en la ubicación (en minutos). Si no se especifica, las ubicaciones recién creadas usarán el valor predeterminado configurado en OptimoRoute (cero por defecto). Al llegar a la ubicación, el conductor deberá pasar al menos checkInTime minutos antes de comenzar el servicio de uno o varios pedidos consecutivos en la misma ubicación.
Ejemplo: si tenemos 3 pedidos en la misma ubicación:
  • A: duración 10min, tiempo de registro 15min
  • B: duración 5min, tiempo de registro 15min
  • C: duración 20min, tiempo de registro 15min
Si un conductor atiende los tres pedidos consecutivamente el conductor llegaría a la ubicación, pasaría 15 minutos en la ubicación (por ejemplo, estacionando y registrándose) y luego comenzaría a atender los pedidos A, B y C. El tiempo total en la ubicación sería de 50min = 15min (duración compartida) + 10min (pedido A) + 5min (pedido B) + 20min (pedido C).
notes cadena Notas opcionales relacionadas con esta ubicación.

Objeto de Conductor Seleccionado

Usa driverExternalId o driverSerial (un campo es suficiente):

Propiedad Tipo / Predeterminado Descripción
driverExternalId
opcional
cadena
-
El identificador externo asignado al conductor en la administración de conductores.
driverSerial
opcional
cadena
-
El número de serie del conductor.

Objeto de Tiempo

Propiedad Tipo Descripción
unixTimestamp
mandatorio
entero Número de segundos transcurridos desde las 00:00 UTC del 1 de enero de 1970.
utcTime
mandatorio
fecha ISO 8601 (cadena) La fecha y hora en UTC
localTime
mandatorio
fecha ISO 8601 (cadena) La hora local

Los campos unixTimestamp, utcTime y localTime se refieren al mismo momento, por lo que puedes usar el que sea más conveniente.

Objeto de Campos Personalizados

El Objeto de Campos Personalizados puede contener cualquier número de propiedades, donde cada nombre de propiedad coincide con la clave de un campo personalizado configurado en OptimoRoute.

Ejemplo de Objeto de Campos Personalizados (fruit_type es de tipo Selección única donde apple es una clave de opción, quantity es de tipo Número con 0 lugares decimales, purity es de tipo Número con 2 lugares decimales e instructions es de tipo Texto):

{
  "fruit_type": "apple",
  "quantity": 100,
  "purity": 99.99,
  "instructions": "Deliver to the customer's door."
}
Propiedad Tipo Descripción
{custom_field_key} cadena o decimal o booleano Si el campo personalizado está configurado con tipo Texto o Número, el valor proporcionado se convertirá al tipo apropiado si es posible.
Si el campo personalizado está configurado con tipo Selección única, el valor debe coincidir exactamente con una de las claves de opción configuradas para ese campo.

NOTA: Contacta con el soporte de OptimoRoute para activar los nuevos campos personalizados. Los campos personalizados heredados (campos personalizados con claves custom_field_1 a través de custom_field_5) no deben incluirse en este objeto. Estos se configuran usando los campos separados en el Objeto de Pedido (customField1 a través de customField5).

Crear Pedido

Crea un nuevo pedido en el sistema o actualiza un pedido existente.

Solicitud HTTP

POST https://api.optimoroute.com/v1/create_order

reqbody.json es un archivo local que contiene los datos JSON a enviar. Asegúrate de reemplazar AUTH_KEY con tu clave API.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/create_order?key=AUTH_KEY'

Parámetros

Ejemplo de cuerpo de solicitud:

{
  "operation": "CREATE",
  "orderNo": "ORD001",
  "type": "D",
  "date": "2014-10-14",
  "location": {
    "address": "393 Hanover St, Boston, MA 02113, USA",
    "locationNo": "LOC001",
    "locationName": "Green Cross Pharmacy North End",
    "acceptPartialMatch": true
  },
  "duration": 20,
  "twFrom": "10:00",
  "twTo": "10:59",
  "load1": 10,
  "load2": 25,
  "vehicleFeatures": ["FR"],
  "skills": ["SK001", "SK002"],
  "notes": "Entregar en la puerta trasera"
}

Además de las propiedades del Objeto del Pedido, están disponibles las siguientes propiedades:

Propiedad Tipo Descripción
operation string enum CREATE – crea un nuevo pedido en el sistema.

UPDATE – actualiza un pedido existente en el sistema. Si el pedido no existe, el sistema devolverá un error.

SYNC – recomendado cuando el objetivo final es asegurar que los pedidos se reflejen en OptimoRoute. Si este es un nuevo pedido, lo crearemos. Si hay un pedido existente en el sistema, será actualizado. SYNC realiza una sincronización limpia de los datos del pedido. Cualquier cosa que tengamos en este pedido será reemplazada por los datos que nos envíes en SYNC.

MERGE – se utiliza para actualizar solo campos específicos y dejar todos los demás campos sin cambios (por ejemplo, si algunos campos fueron editados manualmente en OptimoRoute y no deben actualizarse). Si este es un nuevo pedido, lo crearemos. Si hay un pedido existente en el sistema, será actualizado.

Para operaciones distintas de CREATE, el pedido será buscado por su id único si se usa en la solicitud, o orderNo si no se usa id.
acceptDuplicateOrderNo boolean Si se establece en true, el sistema aceptará pedidos con orderNo que ya existe en el sistema. Cuando es false o no se especifica, el sistema devolverá un error.
twFrom time (string) Obsoleto, por favor usa el campo timeWindows; ignorado si timeWindows está configurado.

La hora más temprana permitida para comenzar el servicio (si el conductor llega demasiado temprano, deberá esperar).
Formato de reloj de 24 horas (militar), por ejemplo: 16:00
Los valores válidos van desde 00:00 hasta 23:59.
twTo time (string) Obsoleto, por favor usa el campo timeWindows; ignorado si timeWindows está configurado.

La fecha límite para terminar el servicio.
Formato de reloj de 24 horas (militar), por ejemplo 17:00
Los valores válidos van desde 00:00 hasta 23:59.

La propiedad operation es obligatoria. Cuando operation se especifica como UPDATE, uno de orderNo o id son obligatorios, de lo contrario, las propiedades obligatorias son date, type, location y uno de orderNo o id.

Objeto de Ubicación

Ejemplo de Objeto de Ubicación que especifica una dirección para ser geocodificada y acepta cualquier resultado:

{
  "address": "1350 N High St, Columbus, OH 43201, USA",
  "acceptPartialMatch": true,
  "acceptMultipleResults": true
}

Además de las propiedades del Objeto de Ubicación, están disponibles las siguientes propiedades:

Propiedad Tipo Descripción
acceptMultipleResults boolean Usado solo si una nueva ubicación es creada mediante geocodificación del campo address. Si es false o no se especifica, el sistema no aceptará direcciones geocodificadas donde se hayan encontrado varios resultados coincidentes con la dirección proporcionada, y se generará un error.
acceptPartialMatch boolean Usado solo si una nueva ubicación es creada mediante geocodificación del campo address. Si es false o no se especifica, el sistema no aceptará direcciones geocodificadas que solo coincidan parcialmente (menor confianza en la geocodificación), y se generará un error.
storeInvalid boolean Usado solo si una nueva ubicación es creada mediante geocodificación del campo address. Si es false o no se especifica, el sistema generará un error cuando la dirección proporcionada sea errónea o incompleta (no se ha encontrado ninguna dirección que coincida con la proporcionada). Configurar este parámetro en true permite almacenar información de ubicación incompleta que puede corregirse posteriormente. Hasta que la ubicación sea corregida, no será posible planificar pedidos con esta ubicación.

Una ubicación se define por uno de los siguientes:

Respuesta

Respuesta a la solicitud de ejemplo:

{
  "success": true,
  "id": "8cde6711026ff11f79f15a719277fe26",
  "location": {
    "notes": "",
    "longitude": -71.0528824,
    "locationName": "Green Cross Pharmacy North End",
    "locationNo": "LOC001",
    "address": "393 Hanover St, Boston, MA 02113, USA",
    "latitude": 42.3651425,
    "valid": true,
    "checkInTime": 0
  },
  "geocodingResults": [
    [
      "393 Hanover St, Boston, MA 02113, USA",
      42.3651425,
      -71.0528824
    ]
  ]
}
Propiedad Tipo / Predeterminado Descripción
success
obligatorio
booleano
-
true si el pedido fue guardado, false si hubo un error.
code
opcional
string
-
Un código de error o un código de advertencia (no se establece si la operación fue exitosa).
message
opcional
string
-
Una descripción del error o una descripción de advertencia (no se establece si la operación fue exitosa).
id
opcional
string
-
El identificador único de solo lectura del pedido, asignado por OptimoRoute
location
opcional
objeto de ubicación
-
Los datos de la ubicación para el pedido creado (solo si la operación fue exitosa).
geocodingResults
opcional
lista
-
La lista de resultados de geocodificación si la ubicación se crea a partir de la dirección proporcionada.
Cada resultado de geocodificación se define como:
[geocodedAddress, latitude, longitude, partialMatchFlag]

Códigos de Error y Advertencias

Los siguientes códigos de error son aplicables al método Crear Pedido:

Código de Error Descripción
ERR_ORD_EXISTS un pedido con el orderNo especificado ya existe en el sistema (comprobado solo si se establece el campo orderNo)
ERR_RELATED_ORD_MISSING el pedido con el ID pasado en relatedOrderNo no existe
ERR_RELATED_ORD_MULTIPLE existen múltiples pedidos con el ID pasado en relatedOrderNo
ERR_RELATED_ORD_LINK el pedido no se puede vincular al pedido con el ID pasado en relatedOrderNo (solo se pueden vincular recoger y entregar)
ERR_DRV_NOT_EXISTS el conductor con el número de serie pasado en assignedTo no existe
ERR_DRV_MULTIPLE hay más de un conductor con el número de serie assignedTo
ERR_LOC_NOT_VALID la ubicación especificada no es válida
ERR_LOC_GEOCODING no se pudo geocodificar la dirección especificada
ERR_LOC_GEOCODING_MULTIPLE se encontraron múltiples resultados durante la geocodificación
ERR_LOC_GEOCODING_PARTIAL el geocodificador no devolvió una coincidencia exacta para la solicitud original
ERR_LOC_NON_EXISTING_LOC la ubicación especificada por locationNo no existe
ERR_LOC_MULTIPLE_LOC se encontraron múltiples ubicaciones con el locationNo especificado
ERR_VF_NOT_EXISTS la característica del vehículo no existe (para uno de los códigos especificados en el campo vehicleFeatures)
ERR_VF_MULTIPLE existen múltiples características de vehículos (para uno de los códigos especificados en el campo vehicleFeatures)
ERR_SK_NOT_EXISTS la habilidad no existe (para uno de los códigos especificados en el campo skills)
ERR_SK_MULTIPLE existen múltiples habilidades (para uno de los códigos especificados en el campo skills)
WAR_LOC_GEOCODING no se pudo geocodificar la dirección especificada (pero el pedido fue creado porque storeInvalid se estableció en True)
WAR_LOC_GEOCODING_MULTIPLE se encontraron múltiples resultados durante la geocodificación (pero el pedido fue creado porque acceptMultipleResults se estableció en True)
WAR_LOC_GEOCODING_PARTIAL el geocodificador no devolvió una coincidencia exacta para la solicitud original (pero el pedido fue creado porque acceptPartialMatch se estableció en True)

Crear o Actualizar Pedidos (en bloque)

Crea, actualiza o reemplaza uno o más pedidos en el sistema.

Tenga en cuenta que la geocodificación de direcciones no está disponible en esta llamada. Las ubicaciones para los pedidos deben existir en el sistema, o especificarse mediante coordenadas de latitud y longitud. La geocodificación está disponible en Crear Pedido.

Solicitud HTTP

POST https://api.optimoroute.com/v1/create_or_update_orders

reqbody.json es un archivo local que contiene los datos JSON a publicar. Asegúrate de reemplazar AUTH_KEY con tu clave de API.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/create_or_update_orders?key=AUTH_KEY'

Parámetros

Ejemplo del cuerpo de la solicitud:

{
  "orders": [
    {
      "orderNo": "54913250",
      "date": "2019-03-22",
      "duration": 60,
      "priority": "H",
      "type": "T",
      "assignedTo": {"externalId": "DRV001", "serial": "001"},
      "location": {
        "locationNo": "G402333",
        "address": "393 Hanover St, Boston, MA 02113, USA",
        "locationName": "Green Cross Pharmacy North End",
        "latitude": 42.365142,
        "longitude": -71.052882,
        "checkInTime": 0,
      },
      "timeWindows": [{
        "twFrom": "11:00",
        "twTo": "17:00"
      }],
      "allowedWeekdays": ["mon", "tue", "wed", "thu", "fri"],
      "allowedDates": {},
      "skills": ["SK001"],
      "vehicleFeatures": [],
      "notes": "Notify manager",
      "email": "joe.customer@example.com",
      "phone": "",
      "customField1": "300",
      "notificationPreference": "email"
    },
    {
      "orderNo": "27463225",
      "date": "2019-03-22",
      "duration": 10,
      "type": "D",
      "load1": 1,
      "location": {
        "locationNo": "999999999",
      },
    },
    {
      "orderNo": "09463221",
      "date": "2019-03-22",
      "duration": 10,
      "type": "D",
      "load1": 1,
      "location": {
        "notes": "",
        "locationNo": "R384892",
        "locationName": "Moe's Southwest Grill",
        "longitude": -71.7520717,
        "latitude": 42.2752323,
        "notes": "Use gate"
      },
    }
  ]
}
Propiedad Tipo / Predeterminado Descripción
orders
obligatorio
lista de objetos de pedido
-
Lista de uno o más objetos de pedido para crear, actualizar o reemplazar en el sistema. Se pueden especificar hasta 500 pedidos.

Objeto Pedido

Además de las propiedades del Objeto Pedido, están disponibles las siguientes propiedades:

Propiedad Tipo Descripción
operation enum de cadena MERGE – se usa para actualizar solo campos específicos y dejar todos los otros campos sin cambios (por ejemplo, si algunos campos fueron editados manualmente en OptimoRoute y no deberían actualizarse). Si este es un nuevo pedido, lo crearemos. Si hay un pedido existente en el sistema, se actualizará.

SYNC – recomendado cuando el objetivo final es asegurarse de que los pedidos se reflejen en OptimoRoute. Si este es un nuevo pedido, lo crearemos. Si hay un pedido existente en el sistema, se actualizará. SYNC realiza una sincronización limpia de los datos del pedido. Todo lo que tengamos sobre este pedido será reemplazado por los datos que nos envíes en SYNC.

CREATE – crea un nuevo pedido en el sistema; no permitido junto con id

UPDATE – actualiza un pedido existente en el sistema. Si el pedido no existe, el sistema devolverá un error.
acceptDuplicateOrderNo booleano Si se establece en true, el sistema permitirá crear pedidos con orderNo que ya existen en el sistema. Cuando es false o no especificado, el sistema devolverá un error.

Cada objeto de pedido dado en orders resultará en un pedido que se creará, actualizará o reemplazará en el sistema. El comportamiento exacto para cada pedido puede configurarse a través de operation en cada objeto de pedido. El comportamiento predeterminado es:

Objeto Ubicación

Consulta el Objeto Ubicación para ver todas las propiedades de ubicación disponibles. Las ubicaciones se pueden crear o actualizar.

Si se especifica locationNo y existe una ubicación coincidente, esa ubicación se actualizará. Si locationNo no tiene coincidencias, se creará una nueva ubicación.

Si locationNo no se especifica y se actualiza un pedido existente, la ubicación del pedido se actualizará.

Durante la actualización, la ubicación coincidente se actualizará con los valores dados en el objeto, si los hay. No hay propiedades obligatorias al actualizar. Al actualizar con SYNC, las propiedades se restablecen a los valores predeterminados; de lo contrario, conservan sus valores existentes.

En los casos en que se crea una nueva ubicación, las siguientes propiedades son obligatorias: latitude, longitude y una de locationNo, address, locationName.

Respuesta

Ejemplo de respuesta:

{
  "orders": [
    {
      "success": true,
      "id": "c821486835d2f20539a9754454f7efbe",
      "orderNo": "54913250"
    },
    {
      "success": false,
      "code": "ERR_LOC_NON_EXISTING_LOC",
      "message": "The location with the given location number does not exist.",
      "orderNo": "27463225",
      "locationNo": "999999999"
    },
    {
      "success": true,
      "id": "8cde6711026ff11f79f15a719277fe26",
      "orderNo": "09463221"
    }
  ],
  "success": true
}
Propiedad Tipo / Predeterminado Descripción
success
obligatorio
booleano
-
true si al menos una operación fue exitosa, false si todas fallaron
orders
lista de objetos de respuesta de pedido
-
Cada objeto de pedido en la lista corresponde al respectivo pedido en la solicitud. Consulta la sección Objeto de Respuesta de Pedido para más información.

Objeto de Respuesta de Pedido

Propiedad Tipo / Predeterminado Descripción
success
obligatorio
booleano
-
true si la operación tuvo éxito, false si hubo un error.
orderNo
opcional
cadena
-
Identificador del pedido respectivo
id
opcional
cadena
-
El identificador único de solo lectura del pedido, asignado por OptimoRoute
locationNo
opcional
cadena
-
Identificador de la ubicación si ocurrió un error relacionado con la ubicación
code
opcional
cadena
-
Un código de error por pedido (no se establece si la operación fue exitosa).
message
opcional
cadena
-
Una descripción del error o advertencia (no se establece si la operación fue exitosa).

Códigos de Error y Advertencia

Los siguientes códigos de error por pedido son aplicables:

Código de Error Descripción
ERR_INVALID_PARAM_FORMAT el pedido especificado no es válido, posiblemente un pedido para crear/actualizar no existía en el sistema pero no pudo crearse porque falta una propiedad obligatoria
ERR_ORD_EXISTS ya existe un pedido con el orderNo especificado en el sistema (solo con CREATE más orderNo)
ERR_ORD_NOT_FOUND no se encontró el pedido con el orderNo coincidente (solo con UPDATE más orderNo, o si se utiliza id en la solicitud)
ERR_MULTIPLE_ORD_FOUND hay múltiples pedidos que coinciden con el orderNo
ERR_OPT_RUNNING la optimización está en ejecución para este pedido
ERR_RELATED_ORD_MISSING el pedido con el orderNo pasado en relatedOrderNo no existe
ERR_RELATED_ORD_MULTIPLE existen múltiples pedidos con orderNo pasado en relatedOrderNo
ERR_RELATED_ORD_LINK el pedido no puede enlazarse con el pedido con orderNo pasado en relatedOrderNo (solo recoger y entregar pueden ser enlazados)
ERR_DRV_NOT_EXISTS el conductor especificado en assignedTo no existe
ERR_DRV_MULTIPLE hay más de un conductor con los valores assignedTo especificados
ERR_LOC_NOT_VALID la ubicación especificada no es válida, posiblemente una ubicación para crear/actualizar no existía en el sistema pero no pudo crearse porque falta una propiedad obligatoria
ERR_LOC_NON_EXISTING_LOC la ubicación especificada por locationNo no existe
ERR_LOC_MULTIPLE_LOC se han encontrado múltiples ubicaciones con el locationNo especificado
ERR_VF_NOT_EXISTS la característica del vehículo no existe (para uno de los códigos especificados en el campo vehicleFeatures)
ERR_VF_MULTIPLE existen múltiples características del vehículo (para uno de los códigos especificados en el campo vehicleFeatures)
ERR_SK_NOT_EXISTS la habilidad no existe (para uno de los códigos especificados en el campo skills)
ERR_SK_MULTIPLE existen múltiples habilidades (para uno de los códigos especificados en el campo skills)

Obtener Pedidos (en lote)

Recupera uno o más pedidos del sistema.

Solicitud HTTP

POST https://api.optimoroute.com/v1/get_orders

reqbody.json es un archivo local que contiene los datos JSON que se van a enviar. Asegúrate de reemplazar AUTH_KEY con tu clave API.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/get_orders?key=AUTH_KEY'

Parámetros

Ejemplo de cuerpo de solicitud:

{
  "orders": [
    {
      "orderNo": "ORD001"
    },
    {
      "orderNo": "ORD99"
    },
    {
      "id": "04e7b09e993e8488024f46aaf9d8c72d"
    }
  ]
}
Propiedad Tipo / Predeterminado Descripción
orders
obligatorio
lista de objetos de pedido
-
Lista de objetos de pedido para recuperar. Cada objeto de pedido puede contener cualquiera de los siguientes:
  • orderNo: el identificador especificado por el usuario de un pedido
  • id: el identificador único del pedido, asignado por OptimoRoute
Se pueden especificar un máximo de 500 pedidos.



Para más flexibilidad, si solo se utiliza orderNo, la llamada a get_orders también se puede hacer como una solicitud HTTP GET:

Ejemplo de solicitud GET:

curl 'https://api.optimoroute.com/v1/get_orders?key=AUTH_KEY&orderNo=ORD001&orderNo=ORD99'
Propiedad Tipo / Predeterminado Descripción
orderNo
obligatorio
cadena de texto
-
El identificador especificado por el usuario de un pedido; se puede repetir para recuperar múltiples pedidos

Respuesta

Ejemplo de respuesta:

{
  "success": true,
  "orders": [
    {
      "success": true,
      "id": "04e7b09e993e8488024f46aaf9d8c72d",
      "data": {
        "orderNo": "ORD001",
        "id": "04e7b09e993e8488024f46aaf9d8c72d",
        "date": "2018-11-12",
        "duration": 60,
        "priority": "M",
        "type": "T",
        "load1": 1,
        "load2": 0,
        "load3": 0,
        "load4": 0,
        "assignedTo": {"externalId": "DRV001", "serial": "001"},
        "location": {
          "locationNo": "LOC001",
          "address": "393 Hanover St, Boston, MA 02113, USA",
          "locationName": "Green Cross Pharmacy North End",
          "latitude": 42.365142,
          "longitude": -71.052882,
          "checkInTime": 0,
          "notes": ""
        },
        "timeWindows": [{
            "twFrom": "11:00",
            "twTo": "17:00"
        }],
        "allowedWeekdays": ["mon", "tue", "wed", "thu", "fri"],
        "allowedDates": {},
        "skills": ["SK001"],
        "vehicleFeatures": [],
        "notes": "",
        "email": "",
        "phone": "",
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "notificationPreference": "email"
      }
    },
    {
      "message": "El pedido con el orderNo coincidente no fue encontrado.",
      "code": "ERR_ORD_NOT_FOUND",
      "orderNo": "ORD99",
      "success": false
    },
    {
      "success": true,
      "id": "04e7b09e993e8488024f46aaf9d8c72d",
      "data": {
        "orderNo": "-",
        "id": "04e7b09e993e8488024f46aaf9d8c72d",
        "date": "2018-11-12",
        "duration": 30,
        "priority": "M",
        "type": "T",
        "load1": 2,
        "load2": 0,
        "load3": 0,
        "load4": 0,
        "assignedTo": null,
        "location": {
          "locationNo": "LOC001",
          "address": "393 Hanover St, Boston, MA 02113, USA",
          "locationName": "Green Cross Pharmacy North End",
          "latitude": 42.365142,
          "longitude": -71.052882,
          "checkInTime": 0,
          "notes": ""
        },
        "timeWindows": [],
        "allowedWeekdays": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"],
        "allowedDates": {},
        "skills": ["SK001"],
        "vehicleFeatures": [],
        "notes": "",
        "email": "",
        "phone": "",
        "customField1": "",
        "customField2": "",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "notificationPreference": "email"
      }
    },
  ]
}
Propiedad Tipo / Predeterminado Descripción
success
obligatorio
booleano
-
true si se recuperó al menos un pedido, false si no se recuperó ningún pedido
orders
obligatorio
lista de objetos de respuesta de pedido
-
Cada objeto de pedido en la lista corresponde al respectivo orderNo y/o id en la solicitud. Ver sección Objeto de Respuesta de Pedido para más información.

Objeto de Respuesta de Pedido

Propiedad Tipo / Predeterminado Descripción
success
obligatorio
booleano
-
true si el pedido fue recuperado, false si hubo un error.
code
opcional
cadena de texto
-
Un código de error o un código de advertencia (no se establece si la operación fue exitosa).
message
opcional
cadena de texto
-
Una descripción del error o una advertencia (no se establece si la operación fue exitosa).
orderNo
opcional
cadena de texto
-
El orderNo cuya recuperación falló. Solo está presente si la operación no fue exitosa y se utilizó orderNo en la solicitud.
id
obligatorio
cadena de texto
-
El identificador único del pedido, asignado por OptimoRoute.
data
opcional
Objeto de pedido
-
El pedido recuperado.

Objeto de Pedido

En caso de éxito, los datos serán un objeto con las propiedades enumeradas en Objeto de Pedido.

La propiedad type devuelta puede ser adicionalmente break o depot.

Códigos de Error y Advertencia

Los siguientes códigos de error por pedido son aplicables al método Obtener Pedidos:

Código de Error Descripción
ERR_ORD_NOT_FOUND el pedido con el orderNo y/o id coincidente no fue encontrado.
ERR_MULTIPLE_ORD_FOUND hay múltiples pedidos que coinciden con el orderNo
ERR_INVALID_PARAM_FORMAT este orderNo no es válido

Eliminar Pedido

Elimina un pedido del sistema.

Solicitud HTTP

POST https://api.optimoroute.com/v1/delete_order

reqbody.json es un archivo local que contiene los datos JSON a publicar. Asegúrate de reemplazar AUTH_KEY con tu clave API.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/delete_order?key=AUTH_KEY'

Parámetros

Ejemplo de cuerpo de solicitud:

{
  "orderNo": "ORD001"
}
Propiedad Tipo / Predeterminado Descripción
orderNo
obligatorio
string
-
El identificador especificado por el usuario del pedido a eliminar.
forceDelete
opcional
boolean
false
Si es true, se ignoran las restricciones habituales sobre eliminar pedidos en un plan en vivo.

Respuesta

Propiedad Tipo / Predeterminado Descripción
success
obligatorio
boolean
-
true si el pedido fue eliminado, false si hubo un error.
code
opcional
string
-
Un código de error o un código de advertencia (no se establece si la operación fue exitosa).
message
opcional
string
-
Una descripción del error o una descripción de advertencia (no se establece si la operación fue exitosa).
planningId
opcional
integer
-
El id del proceso de planificación en caso de que la optimización esté en ejecución para este pedido.

Códigos de Error y Advertencia

Los siguientes códigos de error son aplicables al método Eliminar Pedido:

Código de Error Descripción
ERR_ORD_NOT_FOUND el pedido con el orderNo correspondiente no fue encontrado
ERR_MULTIPLE_ORD_FOUND hay múltiples pedidos que coinciden con el orderNo
ERR_OPT_RUNNING la optimización está en ejecución para este pedido

Eliminar todos los pedidos

Elimina todos los pedidos y rutas planificadas para la fecha especificada del sistema. Si no se establece una fecha, todos los pedidos y rutas se eliminan del sistema.

Solicitud HTTP

POST https://api.optimoroute.com/v1/delete_all_orders

reqbody.json es un archivo local que contiene los datos JSON a enviar. Asegúrate de reemplazar AUTH_KEY con tu clave de API.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/delete_all_orders?key=AUTH_KEY'

Parámetros

Ejemplo de cuerpo de solicitud:

{
  "date": "2014-10-14"
}
Propiedad Tipo / Por defecto Descripción
date
opcional
date (string)
-
Fecha para la cual se eliminarán los pedidos y rutas.
Formato YYYY-MM-DD, por ejemplo 2013-12-20.

Respuesta

Propiedad Tipo / Por defecto Descripción
success
obligatorio
boolean
-
true si los pedidos fueron eliminados, false si hubo un error.
code
opcional
string
-
Un código de error o un código de advertencia (no se establece si la operación fue exitosa).
message
opcional
string
-
Una descripción del error o una descripción de advertencia (no se establece si la operación fue exitosa).
planningId
opcional
integer
-
El ID del proceso de planificación en caso de que la optimización esté en ejecución.

Códigos de error y advertencia

Los siguientes códigos de error son aplicables al método Eliminar pedido:

Código de error Descripción
ERR_OPT_RUNNING la optimización está en ejecución para esta fecha

Eliminar Pedidos (en bloque)

Elimina uno o más pedidos del sistema.

Solicitud HTTP

POST https://api.optimoroute.com/v1/delete_orders

reqbody.json es un archivo local que contiene los datos JSON a enviar. Asegúrate de reemplazar AUTH_KEY con tu clave de API.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/delete_orders?key=AUTH_KEY'

Parámetros

Ejemplo de cuerpo de solicitud:

{
  "orders": [
    {
      "orderNo": "ORD001"
    },
    {
      "orderNo": "ORD999"
    },
    {
      "id": "04e7b09e993e8488024f46aaf9d8c72d"
    }
  ]
}
Propiedad Tipo / Predeterminado Descripción
orders
obligatorio
lista de objetos de pedidos
-
Lista de objetos de pedidos a eliminar. Cada objeto de pedido puede contener cualquiera de:
  • orderNo: el identificador especificado por el usuario de un pedido
  • id: el identificador único del pedido, asignado por OptimoRoute
Se pueden especificar como máximo 500 pedidos.
deleteMultiple
opcional
booleano
false
Si es false, cuando hay varios pedidos coincidentes con un objeto de pedido, se devolverá un error. Si es true, se eliminarán todas las coincidencias.
forceDelete
opcional
booleano
false
Si es true, se ignoran las restricciones habituales respecto a la eliminación de pedidos en un plan activo.

Respuesta

Ejemplo de respuesta:

{
  "success": true,
  "orders": [
    {
      "orderNo": "ORD001",
      "success": true
    },
    {
      "message": "El pedido con el orderNo coincidente no fue encontrado.",
      "code": "ERR_ORD_NOT_FOUND",
      "orderNo": "ORD999",
      "success": false
    },
    {
      "success": true,
      "id": "04e7b09e993e8488024f46aaf9d8c72d"
    }
  ]
}
Propiedad Tipo / Predeterminado Descripción
success
obligatorio
booleano
-
true si al menos un pedido fue eliminado, false si no se eliminaron pedidos.
orders
obligatorio
lista de objetos de respuesta de eliminación
-
Cada objeto de pedido en la lista corresponde al respectivo orderNo y/o id en la solicitud. Ver la sección Eliminar Objeto de Respuesta para más información.

Eliminar Objeto de Respuesta

Propiedad Tipo / Predeterminado Descripción
success
obligatorio
booleano
-
true si fue eliminado, false si hubo un error.
code
opcional
cadena
-
Un código de error o un código de advertencia (no establecido si la operación fue exitosa).
message
opcional
cadena
-
Una descripción del error o una descripción de advertencia (no establecida si la operación fue exitosa).
orderNo
opcional
cadena
-
El orderNo que fue eliminado, o cuyo eliminado falló. Solo presente si orderNo fue utilizado en la solicitud.
id
opcional
cadena
-
El id que fue eliminado, o cuyo eliminado falló. Solo presente si id fue utilizado en la solicitud.
planningId
opcional
entero
-
El id del proceso de planificación en caso de que la optimización esté en ejecución para este pedido.

Códigos de Error y Advertencia

Los siguientes códigos de error por pedido son aplicables al método Eliminar Pedidos:

Código de Error Descripción
ERR_ORD_NOT_FOUND el pedido con el orderNo y/o id coincidente no fue encontrado
ERR_MULTIPLE_ORD_FOUND hay múltiples pedidos que coinciden con el orderNo, pero deleteMultiple fue establecido en false
ERR_OPT_RUNNING la optimización está en ejecución para este pedido
ERR_INVALID_PARAM_FORMAT este orderNo o id no es válido

Obtener Rutas

Obtiene las rutas para una fecha específica.

Solicitud HTTP

GET https://api.optimoroute.com/v1/get_routes

Asegúrate de reemplazar AUTH_KEY con tu clave API.

curl 'https://api.optimoroute.com/v1/get_routes?key=AUTH_KEY&date=2013-12-20'
curl 'https://api.optimoroute.com/v1/get_routes?key=AUTH_KEY&date=2022-03-16&driverSerial=011&includeRoutePolyline=true'

Parámetros

Propiedad Tipo / Predeterminado Descripción
date
obligatorio
date (string)
-
Fecha consultada.
Formato YYYY-MM-DD, por ejemplo 2013-12-20.
driverExternalId
opcional
string
-
Filtrar opcionalmente por el identificador externo del conductor.
driverSerial
opcional
string
-
Filtrar opcionalmente por el número de serie del conductor.
vehicleRegistration
opcional
string
-
Filtrar opcionalmente por registro del vehículo.
includeRoutePolyline
opcional
boolean
false
Propiedad opcional para incluir el polilínea de la ruta en el resultado. Este polilínea puede ser utilizado para mostrar la ruta en el mapa. El polilínea es una lista de coordenadas codificadas con el Algoritmo de Polilínea Codificada.
includeRouteStartEnd
opcional
boolean
false
Propiedad opcional para incluir las ubicaciones de inicio y fin de la ruta en el resultado.

Respuesta

Ejemplo de respuesta

{
  "success": true,
  "routes": [
    {
      "driverExternalId": "",
      "driverSerial": "011",
      "driverName": "Driver 011",
      "vehicleRegistration": "Vehicle 011",
      "vehicleLabel": "011",
      "duration": 37,
      "distance": 19.563,
      "load1": 0,
      "load3": 0,
      "load2": 0,
      "load4": 0,
      "stops": [
        {
          "stopNumber": 1,
          "orderNo": "-",
          "id": "f7afe58fcddfcbf9f42620c79ebad7ff",
          "scheduledAt": "10:16",
          "scheduledAtDt": "2022-03-16 10:16:41",
          "arrivalTimeDt": "2022-03-16 10:16:41",
          "address": "Burwyn, IL",
          "locationName": "Burwyn, IL",
          "locationNo": "",
          "latitude": 41.8505874,
          "longitude": -87.7936685,
          "distance": 0,
          "travelTime": 0
        },
        {
          "stopNumber": 2,
          "orderNo": "-",
          "id": "0a077bd652b4b0c69fd9bdb3efefe729",
          "scheduledAtDt": "2022-03-16 10:33:18",
          "arrivalTimeDt": "2022-03-16 10:33:18",
          "scheduledAt": "10:33",
          "address": "Oak Park, Chicago",
          "locationName": "Oak Park, Chicago",
          "locationNo": "",
          "latitude": 41.8850317,
          "longitude": -87.7845025,
          "distance": 4668,
          "travelTime": 397
        }
      ],
      "routePolyline": "_}l~FlezvO????Ag@?Y?U?s@?c@AgCAmB?w@?]?IAc@Hm@AoCAw@A}C?WA_AAsFCwD?M?m@CsF?k@AwAAw@?W?_@U?qA@S?U@[?gEDiIHm@?cJHmJFiJJoJFmJHqGFe@?u@@gA@Q?oGHuBBuFFmJLq@Bg@?}CD]@m@?k@@o@@i@?oGH}HHc@@M?O?a@@yDD}BBM?_GFY@Y?O?O@W?U@w@?Q@y@?uABwA@Q?S@kA@M?{EDQ@S?gHD??fHER?PAzEEL?jAARAP?vAAtACx@?PAv@?TAV?AYA{E?qACaDAkBAw@?oAAgA?WAqA?E?_@A]?WC}E?k@Ae@?M?[AwBAsB?o@AoA?g@Ai@?mAAsACkCA{DA{BA{BAo@?]CqF?G?e@Ae@?u@CcG?QEcF?O?m@?]A_F?QAy@?[PAX?J?^AH?FA~@AR?XA|@AhACP?R?tAChAAxAAh@A\\AR?RAd@?^AxACzAAvACr@Ad@AzAC~BAt@AN?RBPBfA?b@@f@?L?b@@^AtBQt@KEe@AMGw@c@mFa@wEOyCGoCQ}BMy^G}UC_ICwJC}JE_JIeHI_ICyBIqAMyAMmASsAWqA[mA_@kAo@iBm@{Aa@kA[cA]uAQu@Mw@QuAK}@IeAEcAC_ACcDAqGOwb@CsJCuKKc[AuDM_c@C_DCuASeF]uEWcD_@_F[wDo@uIUmDKsBIuBEsBGuCCqCAeFEkOGuQE}OC}HCkQCwM?wFC_SI{QCmEAwH@}FAmEGoNMqUAeEEcG?cC@sD?sB@mCB_EDkDBuBDeC@yBPuIDqGAyPAyECsBEsACyDAuB?u@?c@?sGCgCGkKC{BA_GAwB?S?u@AcD?Y?_A?yA@aA?s@B}AB{B?uB?]?eA?yC?OAkEAiB?_@?_AAmA?M]?]@G?G?}@Be@?yAB?F?bA?LM?aFFG?"
    }
  ]
}
Propiedad Tipo / Predeterminado Descripción
success
obligatorio
boolean
-
true si la consulta fue exitosa, false si hubo un error.
routes
obligatorio
lista de objetos de ruta
[]
Lista de rutas que coinciden con la consulta.
code
opcional
string
-
Un código de error o un código de advertencia (no se establece si la operación fue exitosa).
message
opcional
string
-
Una descripción del error o una descripción de advertencia (no se establece si la operación fue exitosa).

Objeto Ruta

Propiedad Tipo / Predeterminado Descripción
driverExternalId
obligatorio
string
-
El identificador externo del conductor.
driverSerial
obligatorio
string
-
El número de serie asignado al conductor.
driverName
obligatorio
string
-
El nombre del conductor.
vehicleRegistration
obligatorio
string
-
Registro del vehículo.
vehicleLabel
obligatorio
string
-
Etiqueta del vehículo.
duration
obligatorio
integer
-
Duración de la ruta en minutos.
distance
obligatorio
decimal
-
Distancia de la ruta en kilómetros.
load1
obligatorio
integer
0
Carga de la ruta #1.
load2
obligatorio
integer
0
Carga de la ruta #2.
load3
obligatorio
integer
0
Carga de la ruta #3.
load4
obligatorio
integer
0
Carga de la ruta #4.
stops
obligatorio
lista de objetos stop
[]
Una lista ordenada de paradas/pedidos en la ruta.
routePolyline
opcional
string
-
Polilínea de la ruta codificada con el Algoritmo de Polilínea Codificada. Solo se incluye si includeRoutePolyline está establecido en True.

Objeto Stop

Propiedad Tipo / Predeterminado Descripción
stopNumber
obligatorio
integer
-
Número de parada. Comienza en 1.
orderNo
obligatorio
string
-
El número de pedido.
id
obligatorio
string
-
El identificador único de solo lectura del pedido, asignado por OptimoRoute.
locationNo
obligatorio
string
-
Número de ubicación.
locationName
obligatorio
string
-
Nombre de la ubicación.
address
obligatorio
string
-
Dirección de la ubicación.
latitude
obligatorio
decimal
-
Latitud de la ubicación.
longitude
obligatorio
decimal
-
Longitud de la ubicación.
scheduledAt
obligatorio
hora (string)
-
La hora programada para comenzar el servicio.
Formato de reloj de 24 horas (militar), por ejemplo: 16:00.
Los valores válidos van de 00:00 a 23:59.
scheduledAtDt
obligatorio
datetime (string)
-
La fecha y hora programada para comenzar el servicio. Formato: YYYY-mm-dd HH:MM:SS, por ejemplo 2018-01-01 13:10:37.
arrivalTimeDt
obligatorio
datetime (string)
-
La fecha y hora cuando el conductor llegó a la ubicación. Debido a las ventanas de tiempo, el conductor podría necesitar esperar para comenzar el servicio. Formato: YYYY-mm-dd HH:MM:SS, por ejemplo 2018-01-01 13:10:37.
travelTime
obligatorio
integer
-
Tiempo de viaje desde la parada anterior (en segundos).
distance
obligatorio
integer
-
Distancia desde la parada anterior (en metros).
type
opcional
string
-
Tipo de pedido solo agregado para pausas para almorzar (el valor será break) y para viajes al depósito (el valor será depot).

Códigos de Error y Advertencia

Ninguno.

Obtener Información de Programación

Obtiene la información de programación para el Pedido especificado. Para método masivo, consulte Buscar Pedidos

Solicitud HTTP

GET https://api.optimoroute.com/v1/get_scheduling_info

Asegúrese de reemplazar AUTH_KEY con su clave API.

curl 'https://api.optimoroute.com/v1/get_scheduling_info?key=AUTH_KEY&orderNo=ORD001'

Parámetros

Propiedad Tipo / Predeterminado Descripción
orderNo
opcional
cadena de texto
-
El identificador especificado por el usuario para el pedido.
id
opcional
cadena de texto
-
El identificador único del pedido, asignado por OptimoRoute.

Se debe proporcionar una de las dos propiedades en la solicitud.

Respuesta

Propiedad Tipo / Predeterminado Descripción
success
obligatorio
booleano
-
true si la consulta fue exitosa, false si hubo un error.
orderScheduled
opcional
booleano
-
true si el pedido está programado, false de lo contrario.
scheduleInformation
opcional
objeto de información de programación
-
La información de programación del pedido.
code
opcional
cadena de texto
-
Un código de error o un código de advertencia (no se establece si la operación fue exitosa).
message
opcional
cadena de texto
-
Una descripción del error o una descripción de advertencia (no se establece si la operación fue exitosa).

Objeto de Información de Programación del Pedido

Propiedad Tipo / Predeterminado Descripción
driverExternalId
obligatorio
cadena de texto
-
El identificador externo del conductor.
driverSerial
obligatorio
cadena de texto
-
El número de serie asignado al conductor.
driverName
obligatorio
cadena de texto
-
El nombre del conductor.
vehicleRegistration
obligatorio
cadena de texto
-
Registro del vehículo.
vehicleLabel
obligatorio
cadena de texto
-
Etiqueta del vehículo.
stopNumber
obligatorio
entero
-
Número de parada en la ruta. Comienza en 1.
scheduledAt
obligatorio
hora (cadena de texto)
-
La hora programada para comenzar el servicio.
Formato de 24 horas (militar), por ejemplo: 16:00.
Los valores válidos van desde 00:00 hasta 23:59.
scheduledAtDt
obligatorio
fecha y hora (cadena de texto)
-
La fecha y hora programada para comenzar el servicio. Formato: AAAA-mm-dd HH:MM:SS, por ejemplo 2018-01-01 13:10:37.
arrivalTimeDt
obligatorio
fecha y hora (cadena de texto)
-
La fecha y hora en que el conductor llegó a la ubicación. Debido a las ventanas de tiempo, el conductor podría necesitar esperar para comenzar el servicio. Formato: AAAA-mm-dd HH:MM:SS, por ejemplo 2018-01-01 13:10:37.
travelTime
obligatorio
entero
-
Tiempo de viaje desde la parada anterior (en segundos).
distance
obligatorio
entero
-
Distancia desde la parada anterior (en metros).

Códigos de Error y Advertencia

Los siguientes códigos de error son aplicables al método Obtener Información de Programación:

Código de Error Descripción
ERR_ORD_NOT_FOUND el pedido con el orderNo correspondiente no fue encontrado
ERR_MULTIPLE_ORD_FOUND hay múltiples pedidos que coinciden con el orderNo

Ejemplo de respuesta 1

{
  "success": true,
  "orderScheduled": true,
  "scheduleInformation": {
    "stopNumber": 23,
    "scheduledAt": "11:23",
    "scheduledAtDt": "2020-02-07 11:23:22",
    "arrivalTimeDt": "2020-02-07 11:23:22",
    "driverSerial": "005",
    "driverExternalId": null,
    "driverName": "Driver 005",
    "vehicleLabel": "005",
    "vehicleRegistration": "Vehicle 005",
    "distance": 952,
    "travelTime": 123
  }
}

Ejemplo de respuesta 2

{
    "success":true,
    "orderScheduled":false
}

Iniciar Planificación

Inicia el proceso de planificación para la fecha especificada.

Solicitud HTTP

POST https://api.optimoroute.com/v1/start_planning

reqbody.json es un archivo local que contiene los datos JSON a publicar. Asegúrate de reemplazar AUTH_KEY con tu clave de API.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/start_planning?key=AUTH_KEY'

Parámetros

Ejemplo del cuerpo de la solicitud:

{
  "date": "2013-12-20"
}
Propiedad Tipo / Valor por defecto Descripción
date
obligatorio
date (string)
-
Fecha a planificar.
Formato YYYY-MM-DD, por ejemplo 2013-12-20.
dateRange
opcional
objeto daterange Soporte para planificación semanal (planificación a largo plazo). Si se especifica dateRange, se ignora date y se puede omitir.
Daterange se especifica como un objeto con campos from y to, por ejemplo:
{"from": "2020-04-27", "to": "2020-05-01"}.
balancing
opcional
string
OFF
Configuraciones de balanceo de rutas. Valores permitidos:
OFF – Sin balanceo
ON – Balancear rutas
ON_FORCE – Balancear rutas y usar todos los conductores

Sin balanceo: devuelve las mejores rutas, algunos conductores podrían no ser utilizados.
Balancear rutas: balancea la carga de trabajo entre conductores, algunos conductores pueden no ser utilizados.
Balancear rutas y usar todos los conductores: balancear la carga de trabajo entre todos los conductores disponibles.
balanceBy
opcional
string
WT
Si el balanceo de rutas está activado, esto define el criterio para balancear las rutas.

Valores permitidos:
WT – Tiempo de trabajo
NUM – Número de pedidos por conductor
balancingFactor
opcional
decimal
0.3
Importancia del balanceo comparado con los costos de la ruta. Incrementar el factor de balanceo resultará en rutas más balanceadas.
Solamente aplicable en combinación con ON_FORCE (de lo contrario se ignora).

Valor mínimo: 0.0
Valor máximo: 1.0
startWith
opcional
string
EMPTY
Comenzar a planificar desde las rutas existentes o desde cero.

Valores permitidos:
EMPTY – Ignorar rutas existentes y comenzar desde cero
CURRENT – Comenzar a planificar con las rutas existentes
lockType
opcional
string
NONE
Aplicable si startWith está configurado a CURRENT.

Valores permitidos:
NONE – Permitir todos los cambios en las rutas existentes
ROUTES - Mantener las Rutas planificadas sin cambios y agregar nuevos Pedidos a las no utilizadas
RESOURCES - Mantener a los Conductores/Vehículos para los Pedidos planificados e incluir nuevos Pedidos
depotTrips
opcional
booleano
false
Si true, los conductores estarán programados para regresar al almacén para recargar (o descargar en caso de recoger) si hay tiempo dentro de su horario laboral para hacer otra ruta.
Más información está disponible en nuestro blog:
https://optimoroute.com/es/detener-el-reabastecimiento-y-continuar-en-su-camino/.
depotVisitDuration
opcional
entero
0
Tiempo en minutos requerido para recargar o descargar las mercancías en el almacén antes de que el conductor salga para otro recorrido.
Solo aplicable si depotTrips está configurado a true.
clustering
opcional
booleano
false
Si true, el sistema intentará minimizar la superposición entre las rutas de los conductores.
useDrivers
opcional
lista de objetos SelectedDriver
[]
Conductores seleccionados que deben usarse en la optimización.
Por defecto (si useDrivers no está configurado o la lista está vacía) se usan todos los conductores disponibles para la fecha especificada.
useOrders
opcional
lista de cadenas
[]
Desaprobado en favor de useOrderObjects.
Pedidos seleccionados que deben incluirse en la optimización.
Los pedidos se especifican como una lista de identificadores de pedido (cadenas orderNo).
Por defecto (si useOrders no está configurado o la lista está vacía) se incluyen todos los pedidos para la fecha especificada que tienen una ubicación válida.

Los pedidos que no se seleccionen, pero ya estén programados para conductores que se usarán en la optimización se desprogramarán a menos que la bandera includeScheduledOrders esté configurada a true.
useOrderObjects
opcional
lista de objetos
[]
Subconjunto de pedidos en la fecha planificada que deben incluirse en la optimización.
Los pedidos se especifican como lista de objetos que pueden contener:
  • propiedad orderNo con el identificador del usuario de un pedido
  • id identificador único del pedido asignado por OptimoRoute

Por defecto (si useOrderObjects no está configurado o la lista está vacía) se incluyen todos los pedidos para la fecha especificada que tienen una ubicación válida.

Los pedidos que no se seleccionen, pero ya estén programados para conductores que se usarán en la optimización se desprogramarán a menos que la bandera includeScheduledOrders esté configurada a true.
includeScheduledOrders
opcional
booleano
true
Determina el comportamiento cuando se selecciona un subconjunto de pedidos pero hay otros pedidos ya programados para los conductores apropiados.
Si includeScheduledOrders es true, estos pedidos se incluirán en la optimización, de lo contrario, se desprogramarán.

Respuesta

Propiedad Tipo / Valor por defecto Descripción
success
obligatorio
booleano
-
true si la optimización fue iniciada, false si hubo un error.
code
opcional
string
-
Un código de error o un código de advertencia (no se establece si la operación fue exitosa).
planningId
opcional
entero
-
Devuelve el id de la optimización iniciada si la operación fue exitosa, o la optimización ya en curso en caso de error ERR_OPT_RUNNING_FOR_DATE. El id de planificación puede usarse más tarde para obtener el estado de la planificación o detener el proceso de planificación.
missingOrders
opcional
lista de cadenas
[]
En caso de error ERR_ORD_NOT_FOUND este campo contendrá la lista de identificadores de pedidos faltantes (cadenas orderNo).
missingDrivers
opcional
lista de objetos SelectedDriver
[]
En caso de error ERR_DRIVER_NOT_FOUND este campo contendrá una lista de conductores faltantes. Cada conductor es un objeto SelectedDriver.
ordersWithInvalidLocation
opcional
lista de cadenas
[]
En caso de error ERR_ORD_WITH_INVALID_LOC este campo contendrá la lista de identificadores de pedidos (cadenas orderNo) que tienen una ubicación inválida.

Códigos de Error y Advertencia

Los siguientes códigos de error son aplicables al método Iniciar Planificación:

Código de Error Descripción
ERR_OPT_TRIAL_ENDED prueba gratuita ha terminado para esta cuenta
ERR_OPT_RUNNING_FOR_DATE la planificación ya está en curso para esta fecha
ERR_OPT_RUNNING_FOR_ORDER la optimización ya está en curso para uno o más pedidos listados en useOrders
ERR_OPT_NO_REQUESTS no existen pedidos para la fecha especificada
ERR_OPT_NO_RESOURCES no hay conductores disponibles para esta fecha
ERR_OPT_RESOURCES_EXCEEDED número de conductores excedido
ERR_OPT_REQUESTS_EXCEEDED número de pedidos excedido
ERR_OPT_COULD_NOT_START error interno, por favor contacte con soporte
ERR_ORD_NOT_FOUND uno o más pedidos especificados en useOrders no fueron encontrados
ERR_ORD_WITH_INVALID_LOC uno o más pedidos especificados en useOrders tienen ubicación inválida
ERR_DRIVER_NOT_FOUND uno o más conductores especificados en useDrivers no fueron encontrados
ERR_MULTIPLE_ORD_FOUND se han encontrado múltiples pedidos con el identificador especificado
ERR_MULTIPLE_DRV se han encontrado múltiples conductores con el identificador especificado
ERR_UNSUPPORTED_BY_PRICING_PLAN la planificación semanal solo es soportada con el plan actual
ERR_DATE_RANGE_TOO_LONG el rango de planificación semanal es demasiado largo
ERR_DATE_RANGE_INVALID rango inválido, la fecha to es anterior a la fecha from

Detener planificación

Detiene el proceso de planificación.

Solicitud HTTP

POST https://api.optimoroute.com/v1/stop_planning

reqbody.json es un archivo local que contiene los datos JSON a publicar. Asegúrate de reemplazar AUTH_KEY con tu clave de API.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/stop_planning?key=AUTH_KEY'

Parámetros

Ejemplo de cuerpo de solicitud:

{
  " planningId": 8828
}
Propiedad Tipo / Predeterminado Descripción
planningId
obligatorio
entero
-
El id del proceso de planificación que se desea detener.

Respuesta

Propiedad Tipo / Predeterminado Descripción
success
obligatorio
booleano
-
true si la optimización fue detenida, false si hubo un error.
code
opcional
cadena
-
Un código de error o un código de advertencia (no se establece si la operación fue exitosa).

Códigos de error y advertencia

Los siguientes códigos de error son aplicables al método Detener planificación:

Código de Error Descripción
ERR_JOB_NOT_FOUND no se encontró el trabajo de planificación con el id especificado
ERR_OPT_NOT_RUNNING el trabajo de planificación no se está ejecutando
ERR_OPT_COULD_NOT_STOP error interno, por favor contacta al soporte técnico

Obtener Estado de la Planificación

Devuelve el estado del proceso de planificación.

Solicitud HTTP

GET https://api.optimoroute.com/v1/get_planning_status

Asegúrate de reemplazar AUTH_KEY con tu clave de API.

curl 'https://api.optimoroute.com/v1/get_planning_status?key=AUTH_KEY&planningId=8828'

Parámetros

Propiedad Tipo / Predeterminado Descripción
planningId
obligatorio
integer
-
El id del proceso de planificación.

Respuesta

Propiedad Tipo / Predeterminado Descripción
success
obligatorio
boolean
-
true si la solicitud fue exitosa, false si ocurrió un error.
code
opcional
string
-
Un código de error o un código de advertencia (no se establece si la operación fue exitosa).
status
opcional
string
-
N - Nuevo
R - En ejecución
C - Cancelado por el usuario
F - Finalizado
E - Se produjo un error
percentageComplete
opcional
integer
-
Porcentaje completado: los valores varían de 0 a 100.

Códigos de Error y Advertencia

Los siguientes códigos de error son aplicables al método Obtener Estado de la Planificación:

Código de Error Descripción
ERR_JOB_NOT_FOUND el trabajo de planificación con el id especificado no fue encontrado

Actualizar Parámetros del Conductor

Actualiza los parámetros del conductor para una fecha en particular y la ubicación de inicio y fin del conductor. Cualquier ruta existente para la fecha/conductor especificados será desprogramada.

Los siguientes parámetros pueden ser modificados:

Solicitud HTTP

POST https://api.optimoroute.com/v1/update_driver_parameters

reqbody.json es un archivo local que contiene los datos JSON a enviar. Asegúrate de reemplazar AUTH_KEY con tu clave API.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/update_driver_parameters?key=AUTH_KEY'

Parámetros

Ejemplo de cuerpo de solicitud:

{
  "externalId": "3945300304540",
  "date": "2019-09-25",
  "workTimeFrom": "09:30",
  "workTimeTo": "18:00"
}
Propiedad Tipo / Predeterminado Descripción
externalId
obligatorio
cadena
-
El identificador externo asignado al conductor en la administración de conductores.
date
obligatorio
fecha
-
Fecha a planificar.
Formato YYYY-MM-DD, por ejemplo 2013-12-20.
enabled
opcional
booleano
sin cambios
Habilitar o deshabilitar al conductor para la fecha especificada.
workTimeFrom
opcional
hora (cadena)
sin cambios
Hora de inicio del trabajo del conductor para la fecha especificada.
Formato de reloj de 24 horas (militar), por ejemplo: 08:00.
Los valores válidos van desde 00:00 hasta 23:59.
workTimeTo
opcional
hora (cadena)
sin cambios
Hora de fin del trabajo del conductor para la fecha especificada.
Formato de reloj de 24 horas (militar), por ejemplo: 08:00. Los valores válidos van desde 00:00 hasta 23:59.
assignedVehicle
opcional
cadena
sin cambios
El identificador externo del vehículo que se asignará al conductor para la fecha especificada. Esto también actualizará los parámetros de capacidad de carga del vehículo (a menos que sean anulados con las configuraciones de vehicleCapacityX).
vehicleCapacity1
opcional
entero
sin cambios
La nueva capacidad de carga del vehículo #1 para la fecha especificada.
vehicleCapacity2
opcional
entero
sin cambios
La nueva capacidad de carga del vehículo #2 para la fecha especificada.
vehicleCapacity3
opcional
entero
sin cambios
La nueva capacidad de carga del vehículo #3 para la fecha especificada.
vehicleCapacity4
opcional
entero
sin cambios
La nueva capacidad de carga del vehículo #4 para la fecha especificada.
startLatitude
opcional
decimal
sin cambios
La latitud GPS de inicio del conductor cambiará (esta nueva ubicación se usará para todas las optimizaciones futuras). Si startLongitude no está definido, este valor será ignorado.
startLongitude
opcional
decimal
sin cambios
La longitud GPS de inicio del conductor (esta nueva ubicación se usará para todas las optimizaciones futuras). Si startLatitude no está definido, este valor será ignorado.
startAddress
opcional
cadena
sin cambios
La dirección de inicio del conductor que se mostrará en los informes (esta nueva ubicación se usará para todas las optimizaciones futuras). Si startLatitude y startLongitude no están definidos, este valor será ignorado.
endLatitude
opcional
decimal
sin cambios
La latitud GPS de fin del conductor (esta nueva ubicación se usará para todas las optimizaciones futuras). Si endLongitude no está definido, este valor será ignorado.
endLongitude
opcional
decimal
sin cambios
La longitud GPS de fin del conductor (esta nueva ubicación se usará para todas las optimizaciones futuras). Si endLatitude no está definido, este valor será ignorado.
endAddress
opcional
cadena
sin cambios
La dirección de fin del conductor que se mostrará en los informes (esta nueva ubicación se usará para todas las optimizaciones futuras). Si endLatitude y endLongitude no están definidos, este valor será ignorado.

Respuesta

Propiedad Tipo / Predeterminado Descripción
success
obligatorio
booleano
-
true si los parámetros del conductor se actualizaron, false si ocurrió un error.
code
opcional
cadena
-
Un código de error o un código de advertencia (no se establece si la operación fue exitosa).

Códigos de Error y Advertencia

Los siguientes códigos de error son aplicables al método Actualizar Parámetros del Conductor:

Código de Error Descripción
ERR_DRIVER_NOT_FOUND el conductor con el externalId especificado no fue encontrado
ERR_MULTIPLE_DRV se encontraron múltiples conductores con el externalId especificado
ERR_VEH_NOT_FOUND el vehículo con el externalId especificado no fue encontrado
ERR_MULTIPLE_VEH se encontraron múltiples vehículos con el externalId especificado

Actualizar Parámetros de Conductores (en bloque)

Actualiza los parámetros de múltiples conductores para las fechas especificadas. Cualquier ruta existente para los conductores y fechas especificados será desprogramada.

Los siguientes parámetros para fechas particulares se pueden cambiar:

Solicitud HTTP

POST https://api.optimoroute.com/v1/update_drivers_parameters

reqbody.json es un archivo local que contiene los datos JSON que se van a publicar. Asegúrate de reemplazar AUTH_KEY con tu clave de API.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/update_drivers_parameters?key=AUTH_KEY'

Parámetros

Ejemplo de cuerpo de solicitud:

{
  "updates": [
    {
      "driver": {
        "externalId": "001"
      },
      "date": "2022-02-15",
      "workTime": {
        "from": "08:15",
        "to": "16:15"
      },
      "vehicleCapacity1": 100,
      "startLocation": {
        "type": "custom",
        "latitude": 45.805945,
        "longitude": 16.237825
      },
      "endLocation": {
        "type": "startLocation"
      }
    },
    {
      "driver": {
        "serial": "S001"
      },
      "date": "2022-02-16",
      "workTime": {
        "from": "09:00",
        "to:": "17:00"
      },
      "assignedVehicle": {
        "registration": "VEH001"
      },
      "endLocation": {
        "type": "employeeDefault"
      }
    }
  ]
}
Propiedad Tipo / Predeterminado Descripción
updates
obligatorio
lista de objetos de parámetros de conductor
-
Lista de uno o más objetos de parámetros de conductor para actualizar en el sistema. Se pueden especificar como máximo 500 objetos de parámetros de conductor.

Objeto DriverParameters

Propiedad Tipo / Predeterminado Descripción
driver
obligatorio
objeto
-
Un objeto con propiedades de cadena serial o externalId que identifica de manera única al Conductor. Ejemplo: {"serial": "102"} o {"externalId": "444"}.
date
obligatorio
fecha
-
Fecha a ser planificada.
Formato YYYY-MM-DD, por ejemplo 2013-12-20.
enabled
opcional
booleano
sin cambios
Habilitar o deshabilitar el conductor para la fecha especificada.
workTime
opcional
Objeto WorkTime
sin cambios
Hora de inicio/fin de trabajo del conductor para la fecha especificada.
assignedVehicle
opcional
cadena o objeto
sin cambios
El identificador externo como una cadena o un objeto con propiedades de cadena registration o externalId que identifica de manera única el Vehículo a ser asignado al conductor para la fecha especificada. Esto también actualizará los parámetros de capacidad de carga del vehículo (a menos que sean reemplazados con configuraciones de vehicleCapacityX). Ejemplo: V103 o {"registration": "444"} o {"externalId": "V103"}.
vehicleCapacity1
opcional
entero
sin cambios
La nueva capacidad de carga del vehículo #1 para la fecha especificada.
vehicleCapacity2
opcional
entero
sin cambios
La nueva capacidad de carga del vehículo #2 para la fecha especificada.
vehicleCapacity3
opcional
entero
sin cambios
La nueva capacidad de carga del vehículo #3 para la fecha especificada.
vehicleCapacity4
opcional
entero
sin cambios
La nueva capacidad de carga del vehículo #4 para la fecha especificada.
startLocation
opcional
Objeto LocationType
sin cambios
Ubicación GPS de inicio del conductor (esta ubicación se usará para futuras optimizaciones para la fecha especificada). No se puede usar el tipo de ubicación startLocation.
endLocation
opcional
Objeto LocationType
sin cambios
Ubicación GPS de fin del conductor (esta ubicación se usará para futuras optimizaciones para la fecha especificada).

Cuando locationType es custom y no hay una ubicación con la misma latitude, longitude y address, se creará una nueva ubicación y será visible en la administración de ubicaciones. El nombre de la ubicación será el mismo que la dirección si está definida, de lo contrario, el nombre se genera a partir de la latitud y la longitud.

Objeto WorkTime

Propiedad Tipo / Predeterminado Descripción
from
obligatorio
hora (cadena)
-
Hora de inicio de trabajo del conductor.
Formato de reloj de 24 horas (militar), por ejemplo: 08:00.
Los valores válidos van de 00:00 a 23:59.
to
obligatorio
hora (cadena)
-
Hora de fin de trabajo del conductor.
Formato de reloj de 24 horas (militar), por ejemplo: 08:00. Los valores válidos van de 00:00 a 23:59.

Objeto LocationType

Propiedad Tipo / Predeterminado Descripción
type
obligatorio
enumeración de cadena custom – se usarán la latitud, la longitud y la dirección de la ubicación.

employeeDefault – se usará la ubicación predeterminada del empleado.

startLocation – se usará la ubicación de inicio del empleado.
address
opcional
cadena
-
Dirección de la ubicación que se mostrará en los informes, por ejemplo 393 Hanover St, Boston, MA 02113, US.
latitude
opcional
decimal
-
Latitud de la ubicación.
longitude
opcional
decimal
-
Longitud de la ubicación.

La propiedad type es obligatoria. Cuando type se especifica como create, las propiedades obligatorias son latitude y longitude, de lo contrario, solo se debe definir type.

Respuesta

Ejemplo de respuesta:

{
  "updates": [
    {
      "success": true,
      "driver": {
        "externalId": "005"
      },
      "date": "2022-02-15"
    },
    {
      "success": false,
      "driver": {
        "serial": "S002"
      },
      "date": "2022-02-16",
      "code": "ERR_LOC_NOT_VALID",
      "message": "La ubicación no es válida.",
    },
    {
      "success": false,
      "driver": {
        "externalId": "003"
      },
      "date": "2022-02-17",
      "code": "ERR_DRIVER_NOT_FOUND",
      "message": "No se pudo encontrar un conductor con el id correspondiente",
    },
    {
      "success": false,
      "driver": {
        "externalId": "010"
      },
      "date": "2022-02-18",
      "code": "ERR_MULTIPLE_DRV",
      "message": "Se encontraron varios conductores con el id externo o número de serie correspondiente.",
    }
  ],
  "success": true
}
Propiedad Tipo / Predeterminado Descripción
success
obligatorio
booleano
-
true si al menos una operación fue exitosa, false si todas fallaron
updates
lista de objetos de respuesta de conductor
-
Cada objeto de conductor en la lista corresponde al respectivo conductor en la solicitud. Consultar la sección Objeto de Respuesta del Conductor para más información.

Objeto de Respuesta del Conductor

Propiedad Tipo / Predeterminado Descripción
success
obligatorio
booleano
-
true si la operación tuvo éxito, false si hubo un error.
driver
opcional
objeto
-
Identificador del conductor respectivo como un objeto con propiedades de cadena serial o externalId.
date
opcional
fecha
-
Fecha asociada con el conductor respectivo.
code
opcional
cadena
-
Un código de error por pedido (no establecido si la operación tuvo éxito).
message
opcional
cadena
-
Una descripción del error o una advertencia (no establecida si la operación tuvo éxito).

Códigos de Error y Advertencia

Los siguientes códigos de error son aplicables al método Actualizar Parámetros de Conductores:

Código de Error Descripción
ERR_DRIVER_NOT_FOUND no se encontró el conductor con el externalId o serial especificado
ERR_MULTIPLE_DRV se encontraron múltiples conductores con el externalId o serial especificado
ERR_VEH_NOT_FOUND no se encontró el vehículo con el externalId o serial especificado
ERR_MULTIPLE_VEH se encontraron múltiples vehículos con el externalId o serial especificado
ERR_LOC_NOT_VALID se encontró el tipo de ubicación custom sin latitud y longitud

Obtener Eventos Móviles

Recupera eventos móviles como success, on_duty, failed, … para el plan actualmente activo (es decir, el último plan que se envió a los conductores).

Cada solicitud de get_events devuelve hasta 500 eventos que ocurrieron después de la etiqueta especificada. El resultado contendrá una nueva etiqueta que podrás usar en la siguiente solicitud de get_events para omitir los eventos ya recibidos.

Solicitud HTTP

GET https://api.optimoroute.com/v1/get_events

Asegúrate de reemplazar AUTH_KEY con tu clave API.

curl 'https://api.optimoroute.com/v1/get_events?key=AUTH_KEY&after_tag='

Parámetros

Propiedad Tipo / Predeterminado Descripción
after_tag
opcional
string
-
Especifica el after_tag para recuperar solo los eventos que ocurrieron desde una llamada específica anterior a get_events.
En este caso, el after_tag debe contener la etiqueta devuelta en la llamada anterior.
Mira el ejemplo abajo.

Respuesta

Propiedad Tipo / Predeterminado Descripción
success
obligatorio
boolean
-
true a menos que haya ocurrido un error.
events
opcional
lista de objetos de eventos
[]
Una lista de objetos de eventos en el orden en que llegaron desde las aplicaciones móviles de los conductores.
tag
opcional
string
-
La etiqueta marca el momento del último evento recibido en esta respuesta. Úsala para especificar el parámetro de consulta after_tag en la próxima solicitud de get_events.
remainingEvents
opcional
integer
sin cambios
El número de eventos que ocurrieron pero no fueron obtenidos en esta respuesta (en cada respuesta se devuelven como máximo 500 eventos).

Objeto de Evento

Propiedad Tipo Descripción
event
obligatorio
string Tipo de evento. Actualmente uno de los siguientes:
on_duty – el conductor se puso en servicio
off_duty – el conductor se puso fuera de servicio
start_service - el conductor comenzó el servicio
success – el pedido especificado se completó con éxito
failed – el conductor no pudo completar el pedido
rejected – el conductor rechazó el pedido
start_route – el conductor comenzó la ruta
end_route – el conductor terminó la ruta
start_time_changed – el conductor cambió la hora de inicio planificada
unixTimestamp
obligatorio
integer El momento en el que ocurrió el evento.
Número de segundos transcurridos desde el 1 de enero de 1970 a las 00:00 UTC.
utcTime
obligatorio
fecha ISO 8601 (string) La fecha y hora UTC en la que ocurrió el evento especificado.
localTime
obligatorio
fecha ISO 8601 (string) La hora local en la ubicación del pedido en la que ocurrió el evento especificado.
driverName
opcional
string El nombre del conductor.
Se enviará para eventos relacionados con un conductor específico.
driverSerial
opcional
string El número de serie del conductor.
No se enviará si está vacío o si el evento no está relacionado con un conductor específico.
driverExternalId
opcional
string El identificador externo del conductor.
No se enviará si está vacío o si el evento no está relacionado con un conductor específico.
orderNo
opcional
string El identificador del pedido afectado.
No se enviará para algunos eventos como on_duty.
orderId
opcional
string
-
El identificador único de solo lectura del pedido afectado, asignado por OptimoRoute.
No se enviará para algunos eventos como on_duty.
plannedStartTime
opcional
Objeto de Tiempo La hora en que el conductor planea iniciar la ruta.
Se incluirá solo con el evento start_time_changed.

Los campos de evento devueltos unixTimestamp, utcTime y localTime se refieren al mismo momento en que ocurrió el evento, por lo que puedes usar el que sea más conveniente.

Por favor, ten en cuenta que algunos dispositivos móviles podrían estar desconectados temporalmente y sincronizarán sus eventos solo después de reconectarse, por lo que los eventos que recibirás podrían llegar fuera de orden cronológico. Por ejemplo, el primer conductor podría completar con éxito el pedido 001 a las 9:00 AM, pero podría estar desconectado hasta las 09:15 AM. El segundo conductor podría finalizar el pedido 002 a las 9:10 AM, pero podría estar en línea todo el tiempo. El servidor recibirá primero el evento para el pedido 002 y solo entonces el evento para el pedido 001.

Ejemplos

En la primera solicitud no especificaremos el parámetro after_tag (lo dejaremos vacío):

curl 'https://api.optimoroute.com/v1/get_events?key=AUTH_KEY&after_tag='

Respuesta:

{
  "remainingEvents": 0,
  "tag": "abcd1234xyz",
  "events": [
    {
      "unixTimestamp": 1516294800,
      "utcTime": "2018-01-18T17:00:00",
      "localTime": "2018-01-18T09:00:00",
      "driverName": "Charlie",
      "driverSerial": "0011",
      "event": "on_duty",
    },
    {
      "unixTimestamp": 1516296030,
      "event": "success",
      "utcTime": "2018-01-18T17:20:30",
      "localTime": "2018-01-18T09:20:30",
      "driverName": "Charlie",
      "driverSerial": "0011",
      "orderNo": "ORD232",
      "orderId": "f7afe58fcddfcbf9f42620c79ebad7ff"
    }
  ],
  "success": true
}

Reintentaremos la consulta en 10 segundos, pero esta vez utilizaremos la etiqueta que recibimos en el último resultado como nuestro parámetro after_tag:

curl 'https://api.optimoroute.com/v1/get_events?key=AUTH_KEY&after_tag=abcd1234xyz'

Respuesta:

{
  "remainingEvents": 0,
  "tag": "abcd1234xyz",
  "events": [],
  "success": true
}

No hubo nuevos eventos en este tiempo. Reintentaremos la consulta en 10 segundos:

curl 'https://api.optimoroute.com/v1/get_events?key=AUTH_KEY&after_tag=abcd1234xyz'

Respuesta:

{
  "remainingEvents": 0,
  "tag": "qwe9876541213",
  "events": [
    {
      "unixTimestamp": 1516298030,
      "event": "success",
      "utcTime": "2018-01-18T17:53:50",
      "localTime": "2018-01-18T09:53:50",
      "driverName": "Charlie",
      "driverSerial": "0011",
      "orderNo": "ORD771",
      "id": "04e7b09e993e8488024f46aaf9d8c72d"
    }
  ],
  "success": true
}

Obtener Finalización de Pedido

Recupera los detalles de finalización de uno o más pedidos una vez que se han completado. Para actualizaciones de estado del pedido en tiempo real, utilice el punto de acceso de obtener eventos móviles.

Solicitud HTTP

POST https://api.optimoroute.com/v1/get_completion_details

reqbody.json es un archivo local que contiene los datos JSON que se publicarán. Asegúrese de reemplazar AUTH_KEY con su clave API.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/get_completion_details?key=AUTH_KEY'

Parámetros

Ejemplo de cuerpo de solicitud POST:

{
  "orders": [
    {
      "orderNo": "ORD001"
    },
    {
      "orderNo": "ORD99"
    },
    {
      "orderNo": "ORD55"
    },
    {
      "orderNo": "XXXYZ"
    },
    {
      "id": "84e5e94d341dc637ff77b56ea96cb8e3",
    }
  ]
}
Propiedad Tipo / Predeterminado Descripción
orders
obligatorio
lista de objetos de pedido
-
Lista de objetos de pedido cuyos detalles de finalización se recuperarán. Cada objeto de pedido puede contener cualquiera de:
  • orderNo: el identificador especificado por el usuario de un pedido
  • id: el identificador único del pedido, asignado por OptimoRoute
Se pueden especificar como máximo 500 pedidos.



Para mayor flexibilidad, la llamada a get_completion_details también se puede realizar como una solicitud HTTP GET:

Ejemplo de solicitud GET:

curl 'https://api.optimoroute.com/v1/get_completion_details?key=AUTH_KEY&orderNo=ORD001&orderNo=ORD99&orderNo=ORD55&orderNo=XXXYZ'
Propiedad Tipo / Predeterminado Descripción
orderNo
obligatorio
cadena de texto
-
El identificador especificado por el usuario de un pedido; se puede repetir para obtener los detalles de finalización de múltiples pedidos.

Respuesta

Respuesta:

{
  "orders": [
    {
      "success": true,
      "orderNo": "ORD001",
      "data": {
        "status": "failed",
        "startTime": {
          "unixTimestamp": 1604267055,
          "utcTime": "2020-11-01T21:44:15",
          "localTime": "2020-11-01T16:44:15"
        },
        "endTime": {
          "unixTimestamp": 1604267305,
          "utcTime": "2020-11-01T21:48:25",
          "localTime": "2020-11-01T16:48:25"
        },
        "form": {
          "note": "Customer was not available, waited for 5 minutes, nobody answered the door"
        },
        "tracking_url": "https://order.is/Ka231Xpp"
      }
    },
    {
      "success": true,
      "orderNo": "ORD99",
      "data": {
        "status": "success",
        "startTime": {
           "unixTimestamp": 1604264327,
           "utcTime": "2020-11-01T20:58:47",
           "localTime": "2020-11-01T15:58:47"
        },
        "endTime": {
           "unixTimestamp": 1604264397,
           "utcTime": "2020-11-01T20:59:57",
           "localTime": "2020-11-01T15:59:57"
        },
        "form": {
          "signature": {
            "type": "image/png",
            "url": "https://optimoroute-vixldutrtzrnkmcpgateah.s3-accelerate.amazonaws.com/1fA-LEwk/yV8921_C5DA/0JCKDRJDSah-4N/fb5f0f06a08243f4aba05430664ddc19.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Credential=AKIAI6CIXSXBBNSDQZYN%2F20201101%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Date=20201101T185647Z&X-Amz-Signature=6281e5e133e517beb3b041224b87d473122f1626ab371bf1a523dff0ddad642b"
          },
          "barcode": [
            {
              "barcode": "123456",
              "scanInfo": {
                "status": "success",
                "scanned": "123456"
              }
            },
            {
              "barcode": "345678",
              "scanInfo": {
                "images": [
                  {
                    "type": "image/jpeg",
                    "url": "https://..."
                  }
                ],
                "status": "unscannable"
              }
            }
          ],
          "barcode_collections": [
            {
              "barcode": null,
              "scanInfo": {
                "type": "code-128",
                "status": "added",
                "scanned": "000123"
              }
            }
          ]
        }
      }
    },
    {
      "success": true,
      "orderNo": "ORD55",
      "data": {
        "status": "scheduled"
      }
    },
    {
      "success": false,
      "orderNo": "XXXYZ",
      "message": "The order with the matching orderNo was not found.",
      "code": "ERR_ORD_NOT_FOUND"
    },
    {
      "success": true,
      "id": "84e5e94d341dc637ff77b56ea96cb8e3",
      "data": {
        "status": "success",
        "startTime": {
          "unixTimestamp": 1661438862,
          "utcTime": "2022-08-25T14:47:42",
          "localTime": "2022-08-25T16:47:42"
        },
        "endTime": {
          "unixTimestamp": 1661438878,
          "utcTime": "2022-08-25T14:47:58",
          "localTime": "2022-08-25T16:47:58"
        },
        "tracking_url": "https://order.is/kzrmzcja"
      }
    }
  ],
  "success": true
}
Propiedad Tipo / Predeterminado Descripción
success
obligatorio
booleano
-
true si se recuperaron los detalles de finalización de al menos un pedido, false si no se recuperó ningún pedido.
orders
opcional
lista de objetos de respuesta de finalización
[]
Una lista de objetos que contienen detalles de finalización del pedido, uno para cada pedido solicitado.

Objeto de Respuesta de Finalización

Propiedad Tipo / Predeterminado Descripción
orderNo
opcional
cadena de texto
-
El identificador del pedido. Solo presente si se usó orderNo en la solicitud.
id
opcional
cadena de texto
-
El identificador único del pedido, asignado por OptimoRoute. Solo presente si se usó id en la solicitud.
success
obligatorio
booleano
-
true si la operación fue exitosa, false si hubo un error.
code
opcional
cadena de texto
-
Un código de error o un código de advertencia (no establecido si la operación fue exitosa).
message
opcional
cadena de texto
-
Una descripción de error o una descripción de advertencia (no establecido si la operación fue exitosa).
data
opcional
objeto
{}
Objeto que contiene el estado de finalización del pedido y metadatos. Consulte los campos de Detalles de Finalización para posibles claves.

Campos de Detalles de Finalización

El objeto de Detalles de Finalización devuelto contendrá los campos que se describen a continuación, dependiendo de si el pedido se ha completado o no, cómo se configura la recopilación de Comprobante de entrega y qué se ha llenado. El objeto de Detalles de Finalización devuelto también puede contener campos adicionales aún no descritos aquí.

Propiedad Tipo / Predeterminado Descripción
status
obligatorio
cadena de texto
-
Estado del pedido, vea los valores posibles: Valores del estado del pedido
startTime
opcional
Objeto de tiempo
-
Hora en que se inició el servicio de pedido.
Solo presente para pedidos con estado servicing, success o failed.
endTime
opcional
Objeto de tiempo
-
Hora en que se completó el servicio de pedido (marcado con estado success o failed).
Solo presente para pedidos con estado success o failed.
form
opcional
Objeto de datos de formulario Contiene los valores llenados desde la aplicación móvil al completar el pedido.
Solo presente si se configura Comprobante de entrega.
tracking_url
opcional
cadena de texto Un enlace a la página de Seguimiento de Pedidos en Tiempo Real del pedido. Solo presente si al pedido se le ha asignado un número de seguimiento. El número de seguimiento se asigna cuando los planes se envían al conductor o se han enviado las notificaciones al cliente. El requisito previo es que el Seguimiento del Pedido esté habilitado.

Valores del Estado del Pedido

Valor Descripción
unscheduled El pedido no ha sido programado
scheduled El pedido aún no ha comenzado
on_route El conductor está en camino a la ubicación del pedido
servicing El pedido se está atendiendo actualmente
success El pedido se completó con éxito
failed El conductor no pudo completar el pedido
rejected El pedido fue rechazado por el conductor
cancelled El pedido fue cancelado por el cliente

Objeto de tiempo

Propiedad Tipo Descripción
unixTimestamp
obligatorio
entero Número de segundos transcurridos desde las 00:00 UTC del 1 de enero de 1970.
utcTime
obligatorio
Fecha ISO 8601 (cadena de texto) La fecha y hora UTC
localTime
obligatorio
Fecha ISO 8601 (cadena de texto) La hora local en el lugar del pedido.

Los campos unixTimestamp, utcTime y localTime se refieren al mismo momento, por lo que puede usar el que sea más conveniente.

Objeto de datos de formulario

Todos los campos en los datos del formulario son opcionales, y el objeto puede contener campos adicionales no listados aquí.

Propiedad Tipo Descripción
note
opcional
cadena de texto El texto de la nota incluida al completar el pedido.
Solo presente si está configurado como parte de Comprobante de entrega y se ha rellenado una nota.
signature
opcional
Objeto Adjunto de Imagen El objeto describe el archivo de imagen de firma adjunto
Solo presente si está configurado como parte de Comprobante de entrega y se ha rellenado una firma.
images
opcional
lista de objetos Adjunto de Imagen El objeto enumera las imágenes adjuntas
Solo presentes si están configuradas como parte de Comprobante de entrega y se han tomado imágenes.
barcode
opcional
lista de objetos Escaneo de código de barras El objeto describe los detalles de finalización del código de barras adjunto
Solo presente si un código de barras previamente adjunto a un pedido fue escaneado.
barcode_collections
opcional
lista de objetos Escaneo de código de barras El objeto describe los códigos de barras recogidos con el pedido
Solo presente si está configurado como parte del flujo de trabajo de la Aplicación móvil y se ha escaneado un código de barras no planificado durante una recogida con un pedido.

Objeto Adjunto de Imagen

Propiedad Tipo Descripción
type
obligatorio
cadena de texto El tipo MIME de la imagen adjunta, típicamente image/png o image/jpeg
url
obligatorio
cadena de texto La URL en la que se puede descargar el archivo de imagen. La URL incluirá tokens de autenticación temporales y será válida por al menos 5 días, pero no indefinidamente.

Objeto de Escaneo de Código de Barras

Propiedad Tipo Descripción
barcode cadena de texto El código de barras adjunto al pedido. Puede estar vacío si el código de barras se agrega en lugar de escanear el código de barras previamente adjunto (por ejemplo, recogida de artículos durante una Entrega)
scanInfo Objeto Información del Código de Barras Objeto que describe el estado del escaneo del código de barras e información adicional

Objeto de Información del Código de Barras

Propiedad Tipo Descripción
status
obligatorio
Estado del Código de Barras Describe el estado de un escaneo de código de barras
scanned
opcional
cadena de texto Código de barras que realmente se escaneó. Puede diferir del código de barras esperado según el estado.
images
opcional
lista de objetos Adjunto de Imagen Imágenes que reemplazan al código de barras escaneado cuando el código de barras mismo no es escaneable. Puede estar presente con el estado unscannable
type
opcional
cadena de texto El tipo del código de barras escaneado si se pudo inferir en el momento del escaneo.
Los tipos admitidos incluyen: code-128, code-39, code-93, codabar, ean-13, ean-8, itf, upc-e, upc-a, qr, pdf-417, aztec, data-matrix

Estado del Código de Barras

Código de estado Descripción
success el código de barras correcto fue escaneado, el valor coincide con el adjunto al pedido
unscannable el código de barras no era escaneable. Puede tener imágenes adjuntas dependiendo de la configuración
added un código de barras no planificado fue escaneado y se agregó su código de barras
replaced el código de barras fue reemplazado en el momento de la entrega. La propiedad scanned muestra el valor nuevo
missing el artículo no estaba disponible durante la entrega

Códigos de Error y Advertencia

En caso de que success sea falso, data no se enviará y el campo code contendrá uno de los siguientes códigos de error por pedido:

Código de error Descripción
ERR_ORD_NOT_FOUND el pedido con el orderNo correspondiente no fue encontrado
ERR_MULTIPLE_ORD_FOUND hay múltiples pedidos que coinciden con el orderNo

Actualizar Compleción de Pedidos

Actualizar detalles de finalización para uno o más pedidos.

Solicitud HTTP

POST https://api.optimoroute.com/v1/update_completion_details

reqbody.json es un archivo local que contiene los datos JSON que se publicarán. Asegúrate de reemplazar AUTH_KEY con tu clave API.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/update_completion_details?key=AUTH_KEY'

Parámetros

Ejemplo de cuerpo de solicitud POST:

{
  "updates": [
    {
      "orderNo": "ORD001",
      "data": {
        "status": "failed",
        "startTime": {
           "unixTimestamp": 1604264327,
        },
        "endTime": {
           "unixTimestamp": 1604264397,
        },
      }
    },
    {
      "orderNo": "ORD99",
      "data": {
        "status": "success",
         "startTime": {
          "utcTime": "2020-11-01T21:44:15",
        },
        "endTime": {
          "utcTime": "2020-11-01T21:48:25",
        },
      }
    },
    {
      "orderNo": "ORD55",
      "data": {
        "status": "scheduled"
      }
    },
    {
      "orderNo": "ORD56",
      "data": {
        "status": "servicing",
        "startTime": {
           "unixTimestamp": 1692186190,
        },
      }
    },
    {
      "orderNo": "XXXYZ",
      {
        "data": {
          "status": "cancelled"
        }
      }
    },
    {
      "id": "84e5e94d341dc637ff77b56ea96cb8e3",
      {
          "data": {
            "status": "on_route"
          }
      }
    }
  ],
}

Propiedad Tipo / Predeterminado Descripción
updates
obligatorio
lista de objetos de actualización de detalles de finalización
[]
Una lista de detalles de finalización de pedidos para actualizar. Se pueden especificar un máximo de 500 objetos de detalles de finalización.

Objeto de Actualización de Detalles de Finalización

Propiedad Tipo / Predeterminado Descripción
orderNo
opcional
cadena
-
El identificador del pedido. Obligatorio si no se especifica id.
id
opcional
cadena
-
El identificador único del pedido, asignado por OptimoRoute. Obligatorio si no se especificó orderNo.
data
opcional
objeto
{}
Objeto que contiene el estado de finalización del pedido y los metadatos. Ver campos de Actualización de Detalles de Finalización para posibles claves.

Campos de Actualización de Detalles de Finalización

Propiedad Tipo / Predeterminado Descripción
status
obligatorio
cadena
-
Estado del pedido, ver posibles valores: Valores de estado de pedido
startTime
opcional
Objeto de actualización de tiempo
-
Hora en que se inició el servicio del pedido.
Solo presente para pedidos con estado servicing, success o failed.
endTime
opcional
Objeto de actualización de tiempo
-
Hora en que se completó el servicio del pedido (marcado con estado success o failed).
Solo presente para pedidos con estado success o failed.

Objeto de Actualización de Tiempo

Propiedad Tipo Descripción
unixTimestamp
opcional
entero Número de segundos transcurridos desde 00:00 UTC del 1 de enero de 1970.
utcTime
opcional
fecha ISO 8601 (cadena) La fecha y hora UTC. Ignorado si se especifica unixTimestamp.
localTime
opcional
fecha ISO 8601 (cadena) La hora local en la ubicación del pedido. Ignorado si se especifica unixTimestamp o utcTime.

Al menos uno de unixTimestamp, utcTime, localTime debe ser especificado.

Respuesta

Respuesta:

{
  "orders": [
    {
      "success": true,
      "orderNo": "ORD001",
      "data": {
        "status": "failed",
        "startTime": {
          "unixTimestamp": 1604264327,
          "utcTime": "2020-11-01T20:58:47",
          "localTime": "2020-11-01T15:58:47"
        },
        "endTime": {
          "unixTimestamp": 1604264397,
          "utcTime": "2020-11-01T20:59:57",
          "localTime": "2020-11-01T15:59:57"
        },
      }
    },
    {
      "success": true,
      "orderNo": "ORD99",
      "data": {
        "status": "success",
        "startTime": {
          "unixTimestamp": 1604267055,
          "utcTime": "2020-11-01T21:44:15",
          "localTime": "2020-11-01T16:44:15"
        },
        "endTime": {
          "unixTimestamp": 1604267305,
          "utcTime": "2020-11-01T21:48:25",
          "localTime": "2020-11-01T16:48:25"
        },
      }
    },
    {
      "success": true,
      "orderNo": "ORD55",
      "data": {
        "status": "scheduled"
      }
    },
    {
      "success": true,
      "orderNo": "ORD56",
      "data": {
        "status": "servicing",
        "startTime": {
          "unixTimestamp": 1692186190,
          "utcTime": "2023-08-16T11:43:10",
          "localTime": "2023-08-16T06:43:10"
        },
      }
    },
    {
      "success": false,
      "orderNo": "XXXYZ",
      "message": "The order with the matching orderNo was not found.",
      "code": "ERR_ORD_NOT_FOUND"
    },
    {
      "success": true,
      "id": "84e5e94d341dc637ff77b56ea96cb8e3",
      "data": {
        "status": "on_route",
      }
    }
  ],
  "success": true
}
Propiedad Tipo / Predeterminado Descripción
success
obligatorio
booleano
-
true si se actualizaron los detalles de finalización de al menos un pedido, false si no se actualizaron los detalles de finalización de ningún pedido.
updates
opcional
lista de objetos de respuesta de finalización
[]
Una lista de objetos que contienen los detalles de finalización de pedidos, uno por cada actualización solicitada. Objeto de Respuesta de Finalización

Actualizar Posiciones de Conductores (en lote)

Actualiza las posiciones de varios conductores en momentos de tiempo dados.

Solicitud HTTP

POST https://api.optimoroute.com/v1/update_drivers_positions

reqbody.json es un archivo local que contiene los datos JSON que se van a enviar. Asegúrate de reemplazar AUTH_KEY con tu clave de API.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/update_drivers_positions?key=AUTH_KEY'

Parámetros

Ejemplo del cuerpo de la solicitud:

{
  "updates": [
    {
      "driver": {
        "externalId": "001"
      },
      "positions": [
        {
          "timestamp": 1692186190,
          "latitude": 45.805945,
          "longitude": 16.237825,
          "speed": 0,
          "accuracy": 10.1
        },
        {
          "timestamp": 1692186194,
          "latitude": 45.805945,
          "longitude": 16.237825,
          "speed": 0,
          "accuracy": 10.1
        }
      ]
    },
    {
      "driver": {
        "serial": "S002"
      },
      "positions": [
        {
          "timestamp": 1692186190,
          "latitude": 45.805945,
          "longitude": 16.237825,
          "speed": 20.3,
          "accuracy": 10.1,
          "heading": 34.2
        },
        {
          "timestamp": 1692186194,
          "latitude": 45.805923,
          "longitude": 16.237844,
          "speed": 22.1,
          "accuracy": 12.4,
          "heading": 34.2
        }
      ]
    },
    {
      "driver": {
        "externalId": "S003"
      },
      "positions": [
        {
          "timestamp": 1692186190,
          "latitude": 45.805945,
          "longitude": 16.237825
        }
      ]
    },
    {
      "driver": {
        "serial": "S004"
      },
      "positions": [
        {
          "timestamp": 1692186190,
          "latitude": 45.805945,
          "longitude": 16.237825
        }
      ]
    },
    {
      "driver": {
        "serial": "S004"
      },
      "positions": [
        {
          "timestamp": 1692186190,
          "latitude": 45.805945,
          "longitude": 16.237825
        }
      ]
    }
  ]
}
Propiedad Tipo / Predeterminado Descripción
updates
obligatorio
lista de objetos de Posiciones de Conductores
-
Lista de objetos, cada uno especifica posiciones para un conductor. A lo sumo se puede especificar 1 objeto por conductor.

Objeto de Posiciones de Conductor

Propiedad Tipo / Predeterminado Descripción
driver
obligatorio
objeto
-
Un objeto con propiedades de cadena serial o externalId que identifica de manera única al Conductor. Ejemplo: {"serial": "102"} o {"externalId": "444"}.
positions
obligatorio
lista de objetos de Posición
-
lista de posiciones a través del tiempo. A lo sumo se pueden especificar 100 posiciones para un solo conductor.

Objeto de Posición

Propiedad Tipo / Predeterminado Descripción
timestamp
obligatorio
entero El momento en que ocurrió el evento.
Número de segundos transcurridos desde 00:00 UTC 1 de enero de 1970.
latitude
obligatorio
decimal
-
Latitud de la posición en grados.
longitude
obligatorio
decimal
-
Longitud de la posición en grados.
accuracy
opcional
decimal
-
Radio de incertidumbre para la ubicación en metros.
spped
opcional
decimal
-
Velocidad en metros por segundo.
heading
opcional
decimal
-
Dirección del viaje en grados, 0 indicando norte, 90 este, 180 sur, ...

Respuesta

Ejemplo de respuesta:

{
  "updates": [
     {
      "success": true,
      "driver": {
        "externalId": "001"
      },
    },
    {
      "success": false,
      "driver": {
        "serial": "S002"
      },
      "code": "ERR_MULTIPLE_DRV",
      "message": "Found multiple drivers with matching external id or serial number.",
    },
    {
      "success": false,
      "driver": {
        "externalId": "S003"
      },
      "code": "ERR_DRIVER_NOT_FOUND",
      "message": "Could not find a driver with the matching id",
    },
    {
      "success": false,
      "driver": {
        "serial": "S004"
      },
      "code": "ERR_MULTIPLE_DRV_POS",
      "message": "Multiple driver positions objects for a single driver",
    }, {
      "success": false,
      "driver": {
        "serial": "S004"
      },
      "code": "ERR_MULTIPLE_DRV_POS",
      "message": "Multiple driver positions objects for a single driver",
    }
  ],
  "success": true
}
Propiedad Tipo / Predeterminado Descripción
success
obligatorio
booleano
-
true si al menos una operación fue exitosa, false si todas fallaron.
updates
lista de Objetos de Respuesta de Conductor
-
Cada Objeto de Respuesta de Conductor en la lista corresponde al respectivo objeto de Posiciones de Conductor en la solicitud.

Objeto de Respuesta de Conductor

Propiedad Tipo / Predeterminado Descripción
success
obligatorio
booleano
-
true si la operación tuvo éxito, false si hubo un error.
driver
opcional
objeto
-
Identificador del conductor respectivo como un objeto con propiedades de cadena serial o externalId.
code
opcional
cadena
-
Un código de error específico del pedido (no se establece si la operación fue exitosa).
message
opcional
cadena
-
Una descripción del error o una advertencia (no se establece si la operación fue exitosa).

Códigos de Error y Advertencia

Los siguientes códigos de error son aplicables al método Actualizar Posiciones de Conductores:

Código de Error Descripción
ERR_DRIVER_NOT_FOUND el conductor con el externalId o serial especificado no fue encontrado
ERR_MULTIPLE_DRV se encontraron múltiples conductores con el externalId o serial especificado
ERR_MULTIPLE_DRV_POS se especificaron múltiples objetos de posiciones de conductores para un solo conductor

Buscar Pedidos

Recupera uno o más pedidos del sistema.

Solicitud HTTP

POST https://api.optimoroute.com/v1/search_orders

reqbody.json es un archivo local que contiene los datos JSON a enviar. Asegúrate de reemplazar AUTH_KEY con tu clave de API.

curl -d '@reqbody.json' 'https://api.optimoroute.com/v1/search_orders?key=AUTH_KEY'

Parámetros

Ejemplos de cuerpo de la solicitud:

{
  "dateRange": {
    "from": "2022-01-01",
    "to": "2022-01-03",
  },
  "includeOrderData": true,
  "orderStatus": ["failed", "rejected"]
}
{
  "orders": [
    {
      "orderNo": "10203"
    },
    {
      "orderNo": "10204"
    }
  ]
}
{
  "orders": [
    {
      "id": "72b85bf77fe53ebdc689c42ddaacad73"
    },
    {
      "id": "5a9247a50481860d44573f7d7f8799d5"
    }
  ],
  "includeScheduleInformation": true
}
Propiedad Tipo / Valor por defecto Descripción
orders lista de objetos de pedido
-
Lista de objetos de pedido a recuperar. Cada objeto de pedido puede contener cualquiera de:
  • orderNo: el identificador especificado por el usuario de un pedido
  • id: el identificador único del pedido, asignado por OptimoRoute
Pueden especificarse como máximo 500 pedidos.
dateRange objeto dateRange Un objeto con campos from y to, por ejemplo:
{"from": "2022-01-01", "to": "2022-01-03"}. El rango puede abarcar un máximo de 35 días, es decir, 5 semanas.
orderStatus
opcional
lista de cadenas
-
Lista de cadenas de estado de pedido, para opcionalmente filtrar los pedidos recuperados por estado.
Ver valores posibles: Valores de estado de pedido.
includeOrderData
opcional
booleano
false
Establece esto a true si necesitas obtener los datos del pedido para los pedidos encontrados.
includeScheduleInformation
opcional
booleano
false
Establece esto a true si necesitas obtener la información de programación del pedido.
after_tag
opcional
cadena
-
Especifica el after_tag para recuperar solo la página siguiente de resultados de una llamada anterior a este punto final.
En este caso, todos los parámetros deben repetirse con los mismos valores que la llamada anterior, y after_tag debe contener el valor devuelto en la llamada previa.

Se debe especificar al menos una de las propiedades orders o dateRange en la solicitud.

Respuesta

Ejemplo de respuesta con includeOrderData

{
  "success": true,
  "orders": [
    {
      "id": "cd013f61ad8155802ad4321f2b411f4f",
      "data": {
        "orderNo": "10205",
        "date": "2022-01-03",
        "type": "T",
        "priority": "M",
        "duration": 75,
        "notes": "",
        "email": "",
        "phone": "",
        "load1": 0,
        "load2": 0,
        "load3": 0,
        "load4": 0,
        "customField1": "Revision 5",
        "customField2": "184.5",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "id": "cd013f61ad8155802ad4321f2b411f4f",
        "assignedTo": null,
        "location": {
          "locationNo": "T1275",
          "locationName": "T1275",
          "address": "Moneta, VA 24121, United States",
          "latitude": 37.2636426,
          "longitude": -79.6105659,
          "notes": "",
          "valid": true,
          "checkInTime": 0
        },
        "skills": ["VA"],
        "vehicleFeatures": [],
        "timeWindows": [],
        "notificationPreference": "dont_notify",
        "allowedWeekdays": ["mon", "tue", "wed", "thu"],
        "allowedDates": {}
      }
    }
  ]
}

Ejemplo de respuesta con includeScheduleInformation; la presencia de after_tag después de solo 2 resultados es exagerada solo para ilustración.

{
  "success": true,
  "orders": [
    {
      "id": "72b85bf77fe53ebdc689c42ddaacad73",
      "scheduleInformation": {
        "driverExternalId": "",
        "driverSerial": "JQP",
        "driverName": "John Q P",
        "vehicleRegistration": null,
        "vehicleLabel": null,
        "stopNumber": 3,
        "scheduledAt": "10:03",
        "scheduledAtDt": "2022-01-02 10:03:44",
        "arrivalTimeDt": "2022-01-02 10:03:44",
        "travelTime": 2033,
        "distance": 32254
      }
    },
    {
      "id": "5a9247a50481860d44573f7d7f8799d5",
      "scheduleInformation": null
    },
  ],
  "after_tag": "gAAAAABjGMzYTPcM2QlRwp69tNXXU7asLhGUXJ0SfZZfieAbi37z73cmyfhaoSHWiT8sJX2HnvLjvDTrK3l9TySz0vfWEkuzx6OYOkS4Qc37smFa2Q0t7WE="
}
Propiedad Tipo / Valor por defecto Descripción
success
obligatorio
booleano
-
Esto será false si hubo un error y no se recuperaron pedidos
orders
obligatorio
lista de objetos de respuesta de pedido
-
Cada objeto en la lista representa un resultado de pedido encontrado en el sistema. Ver sección Objeto de Respuesta de Pedido para más información.
Se devolverán hasta 500 pedidos en una llamada. Usa after_tag para obtener las páginas restantes.
after_tag
opcional
cadena
-
Solo presente si hay más páginas de resultados para obtener. Para obtener la siguiente página de resultados, repite la llamada a este punto final con el parámetro after_tag y todos los demás parámetros con los mismos valores.

Objeto de Respuesta de Pedido

Propiedad Tipo / Valor por defecto Descripción
id
obligatorio
cadena
-
El identificador único del pedido, asignado por OptimoRoute.
data
opcional
Objeto de pedido
-
Los datos del pedido recuperados; solo presente si includeOrderData se estableció en true
scheduleInformation
opcional
Objeto de información de programación
-
La información de programación del pedido; solo presente si includeScheduleInformation se estableció en true. Esto será null si el pedido no está programado.