Einführung

Dieses Dokument ist die offizielle Referenz für die OptimoRoute Web Service Application Programming Interface (WS API).

Unsere Webdienst-API basiert auf HTTP

Die Methoden zum Abrufen von Daten aus unserer Webdienst-API erfordern eine HTTP-GET-Anfragemethode.

Die Methoden, die Daten einreichen, ändern oder löschen, erfordern eine POST-Anfragemethode.

Die API-Methoden geben einen Fehler zurück, wenn die Anfrage nicht mit der korrekten HTTP-Methode erfolgt.

Wir verwenden JSON für den strukturierten Datenaustausch

Unsere API verwendet das JSON (JavaScript Object Notation) Format.

Weitere Informationen zu JSON und wie es funktioniert, finden Sie hier: http://json.org/ und hier: http://en.wikipedia.org/wiki/JSON.

Es gibt viele leicht verfügbare Bibliotheken, um in das JSON-Format zu konvertieren und davon zu konvertieren, sowohl für populäre als auch für ungewöhnlichere Programmiersprachen.

SSL ist erforderlich

Die Nutzung von SSL (https) ist erforderlich, um zu vermeiden, dass der Authentifizierungsschlüssel und potenziell vertrauliche Daten im Klartext über das Web übertragen werden.

Begrenzte Anzahl gleichzeitiger Anfragen

Die maximale Anzahl gleichzeitiger Webdienst-API-Anfragen für ein Konto oder eine IP-Adresse ist auf 5 begrenzt.

Allgemeine Fehlercodes

Die folgenden Fehlercodes sind für alle API-Operationen anwendbar:

Es gibt auch spezifische Fehlercodes, die im Abschnitt Fehler- und Warncodes jeder Methode beschrieben sind.

Fehlercodes bei Massenoperationen

Bei Massenoperationen gibt es mehrere Fehlermodi. Zum Beispiel, wenn eine Massenoperation bei Bestellungen durchgeführt wird:

• Die gesamte Anfrage kann fehlschlagen (z.B. ein ernsthafter Validierungs- oder Programmierfehler). Die Antwort wird einen Fehlercode enthalten.
• Die Operation schlug bei einigen Bestellungen fehl, war aber bei anderen erfolgreich. Die Antwort wird eine Liste enthalten, in der einige Objekte einen Fehlercode haben.

Zusätzliche Felder in den Antwortnachrichten zulassen

Zusätzliche Felder könnten in Zukunft zu den JSON-Antwortnachrichten hinzugefügt werden, daher sollte Ihr Client-Code zusätzliche Felder ignorieren.  

Authentifizierung

Der OptimoRoute Webdienst-API-Authentifizierungsschlüsselparameter ist bei allen API-Anfragen erforderlich, zusätzlich zu allen Standardparametern.

Um die API zu aktivieren und den API-Schlüssel zu generieren, melden Sie sich bitte in der OptimoRoute-Webanwendung an. Wählen Sie im Abschnitt Administration die Option Einstellungen -> WS API aus und aktivieren Sie die API. Der API-Schlüssel wird für Sie generiert.

Die Webdienst-API ist auch während der kostenlosen Testphase verfügbar.

Datenobjekte

Einige Endpunkte in der API teilen Definitionen von Objekten, die in der Anfrage und der Antwort gesendet werden.

Bestellobjekt

Beispiel Bestellobjekt

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

Standortobjekt

Standortobjekt-Beispiel mit GPS-Koordinaten:

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

Ausgewähltes Fahrerobjekt

Verwenden Sie entweder driverExternalId oder driverSerial (ein Feld reicht aus):

Zeitobjekt

Die Felder unixTimestamp, utcTime und localTime beziehen sich alle auf denselben Moment, sodass Sie dasjenige verwenden können, das am praktischsten ist.

Benutzerdefiniertes Feldobjekt

