Seitenvergleich

Über disÜber diesen Enpunkt werden alle API-Calls verarbeitet, die sich mit Aufträgen befassen.

Rein Thematisch gehören dazu 2 Thematiken:

Temp. Sperren von Aufträgen (z.B. zum abkassieren an der Kasse)
Anlegen von Aufträgen

Info
Die Abfrage von Aufträgen soll über den Search-API-Endpunkt erfolgen => siehe dazu "API - Search"

Inhalt

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

Codeblock

language	js
theme	DJango
title	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.

Codeblock

language	js
theme	DJango
title	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.

Codeblock

language	js
theme	DJango
title	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.

Warnung

title	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.

Codeblock

language	js
theme	DJango
title	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": [
		{ 
			"auftragAuftrag": {%AuftragObjekt%}
			"auftrag_positionAuftragPosition": [{%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.

Codeblock

language	js
theme	DJango
title	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
Anker
SalesOrderCreate
SalesOrderCreate

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 mit einem Kunden-Objekt und einer Liste (Array) von Auftragpositionen-Objekten bestehen. Ein Kunden-Objekt ist notwendig, da die Aufträge immer einen Bezug haben müssen, damit sie ggf. an anderer Stelle weiter gearbeitet werden können.

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" gesetzt zu übergeben und ist wäre für eine 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 Benutzer Mitarbeiter/Verkäufer verknüpft werden soll.
extaunr	--	INTEGER	Wird eine Auftrags-Nr. mit angegeben, so wird diese in dem Feld "extaunr" gesetzt und ist für eine späteren Export vorhandenIn 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 werden sollten mit dem Status 10 ("offfen") angelegt werden, damit sie bearbeiten 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 müssen können nicht mit übergeben werden und werden somit auch nicht angelegt. Die Kunden-Anlage oder Aktualisierung muss erfolgt über den Endpunkt API : createCustomer erfolgen- Endpunkte - CreateCustomer. Somit muss kann die Kunden-Nr. im Auftrags-Objekt einfach nur direkt angegeben werden.

Codeblock

language	js
theme	DJango
title	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, Kunden und den dazugehörigen Positionen
	]
 }

Antwort

Wenn die gegebenen Auftrag-Datensätze erfolgreich verarbeitet wurden, werden die angelegten Aufträge im Format der Search-Calls noch einmal zurückgeliefertBeim 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.

Codeblock

language	js
theme	DJango
title	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": [
        {%AuftragObjekt%},
        {},		// Ggf. weitere Auftrags-Objekte
    ]
}

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.

Versionen im Vergleich

Alte Version 10

Neue Version Aktuell

Schlüssel

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
Anker
SalesOrderCreate
SalesOrderCreate

Aufruf

Die wichtigsten Werte der Objekte

Antwort

Fehlerfälle

Seitenvergleich

Versionen im Vergleich

Alte Version 10

Neue Version Aktuell

Schlüssel

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 AnkerSalesOrderCreateSalesOrderCreate

Aufruf

Die wichtigsten Werte der Objekte

Antwort

Fehlerfälle

POST- /api/salesorder/create
Anker
SalesOrderCreate
SalesOrderCreate