API - Endpunkte - Salesorder

Beschreibung des Endpunkts

GET- /api/salesorder/startedit/<SALESORDER-ID>/<SYSTEMTYPE>/<SYSTEMNO>

Aufruf

Der Call schreibt Protokoll-Eintrag, dass die Kasse angefangen hat den Auftrag zu editieren. Im TM2 wird dieser dann für eine bestimmte Zeit gesperrt. Dies wird auch in den Masken so dem Benutzer gemeldet.

Der Parameter "VORGANGSPERRDAUER" steuert wie viele Minuten der angegebene Auftrag gesperrt bleibt. Sollte der Parameter aus irgendwelchen Gründen nicht gefunden werden, so werden 15 Minuten als Sperrdauer verwendet.

Beispieldaten:

SALESORDER-ID: 123546
SYSTEMTYPE: POSMAN
SYSTEMNO (Kassen-Nr.): 125

Response

{
  "api_version": 1,
  "code": 200, // HTTP-Statuscode
  "success": true,
  "rowcount": 1,
  "msg": "Erfolg: Der Auftrag wurde erfolgreich zum Bearbeiten vorgemerkt.",
  "warning": "",
  "data": {
    "Auftrag": {%AuftragObjekt%},
	"Kunden": {%KundenObjekt%}
	"AuftragPositionen": [%Array_mit_AuftragPositionenObjekten%]
  }
}

GET -/api/salesorder/continueedit/<SALESORDER-ID>/<SYSTEMTYPE>/<SYSTEMNO>

Aufruf

Verlängert den Timeout für Editieren-Sperre.

Der Parameter "VORGANGSPERRDAUER" steuert wie viele Minuten der angegebene Auftrag gesperrt bleibt. Sollte der Parameter aus irgendwelchen Gründen nicht gefunden werden, so werden 15 Minuten als Sperrdauer verwendet.

Response

{
  "api_version": 1,
  "code": 200, // HTTP-Statuscode
  "success": true,
  "rowcount": 1,
  "msg": "Erfolg: Die Sperre zum Bearbeiten den Auftrags wurde verlängert",
  "warning": "",
  "data": {}
}

Get- /api/salesorder/canceledit/<SALESSORDER-ID>/<SYSTEMTYPE>/<SYSTEMNO>

Aufruf

Dieser Call gibt einen Auftrag wieder frei und nimmt die Sperre wieder von dem Auftrag herunter. Er wird z.B. bei BonAbbruch verwendet.

Response

{
    "api_version": 1,
    "code": 200, // HTTP-Statuscode
    "success": true,
    "rowcount": 1,
    "msg": "Erfolg: Die Sperre zum Bearbeiten des Auftrags wurde aufgehoben.",
    "warning": "" // Hier können Warnungen für die Logs des aufrufenden Systems mitgegeben werden
	"data": {} 
}

POST- /api/salesorder/endedit

Aufruf

Dieser Call ist ein POST, weil hier der bearbeitete Auftrag (z.B. wenn er abkassiert wurde) zurück gegeben wird. Diese Funktion ist auch darauf vorbereitet, dass mehrere Aufträge mit ihren Positionen zurückgeliefert werden.

An dieser stelle werden zuerst 2 Validierungen angestoßen, bevor irgendwelche Änderungen durchgeführt werden:

Validieren des Status aller zurückgemeldeten Aufträge und Auftragspositionen, ob sie sich in einem Status befinden, in dem das Editieren erlaubt ist. Erlaubt sind zur Zeit:
- Auftrag: "Angelegt (10)" und "Beauftragt (20)"
- AuftragPosition: "Angelegt (10)" und "Am Lager (30)"
Validieren des letzten Edit-Calls, ob die Auftrags-Sperre aktiv ist und auch noch nicht abgelaufen ist.

Erst wenn beide Prüfungen erfolgreich abgelaufen sind, werden die Aufträge einzeln weiter verarbeitet

Eine POSMAN-Kasse kann zusätzlich zu Aufträgen auch Anzahlungen mitschicken. Ggfs. werden diese dann als Zahlung gespeichert.

Wichtig

Über die API werden nur die zurückgemeldeten Positionen bearbeitet. Es werden keine Positionen gelöscht! Positionen können nur über den Status als "gelöscht" markiert werden.

Request