Das Benutzerdefinierte Feldobjekt kann beliebig viele Eigenschaften enthalten, wobei jeder Eigenschaftenname mit dem Schlüssel eines benutzerdefinierten Feldes übereinstimmt, das in OptimoRoute konfiguriert ist.

Benutzerdefiniertes Feldobjekt-Beispiel (fruit_type ist vom Typ Einzelauswahl, wobei apple ein Optionsschlüssel ist, quantity ist vom Typ Zahl mit 0 Dezimalstellen, purity ist vom Typ Zahl mit 2 Dezimalstellen und instructions ist vom Typ Text):

{
  "fruit_type": "apple",
  "quantity": 100,
  "purity": 99.99,
  "instructions": "Deliver to the customer's door."
}

HINWEIS: Kontaktieren Sie den OptimoRoute-Support, um die neuen benutzerdefinierten Felder zu aktivieren. Legacy-Benutzerdefinierte Felder (benutzerdefinierte Felder mit Schlüsseln custom_field_1 bis custom_field_5) sollten nicht in diesem Objekt enthalten sein - diese werden mit den separaten Feldern im Bestellobjekt (customField1 bis customField5) eingestellt.

Bestellung erstellen

Erstellt eine neue Bestellung im System oder aktualisiert eine vorhandene Bestellung.

HTTP-Anfrage

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

reqbody.json ist eine lokale Datei, die die zu sendenden JSON-Daten enthält.
Stellen Sie sicher, AUTH_KEY mit Ihrem API-Schlüssel zu ersetzen.

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

Parameter

Beispiel für Anforderungskörper:

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

Zusätzlich zu den Eigenschaften des Bestellobjekts sind folgende Eigenschaften verfügbar:

Die Eigenschaft operation ist obligatorisch. Wenn operation als UPDATE angegeben ist, sind einer von orderNo oder id obligatorisch, ansonsten sind die obligatorischen Eigenschaften date, type, location und einer von orderNo oder id.

Standortobjekt

Beispiel für ein Standortobjekt, das die Adresse zur Geokodierung angibt und jedes Resultat akzeptiert:

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

Zusätzlich zu den Eigenschaften aus dem Standortobjekt sind folgende Eigenschaften verfügbar:

Ein Standort ist durch einen der folgenden Punkte definiert:

• locationNo
  Die Standortnummer eines bereits im System vorhandenen Standorts. Ein vorhandener Standort wird verwendet.
  HINWEIS: Die address, latitude + longitude und locationName sollten NICHT angegeben werden, da das System ansonsten versuchen wird, den Standort erneut zu geokodieren oder einen mit einer definierten GPS-Position zu erstellen.
• latitude + longitude + locationName (mit optionalem address und locationNo)
  Der Standort wird durch Breitengrad und Längengrad definiert.
  Der Standortname wird auf den Wert des locationName-Felds gesetzt.
  Die Standortadresse wird auf address gesetzt, wenn address angegeben ist, andernfalls bleibt sie leer.
  Die Standortnummer wird auf locationNo gesetzt, wenn locationNo angegeben ist, andernfalls bleibt sie leer.
• address (mit optionalem locationName und locationNo)
  Das System wird versuchen, bestehende Standorte mit der angegebenen address (und locationName, wenn einer angegeben ist) zu finden. Wenn kein vorhandener Standort gefunden wird, wird die Standortadresse basierend auf der angegebenen Adresse geokodiert.
  Der Standortname wird auf den Wert des locationName-Felds gesetzt, wenn locationName angegeben ist, andernfalls wird er auf den Wert des Adressfeldes gesetzt.
  Die Standortnummer wird auf locationNo gesetzt, wenn locationNo angegeben ist, andernfalls bleibt sie leer.

Antwort

Antwort auf die Beispielanfrage:

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

Fehler- und Warnungscodes

Die folgenden Fehlercodes sind für die Bestellung erstellen-Methode anwendbar:

