NAV
shell

Introduction

Ce document est la référence officielle pour l'API de service web OptimoRoute (WS API).

Notre API de service web est basée sur HTTP

Les méthodes pour récupérer des données à partir de notre API de service web (WS) nécessitent une méthode de requête HTTP GET.

Les méthodes qui soumettent, modifient, ou détruisent des données nécessitent une méthode de requête POST.

Les méthodes de l'API renverront une erreur si vous ne faites pas votre requête avec la méthode HTTP correcte.

Nous utilisons JSON pour l'échange de données structurées

Notre API utilise le format JSON (JavaScript Object Notation).

Plus d'informations sur JSON et son fonctionnement peuvent être trouvées ici : http://json.org/ et ici : http://en.wikipedia.org/wiki/JSON.

Il existe de nombreuses bibliothèques prêtes à l'emploi pour convertir vers et depuis le format JSON, tant pour les langages de programmation populaires que pour les plus ésotériques.

SSL est requis

L'utilisation de SSL (https) est requise pour éviter de transmettre à la fois la clé d'authentification et des données potentiellement confidentielles en clair sur le web.

Nombre limité de requêtes simultanées

Le nombre maximum de requêtes API de service web simultanées pour un compte ou pour une adresse IP est limité à 5.

Codes d'erreur généraux

Les codes d'erreur suivants sont applicables à toutes les opérations API :

Code d'erreur Description
AUTH_KEY_MISSING la clé d'authentification est manquante
AUTH_KEY_UNKNOWN une clé d'authentification incorrecte a été fournie
MALFORMED_REQUEST quelque chose ne va pas avec l'entrée
ERR_MISSING_MAND_FIELD l'un des champs obligatoires est manquant
ERR_INVALID_PARAM_FORMAT l'un des champs spécifiés n'est pas dans un format valide
ERR_TOO_MANY_CONNECTIONS il y a trop de requêtes simultanées
ERR_INTERNAL une erreur interne du serveur s'est produite

Il y a aussi des codes d'erreur spécifiques décrits dans la section Codes d'erreur et d'avertissement de chaque méthode.

Codes d'erreur avec les opérations en masse

Pour les opérations en masse, il y a plusieurs modes d'échec. Par exemple, lors d'une opération en masse sur des commandes :

Prévoir des champs supplémentaires dans les messages de réponse

Des champs supplémentaires pourraient être ajoutés aux messages de réponse JSON à l'avenir, donc votre code client devrait ignorer les champs supplémentaires.  

Authentification

Le paramètre de clé d'authentification de l'API de service web OptimoRoute est requis pour toutes les requêtes API, en plus de tous les paramètres standards.

Pour activer l'API et générer la clé API, veuillez vous connecter à l'application web OptimoRoute. Dans la section Administration, sélectionnez Paramètres -> WS API et activez l'API. La clé API sera générée pour vous.

L'API de service web est également disponible pendant la période d'essai gratuit.

Objets de données

Certains points d'entrée de l'API partagent des définitions d'objets envoyés dans la requête et la réponse.

Objet Commande

Exemple d'objet Commande

{
  "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"
}
Propriété Type Description
id chaîne L'identifiant unique en lecture seule de la commande, attribué par OptimoRoute. Si cette propriété est envoyée dans les requêtes, elle sera utilisée pour trouver la commande à mettre à jour, supprimer ou récupérer, en priorité sur orderNo.
orderNo chaîne Un identifiant de commande spécifié par l'utilisateur, également affiché dans l'application web. Si id n'est pas utilisé dans les requêtes WS API, les commandes sont appariées par cet identifiant, et il peut être utilisé pour mettre à jour, supprimer ou récupérer des commandes.
relatedOrderNo chaîne ou null orderNo de la commande liée. Utilisé pour lier des ramassages et livraisons dans des situations où les marchandises sont transportées directement d'un emplacement client à un autre emplacement client.
Lors de la création de commandes, la relation doit être spécifiée uniquement pour la deuxième commande créée (la première commande doit déjà exister dans le système pour pouvoir être référencée).
La valeur par défaut est null, ce qui signifie que la commande n'est pas liée à un autre ramassage / livraison.
relatedId chaîne ou null id de la commande liée. Voir relatedOrderNo ci-dessus pour les détails des commandes liées.
date date (chaîne) Date de la commande.
format YYYY-MM-DD, par exemple 2013-12-20.
location objet location Lieu de livraison / service. Voir Objet Location.
type énumération de chaînes Type de commande : D (livraison), P (ramassage) ou T (tâche).
duration décimal Le temps en minutes requis pour décharger les marchandises ou effectuer une tâche à l'emplacement donné. Si non spécifié, les nouvelles commandes créées utiliseront la valeur par défaut configurée dans OptimoRoute.
timeWindows liste de fenêtres horaires Liste des fenêtres horaires pendant lesquelles la commande peut être réalisée.
Chaque fenêtre horaire est un objet avec les champs twFrom et twTo. Les deux heures sont au format 24 heures (militaire), dans l'intervalle de 00:00 à 23:59.
twFrom spécifie l'heure la plus précoce autorisée pour commencer le service (si le conducteur arrive trop tôt, il sera forcé d'attendre). twTo spécifie la date limite pour terminer le service.
Exemple :
[{"twFrom": "10:00", "twTo": "14:00"}].
La valeur par défaut est [], ce qui signifie aucune fenêtre horaire.
allowedWeekdays liste de chaînes Restriction sur les jours de la semaine où la commande peut être programmée :
sun, mon, tue, wed, thu, fri, sat.
Par exemple, si la commande peut être programmée le lundi ou le mardi, la valeur devrait être :
["mon", "tue"].
Par défaut, tous les jours de la semaine sont autorisés.
allowedDates objet daterange Restriction sur les dates où la commande peut être programmée.
L'intervalle de dates est spécifié sous forme d'objet avec les champs from et to, par exemple :
{"from": "2018-06-01", "to": "2018-07-01"}
La valeur par défaut est un objet vide {}, ce qui signifie pas de restriction.
allowedDateTimes liste de fenêtres temporelles Liste des fenêtres temporelles pendant lesquelles la commande peut être effectuée.
Chaque objet peut contenir les champs from et/ou to, qui sont des chaînes datetime, ou null. Les chaînes sont au format YYYY-MM-DDTHH:MM:SS, par exemple 2020-01-30T15:54:02. Le champ from définit le moment le plus précoce pour commencer le service, et to définit le moment le plus tardif pour commencer le service. Lorsqu'une seule extrémité de la restriction est donnée, l'autre est supposée être null, ce qui signifie qu'elle n'est pas limitée.
Exemple :
[{"from": "2019-12-26T00:00:00", "to": "2019-12-31T23:59:59"}].
La valeur par défaut est [], ce qui signifie pas de restriction.
assignedTo objet ou null Un objet avec des propriétés de chaîne serial ou externalId qui identifie de manière unique le conducteur auquel cette commande doit être attribuée. Exemple : {"serial": "102"} ou {"externalId": "444"}. Le fait de définir ce champ force cette commande à être exécutée par le conducteur spécifié. Une valeur null signifie aucune attribution, ce qui est la valeur par défaut.
priority chaîne Priorité de la commande, par défaut M. Les valeurs peuvent être :
L – Basse
M – Moyenne
H – Haute
C – Critique
Les ordres de priorité élevée sont planifiés plus tôt et ont moins de chances d'être laissés non planifiés si toutes les commandes ne peuvent être réalisées.
load1 décimal Les exigences de charge de la commande, c'est-à-dire combien d'unités de charge (nombre de boîtes, kilos, livres, litres etc.) doivent être livrées.
La signification de cette entrée dépend de la configuration fournie des contraintes de charge/capacité.
La valeur par défaut est 0.
load2 décimal Voir load1.
load2 décimal Voir load1.
load3 décimal Voir load1.
vehicleFeatures liste de chaînes Les caractéristiques du véhicule utilisées pour différencier certains Véhicules des autres. Les caractéristiques requises du véhicule sont définies comme une liste de codes de caractéristiques du véhicule. La valeur par défaut est une liste vide [].
skills liste de chaînes Les compétences du conducteur utilisées pour différencier certains Conducteurs des autres. Les compétences requises sont définies comme une liste de codes de compétences. La valeur par défaut est une liste vide [].
notes chaîne La note facultative qui accompagnera les instructions du conducteur. Les notes n'affectent pas le processus d'optimisation. Une chaîne libre.
customField1 chaîne Valeur qui sera enregistrée dans le champ personnalisé n°1, par défaut vide.
customField2 chaîne Valeur qui sera enregistrée dans le champ personnalisé n°2, par défaut vide.
customField3 chaîne Valeur qui sera enregistrée dans le champ personnalisé n°3, par défaut vide.
customField4 chaîne Valeur qui sera enregistrée dans le champ personnalisé n°4, par défaut vide.
customField5 chaîne Valeur qui sera enregistrée dans le champ personnalisé n°5, par défaut vide.
customFields objet customFields Un objet contenant des champs personnalisés. Voir Objet CustomFields.
email chaîne Email du client. Si activé, des notifications de commande peuvent être envoyées à cet email. Par défaut vide.
phone chaîne Numéro de téléphone du client. Par défaut vide.
notificationPreference énumération de chaînes Définit la méthode de livraison pour les notifications de suivi de commande pour cette commande. Les notifications ne seront envoyées que si ce compte a le suivi de commande configuré.
Valeurs autorisées :
dont_notify – ne pas envoyer de notifications
email – envoyer une notification à l'adresse email spécifiée dans le champ email
sms – envoyer un message texte au numéro spécifié dans le champ téléphone
both – envoyer à la fois des notifications par email et sms
La valeur par défaut est both.
barcode liste d'objets de codes-barres
optionnel
Liste des codes-barres attachés à la commande.
Chaque code-barres est un objet avec un champ barcode. La valeur est une chaîne arbitraire.
Exemple :
[{"barcode": "12345678"}].
S'il n'y a pas de codes-barres attachés à la commande, le résultat retournera un tableau vide. Présent seulement si la fonctionnalité Preuve de livraison est disponible.

Objet Location

Exemple d'objet Location avec coordonnées 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
}
Propriété Type par défaut Description
locationNo chaîne L'identifiant unique pour le lieu donné.
locationName chaîne Nom de la location.
address chaîne L'adresse complète incluant le pays, par exemple 393 Hanover St, Boston, MA 02113, US
latitude décimal Latitude de la location.
longitude décimal Longitude de la location.
valid booléen Propriété en lecture seule, utilisée uniquement dans les réponses. Si elle est trouvée dans une requête, elle sera ignorée. Retourne true lorsque la localisation est valide. Retourne false lorsque la localisation est invalide. Les localisations invalides sont celles qui n'ont pas de latitude et longitude connues (par exemple, elles ont été créées en spécifiant une adresse qui n'a pas pu être géocodée).
Par défaut, lors de la création de commandes et de locations, le système n'acceptera pas les adresses erronées ou incomplètes et générera une erreur. L'utilisation du drapeau storeInvalid (à partir des paramètres supplémentaires d'objet de localisation dans la demande de création de commande) empêche de générer une erreur et permet de stocker des localisations invalides et les commandes associées dans OptimoRoute. De cette façon, les adresses problématiques peuvent être corrigées dans OptimoRoute, cependant, les commandes avec des localisations invalides ne peuvent pas faire partie d'un plan jusqu'à ce que ces localisations soient corrigées.
Les localisations invalides auront des propriétés latitude et longitude présentes dans la réponse, mais leurs valeurs ne doivent pas être considérées.
checkInTime entier Temps d'attente minimum à la location (en minutes). Si non spécifié, les nouvelles localisations créées utiliseront la valeur par défaut configurée dans OptimoRoute (zéro par défaut). À l'arrivée à la location, le conducteur passera au moins le temps de check-in avant de commencer à effectuer une ou plusieurs commandes consécutives au même endroit.
Exemple : si nous avons 3 commandes au même endroit :
  • A: durée 10min, check in time 15min
  • B: durée 5min, check in time 15min
  • C: durée 20min, check in time 15min
Si un conducteur sert toutes les trois commandes consécutivement, le conducteur arriverait à l'emplacement, passerait 15 minutes sur place (par exemple, pour garer et s'enregistrer) puis commencerait à réaliser les commandes A, B et C. Le temps total sur place serait de 50min = 15min (durée partagée) + 10min (commande A) + 5min (commande B) + 20min (commande C).
notes chaîne Notes facultatives relatives à cet emplacement.

