API - Allgemeine Richtlinien

Owned by Former user (Deleted)
Last updated: 22 März, 2021 by Meike Blobel (Unlicensed)

Benutzer

Für den Login kann jeder Benutzer verwendet werden, solange er Administrator-Rechte besitzt. Die Benutzerdaten müssen im Http-Header als Basic Authentication mitgegeben werden.

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

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, außerdem muss im Http-Header der Richtige Content-Type gesetzt werden: "Content-Type: application/json"

Beim Aufbau der URLs ist außerdem zu beachten, das diese nicht mir einem "/" (Slash) enden!


MethodeBenutzung
GETBenutzt beim Abrufen von Daten
POSTBenutzt beim Schreiben von neuen Datensätzen und beim Abfragen komplexerer Anfragen
PUTBenutzt beim Überschreiben und Editieren von vorhandenen Datensätzen
DELETEBenutzt beim Löschen von Datensätzen



Request
{
    "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.)

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


Response im Fehlerfall
{
    "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

Beispiel der Sperre anhand von Aufträgen

Übersicht der Unterseiten in diesem Abschnitt des Handbuchs