REST API V1 - Reference DirectoriesX TruckBuddyApp
Hierbei handelt es sich um ein internes API, welches lediglich von der TruckBuddy App genutzt wird!
Übersicht
| |
GET https://[RootUrl]/apiinfos | Liefert technische Informationen zur API |
PUT https://[BaseUrl]/truckBuddyAppInstances/{truckBuddyAppInstanceIdentifier} | Onboarding durch eine neue TruckBuddy APP Instanz. |
GET https://[BaseUrl]/truckBuddyAppInstances/{truckBuddyAppInstanceIdentifier} | Registrierungszustand einer bestimmten TruckBuddy App Instanz abfragen. |
PUT https://[BaseUrl]/truckBuddyAppInstances/{truckBuddyAppInstanceIdentifier}/preferences | Setzen oder aktualisieren der App Preferences. |
GET https://[BaseUrl]/truckBuddyAppInstances/{truckBuddyAppInstanceIdentifier}/preferences | Abfragen der App Preferences. |
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. |
Registrierung
Neue TruckBuddy APP Instanz registrieren
PUT https://[BaseUrl]/truckBuddyAppInstances/{truckBuddyAppInstanceIdentifier} |
|---|
Die Methode wird von der TruckBuddy APP genutzt, um den zweistufigen Registrierungsprozess auszuführen. Der Aufruf registriert die App-Instanz unter der im Body angegebenen Mobilnummer.
Im ersten Registrierungsschritt wird der Endpunkt ohne Angabe einer TAN aufgerufen. Daraufhin sende das System eine SMS mit einer neu generierten TAN an die angegebenen Mobilnummer. Der Anwender gibt die erhaltene TAN in die TruckBuddy APP ein. Die App-Instanz ruft den Endpunkt erneut, diesmal mit Angabe der TAN auf. Stimmen die TAN’s überein, wird die App-Instanz unter der angegebenen Mobilnummer registriert. Anderenfalls erhält der Aufrufer einen Fehler zurück.
Path Params | |
truckBuddyAppInstanceIdentifier | Eindeutiger Identifier der TruckBuddy APP Instanz. |
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. |
tan | Transaktionsnummer, um Mobilnummer zu authentifizieren. Dies geschieht im zweiten Schritt des Registrierungsablaufs. |
disclaimerHash | Hash der Nutzungsbedingungen, welche der Anwender im Zuge der Registrierung akzeptiert hat. |
language | Spracheinstellung der App bzw. des Anwenders. Es handelt sich um eine Kombination aus “<Language Code ISO-639-1>-<Country Code ISO-3166>”. Bsp: ‚de-DE' oder ‚en-GB'. |
Response
200 - OK Der jeweilige Registrierungsschritt wurde erfolgreich abgeschlossen.
Mögliche Fehler
Die angeführte TAN ist nicht korrekt und stimmt nicht mit der ursprünglichen TAN überein
In diesem Fall liefert der Aufruf einen Returncode "409 Conflict" mit dem nachfolgenden Fehlerobjekt:
Attribute | Value |
errorIdentifier | TANValidationError |
errorMessage | The TAN provided is incorrect and does not match the original TAN |
reason | Registration refused |
Registrierungszustand einer bestimmten TruckBuddy App Instanz abfragen
GET https://[BaseUrl]/truckBuddyAppInstances/{truckBuddyAppInstanceIdentifier} |
|---|
Liefert den Status der Registrierung einer bestimmten TruckBuddy APP Instanz.
Path Params | |
truckBuddyAppInstanceIdentifier | Eindeutiger Identifier des TruckBuddy APP Instanz. |
Response
200 - OK
Response Body (truckBuddyAppInstances) | |
status | Aktueller Status der Registrierung: |
disclaimerHash | Hash der Nutzungsbedingungen, welche der Anwender als letztes akzeptiert hat. |
404 - Not Found Für die angegebene Instanz gibt es noch keine Registrierung.
App Preferences
App Preferences setzen oder aktualisieren
PUT https://[BaseUrl]/truckBuddyAppInstances/{truckBuddyAppInstanceIdentifier}/preferences |
|---|
Die Methode wird von der TruckBuddy APP genutzt, um den die Sprach- und Format-Einstellungen zu speichern. Die Einstellungen werden durch das Backend gespeichert und anschliessend zur Lokalisierung und Formatierung von SMS- und Push-Nachrichten verwendet.
Path Params | |
truckBuddyAppInstanceIdentifier | Eindeutiger Identifier der TruckBuddy APP Instanz. |
Request Body | |
language | Spracheinstellung der App bzw. des Anwenders. Es handelt sich um eine Kombination aus “<Language Code ISO-639-1>-<Country Code ISO-3166>”. Bsp: ‚de-DE' oder ‚en-GB'. |
cultureInfo | Regionseinstellung für die Formatierung von Datums- und Zahlen-Werten. Es handelt sich um eine Kombination aus “<Language Code ISO-639-1>-<Country Code ISO-3166>”. Bsp: ‚de-DE' oder ‚en-GB'. |
Response
200 - OK Preferences erfolgreich gespeichert.
App Preferences abfragen
GET https://[BaseUrl]/truckBuddyAppInstances/{truckBuddyAppInstanceIdentifier}/preferences |
|---|
Die Methode liefert die aktuellen Sprach- und Format-Einstellungen der TruckBuddy App. Die Einstellungen werden vom Backend zur Lokalisierung und Formatierung von SMS- und Push-Nachrichten verwendet.
Path Params | |
truckBuddyAppInstanceIdentifier | Eindeutiger Identifier der TruckBuddy APP Instanz. |
Response
200 - OK
Response Body (preferences) | |
language | Spracheinstellung der App bzw. des Anwenders. Es handelt sich um eine Kombination aus “<Language Code ISO-639-1>-<Country Code ISO-3166>”. Bsp: ‚de-DE' oder ‚en-GB'. |
cultureInfo | Regionseinstellung für die Formatierung von Datums- und Zahlen-Werten. Es handelt sich um eine Kombination aus “<Language Code ISO-639-1>-<Country Code ISO-3166>”. Bsp: ‚de-DE' oder ‚en-GB'. |
404 - Not Found Für die angegebene Instanz ist unbekannt oder es gibt es noch keine Registrierung.