Objet SelectedDriver

Utilisez soit driverExternalId soit driverSerial (un champ suffit) :

Propriété Type par défaut Description
driverExternalId
optionnel
chaîne
-
L'identifiant externe attribué au conducteur dans l'administration du conducteur.
driverSerial
optionnel
chaîne
-
Le numéro de série du conducteur.

Objet Time

Propriété Type Description
unixTimestamp
obligatoire
entier Nombre de secondes écoulées depuis 00:00 UTC le 1er janvier 1970.
utcTime
obligatoire
date ISO 8601 (chaîne) La date et l'heure UTC
localTime
obligatoire
date ISO 8601 (chaîne) L'heure locale

Les champs unixTimestamp, utcTime et localTime se réfèrent tous au même moment, de sorte que vous pouvez utiliser celui qui est le plus pratique.

Objet CustomFields

L'objet CustomFields peut contenir un nombre quelconque de propriétés, où chaque nom de propriété correspond à la clé d'un champ personnalisé configuré dans OptimoRoute.

Exemple d'objet CustomFields (fruit_type est de type Sélection uniqueapple est une option clé, quantity est de type Nombre avec 0 décimales, purity est de type Nombre avec 2 décimales et instructions est de type Texte) :

{
  "fruit_type": "apple",
  "quantity": 100,
  "purity": 99.99,
  "instructions": "Deliver to the customer's door."
}
Propriété Type Description
{custom_field_key} chaîne ou décimal ou booléen Si le champ personnalisé est configuré avec le type Texte ou Nombre, la valeur fournie sera convertie dans le type approprié si possible.
Si le champ personnalisé est configuré avec le type Sélection unique, la valeur doit correspondre exactement à une des clés d'option configurées pour ce champ.

REMARQUE : Contactez le support OptimoRoute pour activer les nouveaux champs personnalisés. Les champs personnalisés hérités (champs personnalisés avec des clés custom_field_1 à custom_field_5) ne doivent pas être inclus dans cet objet - ceux-ci sont définis à l'aide des champs séparés dans l'Objet Commande (customField1 à customField5).

Créer une Commande

Crée une nouvelle commande dans le système ou met à jour une commande existante.

Requête HTTP

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

reqbody.json est un fichier local contenant les données JSON à envoyer. Assurez-vous de remplacer AUTH_KEY par votre clé API.

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

Paramètres

Exemple de corps de requête :

{
  "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": "Deliver at back door"
}

En plus des propriétés de l'Objet Commande, les propriétés suivantes sont disponibles :

Propriété Type Description
operation énumération de string CREATE – crée une nouvelle commande dans le système.

UPDATE – met à jour une commande existante dans le système. Si la commande n'existe pas, le système retournera une erreur.

SYNC – recommandé lorsque l'objectif final est de s'assurer que les commandes sont reflétées dans OptimoRoute. Si c'est une nouvelle commande, nous la créerons. S'il existe une commande existante dans le système, elle sera mise à jour. SYNC effectue une synchronisation propre des données de commande. Tout ce que nous avons sur cette commande sera remplacé par les données que vous nous envoyez sur SYNC.

MERGE – utilisé pour mettre à jour uniquement certains champs et laisser tous les autres champs inchangés (par exemple si certains champs ont été modifiés manuellement dans OptimoRoute et ne doivent pas être mis à jour). Si c'est une nouvelle commande, nous la créerons. S'il existe une commande existante dans le système, elle sera mise à jour.

Pour les opérations autres que CREATE, la commande sera recherchée par son id unique si utilisé dans la demande, ou orderNo si id n'est pas utilisé.
acceptDuplicateOrderNo booléen Si défini sur true, le système acceptera les commandes avec un orderNo qui existe déjà dans le système. Quand false ou non spécifié, le système retournera une erreur.
twFrom heure (chaîne de caractères) Déprécié, veuillez utiliser le champ timeWindows; ignoré si timeWindows est défini.

L'heure la plus précoce autorisée pour commencer le service (si le conducteur arrive trop tôt, il sera obligé d'attendre).
Format horaire 24 heures (militaire), par exemple : 16:00
Les valeurs valides vont de 00:00 à 23:59.
twTo heure (chaîne de caractères) Déprécié, veuillez utiliser le champ timeWindows; ignoré si timeWindows est défini.

La date limite pour terminer le service.
Format horaire 24 heures (militaire), par exemple 17:00
Les valeurs valides vont de 00:00 à 23:59.

La propriété operation est obligatoire. Lorsque operation est spécifié comme UPDATE, l'un de orderNo ou id est obligatoire, sinon les propriétés obligatoires sont date, type, location et l'un de orderNo ou id.

Objet de Localisation

Exemple d'Objet Localisation précisant l'adresse à géocoder et acceptant tout résultat :

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

En plus des propriétés de l'Objet Localisation, les propriétés suivantes sont disponibles :

Propriété Type Description
acceptMultipleResults booléen Utilisé uniquement si un nouveau lieu est créé par géocodage du champ address. Si false ou non spécifié, le système n'acceptera pas les adresses géocodées où plusieurs résultats correspondant à l'adresse fournie ont été trouvés et une erreur sera soulevée.
acceptPartialMatch booléen Utilisé uniquement si un nouveau lieu est créé par géocodage du champ address. Si false ou non spécifié, le système n'acceptera pas les adresses géocodées qui étaient seulement une correspondance partielle (confiance de géocodage plus faible) et une erreur sera soulevée.
storeInvalid booléen Utilisé uniquement si un nouveau lieu est créé par géocodage du champ address. Si false ou non spécifié, le système soulèvera une erreur lorsque l'adresse fournie est erronée ou incomplète (aucune adresse correspondant à celle fournie n'a été trouvée). La définition de ce paramètre sur true permet de stocker des informations de localisation incomplètes qui peuvent être corrigées par la suite. Jusqu'à ce que la localisation soit corrigée, la planification des commandes avec cette localisation ne sera pas possible.

Une localisation est définie par l'un des éléments suivants :

Réponse

Réponse à la requête d'exemple :

{
  "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
    ]
  ]
}
Propriété Type / Valeur Défaut Description
success
obligatoire
booléen
-
true si la commande a été enregistrée, false s'il y avait une erreur.
code
optionnel
chaîne de caractères
-
Un code d'erreur ou un code d'avertissement (non défini si l'opération a réussi).
message
optionnel
chaîne de caractères
-
Une description d'erreur ou une description d'avertissement (non définie si l'opération a réussi).
id
optionnel
chaîne de caractères
-
L'identifiant unique en lecture seule de la commande, attribué par OptimoRoute
location
optionnel
objet de localisation
-
Les données de localisation pour la commande créée (uniquement si l'opération a réussi).
geocodingResults
optionnel
liste
-
La liste des résultats de géocodage si la localisation est créée à partir de l'adresse fournie.
Chaque résultat de géocodage est défini comme :
[geocodedAddress, latitude, longitude, partialMatchFlag]

Codes d'Erreur et d'Avertissement

Les codes d'erreur suivants sont applicables à la méthode Créer Commande :

Code d'Erreur Description
ERR_ORD_EXISTS une commande avec le orderNo spécifié existe déjà dans le système (vérifié uniquement si le champ orderNo est défini)
ERR_RELATED_ORD_MISSING la commande avec l'ID passé dans relatedOrderNo n'existe pas
ERR_RELATED_ORD_MULTIPLE plusieurs commandes avec l'ID passé dans relatedOrderNo existent
ERR_RELATED_ORD_LINK la commande ne peut pas être liée à la commande avec l'ID passé dans relatedOrderNo (seules les ramassages et livraisons peuvent être liés)
ERR_DRV_NOT_EXISTS le conducteur avec le numéro de série passé dans assignedTo n'existe pas
ERR_DRV_MULTIPLE il y a plus d'un conducteur avec le numéro de série assignedTo
ERR_LOC_NOT_VALID l'emplacement spécifié n'est pas valide
ERR_LOC_GEOCODING l'adresse spécifiée n'a pas pu être géocodée
ERR_LOC_GEOCODING_MULTIPLE plusieurs résultats ont été trouvés lors du géocodage
ERR_LOC_GEOCODING_PARTIAL le géocodeur n'a pas retourné une correspondance exacte pour la demande originale
ERR_LOC_NON_EXISTING_LOC le lieu spécifié par locationNo n'existe pas
ERR_LOC_MULTIPLE_LOC plusieurs lieux avec le locationNo spécifié ont été trouvés
ERR_VF_NOT_EXISTS la fonctionnalité du véhicule n'existe pas (pour un des codes spécifiés dans le champ vehicleFeatures)
ERR_VF_MULTIPLE plusieurs fonctionnalités de véhicules existent (pour un des codes spécifiés dans le champ vehicleFeatures)
ERR_SK_NOT_EXISTS la compétence n'existe pas (pour un des codes spécifiés dans le champ skills)
ERR_SK_MULTIPLE plusieurs compétences existent (pour un des codes spécifiés dans le champ skills)
WAR_LOC_GEOCODING l'adresse spécifiée n'a pas pu être géocodée (mais la commande a été créée parce que storeInvalid a été défini sur True)
WAR_LOC_GEOCODING_MULTIPLE plusieurs résultats ont été trouvés lors du géocodage (mais la commande a été créée parce que acceptMultipleResults a été défini sur True)
WAR_LOC_GEOCODING_PARTIAL le géocodeur n'a pas retourné une correspondance exacte pour la demande originale (mais la commande a été créée parce que acceptPartialMatch a été défini sur True)

Créer ou Mettre à Jour des Commandes (en masse)

Créez, mettez à jour ou remplacez une ou plusieurs commandes dans le système.

Notez que le géocodage des adresses n'est pas disponible dans cet appel. Les emplacements pour les commandes doivent exister dans le système ou être spécifiés via des coordonnées de latitude et de longitude. Le géocodage est disponible dans Créer Commande.

Requête HTTP

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

reqbody.json est un fichier local contenant les données JSON à envoyer. Assurez-vous de remplacer AUTH_KEY par votre clé API.

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

Paramètres

Exemple de corps de requête :

{
  "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"
      }
    }
  ]
}
Propriété Type / Défaut Description
orders
obligatoire
liste d'objets commande
-
Liste d'un ou plusieurs objets commande à créer, mettre à jour ou remplacer dans le système. Au maximum 500 commandes peuvent être spécifiées.

Objet Commande

En plus des propriétés de l'Objet Commande, les propriétés suivantes sont disponibles :

