REST API V1 - Reference DirectoriesX Logistics
Lizenzbedingung
Die Nutzung der Q Exchange API und dieser Dokumentation unterliegt den API Nutzungsbedingungen, welche Sie hier einsehen können. Copyright Q Point AG (2022) – Alle Rechte vorbehalten.
Übersicht
| |
GET https://[RootUrl]/apiinfos | Liefert technische Informationen zur API. |
POST https://[BaseUrl]/logistic/onboardings/mobileDevice | Onboarding einer neuen Mobilnummer. |
GET https://[BaseUrl]/logistic/onboardings/mobileDevice/{phoneNumber} | Abfragen des Registrierungs-Status zu einer bestimmten Mobilnummer. |
GET https://[BaseUrl]/logistic/vehicles/{vehicleRegistrationNumber}/presence | Prüfen, ob ein Fahrzeug bei einem Transportdienstleister registriert ist. |
GET https://[BaseUrl]/logistic/vehicles/{vehicleRegistrationNumber} | Abfragen der öffentlichen Detail-Informationen zu einem bestimmten Fahrzeug. |
POST https://[BaseUrl]/logistic/vehicles/{vehicleRegistrationNumber}/deliveryNotes | Benachrichtigt eines bestimmten Fahrzeugs über einen neuen Lieferschein. |
Obsolet! | Benachrichtigt eine bestimmte Mobilnummer über einen neuen Lieferschein. |
URL's
API Root URL [RootUrl]
Hierbei handelt es sich um die Root URL von Q Directories bzw. des DirectoriesX-API's.
Zur Einhaltung regulatorischer Anforderungen und um die Latenzzeiten gering zu halten, besitzt jede geografische Region (Europa-West, US, Asia, India, Australia, etc) ihre eigene Q Directories-Instanz. Sie unterscheiden sich jeweils durch ihre Subdomain. Die von Ihnen benötigte Root URL erhalten Sie zusammen mit dem Access-Key vom Q Point Support.
Sie lautet beispielsweise: https://eu-api.q-directories.com
API Base URL [BaseUrl]
Hierbei handelt es sich um die Basis-URL, welche zum eigentlichen Aufruf der einzelnen Methoden verwendet wird. Sie basiert auf der Root-URL und erweitert diese durch den Bezug zu einer bestimmten API-Version. Die von Ihnen benötigte Base URL erhalten Sie zusammen mit dem Access-Key vom Q Point Support.
Sie lautet beispielsweise: https://eu-api.q-directories.com/v7/
API Key
Für den Zugriff auf die in dem Dokument angeführten Endpunkte des API’s ist ein API-Key mit der Key-Role "directoriesXLogistics" notwendig.
Technische Informationen zur API
GET https://[RootUrl]/apiinfos |
|---|
Eine GET-Abfrage auf die API Root-Url liefert technische Informationen zur API. Aktuell handelt es sich hierbei um eine Liste der unterstützten API-Versionen. Ein Server kann gleichzeitig mehrere unterschiedliche Versionen des API unterstützen. Client-Systeme können hiermit zur Laufzeit prüfen, ob der angesprochene Server die benötigte Version des API anbietet.
Response
200 - OK
Response Body |
|---|
{
"supportedApiVersions": [
{
"version": "v7",
"isDeprecated": false
},
{
"version": "v6",
"isDeprecated": true
}
]
//...
} |
Response Body(supportedApiVersions) | |
version | Einzelne vom Cluster bzw. Server unterstützten API Versionen (Bsp: "v2") |
isDeprecated | Die angegebene Version ist veraltet und wird in absehbarer Zeit nicht mehr unterstützt. Dieser Hinweis erlaubt abhängigen Systemen, dem Anwender einen entsprechenden Hinweis anzuzeigen und ihn darauf hinzuweisen, dass ein Update des Systems notwendig ist. |
Onboardings
Onboarding einer neuen Mobilnummer
POST https://[BaseUrl]/logistic/onboardings/mobileDevice |
|---|
Die Methode startet den asynchronen Vorgang zum Onboarding einer neuen Mobilnummer zur Verwendung der TruckBuddy App. Das System sendet im Anschluss eine Welcome-SMS an die spezifizierte Mobilnummer. Die SMS enthält neben einem Text zusätzlich einen BranchIO-Link zur Installation der TruckBuddyApp.
Solang die Registrierung noch nicht abgeschlossen ist oder die App nachträglich deinstalliert wurde, senden Q Directories bei jedem Aufruf der Methode eine Welcome-SMS an das Mobilgerät. Damit besteht für Clients die Möglichkeit, im Bedarfsfalle erneut eine SMS abzusetzen.
Request Body | |
phoneNumber | Telefonnummer des Mobilgeräts im Format (E.164). Hierbei muss es sich um eine Mobilnummer handeln. Andernfalls wird der Aufruf mit einem Fehler abgelehnt. |
language | Bevorzugte Sprache, in welcher der Mobilfunkteilnehmer angesprochen wird. Bsp: ‚de-DE' oder ‚en-GB'. |
companyName | Bezeichnung des Unternehmens, welche das Onboarding beauftragt. |
originSystemIdentifier | Bezeichnung des Systems, welche das Onboarding beauftragt. Diese Bezeichnung wird ausschliesslich zum Logging für Supportzwecke verwendet. |
Response
202 - Accepted Das Onboarding wird asynchron durchgeführt.
409 - Conflict Es besteht bereits eine aktive Registrierung (Status ‘registered’) für die angegebene Mobilnummer.
Abfragen des Registrierung-Status zu einer bestimmten Mobilnummer
GET https://[BaseUrl]/logistic/onboardings/mobileDevice/{phoneNumber} |
|---|
Liefert den Status der Registrierung einer bestimmten Mobile-Telefonnummer
Path Params | |
phoneNumber | Telefonnummer des Mobilgeräts im Format (E.164). Hierbei muss es sich um eine Mobilnummer handeln. Andernfalls wird der Aufruf mit einem Fehler abgelehnt. |
Response
200 - OK
Response Body (status) | |
status | Aktueller Status des Onboardings: |
404 - Not Found Für die angegebene Mobilnummer gibt es bislang noch keinen Eintrag.
Fahrzeuginformationen der Transportdienstleister
Prüfen, ob ein Fahrzeug bei einem Transportdienstleister registriert ist
GET https://[BaseUrl]//logistic/vehicles/{vehicleRegistrationNumber}/presence |
|---|
Liefert im Response Body lediglich die ID des Fahrzeugs zurück. Diese Möglichkeit ist spezielle darauf ausgelegt, effizient zu prüfen, ob das Fahrzeug mit den angegebenen Kennzeichen bei einem Transportdienstleister registriert ist.
Path Params | |
vehicleRegistrationNumber | Amtliches Fahrzeugkennzeichen. Bei LKWs ist dies in Regel das Kennzeichen des Zugfahrzeugs. |
Response
200 - OK
Response Body (vehicles) | |
id | Eindeutige ID (UUID) des Fahrzeugs beim Transportdienstleisters. Die ID ist für den Anwender nicht sichtbar. |
404 - Not Found Falls das adressierte Fahrzeug nicht existiert.
Abfragen der öffentlichen Detail-Informationen zu einem bestimmten Fahrzeug
GET https://[BaseUrl]//logistic/vehicles/{vehicleRegistrationNumber} |
|---|
Liefert die öffentlichen Informationen zu dem adressierten Fahrzeug. Diese stammen aus dem Fahrzeugverzeichnis des zugehörigen Transportdienstleisters.
Path Params | |
vehicleRegistrationNumber | Amtliches Fahrzeugkennzeichen. Bei LKWs ist dies in Regel das Kennzeichen des Zugfahrzeugs. |
Response
200 - OK
Response Body (vehicles) | |
id | Eindeutige ID (UUID) des Fahrzeugs beim Transportdienstleisters. Die ID ist für den Anwender nicht sichtbar. |
vehicleRegistrationNumber | Amtliches Kennzeichen des Fahrzeugs. Bei LKWs ist dies in Regel das Kennzeichen des Zugfahrzeugs. |
vehicleRegistrationNumberTrailer | Amtliches Kennzeichen des Aufliegers. |
name | Zusätzliche fakultative Bezeichnung des Fahrzeugs (bspw: “Fahrzeug 12”) |
vehicleTypeName | Bezeichnung des Fahrzeugtyps (bspw: “Thermo 5-Achser“. |
maxPermittedTotalWeight | Maximal zulässiges Gesamtgewicht der gesamten Fahrzeugkombination (Zugfahrzeug inkl. Auflieger). |
grossWeightRatingUnit | Masseinheit des Gesamtgewichts. Pflichtfeld, falls 'maxPermittedTotalWeight' angegeben ist. |
maxLoadingCapacity | Maximale Ladekapazität des Fahrzeugs. |
maxLoadingCapacityUnit | Masseinheit der Ladekapazität. Pflichtfeld, falls 'maxLoadingCapacity' angegeben ist. |
emissionsClassName | Emissionsklasse des Fahrzeugs (bspw: “EURO V”). |
driverName | Name und Vorname des Fahrers. |
driverMobilePhone | Mobiltelefonnummer des Fahrers im Format (E.164) |
carrierInfo | Zusammenhängende Unternehmensbezeichnung des Transportdienstleisters. |
carrierBaseName | Bezeichnung des Fahrzeugstützpunkts. |
carrierBaseId | Systemübergreifend eindeutige ID des Fahrzeugstützpunkts. |
CarrierBasePostalAdress | Zusammenhängender Informations-String mit der kompletten Postanschrift des Stützpunkts. |
CarrierBaseGeoPosition | Geoposition Fahrzeugstützpunkts. |
404 - Not Found Falls das adressierte Fahrzeug nicht existiert.
Benachrichtigungen über neue Lieferscheine
Benachrichtigt eines bestimmten Fahrzeugs über einen neuen Lieferschein
POST https://[BaseUrl]/logistic/vehicles/{vehicleRegistrationNumber}/deliveryNotes |
|---|
Benachrichtigt ein bestimmtes Fahrzeug über einen neuen Lieferschein.
Path Params | |
vehicleRegistrationNumber | Im Lieferschein angeführtes amtliches Kennzeichen des Fahrzeugs, das den Transport durchführt. Das Fahrzeug bzw. die über die Mobilnummer zugeordnete TruckBuddy-Instanz ist der Empfänger des Lieferscheins. |
Request Body | |
phoneNumber | Telefonnummer des Mobilgeräts für die Lieferscheinweiterleitung im Format (E.164). Diese ist fakultativ und wird vom Auftraggeber des Transportes lediglich dann mitgegeben, wenn eine Registrierung vorliegt. Priorität für die Weiterleitung besitzt jedoch die Lieferscheinweiterleitung in Q Directories. Existiert eine Registrierung durch einen Transportdienstleister, ist dies ausschlaggebend. Fehlt eine solche hingegen, wird der Lieferschein an die hier angegebenen Nummer vermittelt. |
deliveryNoteId | GUID des Lieferscheins. |
deliveryNoteDocketNumber | Lieferscheinnummer. Sowohl der Wert als auch die Formatierung der Nummer wird durch dasjenige System bestimmt, welches den Lieferschein ausgibt. In der Regel handelt es sich hierbei um das Wiegesystem der Mischanlage. |
issueDt | Zeitpunkt, zu welchem der Lieferschein erzeugt und ausgegeben wurde. Dieser Zeitpunkt wird durch die Mischanlage bzw. durch dasjenige System bestimmt, welche den Lieferschein ausgibt. |
deliveryNotePlantName | Auf dem Lieferschein angeführtes Bezeichnung des liefernden Mischwerks. |
deliveryNoteQuantity | Auf dem Lieferschein angeführte Liefermenge. |
deliveryNoteQuantityUnit | Masseinheit der Liefermenge. |
deliveryNoteArticleName | Auf dem Lieferschein angeführte Artikelbezeichnung. |
deliveryNoteSiteInformation | Auf dem Lieferschein angeführte Bezeichnung und Adresse der Baustelle. |
baseUrl | Base URL auf das Logistics-API des Auftraggebers. |
apiVersion | Versionsnummer des Logistics-API des Auftraggebers |
originSystemIdentifier | Bezeichnung des Systems des Auftraggebers. Diese Bezeichnung wird ausschliesslich zum Logging für Supportzwecke verwendet. |
Response
202 - Accepted Die Benachrichtigung wird asynchron ausgeführt und an das Mobilgeräte übermittelt.
Mögliche Fehler
Zu der angegebenen Mobilnummer existiert keine Registrierung
Die Benachrichtigung konnte nicht übermittelt werden, da für die im Pfad adressierten Mobilnummer keine Registrierung existiert. Dies kann unter anderem daran liegen, dass die App zwischenzeitlich wieder deinstalliert wurde. Solange die Registrierung fehlt, liefert die Methode einen Returncode "404 - Not Found" mit dem nachfolgenden Fehlerobjekt zurück:
Attribute | Value |
errorIdentifier | MobileNumberUnknown |
errorMessage | The delivery note cannot be sent. There is no registration for the specified mobile number |
reason | Missing registration |
Das Onboarding der Mobile APP ist noch nicht vollständig abgeschlossen
Die Benachrichtigung konnte nicht übermittelt werden. Die im Pfad adressierte Mobilnummer ist zwar bekannt, das Onbaording der zugehörigen Mobil APP konnte jedoch bislang noch nicht erfolgreich abgeschlossen werden. Dies kann unter anderem daran liegen, dass die Einladung (Welcome SMS) vom Inhaber des Mobilgeräts (noch) nicht gesehen wurde oder ignoriert wird und deshalb die TruckBuddy App auch noch nicht installiert ist. Solange das Onboarding nicht erfolgreich abgeschlossen ist, liefert die Methode einen Returncode "409 - Conflict" mit dem nachfolgenden Fehlerobjekt zurück:
Attribute | Value |
errorIdentifier | OnbardingNotCompleted |
errorMessage | The delivery note cannot be sent. The onboarding of the associated mobile number has not yet been successfully completed |
reason | Onbarding not completed |
Die Mobile APP wurde wieder deinstalliert
Die Benachrichtigung konnte nicht übermittelt werden. Die im Pfad adressierte Mobilnummer ist zwar bekannt, die TruckBuddy App wurde jedoch im Anschluss an die Registrierung wieder deinstalliert. In diesem Fall liefert die Methode einen Returncode "409 - Conflict" mit dem nachfolgenden Fehlerobjekt zurück:
Attribute | Value |
errorIdentifier | MobileAppUninstalled |
errorMessage | The delivery note cannot be sent. The mobile app was uninstalled again following a registration |
reason | Mobile App uninstalled |
Die nachfolgende Methode ist veraltet und darf deshalb nicht mehr verwendet werden! Diese Methode wurde durch POST https://[BaseUrl]/logistic/vehicles/{vehicleRegistrationNumber}/deliveryNotes ersetzt.
Benachrichtigt eine bestimmte Mobilnummer über einen neuen Lieferschein
POST https://[BaseUrl]/logistic/mobileDevice/{phoneNumber}/deliveryNotes |
|---|
Benachrichtigt eine registrierte Mobilnummer über einen neuen Lieferschein.
Path Params | |
phoneNumber | Telefonnummer des Mobilgeräts im Format (E.164). Hierbei muss es sich um eine Mobilnummer handeln. Andernfalls wird der Aufruf mit einem Fehler abgelehnt. |
Request Body | |
deliveryNoteId | GUID des Lieferscheins. |
deliveryNoteDocketNumber | Lieferscheinnummer. Sowohl der Wert als auch die Formatierung der Nummer wird durch dasjenige System bestimmt, welches den Lieferschein ausgibt. In der Regel handelt es sich hierbei um das Wiegesystem der Mischanlage. |
issueDt | Zeitpunkt, zu welchem der Lieferschein erzeugt und ausgegeben wurde. Dieser Zeitpunkt wird durch die Mischanlage bzw. durch dasjenige System bestimmt, welche den Lieferschein ausgibt. |
deliveryNoteVehicleRegistrationNumber | Auf dem Lieferschein angeführtes Fahrzeugkennzeichen. |
deliveryNotePlantName | Auf dem Lieferschein angeführtes Bezeichnung des liefernden Mischwerks. |
deliveryNoteQuantity | Auf dem Lieferschein angeführte Liefermenge. |
deliveryNoteQuantityUnit | Masseinheit der Liefermenge. |
deliveryNoteArticleName | Auf dem Lieferschein angeführte Artikelbezeichnung. |
deliveryNoteSiteInformation | Auf dem Lieferschein angeführte Bezeichnung und Adresse der Baustelle. |
baseUrl | Base URL auf das Logistics-API des Auftraggebers. |
apiVersion | Versionsnummer des Logistics-API des Auftraggebers |
originSystemIdentifier | Bezeichnung des Systems des Auftraggebers. Diese Bezeichnung wird ausschliesslich zum Logging für Supportzwecke verwendet. |
Response
202 - Accepted Die Benachrichtigung wird asynchron ausgeführt und an das Mobilgeräte übermittelt.
Mögliche Fehler
Zu der angegebenen Mobilnummer existiert keine Registrierung
Die Benachrichtigung konnte nicht übermittelt werden, da für die im Pfad adressierten Mobilnummer keine Registrierung existiert. Dies kann unter anderem daran liegen, dass die App zwischenzeitlich wieder deinstalliert wurde. Solange die Registrierung fehlt, liefert die Methode einen Returncode "404 - Not Found" mit dem nachfolgenden Fehlerobjekt zurück:
Attribute | Value |
errorIdentifier | MobileNumberUnknown |
errorMessage | The delivery note cannot be sent. There is no registration for the specified mobile number |
reason | Missing registration |
Das Onboarding der Mobile APP ist noch nicht vollständig abgeschlossen
Die Benachrichtigung konnte nicht übermittelt werden. Die im Pfad adressierte Mobilnummer ist zwar bekannt, das Onbaording der zugehörigen Mobil APP konnte jedoch bislang noch nicht erfolgreich abgeschlossen werden. Dies kann unter anderem daran liegen, dass die Einladung (Welcome SMS) vom Inhaber des Mobilgeräts (noch) nicht gesehen wurde oder ignoriert wird und deshalb die TruckBuddy App auch noch nicht installiert ist. Solange das Onboarding nicht erfolgreich abgeschlossen ist, liefert die Methode einen Returncode "409 - Conflict" mit dem nachfolgenden Fehlerobjekt zurück:
Attribute | Value |
errorIdentifier | OnbardingNotCompleted |
errorMessage | The delivery note cannot be sent. The onboarding of the associated mobile number has not yet been successfully completed |
reason | Onbarding not completed |
Die Mobile APP wurde wieder deinstalliert
Die Benachrichtigung konnte nicht übermittelt werden. Die im Pfad adressierte Mobilnummer ist zwar bekannt, die TruckBuddy App wurde jedoch im Anschluss an die Registrierung wieder deinstalliert. In diesem Fall liefert die Methode einen Returncode "409 - Conflict" mit dem nachfolgenden Fehlerobjekt zurück:
Attribute | Value |
errorIdentifier | MobileAppUninstalled |
errorMessage | The delivery note cannot be sent. The mobile app was uninstalled again following a registration |
reason | Mobile App uninstalled |