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:
- toda la solicitud puede fallar (por ejemplo, un error serio de validación o programación). La respuesta contendrá un código de error.
- la operación falló para algunos pedidos, pero tuvo éxito para otros. La respuesta contendrá una lista en la que algunos objetos tienen un código de error.
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 – BajaM – MediaH – AltaC – CríticaLos 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 smsPor 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:
|
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 tipoSelección única
dondeapple
es una clave de opción,quantity
es de tipoNúmero
con 0 lugares decimales,purity
es de tipoNúmero
con 2 lugares decimales einstructions
es de tipoTexto
):
{
"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:
locationNo
El número de ubicación de una ubicación ya existente en el sistema. Se utiliza una ubicación existente.
NOTA: eladdress
,latitude
+longitude
ylocationName
NO deben especificarse, de lo contrario, el sistema intentará geocodificar la ubicación nuevamente o crear una con una ubicación GPS definida.latitude
+longitude
+locationName
(conaddress
ylocationNo
opcionales)
La ubicación se define por la latitud y longitud.
El nombre de la ubicación se establecerá en el valor del campolocationName
.
La dirección de la ubicación se establecerá enaddress
si se estableceaddress
, de lo contrario se dejará en blanco.
El número de ubicación se establecerá enlocationNo
si se establece enlocationNo
, de lo contrario se dejará en blanco.address
(conlocationName
ylocationNo
opcionales)
El sistema intentará encontrar ubicaciones existentes con eladdress
especificado (ylocationName
si se especifica). Si no se encuentra una ubicación existente, la dirección de la ubicación se geocodificará basándose en la dirección proporcionada.
El nombre de la ubicación se establecerá en el campolocationName
si se proporcionalocationName
, de lo contrario se establecerá al valor del campo de dirección.
El número de ubicación se establecerá enlocationNo
si se establece enlocationNo
, de lo contrario se dejará en blanco.
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:
- si se da
id
, el pedido existente se actualizará con los valores proporcionados;- las propiedades que no se proporcionan en la solicitud conservarán sus valores existentes
- si
id
no se da, yorderNo
no se da o no se encuentra un pedido, se creará un nuevo pedido;- las propiedades
date
ylocation
son obligatorias - las propiedades
duration
ytype
usarán los valores predeterminados configurados en OptimoRoute - otras propiedades pueden omitirse, en cuyo caso se usarán los valores predeterminados listados en el Objeto Pedido
- las propiedades
- si
id
no se da, y se encuentra un pedido existente conorderNo
coincidente, el pedido existente se actualizará con los valores proporcionados;- las propiedades que no se proporcionan en la solicitud conservarán sus valores existentes
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:
|
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 |
booleanfalse |
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:
|
deleteMultiple opcional |
booleanofalse |
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 |
booleanofalse |
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 |
booleanfalse |
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 |
booleanfalse |
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 |
integer0 |
Carga de la ruta #1. |
load2 obligatorio |
integer0 |
Carga de la ruta #2. |
load3 obligatorio |
integer0 |
Carga de la ruta #3. |
load4 obligatorio |
integer0 |
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 |
stringOFF |
Configuraciones de balanceo de rutas. Valores permitidos:OFF – Sin balanceoON – Balancear rutasON_FORCE – Balancear rutas y usar todos los conductoresSin 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 |
stringWT |
Si el balanceo de rutas está activado, esto define el criterio para balancear las rutas. Valores permitidos: WT – Tiempo de trabajoNUM – Número de pedidos por conductor |
balancingFactor opcional |
decimal0.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 |
stringEMPTY |
Comenzar a planificar desde las rutas existentes o desde cero. Valores permitidos: EMPTY – Ignorar rutas existentes y comenzar desde ceroCURRENT – Comenzar a planificar con las rutas existentes |
lockType opcional |
stringNONE |
Aplicable si startWith está configurado a CURRENT .Valores permitidos: NONE – Permitir todos los cambios en las rutas existentesROUTES - Mantener las Rutas planificadas sin cambios y agregar nuevos Pedidos a las no utilizadasRESOURCES - Mantener a los Conductores/Vehículos para los Pedidos planificados e incluir nuevos Pedidos |
depotTrips opcional |
booleanofalse |
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 |
entero0 |
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 |
booleanofalse |
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:
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 |
booleanotrue |
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 - NuevoR - En ejecuciónC - Cancelado por el usuarioF - FinalizadoE - 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:
- Habilitar/deshabilitar conductor
- Hora de inicio del trabajo del conductor
- Hora de fin del trabajo del conductor
- Vehículo asignado
- Capacidad de carga del vehículo #1
- Capacidad de carga del vehículo #2
- Capacidad de carga del vehículo #3
- Capacidad de carga del vehículo #4
- Ubicación de inicio del conductor
- Ubicación de fin del conductor
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:
- Habilitar/deshabilitar conductor
- Hora de inicio del trabajo del conductor
- Hora de fin del trabajo del conductor
- Ubicación de inicio del conductor
- Ubicación de fin del conductor
- Vehículo asignado
- Capacidad de carga del vehículo #1
- Capacidad de carga del vehículo #2
- Capacidad de carga del vehículo #3
- Capacidad de carga del vehículo #4
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 serviciooff_duty – el conductor se puso fuera de serviciostart_service - el conductor comenzó el serviciosuccess – el pedido especificado se completó con éxitofailed – el conductor no pudo completar el pedidorejected – el conductor rechazó el pedidostart_route – el conductor comenzó la rutaend_route – el conductor terminó la rutastart_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:
|
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:
|
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 |
booleanofalse |
Establece esto a true si necesitas obtener los datos del pedido para los pedidos encontrados. |
includeScheduleInformation opcional |
booleanofalse |
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 deafter_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. |