{
    "api_version": 1,
    "systemno": 4711,	// Kassennummer (oder ähnliches bei Fremdsystemen)
    "operatorno": 789,	// Kassierer/Bediener
    "systemtype": "POSMAN",
    "processno": 125,	// Belegnummer oder ähnliches
    "datetime": "2017-04-12T23:20:50+0100"	// Format nach ISO 8601
	"data": [
		{ 
			"Auftrag": {%AuftragObjekt%}
			"AuftragPosition": [{%AuftragsPositionObjekt%},{}]	  // Array von AuftragsPositionen
			"Zahlung":[{%ZahlungObjekt%},{}]	// Array von Zahlungsaufträgen
		},
		{} // Weitere DataSets von Aufträgen und den dazugehörigen Positionen
	]
 }

Antwort

Wenn die gegebenen Aufträge erfolgreich verarbeitet wurden, werden die veränderten Aufträge im Format der Search-Calls noch einmal zurückgeliefert.

Nach der erfolgreichen Abarbeitung wird ebenfalls ein Protokoll-Eintrag geschrieben, der das Ende der Bearbeitung protokolliert.

Fehler-Fälle werden im folgenden Abschnitt beschrieben.

Response

{
    "api_version": 1,
    "code": 200, // HTTP-Statuscode
    "success": true,
    "rowcount": 0,  // Anzahl der betroffenen Zeilen
    "msg": "",
    "warning": "" // Hier können Warnungen für die Logs des aufrufenden Systems mitgegeben werden
	"data": []
}

POST- /api/salesorder/create

Aufruf

Dieser Call ist als POST-Call definiert. Hier werden die Auftragsdaten übergeben, aus denen neue Aufträge angelegt werden. Es können mehrere Datensätze übergeben werden. Jeder Datensatz muss aus einem Auftrag-Objekt und einer Liste (Array) von Auftragpositionen-Objekten bestehen.

Wenn die Aufträge z.B. lediglich zum Abkassieren zur Kasse geschickt werden sollen, ist es ausreichend vorab einen Dummy-Kunden anzulegen und diesen dann immer zu verwenden.

Bei eingerichteter Bestandsführung und wenn der Auftrag im Status "Beauftragt" übergeben wird, werden die Positionen automatisch reserviert. Sollte eine Reservierung fehlschlagen, wird die Auftragsanlage trotzdem ausgeführt und die nicht reservierten Positionen werden im "warning" der Antwort aufgeführt.

Die wichtigsten Werte der Objekte

Auftrag-Objekt (genaue Beschreibung => API - Auftrag-Objekt)
Feldname	Erforderlich	Feldtyp	Beschreibung
aunr	--	INTEGER	Die Auftragsnummer wird mit Hilfe des internen Zählers gesetzt. Wird dennoch eine Auftrags-Nr. mit angegeben, so wird diese verwendet. Es finden dann eine Prüfung statt, ob die Nummer bereits vergeben ist. Wenn zusätzlich eine externe Auftrags-Nr. gesetzt werden soll, ist diese in dem Feld "extaunr" zu übergeben und wäre für einen späteren Export vorhanden.
summe	--	INTEGER	Muss in Cent angegeben werden
anzahlung	--	INTEGER	Wenn bereits eine Anzahlung getätigt wurde, kann diese in Cent angegeben werden
vknr	--	INTEGER	Kann angegeben werden, wenn ein Mitarbeiter/Verkäufer verknüpft werden soll.
extaunr	--	INTEGER	In diesem Feld kann eine "externe Auftragsnummer" gesetzt werden, damit für einen späteren Export eine Referenz zum Drittsystem vorhanden ist.
status	--	INTEGER	Aufträge sollten mit dem Status 10 ("offfen") angelegt werden, damit sie bearbeitet oder abkassiert werden können.
kdnr	--	INTEGER	Die Verknüpfung zu einem Kunden (über die "kdnr") ist notwendig, wenn die Aufträge an anderer Stelle weiter bearbeitet werden sollen.