Erstellen oder Aktualisieren von Aufträgen (Massenverarbeitung)

Erstellen, aktualisieren oder ersetzen Sie einen oder mehrere Aufträge im System.

Beachten Sie, dass die Geokodierung von Adressen in diesem Aufruf nicht verfügbar ist. Die Standorte für Aufträge müssen entweder im System existieren oder mittels Breiten- und Längengradkoordinaten angegeben werden. Geokodierung ist verfügbar bei Auftrag Erstellen.

HTTP-Anfrage

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

reqbody.json ist eine lokale Datei, die die zu postenden JSON-Daten enthält. Stellen Sie sicher, AUTH_KEY durch Ihren API-Schlüssel zu ersetzen.

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

Parameter

Beispiel für einen Anfrageinhalt:

{
  "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": "Manager benachrichtigen",
      "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": "Tor benutzen"
      },
    }
  ]
}

Auftragsobjekt

Zusätzlich zu Eigenschaften des Auftragsobjekts sind folgende Eigenschaften verfügbar:

Jedes im Feld orders angegebene Auftragsobjekt führt zur Erstellung, Aktualisierung oder Ersetzung eines Auftrags im System. Das genaue Verhalten für jeden Auftrag kann über operation in jedem Auftragsobjekt konfiguriert werden. Das Standardverhalten ist:

• wenn id angegeben ist, wird der bestehende Auftrag mit den bereitgestellten Werten aktualisiert;
  • Eigenschaften, die nicht in der Anfrage bereitgestellt werden, behalten ihre bestehenden Werte
• wenn id nicht angegeben ist und orderNo nicht angegeben ist oder kein Auftrag gefunden wird, wird ein neuer Auftrag erstellt;
  • Eigenschaften date und location sind verpflichtend
  • Eigenschaften duration und type verwenden die Standardwerte, die in OptimoRoute konfiguriert wurden
  • andere Eigenschaften können weggelassen werden; in diesem Fall werden die Standardwerte aus dem Auftragsobjekt verwendet
• wenn id nicht angegeben ist und ein bestehender Auftrag mit übereinstimmendem orderNo gefunden wird, wird der bestehende Auftrag mit den bereitgestellten Werten aktualisiert;
  • Eigenschaften, die nicht in der Anfrage bereitgestellt werden, behalten ihre bestehenden Werte

Standortobjekt

Siehe Standortobjekt für alle verfügbaren Standorteigenschaften. Standorte können erstellt oder aktualisiert werden.

Wenn locationNo angegeben ist und ein passender Standort vorhanden ist, wird dieser Standort aktualisiert. Wenn locationNo nicht übereinstimmt, wird ein neuer Standort erstellt.

Wenn locationNo nicht angegeben ist und ein bestehender Auftrag aktualisiert wird, wird der Standort des Auftrags aktualisiert.

Während der Aktualisierung wird der übereinstimmende Standort mit den im Objekt angegebenen Werten aktualisiert, falls vorhanden. Bei der Aktualisierung sind keine Eigenschaften verpflichtend. Bei der Aktualisierung mit SYNC werden die Eigenschaften auf Standardwerte zurückgesetzt; andernfalls behalten sie ihre bestehenden Werte.

In Fällen, in denen ein neuer Standort erstellt wird, sind die folgenden Eigenschaften verpflichtend: latitude, longitude und eine von locationNo, address, locationName.

Antwort

Beispiel für eine Antwort:

{
  "orders": [
    {
      "success": true,
      "id": "c821486835d2f20539a9754454f7efbe",
      "orderNo": "54913250"
    },
    {
      "success": false,
      "code": "ERR_LOC_NON_EXISTING_LOC",
      "message": "Der Standort mit der angegebenen Standortnummer existiert nicht.",
      "orderNo": "27463225",
      "locationNo": "999999999"
    },
    {
      "success": true,
      "id": "8cde6711026ff11f79f15a719277fe26",
      "orderNo": "09463221"
    }
  ],
  "success": true
}