Propriété Type Description
operation énumération de chaînes MERGE – utilisé uniquement pour mettre à jour des champs spécifiques et laisser inchangés tous les autres champs (par exemple si certains champs ont été édités manuellement dans OptimoRoute et ne doivent pas être mis à jour). Si c'est une nouvelle commande, nous la créerons. S'il y a une commande existante dans le système, elle sera mise à jour.

SYNC – recommandé quand l'objectif final est de s'assurer que les commandes sont reflétées dans OptimoRoute. Si c'est une nouvelle commande, nous la créerons. S'il y a une commande existante dans le système, elle sera mise à jour. SYNC effectue une synchronisation propre des données de commande. Tout ce que nous avons sur cette commande sera remplacé par les données que vous nous envoyez avec SYNC.

CREATE – crée une nouvelle commande dans le système ; non autorisé avec id

UPDATE – met à jour une commande existante dans le système. Si la commande n'existe pas, le système retournera une erreur.
acceptDuplicateOrderNo booléen Si défini sur true, le système autorisera la création des commandes avec orderNo qui existent déjà dans le système. Lorsque false ou non spécifié, le système retournera une erreur.

Chaque objet commande donné dans orders aboutira à la création, mise à jour ou remplacement d'une commande dans le système. Le comportement exact pour chaque commande peut être configuré via operation dans chaque objet commande. Le comportement par défaut est :

Objet Emplacement

Voir Objet Emplacement pour toutes les propriétés d'emplacement disponibles. Les emplacements peuvent être créés ou mis à jour.

Si locationNo est spécifié et un emplacement correspondant existe, cet emplacement sera mis à jour. Si locationNo ne correspond à aucun match, un nouvel emplacement sera créé.

Si locationNo n'est pas spécifié et une commande existante est mise à jour - l'emplacement de la commande sera mis à jour.

Lors de la mise à jour, l'emplacement correspondant sera mis à jour avec les valeurs données dans l'objet, le cas échéant. Aucune propriété n'est obligatoire lors de la mise à jour. Lors de l'actualisation avec SYNC, les propriétés sont réinitialisées par défaut, sinon elles conservent leurs valeurs existantes.

Dans les cas où un nouvel emplacement est créé, les propriétés suivantes sont obligatoires : latitude, longitude et l'une de locationNo, address, locationName.

Réponse

Exemple de réponse :

{
  "orders": [
    {
      "success": true,
      "id": "c821486835d2f20539a9754454f7efbe",
      "orderNo": "54913250"
    },
    {
      "success": false,
      "code": "ERR_LOC_NON_EXISTING_LOC",
      "message": "L'emplacement avec le numéro d'emplacement donné n'existe pas.",
      "orderNo": "27463225",
      "locationNo": "999999999"
    },
    {
      "success": true,
      "id": "8cde6711026ff11f79f15a719277fe26",
      "orderNo": "09463221"
    }
  ],
  "success": true
}
Propriété Type / Défaut Description
success
obligatoire
booléen
-
true si au moins une opération a réussi, false si toutes ont échoué
orders
liste d'objets réponse de commande
-
Chaque objet commande dans la liste correspond à la commande respective dans la requête. Voir la section Objet Réponse de Commande pour plus d'informations.

Objet Réponse de Commande

Propriété Type / Défaut Description
success
obligatoire
booléen
-
true si l'opération a réussi, false s'il y a eu une erreur.
orderNo
optionnel
chaîne
-
Identifiant de la commande respective
id
optionnel
chaîne
-
Identifiant unique en lecture seule de la commande, attribué par OptimoRoute
locationNo
optionnel
chaîne
-
Identifiant de l'emplacement s'il y a eu une erreur liée à l'emplacement
code
optionnel
chaîne
-
Un code d'erreur par commande (non défini si l'opération a réussi).
message
optionnel
chaîne
-
Une description de l'erreur ou un avertissement (non défini si l'opération a réussi).

Codes d'erreur et d'avertissement

Les codes d'erreur par commande suivants sont applicables :

Code d'erreur Description
ERR_INVALID_PARAM_FORMAT la commande spécifiée n'est pas valide, peut-être une commande à créer/mettre à jour qui n'existait pas dans le système mais n'a pas pu être créée car une propriété obligatoire est manquante
ERR_ORD_EXISTS une commande avec le orderNo spécifié existe déjà dans le système (uniquement avec CREATE plus orderNo)
ERR_ORD_NOT_FOUND la commande avec le orderNo correspondant n'a pas été trouvée (uniquement avec UPDATE plus orderNo, ou si id est utilisé dans la requête)
ERR_MULTIPLE_ORD_FOUND il existe plusieurs commandes correspondant au orderNo
ERR_OPT_RUNNING l'optimisation est en cours pour cette commande
ERR_RELATED_ORD_MISSING la commande avec le orderNo passé dans relatedOrderNo n'existe pas
ERR_RELATED_ORD_MULTIPLE plusieurs commandes avec le orderNo passé dans relatedOrderNo existent
ERR_RELATED_ORD_LINK la commande ne peut pas être liée à la commande avec le orderNo passé dans relatedOrderNo (seuls les ramassages et les livraisons peuvent être liés)
ERR_DRV_NOT_EXISTS le conducteur spécifié dans assignedTo n'existe pas
ERR_DRV_MULTIPLE il y a plus d'un conducteur avec les valeurs spécifiées dans assignedTo
ERR_LOC_NOT_VALID l'emplacement spécifié n'est pas valide, peut-être un emplacement à créer/mettre à jour qui n'existait pas dans le système mais n'a pas pu être créé car une propriété obligatoire est manquante
ERR_LOC_NON_EXISTING_LOC l'emplacement spécifié par locationNo n'existe pas
ERR_LOC_MULTIPLE_LOC plusieurs emplacements avec le locationNo spécifié ont été trouvés
ERR_VF_NOT_EXISTS la caractéristique de véhicule n'existe pas (pour l'un des codes spécifiés dans le champ vehicleFeatures)
ERR_VF_MULTIPLE plusieurs caractéristiques de véhicule existent (pour l'un des codes spécifiés dans le champ vehicleFeatures)
ERR_SK_NOT_EXISTS la compétence n'existe pas (pour l'un des codes spécifiés dans le champ skills)
ERR_SK_MULTIPLE plusieurs compétences existent (pour l'un des codes spécifiés dans le champ skills)

Obtenir des Commandes (en masse)

Récupère une ou plusieurs commandes du système.

Requête HTTP

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

reqbody.json est un fichier local contenant les données JSON à publier. Assurez-vous de remplacer AUTH_KEY par votre clé API.

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

Paramètres

Exemple de corps de requête :

{
  "orders": [
    {
      "orderNo": "ORD001"
    },
    {
      "orderNo": "ORD99"
    },
    {
      "id": "04e7b09e993e8488024f46aaf9d8c72d"
    }
  ]
}
Propriété Type / Par défaut Description
orders
obligatoire
liste d'objets commande
-
Liste des objets commande à récupérer. Chaque objet commande peut contenir soit :
  • orderNo: l'identifiant spécifié par l'utilisateur d'une commande
  • id: l'identifiant unique de la commande, attribué par OptimoRoute
Au maximum 500 commandes peuvent être spécifiées.



Pour plus de flexibilité, si vous utilisez seulement orderNo, l'appel à get_orders peut également être effectué comme une requête HTTP GET :

Exemple de requête GET :

curl 'https://api.optimoroute.com/v1/get_orders?key=AUTH_KEY&orderNo=ORD001&orderNo=ORD99'
Propriété Type / Par défaut Description
orderNo
obligatoire
chaîne de caractères
-
L'identifiant spécifié par l'utilisateur d'une commande; peut être répété pour récupérer plusieurs commandes

Réponse

Exemple de réponse :

{
  "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": "La commande avec le orderNo correspondant n'a pas été trouvée.",
      "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"
      }
    },
  ]
}
Propriété Type / Par défaut Description
success
obligatoire
booléen
-
true si au moins une commande a été récupérée, false si aucune commande n'a été récupérée
orders
obligatoire
liste d'objets réponse de commande
-
Chaque objet commande dans la liste correspond au orderNo et/ou id respectif dans la requête. Voir la section Objet Réponse de Commande pour plus d'informations.

Objet Réponse de Commande

