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
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
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 | 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 | 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:
| |||
{
"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.
{
"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. |