Auftragsantwortobjekt

Fehler- und Warncodes

Die folgenden auftragsweise spezifischen Fehlercodes sind anwendbar:

Aufträge abrufen (bulk)

Ruft einen oder mehrere Aufträge aus dem System ab.

HTTP-Anfrage

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

reqbody.json ist eine lokale Datei, die die zu postenden JSON-Daten enthält.
Stellen Sie sicher, AUTH_KEY durch Ihren API-Schlüssel zu ersetzen.

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

Parameter

Beispiel für den Anfragetext:

{
  "orders": [
    {
      "orderNo": "ORD001"
    },
    {
      "orderNo": "ORD99"
    },
    {
      "id": "04e7b09e993e8488024f46aaf9d8c72d"
    }
  ]
}

Zur Flexibilität kann, wenn nur orderNo verwendet wird, der Aufruf von get_orders auch als HTTP GET-Anfrage durchgeführt werden:

Beispiel für GET-Anfrage:

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

Antwort

Beispiel für eine Antwort:

{
  "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": "Der Auftrag mit der passenden orderNo wurde nicht gefunden.",
      "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"
      }
    },
  ]
}

Auftrag-Antwortobjekt

Auftrag-Objekt

Im Erfolgsfall wird data ein Objekt mit den im Auftrag-Objekt aufgelisteten Eigenschaften sein.

Die zurückgegebene Eigenschaft type kann zusätzlich break oder depot sein.

Fehler- und Warncodes

Die folgenden pro Auftrag geltenden Fehlercodes sind für die Methode Aufträge Abrufen anwendbar:

Bestellung löschen

Entfernt eine Bestellung aus dem System.

HTTP-Anfrage

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

reqbody.json ist eine lokale Datei mit den zu sendenden JSON-Daten. Stellen Sie sicher, dass Sie AUTH_KEY durch Ihren API-Schlüssel ersetzen.

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

Parameter

Beispiel für den Anfragetext:

{
  "orderNo": "ORD001"
}

Antwort

Fehler- und Warncodes

Die folgenden Fehlercodes gelten für die Methode Bestellung löschen:

Alle Bestellungen löschen

Entfernt alle Bestellungen und geplanten Routen für das angegebene Datum aus dem System. Wenn kein Datum festgelegt ist, werden alle Bestellungen und Routen aus dem System entfernt.

HTTP-Anfrage

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

reqbody.json ist eine lokale Datei, die die zu sendenden JSON-Daten enthält. Stellen Sie sicher, AUTH_KEY durch Ihren API-Schlüssel zu ersetzen.

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

Parameter

Beispiel für den Anforderungskörper:

{
  "date": "2014-10-14"
}

Antwort

Fehler- und Warncodes

Die folgenden Fehlercodes gelten für die Bestellung löschen-Methode:

Bestellungen löschen (Massenlöschung)

Entfernt eine oder mehrere Bestellungen aus dem System.

HTTP-Anfrage

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

reqbody.json ist eine lokale Datei, die die zu sendenden JSON-Daten enthält.
Stellen Sie sicher, AUTH_KEY durch Ihren API-Schlüssel zu ersetzen.

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

Parameter

Beispiel für den Anfrageinhalt:

{
  "orders": [
    {
      "orderNo": "ORD001"
    },
    {
      "orderNo": "ORD999"
    },
    {
      "id": "04e7b09e993e8488024f46aaf9d8c72d"
    }
  ]
}

Antwort

Beispiel für eine Antwort:

{
  "success": true,
  "orders": [
    {
      "orderNo": "ORD001",
      "success": true
    },
    {
      "message": "Die Bestellung mit der passenden Bestellnummer wurde nicht gefunden.",
      "code": "ERR_ORD_NOT_FOUND",
      "orderNo": "ORD999",
      "success": false
    },
    {
      "success": true,
      "id": "04e7b09e993e8488024f46aaf9d8c72d"
    }
  ]
}