Propriété Type / Par défaut Description
success
obligatoire
booléen
-
true si la commande a été récupérée, false s'il y a eu une erreur.
code
facultatif
chaîne de caractères
-
Un code d'erreur ou un code d'avertissement (non défini si l'opération a réussi).
message
facultatif
chaîne de caractères
-
Une description d'erreur ou une description d'avertissement (non définie si l'opération a réussi).
orderNo
facultatif
chaîne de caractères
-
Le orderNo dont la récupération a échoué. Présent uniquement si l'opération n'a pas réussi et que orderNo a été utilisé dans la requête.
id
obligatoire
chaîne de caractères
-
L'identifiant unique de la commande, attribué par OptimoRoute.
data
facultatif
Objet commande
-
La commande récupérée.

Objet Commande

En cas de succès, data sera un objet avec les propriétés listées dans Objet Commande.

La propriété type retournée peut être break ou depot.

Codes d'Erreur et d'Avertissement

Les codes d'erreur par commande suivants sont applicables à la méthode Obtenir des Commandes :

Code d'Erreur Description
ERR_ORD_NOT_FOUND la commande avec le orderNo et/ou le id correspondant n'a pas été trouvée.
ERR_MULTIPLE_ORD_FOUND il y a plusieurs commandes correspondant au orderNo
ERR_INVALID_PARAM_FORMAT ce orderNo n'est pas valide

Supprimer une commande

Supprime une commande du système.

Requête HTTP

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

reqbody.json est un fichier local contenant les données JSON à envoyer. Assurez-vous de remplacer AUTH_KEY par votre clé API.

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

Paramètres

Exemple de corps de requête :

{
  "orderNo": "ORD001"
}
Propriété Type / Valeur par défaut Description
orderNo
obligatoire
string
-
L'identifiant spécifié par l'utilisateur de la commande à supprimer.
forceDelete
optionnel
boolean
false
Si true, les restrictions habituelles concernant la suppression de commandes sur un plan en direct sont ignorées.

Réponse

Propriété Type / Valeur par défaut Description
success
obligatoire
boolean
-
true si la commande a été supprimée, false s'il y a eu une erreur.
code
optionnel
string
-
Un code d'erreur ou un code d'avertissement (non défini si l'opération a réussi).
message
optionnel
string
-
Une description d'erreur ou une description d'avertissement (non défini si l'opération a réussi).
planningId
optionnel
integer
-
L'identifiant du processus de planification si l'optimisation est en cours pour cette commande.

Codes d'erreur et d'avertissement

Les codes d'erreur suivants sont applicables à la méthode Supprimer une commande :

Code d'erreur Description
ERR_ORD_NOT_FOUND la commande avec le orderNo correspondant n'a pas été trouvée
ERR_MULTIPLE_ORD_FOUND il y a plusieurs commandes correspondant au orderNo
ERR_OPT_RUNNING l'optimisation est en cours pour cette commande

Supprimer toutes les commandes

Supprime toutes les commandes et itinéraires planifiés pour la date spécifiée du système. Si aucune date n'est définie, toutes les commandes et itinéraires sont supprimés du système.

Requête HTTP

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

reqbody.json est un fichier local contenant les données JSON à envoyer. Assurez-vous de remplacer AUTH_KEY par votre clé API.

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

Paramètres

Exemple de corps de requête :

{
  "date": "2014-10-14"
}
Propriété Type / Défaut Description
date
optionnel
date (chaîne)
-
Date pour laquelle les commandes et itinéraires seront supprimés.
Format YYYY-MM-DD, par exemple 2013-12-20.

Réponse

Propriété Type / Défaut Description
success
obligatoire
booléen
-
true si les commandes ont été supprimées, false s'il y a eu une erreur.
code
optionnel
chaîne
-
Un code d'erreur ou un code d'avertissement (non défini si l'opération a réussi).
message
optionnel
chaîne
-
Une description d'erreur ou d'avertissement (non définie si l'opération a réussi).
planningId
optionnel
entier
-
L'ID du processus de planification en cas d'exécution d'une optimisation.

Codes d'erreur et d'avertissement

Les codes d'erreur suivants s'appliquent à la méthode Supprimer la commande :

Code d'erreur Description
ERR_OPT_RUNNING une optimisation est en cours pour cette date

Suppression des Commandes (en masse)

Supprime une ou plusieurs commandes du système.

Requête HTTP

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

reqbody.json est un fichier local contenant les données JSON à envoyer. Assurez-vous de remplacer AUTH_KEY par votre clé API.

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

Paramètres

Exemple de corps de requête :

{
  "orders": [
    {
      "orderNo": "ORD001"
    },
    {
      "orderNo": "ORD999"
    },
    {
      "id": "04e7b09e993e8488024f46aaf9d8c72d"
    }
  ]
}
Propriété Type / Par Défaut Description
orders
obligatoire
liste d'objets commande
-
Liste des objets commande à supprimer. Chaque objet commande peut contenir soit :
  • orderNo: l'identifiant spécifié par l'utilisateur d'une commande
  • id: l'identifiant unique de la commande, attribué par OptimoRoute
Au maximum 500 commandes peuvent être spécifiées.
deleteMultiple
optionnel
booléen
false
Si false, lorsqu'il y a plusieurs commandes correspondant à un objet commande, une erreur sera retournée. Si true, toutes les correspondances seront supprimées.
forceDelete
optionnel
booléen
false
Si true, les restrictions habituelles concernant la suppression des commandes sur un plan en direct sont ignorées.

Réponse

Exemple de réponse :

{
  "success": true,
  "orders": [
    {
      "orderNo": "ORD001",
      "success": true
    },
    {
      "message": "La commande avec l'orderNo correspondant n'a pas été trouvée.",
      "code": "ERR_ORD_NOT_FOUND",
      "orderNo": "ORD999",
      "success": false
    },
    {
      "success": true,
      "id": "04e7b09e993e8488024f46aaf9d8c72d"
    }
  ]
}
Propriété Type / Par Défaut Description
success
obligatoire
booléen
-
true si au moins une commande a été supprimée, false si aucune commande n'a été supprimée.
orders
obligatoire
liste d'objets de réponse de suppression
-
Chaque objet commande de la liste correspond au orderNo et/ou id respectif dans la requête. Voir la section Objet de Réponse de Suppression pour plus d'informations.

Objet de Réponse de Suppression

Propriété Type / Par Défaut Description
success
obligatoire
booléen
-
true si supprimé, false s'il y a eu une erreur.
code
optionnel
chaîne de caractères
-
Un code d'erreur ou un code d'avertissement (non défini si l'opération a réussi).
message
optionnel
chaîne de caractères
-
Une description de l'erreur ou de l'avertissement (non défini si l'opération a réussi).
orderNo
optionnel
chaîne de caractères
-
Le orderNo qui a été supprimé, ou dont la suppression a échoué. Présent uniquement si orderNo a été utilisé dans la requête.
id
optionnel
chaîne de caractères
-
L'id qui a été supprimé, ou dont la suppression a échoué. Présent uniquement si id a été utilisé dans la requête.
planningId
optionnel
entier
-
L'identifiant du processus de planification en cas d'optimisation en cours pour cette commande.

Codes d'Erreur et d'Avertissement

Les codes d'erreur par commande suivants sont applicables à la méthode Suppression des Commandes :

Code d'Erreur Description
ERR_ORD_NOT_FOUND la commande avec le orderNo et/ou id correspondant n'a pas été trouvée
ERR_MULTIPLE_ORD_FOUND il y a plusieurs commandes correspondant au orderNo, mais deleteMultiple était défini sur false
ERR_OPT_RUNNING l'optimisation est en cours pour cette commande
ERR_INVALID_PARAM_FORMAT ce orderNo ou id n'est pas valide

Obtenir des itinéraires

Obtient les itinéraires pour une date spécifique.

Requête HTTP

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

Assurez-vous de remplacer AUTH_KEY par votre clé 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'

Paramètres

Propriété Type / Par défaut Description
date
obligatoire
date (chaîne)
-
Date interrogée.
Format YYYY-MM-DD, par exemple 2013-12-20.
driverExternalId
facultatif
chaîne
-
Filtrer optionnellement par identifiant externe des conducteurs.
driverSerial
facultatif
chaîne
-
Filtrer optionnellement par numéro de série du conducteur.
vehicleRegistration
facultatif
chaîne
-
Filtrer optionnellement par immatriculation du véhicule.
includeRoutePolyline
facultatif
booléen
false
Propriété optionnelle pour inclure la polyligne de l'itinéraire dans la sortie. Cette polyligne peut être utilisée pour afficher l'itinéraire sur la carte. La polyligne est une liste de coordonnées encodée avec l'algorithme Polyline Encoded.
includeRouteStartEnd
facultatif
booléen
false
Propriété optionnelle pour inclure les emplacements de départ et d'arrivée de l'itinéraire dans la sortie.

Réponse

Exemple de réponse

{
  "success": true,
  "routes": [
    {
      "driverExternalId": "",
      "driverSerial": "011",
      "driverName": "Conducteur 011",
      "vehicleRegistration": "Véhicule 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]?[A??}@Be@?yAB?F?bA?LM?aFFG?"
    }
  ]
}
Propriété Type / Par défaut Description
success
obligatoire
booléen
-
true si la requête a réussi, false s'il y a eu une erreur.
routes
obligatoire
liste d'objets itinéraire
[]
Liste d'itinéraires correspondant à la requête.
code
facultatif
chaîne
-
Un code d'erreur ou un code d'avertissement (non défini si l'opération a réussi).
message
facultatif
chaîne
-
Une description d'erreur ou d'avertissement (non définie si l'opération a réussi).

Objet Itinéraire

Propriété Type / Par défaut Description
driverExternalId
obligatoire
chaîne
-
L'identifiant externe des conducteurs.
driverSerial
obligatoire
chaîne
-
Le numéro de série attribué au conducteur.
driverName
obligatoire
chaîne
-
Le nom du conducteur.
vehicleRegistration
obligatoire
chaîne
-
Immatriculation du véhicule.
vehicleLabel
obligatoire
chaîne
-
Étiquette du véhicule.
duration
obligatoire
entier
-
Durée de l'itinéraire en minutes.
distance
obligatoire
décimal
-
Distance de l'itinéraire en kilomètres.
load1
obligatoire
entier
0
Chargement #1 de l'itinéraire.
load2
obligatoire
entier
0
Chargement #2 de l'itinéraire.
load3
obligatoire
entier
0
Chargement #3 de l'itinéraire.
load4
obligatoire
entier
0
Chargement #4 de l'itinéraire.
stops
obligatoire
liste d'objets arrêt
[]
Une liste ordonnée d'arrêts/commandes sur l'itinéraire.
routePolyline
facultatif
chaîne
-
Polyligne de l'itinéraire encodée avec l'algorithme Polyline Encoded. Incluse seulement si includeRoutePolyline est défini à True.

Objet Arrêt

Propriété Type / Par défaut Description
stopNumber
obligatoire
entier
-
Numéro de l'arrêt. Commence à 1.
orderNo
obligatoire
chaîne
-
Le numéro de la commande.
id
obligatoire
chaîne
-
L'identifiant unique en lecture seule de la commande, attribué par OptimoRoute.
locationNo
obligatoire
chaîne
-
Numéro de l'emplacement.
locationName
obligatoire
chaîne
-
Nom de l'emplacement.
address
obligatoire
chaîne
-
Adresse de l'emplacement.
latitude
obligatoire
décimal
-
Latitude de l'emplacement.
longitude
obligatoire
décimal
-
Longitude de l'emplacement.
scheduledAt
obligatoire
heure (chaîne)
-
L'heure prévue pour commencer le service.
Format de l'horloge militaire (24 heures), par exemple : 16:00.
Les valeurs valides vont de 00:00 à 23:59.
scheduledAtDt
obligatoire
datetime (chaîne)
-
La date et l'heure prévues pour commencer le service. Format : YYYY-mm-dd HH:MM:SS, par exemple 2018-01-01 13:10:37.
arrivalTimeDt
obligatoire
datetime (chaîne)
-
La date et l'heure d'arrivée du conducteur à l'emplacement. En raison des fenêtres horaires, le conducteur pourrait avoir besoin d'attendre pour commencer le service. Format : YYYY-mm-dd HH:MM:SS, par exemple 2018-01-01 13:10:37.
travelTime
obligatoire
entier
-
Temps de voyage depuis l'arrêt précédent (en secondes).
distance
obligatoire
entier
-
Distance depuis l'arrêt précédent (en mètres).
type
facultatif
chaîne
-
Type de commande uniquement ajouté pour les pauses déjeuner (la valeur sera break) et pour les trajets de dépôt (la valeur sera depot).

Codes d'erreur et d'avertissement

Aucun.

Obtenir des informations de planification

Obtient les informations de planification pour la Commande spécifiée. Pour la méthode en vrac, voir Rechercher des Commandes

Requête HTTP

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

Assurez-vous de remplacer AUTH_KEY par votre clé API.

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

Paramètres

Propriété Type / Par défaut Description
orderNo
optionnel
string
-
L'identifiant spécifié par l'utilisateur pour la commande.
id
optionnel
string
-
L'identifiant unique de la commande, assigné par OptimoRoute.

Une des deux propriétés doit être fournie dans la demande.

Réponse

Propriété Type / Par défaut Description
success
obligatoire
boolean
-
true si la requête a été réussie, false s'il y a eu une erreur.
orderScheduled
optionnel
boolean
-
true si la commande est planifiée, false sinon.
scheduleInformation
optionnel
objet d'info de planification
-
Les informations de planification de la commande.
code
optionnel
string
-
Un code d'erreur ou un code d'avertissement (non défini si l'opération a réussi).
message
optionnel
string
-
Une description d'erreur ou une description d'avertissement (non définie si l'opération a réussi).

Objet d'informations de planification de commande

Propriété Type / Par défaut Description
driverExternalId
obligatoire
string
-
L'identifiant externe des conducteurs.
driverSerial
obligatoire
string
-
Le numéro de série attribué au conducteur.
driverName
obligatoire
string
-
Le nom du conducteur.
vehicleRegistration
obligatoire
string
-
Immatriculation du véhicule.
vehicleLabel
obligatoire
string
-
Étiquette du véhicule.
stopNumber
obligatoire
integer
-
Numéro d'arrêt sur l'itinéraire. Commence à 1.
scheduledAt
obligatoire
heure (string)
-
L'heure prévue pour commencer le service.
Format 24 heures, par exemple : 16:00.
Les valeurs valides vont de 00:00 à 23:59.
scheduledAtDt
obligatoire
date-heure (string)
-
La date et l'heure prévues pour commencer le service. Format : YYYY-mm-dd HH:MM:SS, par exemple 2018-01-01 13:10:37.
arrivalTimeDt
obligatoire
date-heure (string)
-
La date et l'heure d'arrivée du conducteur à l'emplacement. En raison des fenêtres horaires, le conducteur pourrait avoir besoin d'attendre pour commencer le service. Format : YYYY-mm-dd HH:MM:SS, par exemple 2018-01-01 13:10:37.
travelTime
obligatoire
integer
-
Temps de trajet depuis l'arrêt précédent (en secondes).
distance
obligatoire
integer
-
Distance depuis l'arrêt précédent (en mètres).

Codes d'erreur et d'avertissement

Les codes d'erreur suivants sont applicables à la méthode Obtenir des informations de planification :

Code d'erreur Description
ERR_ORD_NOT_FOUND la commande avec le orderNo correspondant n'a pas été trouvée
ERR_MULTIPLE_ORD_FOUND il y a plusieurs commandes correspondant au orderNo

Exemple de réponse 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
  }
}

Exemple de réponse 2

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

Démarrer la Planification

Démarre le processus de planification pour la date spécifiée.

Requête HTTP

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

reqbody.json est un fichier local contenant les données JSON à envoyer. Assurez-vous de remplacer AUTH_KEY par votre clé d'API.

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

Paramètres

Exemple de corps de requête :

{
  "date": "2013-12-20"
}
Propriété Type / Valeur par défaut Description
date
obligatoire
date (string)
-
Date à planifier.
Format YYYY-MM-DD, par exemple 2013-12-20.
dateRange
optionnel
objet daterange Support pour la planification hebdomadaire (planifier un horizon temporel plus long). Si dateRange est spécifié, date est ignoré et peut être omis.
L'intervalle de dates est spécifié comme un objet avec les champs from et to, par exemple :
{"from": "2020-04-27", "to": "2020-05-01"}.
balancing
optionnel
string
OFF
Paramètres d'équilibrage des itinéraires. Valeurs autorisées :
OFF – Pas d'équilibrage
ON – Équilibrer les itinéraires
ON_FORCE – Équilibrer les itinéraires et utiliser tous les conducteurs

Pas d'équilibrage : retourne les meilleurs itinéraires, certains conducteurs pourraient ne pas être utilisés.
Équilibrer les itinéraires : équilibre la charge de travail entre les conducteurs, certains conducteurs peuvent ne pas être utilisés.
Équilibrer les itinéraires et utiliser tous les conducteurs : équilibre la charge de travail entre tous les conducteurs disponibles.
balanceBy
optionnel
string
WT
Si l'équilibrage des itinéraires est activé, cela définit les critères pour l'équilibrage des itinéraires.

Valeurs autorisées :
WT – Temps de travail
NUM – Nombre de commandes par conducteur
balancingFactor
optionnel
décimal
0.3
Importance de l'équilibrage par rapport aux coûts des itinéraires. Augmenter le facteur d'équilibrage aboutira à des itinéraires plus équilibrés.
Applicable uniquement en combinaison avec ON_FORCE (sinon ignoré).

Valeur minimum : 0.0
Valeur maximum : 1.0
startWith
optionnel
string
EMPTY
Commence la planification à partir des itinéraires existants ou de zéro.

Valeurs autorisées :
EMPTY – Ignorer les itinéraires existants et commencer de zéro
CURRENT – Commencer la planification avec les itinéraires existants
lockType
optionnel
string
NONE
Applicable si startWith est défini sur CURRENT.

Valeurs autorisées :
NONE – Permet tous les changements sur les itinéraires existants
ROUTES - Conserve les itinéraires planifiés inchangés et ajoute de nouvelles commandes à ceux inutilisés
RESOURCES - Conserve les conducteurs/véhicules pour les commandes planifiées et intègre de nouvelles commandes
depotTrips
optionnel
booléen
false
Si true, les conducteurs seront programmés pour retourner à l'entrepôt pour recharger (ou décharger en cas de ramassages) s'il y a encore du temps dans leurs heures de travail pour effectuer un autre itinéraire.
Des informations supplémentaires sont disponibles sur notre blog :
https://optimoroute.com/fr/arretez-le-reapprovisionnement-et-continuez-votre-chemin/.
depotVisitDuration
optionnel
entier
0
Temps en minutes requis pour recharger ou décharger les marchandises à l'entrepôt avant que le conducteur ne parte pour une autre course.
Applicable uniquement si depotTrips est défini sur true.
clustering
optionnel
booléen
false
Si true, le système tentera de minimiser les chevauchements entre les itinéraires des conducteurs.
useDrivers
optionnel
liste d'objets SelectedDriver
[]
Conducteurs sélectionnés qui devraient être utilisés dans l'optimisation.
Par défaut (si useDrivers n'est pas défini ou que la liste est vide), tous les conducteurs disponibles pour la date spécifiée sont utilisés.
useOrders
optionnel
liste de chaînes de caractères
[]
Obsolète au profit de useOrderObjects.
Commandes sélectionnées qui devraient être incluses dans l'optimisation.
Les commandes sont spécifiées sous forme de liste d'identifiants de commande (orderNo strings).
Par défaut (si useOrders n'est pas défini ou que la liste est vide), toutes les commandes pour la date spécifiée qui ont un emplacement valide sont incluses.

Les commandes qui ne sont pas sélectionnées, mais qui sont déjà programmées pour des conducteurs qui seront utilisés dans l'optimisation seront déprogrammées à moins que l'indicateur includeScheduledOrders ne soit défini sur true.
useOrderObjects
optionnel
liste d'objets
[]
Sous-ensemble de commandes à la date prévue qui devrait être inclus dans l'optimisation.
Les commandes sont spécifiées sous forme de liste d'objets pouvant contenir l'un des éléments suivants :
  • propriété orderNo avec l'identifiant spécifié par l'utilisateur d'une commande
  • id identifiant unique de la commande tel qu'assigné par OptimoRoute

Par défaut (si useOrderObjects n'est pas défini ou que la liste est vide), toutes les commandes pour la date spécifiée qui ont un emplacement valide sont incluses.

Les commandes qui ne sont pas sélectionnées, mais qui sont déjà programmées pour des conducteurs qui seront utilisés dans l'optimisation seront déprogrammées à moins que l'indicateur includeScheduledOrders ne soit défini sur true.
includeScheduledOrders
optionnel
booléen
true
Détermine le comportement lorsqu'un sous-ensemble de commandes est sélectionné mais qu'il y a d'autres commandes déjà programmées pour les conducteurs concernés.
Si includeScheduledOrders est true, ces commandes seront incluses dans l'optimisation, sinon elles seront déprogrammées.

Réponse

Propriété Type / Valeur par défaut Description
success
obligatoire
booléen
-
true si l'optimisation a été lancée, false s'il y a eu une erreur.
code
optionnel
string
-
Un code d'erreur ou un code d'avertissement (non défini si l'opération a réussi).
planningId
optionnel
entier
-
Retourne l'identifiant de l'optimisation démarrée si l'opération a réussi, ou l'optimisation déjà en cours en cas d'erreur ERR_OPT_RUNNING_FOR_DATE. L'identifiant de planification peut être utilisé ultérieurement pour obtenir le statut de la planification ou arrêter le processus de planification.
missingOrders
optionnel
liste de chaînes de caractères
[]
En cas d'erreur ERR_ORD_NOT_FOUND, ce champ contiendra la liste des identifiants de commandes manquantes (orderNo strings).
missingDrivers
optionnel
liste d'objets SelectedDriver
[]
En cas d'erreur ERR_DRIVER_NOT_FOUND, ce champ contiendra une liste de conducteurs manquants. Chaque conducteur est un objet SelectedDriver.
ordersWithInvalidLocation
optionnel
liste de chaînes de caractères
[]
En cas d'erreur ERR_ORD_WITH_INVALID_LOC, ce champ contiendra la liste des identifiants de commandes (orderNo strings) ayant un emplacement invalide.

Codes d'erreur et d'avertissement

Les codes d'erreurs suivants sont applicables à la méthode Démarrer la Planification :

Code d'erreur Description
ERR_OPT_TRIAL_ENDED la version d'essai gratuite est terminée pour ce compte
ERR_OPT_RUNNING_FOR_DATE la planification est déjà en cours pour cette date
ERR_OPT_RUNNING_FOR_ORDER l'optimisation est déjà en cours pour une ou plusieurs commandes listées dans useOrders
ERR_OPT_NO_REQUESTS aucune commande n'existe pour la date spécifiée
ERR_OPT_NO_RESOURCES aucun conducteur n'est disponible pour cette date
ERR_OPT_RESOURCES_EXCEEDED nombre de conducteurs dépassé
ERR_OPT_REQUESTS_EXCEEDED nombre de commandes dépassé
ERR_OPT_COULD_NOT_START erreur interne, veuillez contacter le support
ERR_ORD_NOT_FOUND une ou plusieurs commandes spécifiées dans useOrders n'ont pas été trouvées
ERR_ORD_WITH_INVALID_LOC une ou plusieurs commandes spécifiées dans useOrders ont un emplacement invalide
ERR_DRIVER_NOT_FOUND un ou plusieurs conducteurs spécifiés dans useDrivers n'ont pas été trouvés
ERR_MULTIPLE_ORD_FOUND plusieurs commandes avec l'identifiant spécifié ont été trouvées
ERR_MULTIPLE_DRV plusieurs conducteurs avec l'identifiant spécifié ont été trouvés
ERR_UNSUPPORTED_BY_PRICING_PLAN la planification hebdomadaire est uniquement supportée avec le plan actuel
ERR_DATE_RANGE_TOO_LONG intervalle de planification hebdomadaire trop long
ERR_DATE_RANGE_INVALID intervalle invalide, la date to est antérieure à la date from

Arrêt de la Planification

Met fin au processus de planification.

Requête HTTP

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

reqbody.json est un fichier local contenant les données JSON à envoyer. Assurez-vous de remplacer AUTH_KEY par votre clé API.

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

Paramètres

Exemple de corps de requête :

{
  " planningId": 8828
}
Propriété Type / Valeur par défaut Description
planningId
obligatoire
entier
-
L'identifiant du processus de planification à arrêter.

Réponse

Propriété Type / Valeur par défaut Description
success
obligatoire
booléen
-
true si l'optimisation a été arrêtée, false s'il y a eu une erreur.
code
optionnel
chaîne de caractères
-
Un code d'erreur ou un code d'avertissement (non défini si l'opération a réussi).

Codes d'erreur et d'avertissement

Les codes d'erreur suivants sont applicables à la méthode Arrêt de la Planification :

Code d'erreur Description
ERR_JOB_NOT_FOUND tâche de planification avec l'identifiant spécifié n'a pas été trouvée
ERR_OPT_NOT_RUNNING tâche de planification n'est pas en cours d'exécution
ERR_OPT_COULD_NOT_STOP erreur interne, veuillez contacter le support

Obtenir le statut de la planification

Retourne le statut du processus de planification.

Requête HTTP

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

Assurez-vous de remplacer AUTH_KEY par votre clé API.

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

Paramètres

Propriété Type / Par défaut Description
planningId
obligatoire
entier
-
L'id du processus de planification.

Réponse

Propriété Type / Par défaut Description
success
obligatoire
booléen
-
true si la requête a réussi, false si une erreur s'est produite.
code
facultatif
chaîne de caractères
-
Un code d'erreur ou un code d'avertissement (non défini si l'opération a réussi).
status
facultatif
chaîne de caractères
-
N - Nouveau
R - En cours
C - Annulé par l'utilisateur
F - Terminé
E - Erreur survenue
percentageComplete
facultatif
entier
-
Pourcentage d'achèvement – les valeurs vont de 0 à 100.

Codes d'erreur et d'avertissement

Les codes d'erreur suivants s'appliquent à la méthode Obtenir le statut de la planification :

Code d'erreur Description
ERR_JOB_NOT_FOUND le travail de planification avec l'id spécifié n'a pas été trouvé

Mettre à jour les paramètres du conducteur

Met à jour les paramètres du conducteur pour une date particulière et les lieux de départ et d'arrivée du conducteur. Tout itinéraire existant pour la date et le conducteur spécifiés sera déprogrammé.

Les paramètres suivants peuvent être modifiés :

Requête HTTP

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

reqbody.json est un fichier local contenant les données JSON à envoyer. Assurez-vous de remplacer AUTH_KEY par votre clé API.

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

Paramètres

Exemple de corps de requête :

{
  "externalId": "3945300304540",
  "date": "2019-09-25",
  "workTimeFrom": "09:30",
  "workTimeTo": "18:00"
}
Propriété Type / Par défaut Description
externalId
obligatoire
string
-
L'identifiant externe attribué au conducteur dans l'administration des conducteurs.
date
obligatoire
date
-
Date à planifier.
Format AAAA-MM-JJ, par exemple 2013-12-20.
enabled
optionnel
booléen
inchangé
Activer ou désactiver le conducteur pour la date spécifiée.
workTimeFrom
optionnel
time (string)
inchangé
Heure de début de travail du conducteur pour la date spécifiée.
Format 24 heures (militaire), par exemple : 08:00.
Les valeurs valides vont de 00:00 à 23:59.
workTimeTo
optionnel
time (string)
inchangé
Heure de fin de travail du conducteur pour la date spécifiée.
Format 24 heures (militaire), par exemple : 08:00. Les valeurs valides vont de 00:00 à 23:59.
assignedVehicle
optionnel
string
inchangé
L'identifiant externe du véhicule à assigner au conducteur pour la date spécifiée. Cela mettra également à jour les paramètres de capacité de chargement du véhicule (sauf s'ils sont remplacés par les réglages vehicleCapacityX).
vehicleCapacity1
optionnel
entier
inchangé
La nouvelle capacité de chargement du véhicule #1 pour la date spécifiée.
vehicleCapacity2
optionnel
entier
inchangé
La nouvelle capacité de chargement du véhicule #2 pour la date spécifiée.
vehicleCapacity3
optionnel
entier
inchangé
La nouvelle capacité de chargement du véhicule #3 pour la date spécifiée.
vehicleCapacity4
optionnel
entier
inchangé
La nouvelle capacité de chargement du véhicule #4 pour la date spécifiée.
startLatitude
optionnel
décimal
inchangé
La latitude GPS du lieu de départ du conducteur sera modifiée (ce nouveau lieu sera utilisé pour toutes les futures optimisations). Si startLongitude n'est pas défini, cette valeur sera ignorée.
startLongitude
optionnel
décimal
inchangé
La longitude GPS du lieu de départ du conducteur (ce nouveau lieu sera utilisé pour toutes les futures optimisations). Si startLatitude n'est pas défini, cette valeur sera ignorée.
startAddress
optionnel
string
inchangé
L'adresse du lieu de départ du conducteur qui sera affichée sur les rapports (ce nouveau lieu sera utilisé pour toutes les futures optimisations). Si startLatitude et startLongitude ne sont pas définis, cette valeur sera ignorée.
endLatitude
optionnel
décimal
inchangé
La latitude GPS du lieu d'arrivée du conducteur (ce nouveau lieu sera utilisé pour toutes les futures optimisations). Si endLongitude n'est pas défini, cette valeur sera ignorée.
endLongitude
optionnel
décimal
inchangé
La longitude GPS du lieu d'arrivée du conducteur (ce nouveau lieu sera utilisé pour toutes les futures optimisations). Si endLatitude n'est pas défini, cette valeur sera ignorée.
endAddress
optionnel
string
inchangé
L'adresse du lieu d'arrivée du conducteur qui sera affichée sur les rapports (ce nouveau lieu sera utilisé pour toutes les futures optimisations). Si endLatitude et endLongitude ne sont pas définis, cette valeur sera ignorée.

Réponse

Propriété Type / Par défaut Description
success
obligatoire
booléen
-
true si les paramètres du conducteur ont été mis à jour, false si une erreur s'est produite.
code
optionnel
string
-
Un code d'erreur ou un code d'avertissement (non défini si l'opération a réussi).

Codes d'erreur et d'avertissement

Les codes d'erreur suivants s'appliquent à la méthode Mettre à jour les paramètres du conducteur :

Code d'erreur Description
ERR_DRIVER_NOT_FOUND le conducteur avec l'identifiant externalId spécifié n'a pas été trouvé
ERR_MULTIPLE_DRV plusieurs conducteurs avec l'identifiant externalId spécifié ont été trouvés
ERR_VEH_NOT_FOUND le véhicule avec l'identifiant externalId spécifié n'a pas été trouvé
ERR_MULTIPLE_VEH plusieurs véhicules avec l'identifiant externalId spécifié ont été trouvés

Mise à jour des paramètres des Conducteurs (en masse)

Met à jour les paramètres de plusieurs conducteurs pour les dates spécifiées. Les itinéraires existants pour les conducteurs et les dates spécifiés seront déprogrammés.

Les paramètres pour des dates particulières peuvent être modifiés :

Requête HTTP

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

reqbody.json est un fichier local contenant les données JSON à envoyer. Assurez-vous de remplacer AUTH_KEY par votre clé API.

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

Paramètres

Exemple de corps de requête :

{
  "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"
      }
    }
  ]
}
Propriété Type / Défaut Description
updates
obligatoire
liste de objets paramètres conducteur
-
Liste d'un ou plusieurs objets paramètres conducteur à mettre à jour dans le système. Au maximum 500 objets paramètres conducteur peuvent être spécifiés.

Objet DriverParameters

Propriété Type / Défaut Description
driver
obligatoire
objet
-
Un objet avec les propriétés de chaîne serial ou externalId qui identifie de manière unique le Conducteur. Exemple : {"serial": "102"} ou {"externalId": "444"}.
date
obligatoire
date
-
Date à planifier.
Format YYYY-MM-DD, par exemple 2013-12-20.
enabled
optionnel
booléen
inchangé
Activer ou désactiver le conducteur pour la date spécifiée.
workTime
optionnel
Objet WorkTime
inchangé
Temps de travail du conducteur de/à pour la date spécifiée.
assignedVehicle
optionnel
chaîne ou objet
inchangé
L'identifiant externe sous forme de chaîne ou d'un objet avec des propriétés de chaîne registration ou externalId qui identifie de manière unique le Véhicule à assigner au conducteur pour la date spécifiée. Cela mettra également à jour les paramètres de capacité de chargement du véhicule (sauf s'ils sont remplacés avec les paramètres vehicleCapacityX). Exemple : V103 ou {"registration": "444"} ou {"externalId": "V103"}.
vehicleCapacity1
optionnel
entier
inchangé
La nouvelle capacité de chargement du véhicule #1 pour la date spécifiée.
vehicleCapacity2
optionnel
entier
inchangé
La nouvelle capacité de chargement du véhicule #2 pour la date spécifiée.
vehicleCapacity3
optionnel
entier
inchangé
La nouvelle capacité de chargement du véhicule #3 pour la date spécifiée.
vehicleCapacity4
optionnel
entier
inchangé
La nouvelle capacité de chargement du véhicule #4 pour la date spécifiée.
startLocation
optionnel
Objet LocationType
inchangé
Lieu de départ GPS du conducteur (ce lieu sera utilisé pour les optimisations futures pour la date spécifiée). Le type de localisation startLocation ne peut pas être utilisé.
endLocation
optionnel
Objet LocationType
inchangé
Lieu d'arrivée GPS du conducteur (ce lieu sera utilisé pour les optimisations futures pour la date spécifiée).

Quand locationType est custom et qu'il n'y a pas de lieu avec les mêmes latitude, longitude et address, un nouveau lieu sera créé et visible dans l'administration des lieux. Le nom du lieu sera le même que l'adresse si définie, sinon le nom est généré à partir de la latitude et longitude.

Objet WorkTime

Propriété Type / Défaut Description
from
obligatoire
heure (chaîne)
-
Heure de début de travail du conducteur.
Format sur 24 heures (militaire), par exemple : 08:00.
Les valeurs valides varient de 00:00 à 23:59.
to
obligatoire
heure (chaîne)
-
Heure de fin de travail du conducteur.
Format sur 24 heures (militaire), par exemple : 08:00. Les valeurs valides varient de 00:00 à 23:59.

Objet LocationType

Propriété Type / Défaut Description
type
obligatoire
énumération de chaîne custom – la latitude, la longitude et l'adresse du lieu seront utilisées.

employeeDefault – le lieu par défaut de l'employé sera utilisé.

startLocation – le lieu de départ de l'employé sera utilisé.
address
optionnel
chaîne
-
Adresse du lieu qui sera affichée sur les rapports, par exemple 393 Hanover St, Boston, MA 02113, US.
latitude
optionnel
décimal
-
Latitude du lieu.
longitude
optionnel
décimal
-
Longitude du lieu.

La propriété type est obligatoire. Quand type est spécifié comme create, les propriétés obligatoires sont latitude et longitude, sinon seul type doit être défini.

Réponse

Exemple de réponse :

{
  "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": "Location is not valid.",
    },
    {
      "success": false,
      "driver": {
        "externalId": "003"
      },
      "date": "2022-02-17",
      "code": "ERR_DRIVER_NOT_FOUND",
      "message": "Could not find a driver with the matching id",
    },
    {
      "success": false,
      "driver": {
        "externalId": "010"
      },
      "date": "2022-02-18",
      "code": "ERR_MULTIPLE_DRV",
      "message": "Found multiple drivers with matching external id or serial number.",
    }
  ],
  "success": true
}
Propriété Type / Défaut Description
success
obligatoire
booléen
-
true si au moins une opération a réussi, false si tous ont échoué
updates
liste de objets réponse conducteur
-
Chaque objet conducteur dans la liste correspond au conducteur respectif dans la requête. Voir la section Objet Réponse Conducteur pour plus d'informations.

Objet Réponse Conducteur

Propriété Type / Défaut Description
success
obligatoire
booléen
-
true si l'opération a réussi, false s'il y a eu une erreur.
driver
optionnel
objet
-
Identifiant du conducteur respectif en tant qu'objet avec les propriétés de chaîne serial ou externalId.
date
optionnel
date
-
Date associée au conducteur respectif.
code
optionnel
chaîne
-
Un code d'erreur par commande (non défini si l'opération a réussi).
message
optionnel
chaîne
-
Une description d'erreur ou un avertissement (non défini si l'opération a réussi).

Codes d'erreur et d'avertissement

Les codes d'erreur suivants sont applicables à la méthode Update Drivers Parameters :

Code d'erreur Description
ERR_DRIVER_NOT_FOUND le conducteur avec l'externalId ou serial spécifié n'a pas été trouvé
ERR_MULTIPLE_DRV plusieurs conducteurs avec l'externalId ou serial spécifié ont été trouvés
ERR_VEH_NOT_FOUND le véhicule avec l'externalId ou serial spécifié n'a pas été trouvé
ERR_MULTIPLE_VEH plusieurs véhicules avec l'externalId ou serial spécifié ont été trouvés
ERR_LOC_NOT_VALID le type de localisation custom sans latitude et longitude a été trouvé

Obtenir les Événements Mobiles

Récupérez les événements mobiles tels que success, on_duty, failed, … pour le plan actuellement actif (c’est-à-dire le dernier plan qui a été envoyé aux conducteurs).

Chaque requête get_events retourne jusqu'à 500 événements qui ont eu lieu après le tag spécifié. Le résultat contiendra un nouveau tag que vous pourrez utiliser dans la prochaine requête get_events pour ignorer les événements déjà reçus.

Requête HTTP

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

Assurez-vous de remplacer AUTH_KEY par votre clé API.

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

Paramètres

Propriété Type / Défaut Description
after_tag
facultatif
string
-
Précisez le after_tag pour ne récupérer que les événements qui se sont produits depuis un appel spécifique antérieur à get_events.
Dans ce cas, le after_tag doit contenir le tag retourné dans l'appel précédent.
Voir l'exemple ci-dessous.

Réponse

Propriété Type / Défaut Description
success
obligatoire
boolean
-
true sauf si une erreur s'est produite.
events
facultatif
liste d'objets événementiels
[]
Une liste d'objets événementiels dans l'ordre où ils sont arrivés des applications mobiles des conducteurs.
tag
facultatif
string
-
Tag qui marque le moment du dernier événement reçu dans cette réponse. Utilisez-le pour spécifier le paramètre de requête after_tag dans la prochaine requête get_events.
remainingEvents
facultatif
integer
inchangé
Le nombre d'événements qui se sont produits mais n'ont pas été récupérés dans cette réponse (dans chaque réponse au maximum 500 événements sont retournés).

Objet Événement

Propriété Type Description
event
obligatoire
string Type d'événement. Actuellement l'un des suivants :
on_duty – le conducteur est en service
off_duty – le conducteur est hors service
start_service - le conducteur a commencé le service
success – la commande spécifiée a été complétée avec succès
failed – le conducteur n'a pas réussi à compléter la commande
rejected – le conducteur a rejeté la commande
start_route – le conducteur a commencé l'itinéraire
end_route – le conducteur a terminé l'itinéraire
start_time_changed – le conducteur a modifié l'heure de début planifiée
unixTimestamp
obligatoire
integer Le moment où l'événement s'est produit.
Nombre de secondes écoulées depuis 00:00 UTC le 1er janvier 1970.
utcTime
obligatoire
date ISO 8601 (string) La date et l'heure UTC auxquelles l'événement spécifié s'est produit.
localTime
obligatoire
date ISO 8601 (string) L'heure locale à l'emplacement de la commande où l'événement spécifié s'est produit.
driverName
facultatif
string Le nom du conducteur.
Sera envoyé pour les événements liés à un conducteur spécifique.
driverSerial
facultatif
string Le numéro de série du conducteur.
Ne sera pas envoyé si vide ou si l'événement n'est pas lié à un conducteur spécifique.
driverExternalId
facultatif
string L'identifiant externe du conducteur.
Ne sera pas envoyé si vide ou si l'événement n'est pas lié à un conducteur spécifique.
orderNo
facultatif
string L'identifiant de la commande affectée.
Non envoyé pour certains événements tels que on_duty.
orderId
facultatif
string
-
L'identifiant unique en lecture seule de la commande affectée, attribué par OptimoRoute.
Non envoyé pour certains événements tels que on_duty.
plannedStartTime
facultatif
Objet Temps L'heure à laquelle le conducteur prévoit de démarrer l'itinéraire.
Sera inclus uniquement avec l'événement start_time_changed.

Les champs d'événement retournés unixTimestamp, utcTime et localTime se réfèrent tous au même moment où l'événement s'est produit, donc vous pouvez utiliser celui qui est le plus pratique.

Veuillez noter que certains appareils mobiles peuvent être temporairement hors ligne et ils synchroniseront leurs événements seulement après s'être reconnectés, de sorte que les événements que vous recevrez pourraient arriver hors ordre chronologique. Par exemple, le premier conducteur pourrait terminer avec succès la commande 001 à 9h00, mais pourrait être hors ligne jusqu'à 09h15. Le deuxième conducteur pourrait terminer la commande 002 à 9h10, mais être en ligne tout le temps. Le serveur recevra d'abord l'événement pour la commande 002 puis seulement l'événement pour la commande 001.

Exemples

Dans la première requête, nous ne spécifierons pas le paramètre after_tag (nous le laisserons vide) :

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

Réponse :

{
  "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
}

Nous allons relancer la requête dans 10 secondes, mais cette fois nous utiliserons le tag que nous avons reçu dans le dernier résultat comme notre paramètre after_tag :

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

Réponse :

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

Il n'y avait pas de nouveaux événements entre-temps. Nous allons relancer la requête dans 10 secondes :

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

Réponse :

{
  "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
}

Obtenir l'achèvement de la commande

Récupérez les détails de l'achèvement pour une ou plusieurs commandes, une fois qu'elles ont été complétées. Pour des mises à jour en temps réel du statut de la commande, veuillez utiliser le point de terminaison des événements mobiles.

Requête HTTP

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

reqbody.json est un fichier local contenant les données JSON à poster. Assurez-vous de remplacer AUTH_KEY par votre clé API.

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

Paramètres

Exemple de corps de requête POST :

{
  "orders": [
    {
      "orderNo": "ORD001"
    },
    {
      "orderNo": "ORD99"
    },
    {
      "orderNo": "ORD55"
    },
    {
      "orderNo": "XXXYZ"
    },
    {
      "id": "84e5e94d341dc637ff77b56ea96cb8e3",
    }
  ]
}
Propriété Type / Par défaut Description
orders
obligatoire
liste d'objets commande
-
Liste d'objets commande dont les détails d'achèvement seront récupérés. Chaque objet commande peut contenir soit :
  • orderNo: l'identifiant spécifié par l'utilisateur d'une commande
  • id: l'identifiant unique de la commande, attribué par OptimoRoute
Au maximum 500 commandes peuvent être spécifiées.



Pour plus de flexibilité, l'appel à get_completion_details peut également être effectué sous forme de requête HTTP GET :

Exemple de requête GET :

curl 'https://api.optimoroute.com/v1/get_completion_details?key=AUTH_KEY&orderNo=ORD001&orderNo=ORD99&orderNo=ORD55&orderNo=XXXYZ'
Propriété Type / Par défaut Description
orderNo
obligatoire
chaîne
-
L'identifiant spécifié par l'utilisateur d'une commande ; peut être répété pour récupérer les détails d'achèvement pour plusieurs commandes.

Réponse

Réponse :

{
  "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
}
Propriété Type / Par défaut Description
success
obligatoire
booléen
-
true si les détails d'achèvement d'au moins une commande ont été récupérés, false si aucune commande n'a été récupérée.
orders
optionnel
liste d'objets de réponse d'achèvement
[]
Une liste d'objets contenant les détails d'achèvement de la commande, un pour chaque commande demandée.

Objet de réponse d'achèvement

Propriété Type / Par défaut Description
orderNo
optionnel
chaîne
-
L'identifiant de la commande. Présent uniquement si orderNo a été utilisé dans la requête.
id
optionnel
chaîne
-
L'identifiant unique de la commande, attribué par OptimoRoute. Présent uniquement si id a été utilisé dans la requête.
success
obligatoire
booléen
-
true si l'opération a réussi, false s'il y a eu une erreur.
code
optionnel
chaîne
-
Un code d'erreur ou un code d'avertissement (non défini si l'opération a réussi).
message
optionnel
chaîne
-
Une description de l'erreur ou une description de l'avertissement (non défini si l'opération a réussi).
data
optionnel
objet
{}
Objet contenant le statut et les métadonnées d'achèvement de la commande. Voir les champs des détails d'achèvement pour les clés possibles.

Champs des détails de l'achèvement

L'objet des détails de l'achèvement retourné contiendra les champs décrits ci-dessous, selon que la commande a été complétée ou non, comment la collecte de la Preuve de livraison est configurée et ce qui a été rempli. L'objet des détails de l'achèvement retourné peut également contenir des champs supplémentaires non encore décrits ici.

Propriété Type / Par défaut Description
status
obligatoire
chaîne
-
Statut de la commande, voir les valeurs possibles : Valeurs de statut de la commande.
startTime
optionnel
Objet Temps
-
Heure à laquelle le service de commande a commencé.
Présent uniquement pour les commandes avec le statut servicing, success ou failed.
endTime
optionnel
Objet Temps
-
Heure à laquelle le service de commande a été complété (marqué avec le statut success ou failed).
Présent uniquement pour les commandes avec le statut success ou failed.
form
optionnel
Objet de données de formulaire Contient les valeurs remplies depuis l'application mobile lors de la complétion de la commande.
Présent uniquement si la Preuve de livraison est configurée.
tracking_url
optionnel
chaîne Un lien vers la page de suivi de commande en temps réel. Présent uniquement si une commande a été assignée à un numéro de suivi. Le numéro de suivi est assigné lorsque les plans sont envoyés au conducteur ou que les notifications client ont été envoyées. Le suivi de commande doit être activé.

Valeurs de statut de la commande

Valeur Description
unscheduled La commande n'a pas été planifiée
scheduled La commande n'a pas encore été lancée
on_route Le conducteur est en route vers l'emplacement de la commande
servicing La commande est en cours d'exécution
success La commande a été complétée avec succès
failed Le conducteur n'a pas réussi à compléter la commande
rejected La commande a été rejetée par le conducteur
cancelled La commande a été annulée par le client

Objet Temps

Propriété Type Description
unixTimestamp
obligatoire
entier Nombre de secondes écoulées depuis 00:00 UTC 1er janvier 1970.
utcTime
obligatoire
date ISO 8601 (chaîne) La date et l'heure UTC
localTime
obligatoire
date ISO 8601 (chaîne) L'heure locale à l'emplacement de la commande.

Les champs unixTimestamp, utcTime et localTime font tous référence au même moment, vous pouvez donc utiliser celui qui est le plus pratique.

Objet de données de formulaire

Tous les champs des données de formulaire sont optionnels et l'objet peut contenir des champs supplémentaires non répertoriés ici.

Propriété Type Description
note
optionnel
chaîne Le texte de la note incluse lors de la complétion de la commande.
Présent uniquement si configuré dans le cadre de la Preuve de livraison et si une note a été remplie.
signature
optionnel
objet Pièce jointe image L'objet décrit le fichier image de la signature jointe
Présent uniquement si configuré dans le cadre de la Preuve de livraison et si une signature a été remplie.
images
optionnel
liste d'objets Pièce jointe image L'objet liste les images jointes
Présent uniquement si configuré dans le cadre de la Preuve de livraison et si des images ont été prises.
barcode
optionnel
liste d'objets Scan de codes-barres L'objet décrit les détails d'achèvement des codes-barres attachés
Présent uniquement si un code-barres pré-attaché à une commande a été scanné.
barcode_collections
optionnel
liste d'objets Scan de codes-barres L'objet décrit les codes-barres collectés avec la commande
Présent uniquement si configuré dans le cadre du flux de travail de l'application pour conducteur et si un code-barres imprévu a été scanné pendant une collecte avec une commande.

Objet Pièce jointe image

Propriété Type Description
type
obligatoire
chaîne Le type MIME de l'image jointe, généralement image/png ou image/jpeg.
url
obligatoire
chaîne L'URL à laquelle le fichier image peut être téléchargé. L'URL inclura des jetons d'authentification temporaires et sera valable pendant au moins 5 jours, mais pas indéfiniment.

Objet Scan de codes-barres

Propriété Type Description
barcode chaîne Le code-barres attaché à la commande. Peut être vide si le code-barres est ajouté au lieu de scanner le code-barres pré-attaché (par exemple, collecte d'article lors d'une livraison)
scanInfo objet Info de codes-barres Objet décrivant le statut du scan du code-barres et d'autres informations

Objet Info de codes-barres

Propriété Type Description
status
obligatoire
Statut de codes-barres Décrit le statut d'un scan de codes-barres
scanned
optionnel
chaîne Code-barres qui a effectivement été scanné. Peut différer du code-barres attendu selon le statut.
images
optionnel
liste d'objets Pièce jointe image Images remplaçant le code-barres scanné lorsque le code-barres lui-même n'est pas scannable. Peut être présent avec le statut unscannable.
type
optionnel
chaîne Le type du code-barres scanné s'il a pu être déduit au moment du scan.
Les types pris en charge incluent : code-128, code-39, code-93, codabar, ean-13, ean-8, itf, upc-e, upc-a, qr, pdf-417, aztec, data-matrix.

Statut de codes-barres

Code de statut Description
success le code-barres correct a été scanné, la valeur correspond à celle attachée à la commande
unscannable le code-barres n'était pas scannable. Peut avoir des images jointes selon la configuration
added un code-barres non planifié a été scanné et son code-barres a été ajouté
replaced le code-barres a été remplacé au moment de la livraison. La propriété scanned montre la nouvelle valeur
missing l'article n'était pas disponible lors de la livraison

Codes d'erreur et d'avertissement

Dans le cas où success est faux, data ne sera pas envoyé et le champ code contiendra l'un des codes d'erreur suivants par commande :

Code d'erreur Description
ERR_ORD_NOT_FOUND la commande avec le orderNo correspondant n'a pas été trouvée
ERR_MULTIPLE_ORD_FOUND il y a plusieurs commandes correspondant au orderNo

Mise à jour de l'achèvement des commandes

Mettre à jour les détails d'achèvement pour une ou plusieurs commandes.

Requête HTTP

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

reqbody.json est un fichier local contenant les données JSON à poster.
Assurez-vous de remplacer AUTH_KEY par votre clé API.

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

Paramètres

Exemple de corps de requête 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"
          }
      }
    }
  ],
}

Propriété Type / Par défaut Description
updates
obligatoire
liste d'objets de mise à jour des détails d'achèvement
[]
Une liste de détails de l'achèvement des commandes à mettre à jour. Au maximum 500 objets de détails d'achèvement peuvent être spécifiés.

Objet de mise à jour des détails d'achèvement

Propriété Type / Par défaut Description
orderNo
optionnel
chaîne
-
L'identifiant de la commande. Obligatoire si id n'est pas spécifié.
id
optionnel
chaîne
-
L'identifiant unique de la commande, attribué par OptimoRoute. Obligatoire si orderNo n'a pas été spécifié.
data
optionnel
objet
{}
Objet contenant le statut d'achèvement de la commande et les métadonnées. Voir les champs de mise à jour des détails d'achèvement pour les clés possibles.

Champs de mise à jour des détails d'achèvement

Propriété Type / Par défaut Description
status
obligatoire
chaîne
-
Statut de la commande, voir valeurs possibles : Valeurs de statut de commande
startTime
optionnel
Objet de mise à jour du temps
-
Heure de début du service de commande.
Présent seulement pour les commandes avec le statut servicing, success ou failed.
endTime
optionnel
Objet de mise à jour du temps
-
Heure à laquelle le service de commande a été terminé (marqué avec soit le statut success ou failed.
Présent seulement pour les commandes avec le statut success ou failed.

Objet de mise à jour du temps

Propriété Type Description
unixTimestamp
optionnel
entier Nombre de secondes écoulées depuis 00:00 UTC le 1er janvier 1970.
utcTime
optionnel
date ISO 8601 (chaîne) La date et l'heure UTC. Ignoré si unixTimestamp est spécifié.
localTime
optionnel
date ISO 8601 (chaîne) L'heure locale sur le lieu de la commande. Ignoré si unixTimestamp ou utcTime sont spécifiés.

Au moins un des champs unixTimestamp, utcTime, localTime doit être spécifié.

Réponse

Réponse :

{
  "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
}
Propriété Type / Par défaut Description
success
obligatoire
booléen
-
true si les détails d'achèvement d'au moins une commande ont été mis à jour, false si aucun détail d'achèvement de commande n'a été mis à jour.
updates
optionnel
liste d'objets de réponse de l'achèvement
[]
Une liste d'objets contenant les détails de l'achèvement des commandes, un pour chaque mise à jour demandée. Objet de réponse d'achèvement

Mettre à jour les positions des conducteurs (en masse)

Met à jour les positions de plusieurs conducteurs à des horodatages donnés.

Requête HTTP

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

reqbody.json est un fichier local contenant les données JSON à publier. Assurez-vous de remplacer AUTH_KEY par votre clé API.

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

Paramètres

Exemple de corps de requête :

{
  "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
        }
      ]
    }
  ]
}
Propriété Type / Par défaut Description
updates
obligatoire
liste d'objets Positions de Conducteurs
-
Liste d'objets spécifiant chacun les positions pour un conducteur. Au plus un objet pour un conducteur unique peut être spécifié.

Objet de Positions de Conducteurs

Propriété Type / Par défaut Description
driver
obligatoire
objet
-
Un objet avec les propriétés de chaîne serial ou externalId qui identifient de manière unique le Conducteur. Exemple : {"serial": "102"} ou {"externalId": "444"}.
positions
obligatoire
liste d'objets Position
-
liste de positions au fil du temps. Au plus 100 positions peuvent être spécifiées pour un seul conducteur.

Objet de Position

Propriété Type / Par défaut Description
timestamp
obligatoire
entier Le moment où l'événement s'est produit.
Nombre de secondes écoulées depuis 00:00 UTC le 1er janvier 1970.
latitude
obligatoire
décimal
-
Latitude de position en degrés.
longitude
obligatoire
décimal
-
Longitude de position en degrés.
accuracy
optionnel
décimal
-
Rayon d'incertitude pour l'emplacement en mètres.
speed
optionnel
décimal
-
Vitesse en mètres par seconde.
heading
optionnel
décimal
-
Direction de déplacement en degrés, 0 indiquant le nord, 90 l'est, 180 le sud, ...

Réponse

Exemple de réponse :

{
  "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
}
Propriété Type / Par défaut Description
success
obligatoire
booléen
-
true si au moins une opération a réussi, false si toutes ont échoué
updates
liste d'objets Réponse Conducteurs
-
Chaque Objet de Réponse Conducteurs dans la liste correspond à l'objet de Positions de Conducteurs respectif dans la requête.

Objet de Réponse Conducteurs

Propriété Type / Par défaut Description
success
obligatoire
booléen
-
true si l'opération a réussi, false s'il y a eu une erreur.
driver
optionnel
objet
-
Identifiant du conducteur respectif sous forme d'objet avec les propriétés de chaîne serial ou externalId.
code
optionnel
chaîne
-
Un code d'erreur par commande (non défini si l'opération a réussi).
message
optionnel
chaîne
-
Une description d'erreur ou d'avertissement (non défini si l'opération a réussi).

Codes d'erreur et d'avertissement

Les codes d'erreur suivants sont applicables à la méthode Mettre à jour les positions des conducteurs :

Code d'erreur Description
ERR_DRIVER_NOT_FOUND le conducteur avec le externalId ou serial spécifié n'a pas été trouvé
ERR_MULTIPLE_DRV plusieurs conducteurs avec le externalId ou serial spécifié ont été trouvés
ERR_MULTIPLE_DRV_POS plusieurs objets de positions de conducteurs spécifiés pour un conducteur unique

Recherche de Commandes

Récupère une ou plusieurs commandes du système.

Requête HTTP

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

reqbody.json est un fichier local contenant les données JSON à poster. Assurez-vous de remplacer AUTH_KEY par votre clé API.

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

Paramètres

Exemples de corps de requête :

{
  "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
}
Propriété Type / Par défaut Description
orders liste d'objets commande
-
Liste des objets commande à récupérer. Chaque objet commande peut contenir soit :
  • orderNo: l'identifiant spécifié par l'utilisateur d'une commande
  • id: l'identifiant unique de la commande, assigné par OptimoRoute
Au maximum 500 commandes peuvent être spécifiées.
dateRange objet de plage de dates Un objet avec les champs from et to, par exemple :
{"from": "2022-01-01", "to": "2022-01-03"}. La plage peut s'étendre sur au plus 35 jours, soit 5 semaines.
orderStatus
optionnel
liste de chaînes
-
Liste de chaînes d'état de commande, pour éventuellement filtrer les commandes récupérées par statut.
Voir les valeurs possibles : Valeurs de statut de commande.
includeOrderData
optionnel
booléen
false
Mettez ce paramètre à true si vous devez récupérer les données de commande pour les commandes trouvées
includeScheduleInformation
optionnel
booléen
false
Mettez ce paramètre à true si vous devez récupérer les informations de planification de commande
after_tag
optionnel
chaîne
-
Spécifiez le after_tag pour récupérer uniquement la page suivante de résultats d'un appel précédent à cet endpoint.
Dans ce cas, tous les paramètres doivent être répétés avec les mêmes valeurs que l'appel précédent, et le after_tag doit contenir la valeur renvoyée dans l'appel précédent.

Au moins une des propriétés orders ou dateRange doit être spécifiée dans la requête.

Réponse

Exemple de réponse avec 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": "Révision 5",
        "customField2": "184.5",
        "customField3": "",
        "customField4": "",
        "customField5": "",
        "id": "cd013f61ad8155802ad4321f2b411f4f",
        "assignedTo": null,
        "location": {
          "locationNo": "T1275",
          "locationName": "T1275",
          "address": "Moneta, VA 24121, États-Unis",
          "latitude": 37.2636426,
          "longitude": -79.6105659,
          "notes": "",
          "valid": true,
          "checkInTime": 0
        },
        "skills": ["VA"],
        "vehicleFeatures": [],
        "timeWindows": [],
        "notificationPreference": "dont_notify",
        "allowedWeekdays": ["mon", "tue", "wed", "thu"],
        "allowedDates": {}
      }
    }
  ]
}