AuftragPosition (genaue Beschreibung => API - AuftragPosition-Objekt )
Feldname	Erforderlich	Feldtyp	Beschreibung
aunr	--	INTEGER	Wird bei der Generierung des Auftrags erzeugt und verwendet
bonpos	X	INTEGER	Muss zwingend angegeben werden und eindeutig sein
artnr1	X	VARCHAR(255)	Referenz zum Artikel muss gegeben sein
artnr1extern	X	VARCHAR(255)	Gibt eine "externe Artikel-Nr." an, die über die Tbl.mapping_definition gemapped werden soll
artbez	--	VARCHAR(255)	Kann angegeben werden, wenn in der Position die Bezeichnung vom Artikel-Text (im Stamm) abweichen soll
menge	X	INTEGER	Menge die verkauft werden soll
preis	X	INTEGER	Summe Verkaufspreis in Cent
mwstid	X	INTEGER	Eins dieser Felder muss gefüllt sein, da sonst keine MwSt-Zuordnung geschehen kann. Das Feld "mwstid" bezieht sich auf die Tbl.mwst und hat Vorrang vor dem "mwstsatz" und der "mwstartnr1extern". Wenn das Flag "mwstartnr1extern" aktiv ist ("true", "t" oder "1") wird die MWST-ID aus dem Dummy-Artikel (Mapping der Artnr1extern) verwendet. Dies hat Vorrang vor dem "mwstsatz". Wenn keine MwSt-ID gegeben ist, wird mit dem MwSt-Satz versucht in der Tbl.mwsteinen entsprechenden Datensatz für das Systemland (Parameter) zu finden.
mwstsatz		FLOAT
mwstartnr1extern		BOOLEAN
langtext	--	TEXT	Falls TextPositionen im Auftrag enthalten sind
linkpos	--	INTEGER	Wichtig zur Verknüpfung von TextPositionen zu ArtikelPositionen

Kunden (genaue Beschreibung => API - Kunden-Objekt )
Bemerkung: Kunden können nicht mit übergeben werden. Die Kunden-Anlage oder Aktualisierung erfolgt über den Endpunkt API - Endpunkte - CreateCustomer. Somit kann die Kunden-Nr. im Auftrags-Objekt direkt angegeben werden.

Request

{
    "api_version": 1,
    "systemno": 4711,			// Kassennummer (oder ähnliches bei Fremdsystemen)
    "operatorno": 789,			// Kassierer/Bediener/Benutzer
    "systemtype": "POSMAN",		// SystemTyp ('POSMAN' für Kasse)
    "processno": 0,
    "datetime": "2019-02-21T12:20:50+0100"	// Format nach ISO 8601
	"data": [
		{ 
			"auftrag": {%AuftragObjekt%},
			"auftrag_position": [{%AuftragsPositionObjekt%},{}]	  // Array von AuftragsPositionen
        },
		{} // Weitere DataSets von Aufträgen und den dazugehörigen Positionen
	]
 }

Antwort

Beim erfolgreichen Anlegen der Aufträge wird der HTTP-Statuscode "200" zurückgegeben.

Die aktuellen Daten der angelegten Aufträge können über den Search-Call abgefragt werden.

Fehler-Fälle werden im folgenden Abschnitt beschrieben.

Response

{
    "api_version": 1,
    "code": 200, 		// HTTP-Statuscode
    "success": true,
    "rowcount": 0,  	// Anzahl der betroffenen Zeilen (Aufträge)
    "msg": "",
    "warning": "" 		// Hier werden ggf. Warnungen für die Logs des aufrufenden Systems mitgegeben
	"data": []
}

Fehlerfälle

Die folgenden Fehlerfälle können auftreten und zurückgemeldet werden

Fehler-Code

Erklärung

Bemerkung

404

Der Auftrag, der bearbeitet werden sollte, wurde nicht gefunden

405

Die angegebene Aktion ("Start", "Continue", "Cancel" oder "End") kann nicht ausgeführt werden.

Es kann z.B. kein "Start" erfolgen, wenn ein "Continue" noch nicht abgelaufen ist oder die Rückmeldung über den "End"-Call darf nicht erfolgen, wenn kein aktiver "Start" oder "Continue" gefunden wurde (unter Beachtung der Sperrzeit).

Beim"End"-Call kann dieser Status zurückgemeldet werden, wenn die gegebenen Aufträge sich nicht in einem erlaubten Status befinden.

poe Doku

API - Endpunkte - Salesorder

Inhalt

Beschreibung des Endpunkts

GET- /api/salesorder/startedit/<SALESORDER-ID>/<SYSTEMTYPE>/<SYSTEMNO>

Aufruf

GET -/api/salesorder/continueedit/<SALESORDER-ID>/<SYSTEMTYPE>/<SYSTEMNO>

Aufruf

Get- /api/salesorder/canceledit/<SALESSORDER-ID>/<SYSTEMTYPE>/<SYSTEMNO>

Aufruf

POST- /api/salesorder/endedit

Aufruf

Antwort

POST- /api/salesorder/create

Aufruf

Die wichtigsten Werte der Objekte

Antwort

Fehlerfälle