Löschantwortobjekt

Fehler- und Warnungscodes

Die folgenden fehlerbezogenen Codes sind auf die Methode Bestellungen löschen anwendbar:

Routen abrufen

Lädt die Routen für ein bestimmtes Datum.

HTTP-Anfrage

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

Stellen Sie sicher, dass Sie AUTH_KEY durch Ihren API-Schlüssel ersetzen.

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'

Parameter

Antwort

Beispielantwort

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

Routenobjekt

Halteobjekt

Fehler- und Warncodes

Keine.

Zeitpläne abrufen

Erhält die Zeitplaninformationen für die angegebene Bestellung. Für die Massenmethode siehe Bestellungen suchen

HTTP-Anfrage

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

Stellen Sie sicher, dass Sie AUTH_KEY durch Ihren API-Schlüssel ersetzen.

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

Parameter

Einer der beiden Eigenschaften muss in der Anfrage angegeben werden.

Antwort

Objekt der Bestellungs-Zeitplaninformationen

Fehler- und Warncodes

Die folgenden Fehlercodes gelten für die Methode Zeitpläne abrufen:

Beispielantwort 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
  }
}

Beispielantwort 2

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

Start Planung

Startet den Planungsprozess für das angegebene Datum.

HTTP-Anfrage

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

reqbody.json ist eine lokale Datei, die die zu postenden JSON-Daten enthält. Stellen Sie sicher, AUTH_KEY durch Ihren API-Schlüssel zu ersetzen.

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

Parameter

Beispiel für Anfragetext:

{
  "date": "2013-12-20"
}

Antwort

Fehler- und Warncodes

Die folgenden Fehlercodes sind für die Methode Start Planung anwendbar:

Planung beenden

Beendet den Planungsprozess.

HTTP-Anfrage

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

reqbody.json ist eine lokale Datei, die die zu postenden JSON-Daten enthält. Stellen Sie sicher, AUTH_KEY durch Ihren API-Schlüssel zu ersetzen.

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

Parameter

Beispiel für den Anfragetext:

{
  " planningId": 8828
}

Antwort

Fehler- und Warncodes

Die folgenden Fehlercodes sind für die Methode Planung beenden anwendbar:

Abrufen des Planungsstatus

Gibt den Status des Planungsprozesses zurück.

HTTP-Anfrage

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

Stellen Sie sicher, dass Sie AUTH_KEY durch Ihren API-Schlüssel ersetzen.

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

Parameter

Antwort

Fehler- und Warnungscodes

Die folgenden Fehlercodes gelten für die Methode Abrufen des Planungsstatus:

Fahrerparameter aktualisieren

Aktualisiert Fahrerparameter für ein bestimmtes Datum sowie den Start- und Endstandort des Fahrers. Alle bestehenden Routen für das angegebene Datum/Fahrer werden nicht eingeplant.

Die folgenden Parameter können geändert werden:

• Fahrer aktivieren/deaktivieren
• Fahrer Arbeitszeit ab
• Fahrer Arbeitszeit bis
• Zugewiesenes Fahrzeug
• Fahrzeugladekapazität #1
• Fahrzeugladekapazität #2
• Fahrzeugladekapazität #3
• Fahrzeugladekapazität #4
• Fahrerstartort
• Fahrerendort

HTTP-Anfrage

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

reqbody.json ist eine lokale Datei, die die zu veröffentlichenden JSON-Daten enthält. Stellen Sie sicher, AUTH_KEY mit Ihrem API-Schlüssel zu ersetzen.

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

Parameter

Beispiel für den Anfragetext:

{
  "externalId": "3945300304540",
  "date": "2019-09-25",
  "workTimeFrom": "09:30",
  "workTimeTo": "18:00"
}

Antwort

Fehler- und Warncodes

Die folgenden Fehlercodes gelten für die Methode Fahrerparameter aktualisieren:

Fahrerparameter aktualisieren (bulk)

Aktualisiert Parameter mehrerer Fahrer für die angegebenen Daten. Alle bestehenden Routen für die angegebenen Fahrer und Daten werden storniert.

Die folgenden Parameter für bestimmte Daten können geändert werden:

• Fahrer aktivieren/deaktivieren
• Arbeitszeit des Fahrers von
• Arbeitszeit des Fahrers bis
• Startort des Fahrers
• Zielort des Fahrers
• Zugewiesenes Fahrzeug
• Fahrzeugladekapazität #1
• Fahrzeugladekapazität #2
• Fahrzeugladekapazität #3
• Fahrzeugladekapazität #4

HTTP-Anfrage

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

reqbody.json ist eine lokale Datei, die die zu postenden JSON-Daten enthält. Stellen Sie sicher, dass Sie AUTH_KEY mit Ihrem API-Schlüssel ersetzen.

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

Parameter

Beispiel für Anforderungskörper:

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

DriverParameters Objekt

Wenn locationType custom ist und es keinen Standort mit denselben latitude, longitude und address gibt, wird ein neuer Standort erstellt und in der Standortverwaltung angezeigt. Der Standortname entspricht der Adresse, falls definiert, andernfalls wird der Name aus Breite und Länge erzeugt.

WorkTime Objekt

LocationType Objekt

Die type-Eigenschaft ist obligatorisch. Wenn type als create festgelegt ist, sind die Pflichtfelder latitude und longitude, andernfalls sollte nur type definiert werden.

Antwort

Beispiel für eine Antwort:

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

Fahrerantwortobjekt

Fehler- und Warncodes

Die folgenden Fehlercodes sind für die Methode Fahrerparameter aktualisieren anwendbar:

Mobile Events Abrufen

Rufen Sie mobile Ereignisse wie success, on_duty, failed, … für den derzeit aktiven Plan ab (d. h. der letzte Plan, der an die Fahrer gesendet wurde).

Jede Anfrage get_events gibt bis zu 500 Ereignisse zurück, die nach dem angegebenen Tag aufgetreten sind. Das Ergebnis enthält ein neues Tag, das Sie in der nächsten get_events Anfrage verwenden können, um bereits empfangene Ereignisse zu überspringen.

HTTP-Anfrage

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

Achten Sie darauf, AUTH_KEY durch Ihren API-Schlüssel zu ersetzen.

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

Parameter

Antwort

Ereignisobjekt

Die zurückgegebenen Ereignisfelder unixTimestamp, utcTime und localTime beziehen sich alle auf denselben Zeitpunkt, zu dem das Ereignis auftrat, sodass Sie das am besten geeignete verwenden können.

Bitte beachten Sie, dass einige mobile Geräte vorübergehend offline sein könnten und sie ihre Ereignisse erst dann synchronisieren, wenn sie sich wieder verbinden, sodass die von Ihnen empfangenen Ereignisse möglicherweise nicht in chronologischer Reihenfolge ankommen. Zum Beispiel könnte der erste Fahrer die Bestellung 001 um 09:00 Uhr erfolgreich abschließen, aber bis 09:15 Uhr offline sein. Der zweite Fahrer könnte die Bestellung 002 um 09:10 Uhr abschließen, aber die ganze Zeit online sein. Der Server wird das Ereignis für die Bestellung 002 zuerst empfangen und erst dann das Ereignis für die Bestellung 001.

Beispiele

Bei der ersten Anfrage werden wir den Parameter after_tag nicht angeben (wir lassen ihn leer):

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

Antwort:

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

Wir werden die Abfrage in 10 Sekunden wiederholen, aber diesmal verwenden wir das Tag, das wir im letzten Ergebnis erhalten haben, als unseren after_tag Parameter:

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

Antwort:

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

