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 :
- la requête entière peut échouer (par exemple, une erreur sérieuse de validation ou de programmation). La réponse contiendra un code d'erreur.
- l'opération a échoué pour certaines commandes, mais a réussi pour d'autres. La réponse contiendra une liste dans laquelle certains objets ont un code d'erreur.
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 – BasseM – MoyenneH – HauteC – CritiqueLes 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 smsLa 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 :
|
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 typeSélection unique
oùapple
est une option clé,quantity
est de typeNombre
avec 0 décimales,purity
est de typeNombre
avec 2 décimales etinstructions
est de typeTexte
) :
{
"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 :
locationNo
Le numéro du lieu déjà existant dans le système. Un lieu existant est utilisé.
NOTE : l'address
, lalatitude
+longitude
et lelocationName
ne doivent PAS être spécifiés, sinon le système essaiera de géocoder à nouveau l'emplacement ou d'en créer un avec une position GPS définie.latitude
+longitude
+locationName
(avecaddress
etlocationNo
facultatifs)
Le lieu est défini par la latitude et la longitude.
Le nom de l'emplacement sera défini sur la valeur du champlocationName
.
L'adresse du lieu sera définie suraddress
siaddress
est défini, sinon elle restera vide.
Le numéro du lieu sera défini surlocationNo
silocationNo
est défini, sinon il restera vide.address
(aveclocationName
etlocationNo
facultatifs)
Le système essaiera de trouver des lieux existants avec l'address
spécifiée (etlocationName
si un est spécifié). Si un lieu existant n'est pas trouvé, l'adresse de l'emplacement sera géocodée sur la base de l'adresse fournie.
Le nom du lieu sera défini sur le champlocationName
silocationName
est fourni, sinon il sera défini sur la valeur du champ de l'adresse.
Le numéro de l'emplacement sera défini surlocationNo
silocationNo
est défini, sinon il restera vide.
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 :
- si
id
est donné, la commande existante sera mise à jour avec les valeurs fournies ;- les propriétés non fournies dans la requête garderont leurs valeurs existantes
- si
id
n'est pas donné, etorderNo
n'est pas donné ou aucune commande n'est trouvée, une nouvelle commande sera créée ;- les propriétés
date
etlocation
sont obligatoires - les propriétés
duration
ettype
utiliseront les valeurs par défaut configurées dans OptimoRoute - d'autres propriétés peuvent être omises, auquel cas les valeurs par défaut listées dans Objet Commande seront utilisées
- les propriétés
- si
id
n'est pas donné, et une commande existante avec unorderNo
correspondant est trouvée, la commande existante sera mise à jour avec les valeurs fournies ;- les propriétés non fournies dans la requête garderont leurs valeurs existantes
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 :
|
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 |
booleanfalse |
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 :
|
deleteMultiple optionnel |
booléenfalse |
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éenfalse |
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éenfalse |
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éenfalse |
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 |
entier0 |
Chargement #1 de l'itinéraire. |
load2 obligatoire |
entier0 |
Chargement #2 de l'itinéraire. |
load3 obligatoire |
entier0 |
Chargement #3 de l'itinéraire. |
load4 obligatoire |
entier0 |
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 |
stringOFF |
Paramètres d'équilibrage des itinéraires. Valeurs autorisées :OFF – Pas d'équilibrageON – Équilibrer les itinérairesON_FORCE – Équilibrer les itinéraires et utiliser tous les conducteursPas 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 |
stringWT |
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 travailNUM – Nombre de commandes par conducteur |
balancingFactor optionnel |
décimal0.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 |
stringEMPTY |
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éroCURRENT – Commencer la planification avec les itinéraires existants |
lockType optionnel |
stringNONE |
Applicable si startWith est défini sur CURRENT .Valeurs autorisées : NONE – Permet tous les changements sur les itinéraires existantsROUTES - Conserve les itinéraires planifiés inchangés et ajoute de nouvelles commandes à ceux inutilisésRESOURCES - Conserve les conducteurs/véhicules pour les commandes planifiées et intègre de nouvelles commandes |
depotTrips optionnel |
booléenfalse |
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 |
entier0 |
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éenfalse |
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 :
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éentrue |
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 - NouveauR - En coursC - Annulé par l'utilisateurF - 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 :
- Activer/désactiver le conducteur
- Heure de travail du conducteur à partir de
- Heure de travail du conducteur jusqu'à
- Véhicule assigné
- Capacité de chargement du véhicule #1
- Capacité de chargement du véhicule #2
- Capacité de chargement du véhicule #3
- Capacité de chargement du véhicule #4
- Lieu de départ du conducteur
- Lieu d'arrivée du conducteur
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 :
- Activer/désactiver le conducteur
- Heure de travail du conducteur de
- Heure de travail du conducteur à
- Lieu de départ du conducteur
- Lieu d'arrivée du conducteur
- Véhicule assigné
- Capacité de chargement du véhicule #1
- Capacité de chargement du véhicule #2
- Capacité de chargement du véhicule #3
- Capacité de chargement du véhicule #4
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 serviceoff_duty – le conducteur est hors servicestart_service - le conducteur a commencé le servicesuccess – la commande spécifiée a été complétée avec succèsfailed – le conducteur n'a pas réussi à compléter la commanderejected – le conducteur a rejeté la commandestart_route – le conducteur a commencé l'itinéraireend_route – le conducteur a terminé l'itinérairestart_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 :
|
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 remplacerAUTH_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 :
|
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éenfalse |
Mettez ce paramètre à true si vous devez récupérer les données de commande pour les commandes trouvées |
includeScheduleInformation optionnel |
booléenfalse |
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 deafter_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. |