Exemple de réponse avec includeScheduleInformation; présence de after_tag après seulement 2 résultats exagérée pour illustration uniquement.

{
  "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="
}
Propriété Type / Par défaut Description
success
obligatoire
booléen
-
Cela sera false s'il y a eu une erreur et qu'aucune commande n'a été récupérée
orders
obligatoire
liste d'objets réponse commande
-
Chaque objet de la liste représente une commande trouvée dans le système. Voir la section Objet de Réponse de Commande pour plus d'informations.
Jusqu'à 500 commandes seront retournées en un seul appel. Utilisez after_tag pour récupérer les pages restantes.
after_tag
optionnel
chaîne
-
Présent uniquement s'il y a plus de pages de résultats à récupérer. Pour récupérer la page suivante de résultats, répétez l'appel à cet endpoint avec le paramètre after_tag et tous les autres paramètres avec les mêmes valeurs.

Objet de Réponse de Commande

Propriété Type / Par défaut Description
id
obligatoire
chaîne
-
L'identifiant unique de la commande, assigné par OptimoRoute.
data
optionnel
Objet commande
-
Les données de commande récupérées; présentes seulement si includeOrderData est défini sur true
scheduleInformation
optionnel
objet info de planification
-
Les informations de planification de commande; présentes seulement si includeScheduleInformation est défini sur true. Cela sera null si la commande n'est pas planifiée.