Es gab in der Zwischenzeit keine neuen Ereignisse. Wir werden die Abfrage in 10 Sekunden wiederholen:

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

Antwort:

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

Abschluss von Bestellungen abrufen

Ruft Abschlussdetails für eine oder mehrere Bestellungen ab, sobald diese abgeschlossen wurden. Für Echtzeit-Auftragsstatus-Updates verwenden Sie bitte den Get Mobile Events Endpoint.

HTTP-Anfrage

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

reqbody.json ist eine lokale Datei, die die zu postenden JSON-Daten enthält. Stellen Sie sicher, dass Sie AUTH_KEY durch Ihren API-Schlüssel ersetzen.

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

Parameter

Beispiel für den POST-Anfragekörper:

{
  "orders": [
    {
      "orderNo": "ORD001"
    },
    {
      "orderNo": "ORD99"
    },
    {
      "orderNo": "ORD55"
    },
    {
      "orderNo": "XXXYZ"
    },
    {
      "id": "84e5e94d341dc637ff77b56ea96cb8e3"
    }
  ]
}

Für Flexibilität kann der Aufruf von get_completion_details auch als HTTP GET-Anfrage erfolgen:

Beispiel für GET Anfrage:

curl 'https://api.optimoroute.com/v1/get_completion_details?key=AUTH_KEY&orderNo=ORD001&orderNo=ORD99&orderNo=ORD55&orderNo=XXXYZ'

Antwort

Antwort:

{
  "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": "Kunde war nicht verfügbar, wartete 5 Minuten, niemand öffnete die Tür"
        },
        "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": "Die Bestellung mit dem entsprechenden orderNo wurde nicht gefunden.",
      "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
}

Abschlussantwortobjekt

Felder der Abschlussdetails

Das zurückgegebene Abschlussdetails-Objekt enthält je nach dem Fortschritt der Bestellung, wie der Liefernachweis konfiguriert ist, und was ausgefüllt wurde, die unten beschriebenen Felder. Das zurückgegebene Abschlussdetails-Objekt kann auch zusätzliche Felder enthalten, die hier noch nicht beschrieben sind.

Bestellstatus-Werte

Zeitobjekt

Die Felder unixTimestamp, utcTime und localTime beziehen sich alle auf denselben Moment, sodass Sie das für Sie bequemste verwenden können.

Formulardatenobjekt

Alle Felder in den Formulardaten sind optional, und das Objekt kann zusätzliche Felder enthalten, die hier nicht aufgeführt sind.

Bildanhangsobjekt

Barcode-Scan-Objekt

Barcode-Info-Objekt

Barcode-Status

Fehler- und Warncodes

Falls success false ist, werden data nicht gesendet und das Feld code enthält einen der folgenden Fehlercodes pro Bestellung:

Update-Auftragsabschluss

Aktualisieren Sie die Abschlussdetails für eine oder mehrere Bestellungen.

HTTP-Anfrage

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

reqbody.json ist eine lokale Datei, die die zu postenden JSON-Daten enthält. Stellen Sie sicher, dass Sie AUTH_KEY mit Ihrem API-Schlüssel ersetzen.

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

Parameter

Beispiel für den POST-Anfragekörper:

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

Abschlussdetails-Aktualisierungsobjekt

Felder für Abschlussdetails-Aktualisierung

](#abschluss-von-bestellungen-abrufen-bestellstatus-werte) startTime
optional | Zeit-Aktualisierungsobjekt
- | Zeit, zu der die Bestellung begonnen wurde.
Nur vorhanden für Aufträge mit Status servicing, success oder failed. endTime
optional | Zeit-Aktualisierungsobjekt
- | Zeit, zu der der Auftrag abgeschlossen wurde (gekennzeichnet durch den Status success oder failed).
Nur vorhanden für Aufträge mit Status success oder failed.

Zeit-Aktualisierungsobjekt

Mindestens eines von unixTimestamp, utcTime, localTime sollte angegeben werden.