Aufbau der URL
Die Basis-URL der API ist
https://<<URLzumTRADEMAN>>/api/<<ENDPUNKT>>
Beispiel für einen POST-Call
https://demopoe.poslive.de/api/search/REGISTER?v=1
Dieser Call ist eine Such-Anfrage nach "Kassen" des Systems.
Aufbau des Requests
Bei einem POST, PUT oder DELETE Aufruf innerhalb der API sind folgenden JSON Parameter immer mit anzugeben
Beim Aufbau der URLs ist außerdem zu beachten, das diese nicht mir einem "/" (Slash) enden!
| Methode | Benutzung |
|---|---|
| GET | Benutzt beim Abrufen von Daten |
| POST | Benutzt beim Schreiben von neuen Datensätzen und beim Abfragen komplexerer Anfragen |
| PUT | Benutzt beim Überschreiben und Editieren von vorhandenen Datensätzen |
| DELETE | Benutzt beim Löschen von Datensätzen |
| Codeblock | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"api_version": 1,
"systemno": 4711, // Kassennummer oder ähnliches bei Fremdsystemen
"operatorno": 789, // KassiererNr/BedienerID
"systemtype": "POSMAN",
"processno": 125, // Belegnummer oder ähnliches
"datetime": "2019-01-21T15:20:50+0100" // Format nach ISO 8601
} |
Aufbau der Response
Der Response wird immer ähnlich aufgebaut sein und folgende Informationen enthalten:
- API_Version: Die Version der API ist zu beachten, falls sich anfragen grundlegend ändern.
- Code: Dies ist der HTTP-Statuscode
- Success: Gibt neben dem Status-Code an, ob die Anfrage korrekt verarbeitet wurde
- RowCount; Anzahl der betroffenen Zeilen beim Löschen oder Suchen
- Warning: Hier können Warnungen für die Logs des aufrufenden Systems mitgegeben werden
- Data: Data ist immer vorhanden, kann aber je nach abfrage abweichen. Hier kann ein einzelnes Objekt, eine Liste (Array) von Objekten doer eine Liste von zusammengefassten Data-Sets (jeweils zusammenhängende Objekte) zurückgegeben werden
TRADEMAN antwortet mit der Version mit der die Anfrage gesendet worden ist. Falls diese Version nicht mehr unterstützt wird, kommt eine Antwort mit dem HTTP-Statuscode 410.
(Die Versionsnummer wird immer ganzzahlig hochgezählt.)
| Codeblock | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"api_version": 1,
"code": 200,
"success": true,
"rowcount": 1,
"msg": "",
"warning": "",
-----
"data": [
{
"kundenkarte":{
nummer: 426,
guthaben: 2345
},
"kunde" : {
...
}
},
...
]
----- oder
"data":{
"kundenkarte":{
nummer: 426,
guthaben: 2345
},
"kunde" : {
...
},
...
}
----- oder
"data": []
-----
} |
| Codeblock | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"api_version": 1,
"code": 4xx,
"success": false,
"rowcount": 0,
"msg": "Die xxx konnte nicht gespeichert werden", // Fehlermeldung für den Benutzer
"error": "Schlüsselverletzung bei xxx", // Technische Fehlerbeschreibung für Logs
"data": [ ]
} |
Sperre von Transaktionen
Fragt die Kasse etwas an (z.B. Auftrag, Bon für Rücknahme, ...) dann wird eine Sperre gesetzt (StartEdit-Call). So wird verhindert, dass eine andere Kasse oder ein anderes (Dritt-) System die gleiche Transaktion anfragt. Bei zukünftigen Umsetzungen wird die gleiche einheitliche Logik verwendet werden.
Dazu gehören die folgenden Calls:
- StartEdit
- ContinueEdit
- EndEdit
- CancelEdit
- CreateNew