Diese Seite gibt Ihnen einen ersten Überblick zur API. Für detaillierte Einblicke nutzen Sie gern auch unser Entwicklerportal
Inhalt
- Einleitung
1.1 Zweck des Dokuments
1.2 Zweck der API - Funktionsweise
2.1 Definition des externen Systemaufrufs
2.1.1 Definition der Display URL
2.1.2 Definition der System URL
2.1.3 Auslöser für externen Systemaufruf
2.2 Sequenz
2.3 Das JSON Request Objekt
2.4 Das JSON Respone Objekt - Methoden
3.1 addAccountTransaction
3.2 addPayment
3.3 addSale
3.4 displayMessage
3.5 logMessage
3.6 modifyAccountTransaction
3.7 modifyPayment
3.8 modifySale
3.9 printMessage
3.10 removeReceiptItem
3.11 setInputLine
3.12 setReceiptCustomer
3.13 setReceiptCustomerGroup
3.14 setReceiptDiscount
3.15 setReceiptCustomData
3.16 callExternalSystem
3.17 unsetReceiptCustomer
3.18 unsetReceiptCustomerGroup
3.19 setReceiptOrderNumber
3.20 showWebPage
3.21 setCustomerDisplayMediaUrl
3.22 showButtons
3.23 switchButtonBadges
3.24 setAdditionalReceiptInfo
3.25 setReceiptInfotexts
3.26 addCouponItem
3.27 setReceiptFinishBlockingIndicator
3.28 unsetReceiptFinishBlockingIndicator - Demo & Beispiel
4.1 Integrierte Demo
4.2 Beispiel – Preisänderung
4.3 Beispiel – Hinzufügen eines Postens
1 Einleitung
1.1 Zweck des Dokuments
Mit dem Kassensystem KORONA.pos stellt die COMBASE AG ein leistungsfähiges Kassensystem bereit. Für das System stehen vielfältige Schnittstellen zur Verfügung, jedoch sind diese Rahmen der Definition festgeschrieben und dadurch für bestimmte Anwendungsfälle relativ unflexibel. In diesem Dokument wird eine Schnittstelle für die Anbindung beliebiger webbasierter Systeme an die Kassenanwendung KORONA.pos Client beschrieben.
1.2 Zweck der API
Mit der KORONA.pos Client API sollen webbasierte Drittsysteme oder einfache Webseiten mit dem Kassenanwendung interagieren können, d.h. während des Kassiervorgangs sollen Belegdaten zu einem Fremdsystem gesendet werden. In Abhängigkeit dieser Belegdaten, kann das Fremdsystem bestimmte Aktionen an der Kasse auslösen die den Beleg verändern oder erweitern.
Damit sollen beispielsweise Aktionen wie
- Laden eines Warenkorbs aus einem Webshop
- Erfassung von Kundenumsätzen in einem CRM
- Sammeln von Bonuspunkten
- Berechnung von Rabatten, Preisänderungen und Mengenänderungen
- Abfrage von individuellen Daten (PLZ, Kunden)
- Erfassung von Zusatzinformationen (Zertifikate, Bilder, Adressen)
gegen beliebige Fremdsysteme möglich sein. Diese Auflistung stellt nur einen kleinen Teil der Möglichkeiten dar, und ist beliebig erweiterbar.
2 Funktionsweise
Die Kasse ruft, entweder durch den Kassierer oder einen bestimmten Belegzustand ausgelöst, eine Website auf dem Hoheitsgebiet des Fremdsystems auf, und zeigt diese im Browser Control der Kasse an. Gleichzeitig werden alle bis dahin erfassten Belegdaten, an das Fremdsystem übergeben.
Das Fremdsystem kann jetzt anhand der Belegdaten und z.B. weiterer Eingaben des Kassierers im Browser Aktionen festlegen, die den Beleg verändern.
Die Aktionen werden mit dem Schließen des Browsers an die Kasse zurückgegeben und auf den Beleg angewendet. Der Kassierer kann jetzt noch beliebige „normale“ Aktionen durchführen, d.h. Artikel erfassen, stornieren, Preise und Menge ändern.
Damit Funktionen der Client-API auf Fremdsystemseite genutzt werden können, muss die Datei „korona-plugin-api.js“ im Javascript-Kontext auf der entsprechenden Webseite des Fremdsystems eingebunden sein. Um die Datei einzubinden, muss die Datei im Header der HTML-Webseite folgendermaßen als <script> referenziert werden: <script type=“text/javascript“ src=“webbrowser:korona-plugin-api.js“ />, wobei „src“ den Dateipfad von „korona-plugin-api.js“ angibt.
Ist das Fremdsystem nicht erreichbar wird die Aktion nach Erreichen des konfigurierten Timeouts abgebrochen.
2.1 Definition des externen Systemaufrufs
Ein externer Systemaufruf besteht aus zwei URLs, von denen mindestens eine konfiguriert sein muss:
• Display URL
• System URL
Ist nur die System-URL konfiguriert, wird direkt mit dem Aufruf der System-URL fortgefahren.
Ist nur die Display-URL konfiguriert, entfällt der Aufruf der System-URL beim Schließen der Webbrowser-Komponente.
Die URLs werden im Konfigurationsbereich des Backoffice von KORONA.pos Cloud gepflegt.
2.1.1 Definition der Display URL
Diese URL wird in der Browserkomponente der Kassenanwendung geladen. Zusätzlich kann über ein Flag definiert werden, ob Request-Daten(Kassen/Belegdaten) per HTTP-POST im JSON-Format an die entsprechende Webseite übermittelt werden, oder nur ein HTTP-GET-Aufruf ohne Request-Datenübermittlung ausgeführt wird.
2.1.2 Definition der System URL
Diese URL wird auf gerufen, wenn die Webbrowserkomponente der Kassenanwendung geschlossen wird, oder direkt, wenn keine Display-URL konfiguriert wurde. Die Request-Daten (Kassen/Belegdaten) werden per HTTP-POST im JSON-Format übermittelt. Die Response-Daten werden in der Rückgabe des HTTP-Aufrufs im JSON-Format erwartet.
(Zusätzlich können noch für die System-URL die Logindaten für eine HTTP-Basic-Authentifikation und die Timeouts für den Connect und Read konfiguriert werden)
2.1.3 Auslöser für externen Systemaufruf
Die Kommunikation wird immer durch die Kassenanwendung initiiert. Ein externer Systemaufruf kann an folgende Auslöser der Kassenanwendung konfiguriert werden:
- Auf eine oder mehrere beliebige Taste(n)
- Bei Total (Wechsel in den Bezahlstatus der Kassenanwendung)
- Beim Abschluss des Belegs als Rechnung
- Beim Abbrechen/Entfernen eines Belegs (Belegabbruch)
- Beim Stornieren einer zuvor abgeschlossenen Rechnungsbeleg
- Beim Abschluss des Belegs als Lieferschein
- Beim Kassiererlogin
- Beim Kassiererlogout
Der erste Auslöser wird im KORONA.pos Cloud Backoffice direkt bei der Konfiguration der Tastenlayouts bearbeitet. Die restlichen Auslöser werden am jeweiligen Kassenprofil konfiguriert.
2.2 Sequenz
Auslöser sind eine definierte Taste, der Wechsel in den Total Status oder der Belegabschluss.
2.3 Das JSON Request Objekt
Die Kasse sendet bei jedem Auslösen des externen Systemaufrufs den aktuellen Beleg als JSON Objekt im als Request an die hinterlegte URL. Das JSON Objekt entspricht dem Aufbau und Inhalt des Kassenbelegs. Es werden nur vorhandene Belegteile übertragen, ist auf dem Beleg kein Kunde vorhanden, fehlt der Objektteil im Aufruf. Damit kann der Request aus folgenden Haupteilen mit den jeweiligen Eigenschaften bestehen:
- Requestobjekt
- Belegobjekt – receipt
- Belegkunde – customer
- Posten – sales
- Kontenbuchungen – accounttransactions
- Zahlungen – payments
Beispiel eines Belegs mit zwei Posten, einer Kontenbuchung, für den Kunden Thomas Müller:
{
"application": {
"key": "KORONA.pos-Client",
"version": "1.84.1"
},
"cashier": {
"name": "Max Mustermann",
"number": "1"
},
"inputLine": "",
"organizationalUnit": {
"name": "COMBASE AG",
"number": "40"
},
"pos": {
"name": "Kasse 1 - CAG",
"number": "02"
},
"receipt": {
"accountTransactions": [
{
"bookingTime": "2017-02-24T19:11:50.828+01:00",
"cashier": {
"name": "Max Mustermann",
"number": "1"
},
"description": "Einzahlung",
"modifier": 3,
"sortingOrder": 2,
"account": {
"name": "Einzahlung",
"number": "1"
},
"amount": 10
}
],
"cashier": {
"name": "Max Mustermann",
"number": "1"
},
"counter": 0,
"creationTime": "2017-02-24T15:12:49.000+01:00",
"currency": {
"isoCode": "EUR",
"name": "Euro",
"number": "1"
},
"customer": {
"address": {
"city": "Dresden",
"line1": "Behringstrasse 45",
"state": "Deutschland"
},
"company": "COMBASE AG",
"firstName": "Thomas",
"gender": "MALE",
"lastName": "Meier",
"number": "1"
},
"customerGroup": {
"name": "Standard",
"number": "1"
},
"modificationTime": "2017-02-24T19:11:52.831+01:00",
"number": "1002117",
"organizationalUnit": {
"name": "COMBASE AG",
"number": "40"
},
"pos": {
"name": "Kasse 1 - CAG",
"number": "02"
},
"readonly": false,
"sales": [
{
"bookingTime": "2017-02-24T19:11:34.040+01:00",
"cashier": {
"name": "Max Mustermann",
"number": "1"
},
"description": "Tageskarte Erwachsener",
"modifier": 1,
"sortingOrder": 0,
"alternativeSector": true,
"hierarchicalOutline": "1",
"price": 15,
"product": {
"commodityGroup": {
"name": "Eintritt",
"number": "203"
},
"name": "Tageskarte Erwachsener",
"number": "2000",
"tags": [
"tageskarte"
]
},
"quantity": 1,
"recognitionCode": "2000",
"sector": {
"name": "MwSt – Standard 19%",
"number": "1"
},
"taxPayments": [
{
"amount": 2.39,
"taxRate": 19,
"vat": true
}
],
"total": {
"gross": 15,
"net": 12.61,
"value": 15
}
},
{
"bookingTime": "2017-02-24T19:11:35.042+01:00",
"cashier": {
"name": "Max Mustermann",
"number": "1"
},
"description": "Tageskarte Kind",
"modifier": 2,
"sortingOrder": 1,
"alternativeSector": true,
"hierarchicalOutline": "2",
"price": 8,
"product": {
"commodityGroup": {
"name": "Eintritt",
"number": "203"
},
"name": "Tageskarte Kind",
"number": "2001",
"tags": []
},
"quantity": 1,
"recognitionCode": "2001",
"sector": {
"name": "MwSt – Standard 19%",
"number": "1"
},
"taxPayments": [
{
"amount": 1.28,
"taxRate": 19,
"vat": true
}
],
"total": {
"gross": 8,
"net": 6.72,
"value": 8
}
}
],
"total": {
"discount": 0,
"gross": 33,
"net": 29.33,
"value": 33
},
"voided": false
},
"systemCurrency": {
"isoCode": "EUR",
"name": "Euro",
"number": "1"
},
"zcounter": 4
}
2.4 Das JSON Response Objekt
Das Response-Objekt für die gewünschten Aktionen auf dem Beleg wird einfach über die Verwendung der entsprechenden Funktionen in der Java-Skript Bibliothek erzeugt.
Im Beispiel wird ein neuer Posten „Artikel 1“ für 5 EUR auf den Beleg hinzugefügt, gleichzeitig wird ein Belegrabatt in Höhe von 10% vergeben, und dem Kassierer eine Nachricht „ Auf Sommeraktion hinweisen“ angezeigt.
Die verfügbaren Aktionen werden im nächsten Kapitel erläutert.
{
"actions": [
{
"type": "addSaleAction",
"infoTexts": [],
"price": "5",
"quantity": "1",
"recognitionCode": "1001",
"useAlternativeSector": false
},
{
"type": "modifyReceiptAction",
"discount": {
"amount": 10
}
}
],
"application": {
"key": null,
"version": null
}
3 Methoden
Zur Vereinfachung der Erstellung eines gültigen Response Objekts existiert eine Java-Skript Bibliothek (korona-plugin-api.js) die die notwendigen Funktionen zum Aufbau bereitstellt.
Die Bibliothek kann frei in der jeweiligen Anwendung verwendet werden. In den folgenden Kapiteln werden die in der API verfügbaren Belegaktionen erläutert.
Werden Eigenschaften in der Funktion nicht befüllt, werden diese durch die Standardeigenschaften des Objekts an der Kasse definiert.
Wird z.B. der Preis an einem Artikel nicht mitgegeben, wird der Standardpreis der Kasse verwendet.
An allen Teilobjekten des Belegs gibt es eine Eigenschaft „customData“ damit können während der Bearbeitung des Belegs beliebige Daten/Referenzen gespeichert werden, diese Daten werden mit jedem erneuten Request wieder übertragen. Die Werte der Eigenschaft „customData“ sind nach dem Belegabschluss nicht gespeichert.
3.1 addAccountTransaction
Mit dieser Funktion kann einem Beleg eine Kontobuchung (nicht umsatzwirksame Ein- oder Auszahlung) hinzugefügt werden. Die Nummer des Kontos muss einer Kontonummer im Kassensystem entsprechen.
korona_plugin_api.response.addAccountTransaction({
accountNumber: your.accountNumber.value,
description: your.description.value,
amount: your.amount.value,
fixedAmount: your.fixedAmount.checked,
infoTexts: your.InfoTexts,
notRemovable: your.notRemovable.checked,
customData: your.customData.value,
serialNumbers: your.serialNumbers.value,
customReferences: your.customReferences.value
});
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| accountNumber | Nummer des Kontos für die Buchung | ID |
| amount | Betrag | Variant |
| description | Bezeichnung des Kontos | Text |
| fixedAmount | Der Betrag kann durch den Kassierer nicht geändert werden | Boolean |
| infoTexts | Infotext an der Kontobuchung | Text |
| notRemovable | Die Buchung kann durch den Kassierer nicht storniert werden | Boolean |
| customData | Nicht sichtbare Daten zur freien Verwendung | Text |
| serialNumbers | Seriennummer an der Buchung für die Erfassung einer Gutscheinnummer oder Kostenstelle | Integer |
| customReferences | Benutzerdefinierte Referenzen | Variant |
3.2 addPayment
Mit dieser Funktion kann einem Beleg eine Zahlung hinzugefügt werden. Ein Teil oder der Ganze Beleg gilt damit als bezahlt, es muss nur noch die Differenz bezahlt werden, oder beim vollen Betrag nichts mehr. Die Nummer muss einer ID im Kassensystem entsprechen.
korona_plugin_api.response.addPayment({
inputAmount: your.inputAmount.value,
paymentMethodNumber: your.paymentMethodNumber.value,
customData: your.customData.value,
balanceInfo: your.balanceInfo.value,
paymentCardInformation: your.paymentCardInformation.value,
customReferences: your.customReferences.value
});
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| inputAmount | Betrag der Zahlung | Variant |
| paymentMethodNumber | Nummer der Zahlungsmethode | ID |
| customData | Nicht sichtbare Daten zur freien Verwendung | Text |
| balanceInfo | Kontostandinformationen | Integer |
| paymentCardInformation | Karteninformation zur Bezahlung | Text |
| customReferences | Benutzerdefinierte Referenzen | Variant |
3.3 addSale
Fügt dem Beleg einen Posten hinzu. Der Code muss einer Artikelnummer oder einer EAN im Kassensystem entsprechen.
korona_plugin_api.response.addSale({
discount: {
your.amount.value,
your.percent.checked
},
ticketDefinition: {
your.categoryName.value,
your.printCopies.value,
your.mergedTicketPrintout.checked,
your.infoTexts.value,
your.eventInfo.value,
your.ticketValidityDescription.value
},
infoTexts: your.InfoTexts,
notRemovable: your.notRemovable.checked,
price: your.price.value,
quantity: your.quantity.value,
recognitionCode: your.recognitionCode.value,
useAlternativeSector: your.useAlternativeSector.checked,
customData: your.customData.value,
serialNumbers: your.serialNumbers.value,
customReferences: your.customReferences.value
});
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| description | Bezeichnung des Artikels | Text |
| amount | Wert des Rabatts für den Posten | Variant |
| percent | Definiert ob der Wert als prozentualer Rabatt berechnet wird | Boolean |
| categoryName | Name der Ticketkategorie | String |
| printCopies | Anzahl zu druckender Ticketkopien | Integer |
| mergedTicketPrintout | Zusammengefügter Ticketdruck | Boolean |
| infoTexts | Neuer Infotext für das Ticket | Text |
| eventInfo | Neue Eventinformationen auf dem Ticket | Text |
| ticketValidityDescription | Beschreibung zur Gültigkeit des Tickets | Text |
| infoTexts | Infotext zu dem Artikel | Text |
| notRemovable | Der Posten kann nicht storniert werden | Boolean |
| price | Artikelpreis | Variant |
| quantity | Artikelmenge | Variant |
| recognitionCode | Artikelnummer oder EAN | ID |
| useAlternativeSector | Alternativsteuer verwenden | Boolean |
| customData | Nicht sichtbare Daten zur freien Verwendung | Text |
| serialNumbers | Seriennummer oder Ticketnummer des Artikels | Variant |
| customReferences | Benutzerdefinierte Referenzen | Variant |
3.4 displayMessage
Zeigt dem Kassierer eine Nachricht als Popup zur Bestätigung.
korona_plugin_api.response.displayMessage({
text: your.text.value,
title: your.title.value,
level: your.level.value
});
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| level | INFO, WARN, ERROR | String |
| text | Nachricht die angezeigt werden soll | Text |
| title | Überschrift der Meldung | Text |
3.5 logMessage
Schreibt einen Log-Eintrag in die lokale Kassenlog-Datei.
korona_plugin_api.response.logMessage({
text: your.text.value,
level: your.level.value
});
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| level | INFO, WARN, ERROR | String |
| text | Nachricht die angezeigt werden soll | Text |
3.6 modifyAccountTransaction
Ändert eine vorhandene Kontobuchung am Beleg.
korona_plugin_api.response.modifyAccountTransaction({
modifier: your.modifier.value,
amount: your.amount.value,
fixedAmount: your.fixedAmount.checked,
infoTexts: your.infoTexts.value
notRemovable: your.notRemovable.checked,
customData: your.customData.value,
serialNumbers: your.serialNumbers.value,
customReferences: your.customReferences.value
});
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| modifier | ID-der Belegposition | ID |
| amount | Neuer Betrag der Buchung | Variant |
| fixedAmount | Markiert den Betrag als nicht änderbar | Boolean |
| infoTexts | Neuer Infotext an der Buchung | Text |
| notRemovable | Markiert die Buchung als nicht stornierbar | Boolean |
| customData | Nicht sichtbare Daten zur freien Verwendung | Text |
| serialNumbers | Seriennummer oder Gutscheinnummer | Variant |
| customReferences | Benutzerdefinierte Referenzen | Variant |
3.7 modifyPayment
Fügt einer vorhandenen Zahlung eine interne Information hinzu.
korona_plugin_api.response.modifyPayment({
modifier: form.modifier.value,
customData: your.customData.value,
customReferences: your.customReferences.value
});
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| modifier | ID-der Belegposition | ID |
| customData | Nicht sichtbare Daten zur freien Verwendung | Text |
| customReferences | Benutzerdefinierte Referenzen | Variant |
3.8 modifySale
Ändert eine angegebene Belegposition (Posten) mit den entsprechenden Werten.
korona_plugin_api.response.modifySale({
modifier: your.modifier.value,
discount: {
your.amount.value,
your.percent.checked
},
ticketDefinition: {
your.categoryName.value,
your.printCopies.value,
your.mergedTicketPrintout.checked,
your.infoTexts.value,
your.eventInfo.value,
your.ticketValidityDescription.value
},
infoTexts: your.InfoTexts,
price: your.price.value,
quantity: your.quantity.value,
useAlternativeSector: your.useAlternativeSector.value,
serialNumbers: your.serialNumbers.value,
customData: your.customData.value,
customReferences: your.customReferences.value
});
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| modifier | ID-der Belegposition | Integer |
| amount | Neuer Wert des Rabatts für den Posten | Variant |
| percent | Definiert ob der Wert als prozentualer Rabatt berechnet wird | Boolean |
| categoryName | Name der Ticketkategorie | String |
| printCopies | Anzahl zu druckender Ticketkopien | Integer |
| mergedTicketPrintout | Zusammengefügter Ticketdruck | Boolean |
| infoTexts | Neuer Infotext für das Ticket | Text |
| eventInfo | Neue Eventinformationen auf dem Ticket | Text |
| ticketValidityDescription | Beschreibung zur Gültigkeit des Tickets | Text |
| infoTexts | Neuer Infotext für den Posten | Text |
| price | Neuer Preis am Posten | Variant |
| quantity | Neue Menge des Postens | Variant |
| useAlternativeSector | Alternative Steuer verwenden | Boolean |
| serialNumbers | Seriennummer oder Ticketnummer des Artikels | Variant |
| customData | Nicht sichtbare Daten zur freien Verwendung | Text |
| customReferences | Benutzerdefinierte Referenzen | Variant |
3.9 printMessage
Druckt einen beliebigen Inhalt inkl. Barcode oder QR-Code auf dem Belegdrucker.
korona_plugin_api.response.printMessage({
text: your.text.value,
lines: your.lines.value,
title: your.title.value,
qrCode: your.qrCode.value,
code39Barcode: your.code39Barcode.value,
barcode: your.barcode.value,
printFooter: your.printFooter.checked,
printHeader: your.printHeader.checked
});
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| text | Zu druckender Text | Text |
| lines | Legt Formatierung des Textes fest | Variant |
| title | Drucktitel (wird fett gedruckt) | Text |
| qrCode | Wert der als QR-Code gedruckt werden soll | Text |
| code39Barcode | Wert der als Code39 Barcode gedruckt werden soll | Text |
| printFooter | Legt fest ob der Standardbelegfuß gedruckt wird | Boolean |
| printHeader | Legt fest ob der Standardbelegkopf gedruckt wird | Boolean |
3.10 removeReceiptItem
Entfernt ein ausgewähltes Belegobjekt (Posten, Kontobuchung oder Zahlung) vom Beleg anhand der Eigenschaft „Modifier“ an jedem Objekt.
korona_plugin_api.response.removeReceiptItem({
modifier: form.modifier.value
});
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| modifier | ID-der Belegposition | Integer |
3.11 setInputLine
Füllt die Eingabezeile der Kasse beim Rücksprung mit dem angegeben Wert.
korona_plugin_api.response.setInputLine({
value: your.value.value
});
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| value | Wert für die Eingabezeile | Variant |
3.12 setReceiptCustomer
Setzt einen Kunden am Beleg, ist der Kunde noch nicht vorhanden, wird dieser mit den übergebenen Daten angelegt.
korona_plugin_api.response.setReceiptCustomer({
address: {
city: your.city.value,
country: your.country.value,
line1: your.line1.value,
line2: your.line2.value,
postalCode: your.postalCode.value,
state: your.state.value
},
alternativePhone: your.alternativePhone.value,
birthday: your.birthday.value,
company: your.company.value,
fax: your.fax.value,
firstName: your.firstName.value,
gender: your.gender.value,
lastName: your.lastName.value,
number: your.number.value,
phone: your.phone.value,
salutation: your.salutation.value,
title: your.title.value
});
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| city | Stadt | Text |
| country | Land | Text |
| line1 | Anschrift Zeile 1 | Text |
| line2 | Anschrift Zeile 2 | Text |
| postalCode | PLZ | Text |
| state | Bundesland | Text |
| alternativePhone | Telefon 2 | Text |
| birthday | Geburtsdatum | Text |
| company | Firma | Text |
| fax | Fax | Text |
| firstName | Vorname | Text |
| gender | Geschlecht | Text |
| lastName | Nachname | Text |
| number | Kundennummer | Text |
| phone | Telefon | Text |
| salutation | Anrede | Text |
| title | Titel | Text |
3.13 setReceiptCustomerGroup
Setzt eine Kundengruppe anhand der Kundengruppennummer am Beleg.
korona_plugin_api.response.setReceiptCustomerGroup({
customerGroupNumber: your.customerGroupNumber.value,
});
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| customerGroupNumber | Nummer der gewünschten Kundengruppe | Variant |
3.14 setReceiptDiscount
Setzt eine Kundengruppe anhand der Kundengruppennummer am Beleg.
korona_plugin_api.response.setReceiptDiscount(
amount: your.amount.value,
percent: your.percent.checked
);
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| amount | Wert des Rabatts | Variant |
| percent | Definiert ob der Wert als prozentualer Rabatt berechnet wird | Boolean |
3.15 setReceiptCustomData
Setzt das Datenfeld für benutzerdefinierte Informationen am Beleg.
korona_plugin_api.response.setReceiptCustomData({
customData: your.customData.value
});
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| customData | Nicht sichtbare Daten zur freien Verwendung auf Belegebene | Text |
3.16 callExternalSystem
Damit kann über das Response Objekt eine weitere URL aufgerufen werden.
korona_plugin_api.response.callExternalSystem({
displayUrl: your.displayUrl.value,
displayUrlPost: your.displayUrlPost.checked,
systemUrl: your.systemUrl.value,
login: your.dontStoreLogin.value,
password: your.dontStorePassword.value,
connectTimeoutMillis: your.connectTimeoutMillis.value,
readTimeoutMillis: your.readTimeoutMillis.value
});
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| displayUrl | URL zur Anzeige im Browser | String |
| displayUrlPost | Soll der Aufruf als POST Request gesendet werden? | Boolean |
| systemUrl | URL zum Aufruf im Hintergrund ohne Interaktion | String |
| login | Nutzername (falls notwendig) | String |
| password | Passwort (falls notwendig) | String |
| connectTimeoutMillis | Verbindungs-Timout in ms | Integer |
| readTimeoutMillis | Lesen-Timeout in ms | Integer |
3.17 unsetReceiptCustomer
Löscht einen vorhandenen Kunden vom Beleg, der Beleg wird wieder auf den anonymen Standardkunden gesetzt.
korona_plugin_api.response.unsetReceiptCustomer();
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| keine | - | - |
3.18 unsetReceiptCustomerGroup
Löscht eine gesetzte Kundengruppe am Beleg, es gilt dann wieder die Standard-Kundengruppe.
korona_plugin_api.response.unsetReceiptCustomerGroup();
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| keine | - | - |
3.19 setReceiptOrderNumber
Setzt eine Auftragsnummer oder Buchungsnummer am Beleg.
korona_plugin_api.response.setReceiptOrderNumber({
orderNumber: your.orderNumber.value
});
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| orderNumber | Nummer des Auftrags oder der Buchung | Variant |
3.20 showWebPage
Zeigt eine Website an.
korona_plugin_api.response.showWebPage({ displayUrl: your.displayUrl.value, customerDisplayUrl: your.customerDisplayUrl, displayUrl: your.displayUrlPost.checked, login: your.login.value, password: your.password.value });
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| displayUrl | Webseite für Kassierer | String |
| customerDisplayUrl | Webseite für Kundendisplay | String |
| login | Logindaten | String |
| password | Passwort | String |
3.21 setCustomerDisplayMediaUrl
Zeigt eine URL auf dem digitalen Kundendisplay an.
korona_plugin_api.response.setCustomerDisplayMediaUrl({ mediaUrl: your.mediaUrl.value });
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| MediaUrl | Url auf dem Kundendisplay | String |
3.22 showButtons
Erstellt Buttons mit Layout Nummer und Namen auf angegebener Ansicht.
korona_plugin_api.response.showButtons({ title: your.title.value, buttons: your.buttons.value, buttonLayoutNumber: your.buttonLayoutNumber.value });
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| title | Titel des Buttons | Text |
| buttons | Beschriftung | Text |
| buttonLayoutNumber | Integer |
3.23 switchButtonBadges
Wechselt das Tastenlayout auf Basis von Voreinstellung im Backoffice.
korona_plugin_api.response.switchButtonBadges({ badges: your.badges.value });
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| badges | Tastaturlayout | Integer |
3.24 setAdditionalReceiptInfo
Zusätzliche Beleginformationen abrufen.
korona_plugin_api.response.setAdditionalReceiptInfo({ additionalReceiptInfoTypeNumber: your.additionalReceiptInfoTypeNumber.value, info: your.info.value });
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| additionalReceiptInfoTypeNumber | Infotypnummer | Integer |
| info | Information | Text |
3.25 setReceiptInfotexts
Setzt dem Beleg einen Infotext.
korona_plugin_api.response.setReceiptInfotexts({ infoTexts: your.infoTexts.value )};
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| infoTexts | Neuer Infotext für den Beleg | Text |
3.26 addCouponItem
Externe Couponnummer hinzufügen.
korona_plugin_api.response.addCouponItem({ number: your.number.value )};
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| number | Couponnummer | Integer |
3.27 setReceiptFinishBlockingIndicator
Setzt Belegabschlusssperre, verhindert Belegabschluss.
korona_plugin_api.response.setReceiptFinishBlockingIndicator({ blockingIndicatoryour.blockingIndicator.checked });
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| blockingIndicator | Soll Belegabschluss verhindert werden? | Boolean |
3.28 unsetReceiptFinishBlockingIndicator
Hebt Belegabschlusssperre auf.
korona_plugin_api.response.setReceiptFinishBlockingIndicator();
| Eigenschaft | Beschreibung | Typ |
|---|---|---|
| keine | - | - |
4 Demo & Beispiel
4.1 Integrierte Demo
Unter diesem Absatz befindet sich ein Link, welcher auf eine Demowebseite führt. Dort kann unter Request ein Beispiel eines Request–Objektes betrachtet werden. Über die Funktionalitäten der Seite kann ein beliebiges Response Objekt interaktiv zusammengestellt werden, welches am Ende der Seite angezeigt wird.
Im Kassenclient ist die Demowebseite ebenfalls integriert, diese kann als externer Systemaufruf über eine Taste aufgerufen werden.
Für die Demo muss als Display-URL „webbrowser:korona-plugin-api-demo.html“ eingetragen werden.
Link für die Demowebseite: https://support.korona.de/misc/korona-pos-api-demo/1.96/korona-plugin-api-demo.html
4.2 Beispiel – Preisänderung
Das folgende Beispiel zeigt einen Ausgangsbeleg (100575). In diesem Belegzustand wird nun der Preis für einen vorhanden Posten von 3,00 EUR auf 2,80 EUR verändert.
Ausgangsbeleg
BELEG 100575 Datum: 29.12.2014 15:11:59 Kassierer: Max Mustermann Filiale: Store 1 Kasse: Kasse 3 12 * 2,95 EUR Coca Cola .................. 35,40 EUR(19%) 10 * 3,00 EUR Fanta ...................... 30,00 EUR(19%) ________________________________________________________ Summe: 65,40 EUR Summe (Netto) 54,96 EUR 2 * 19% USt (Netto): 54,96 EUR 10,44 EUR ________________________________________________________
Beleg als POST Objekt zum Fremdsystem
application/x-www-form-urlencoded
request =
{
"application":{
"key":"KORONA.pos-Client",
"version":"1"
},
"cashier":{
"name":"Max Mustermann",
"number":"1"
},
"inputLine":"",
"organizationalUnit":{
"name":"Store 1",
"number":"1"
},
"pos":{
"name":"Kasse 3",
"number":"03"
},
"receipt":{
"accountTransactions":[
],
"cashier":{
"name":"Max Mustermann",
"number":"1"
},
"counter":0,
"creationTime":"2014-12-29T15:11:06.000+01:00",
"currency":{
"isoCode":"EUR",
"name":"Euro",
"number":"1"
},
"customerGroup":{
"name":"Standard",
"number":"1"
},
"modificationTime":"2014-12-29T15:29:47.395+01:00",
"number":"100575",
"organizationalUnit":{
"name":"Store 1",
"number":"1"
},
"pos":{
"name":"Kasse 3",
"number":"03"
},
"sales":[
{
"bookingTime":"2014-12-29T15:11:08.000+01:00",
"cashier":{
"name":"Max Mustermann",
"number":"1"
},
"description":"Coca Cola",
"modifier":1,
"sortingOrder":0,
"alternativSector":true,
"hierarchicalOutline":"1",
"price":2.95,
"product":{
"name":"Coca Cola",
"number":"1001"
},
"quantity":12,
"recognitionCode":"1001",
"sector":{
"name":"Standard",
"number":"1"
},
"taxPayments":[
{
"amount":5.64,
"taxRate":19,
"vat":true
}
],
"total":{
"gross":35.4,
"net":29.76,
"value":35.4
}
},
{
"bookingTime":"2014-12-29T15:11:15.000+01:00",
"cashier":{
"name":"Max Mustermann",
"number":"1"
},
"description":"Fanta",
"modifier":2,
"sortingOrder":1,
"alternativSector":true,
"hierarchicalOutline":"2",
"price":3,
"product":{
"name":"Fanta",
"number":"1002"
},
"quantity":10,
"recognitionCode":"1002",
"sector":{
"name":"Standard",
"number":"1"
},
"taxPayments":[
{
"amount":4.8,
"taxRate":19,
"vat":true
}
],
"total":{
"gross":30,
"net":25.2,
"value":30
}
}
],
"total":{
"discount":0,
"gross":65.4,
"net":54.96,
"value":65.4
},
"voided":false
},
"systemCurrency":{
"isoCode":"EUR",
"name":"Euro",
"number":"1"
},
"zcounter":24
}
Java-Skript für die Preisänderung des zweiten Postens auf 2,80 EUR.
korona_plugin_api.response.modifySale({
modifier : 2,
price : 3.00
});
Response-Objekt nach der Aktion
application/json
response =
{
"actions":[
{
"type":"modifySaleAction",
"modifier":"2",
"price": "2.8"
}
],
}
Neuer Beleg auf Basis der Antwort
BELEG 100575 Datum: 29.12.2014 15:45:26 Kassierer: Max Mustermann Filiale: Store 1 Kasse: Kasse 3 12 * 2,95 EUR Coca Cola .................. 35,40 EUR(19%) 10 * 2,80 EUR Fanta ...................... 28,00 EUR(19%) ________________________________________________________ Summe: 63,40 EUR Summe (Netto) 53,26 EUR 2 * 19% USt (Netto): 53,26 EUR 10,14 EUR ________________________________________________________
4.3 Beispiel – Hinzufügen eines Postens
Das folgende Beispiel zeigt einen Ausgangsbeleg (100575). In diesem Belegzustand wird nun ein weiterer Artikel (Versand) hinzugefügt.
Ausgangsbeleg
Neuer Beleg auf Basis der Antwort
BELEG 100575 Datum: 29.12.2014 15:45:26 Kassierer: Max Mustermann Filiale: Store 1 Kasse: Kasse 3 12 * 2,95 EUR Coca Cola .................. 35,40 EUR(19%) 10 * 2,80 EUR Fanta ...................... 28,00 EUR(19%) ________________________________________________________ Summe: 63,40 EUR Summe (Netto) 53,26 EUR 2 * 19% USt (Netto): 53,26 EUR 10,14 EUR ________________________________________________________
Request-Objekt aus der Kasse an die aufgerufene URL
application/x-www-form-urlencoded
request =
{
"application":{
"key":"KORONA.pos-Client",
"version":"1"
},
"cashier":{
"name":"Max Mustermann",
"number":"1"
},
"inputLine":"",
"organizationalUnit":{
"name":"Store 1",
"number":"1"
},
"pos":{
"name":"Kasse 3",
"number":"03"
},
"receipt":{
"accountTransactions":[
],
"cashier":{
"name":"Max Mustermann",
"number":"1"
},
"counter":0,
"creationTime":"2014-12-29T15:11:06.000+01:00",
"currency":{
"isoCode":"EUR",
"name":"Euro",
"number":"1"
},
"customerGroup":{
"name":"Standard",
"number":"1"
},
"modificationTime":"2014-12-29T15:29:47.395+01:00",
"number":"100575",
"organizationalUnit":{
"name":"Store 1",
"number":"1"
},
"pos":{
"name":"Kasse 3",
"number":"03"
},
"sales":[
{
"bookingTime":"2014-12-29T15:11:08.000+01:00",
"cashier":{
"name":"Max Mustermann",
"number":"1"
},
"description":"Coca Cola",
"modifier":1,
"sortingOrder":0,
"alternativSector":true,
"hierarchicalOutline":"1",
"price":2.95,
"product":{
"name":"Coca Cola",
"number":"1001"
},
"quantity":12,
"recognitionCode":"1001",
"sector":{
"name":"Standard",
"number":"1"
},
"taxPayments":[
{
"amount":5.64,
"taxRate":19,
"vat":true
}
],
"total":{
"gross":35.4,
"net":29.76,
"value":35.4
}
},
{
"bookingTime":"2014-12-29T15:11:15.000+01:00",
"cashier":{
"name":"Max Mustermann",
"number":"1"
},
"description":"Fanta",
"modifier":2,
"sortingOrder":1,
"alternativSector":true,
"hierarchicalOutline":"2",
"price":2.80,
"product":{
"name":"Fanta",
"number":"1002"
},
"quantity":10,
"recognitionCode":"1002",
"sector":{
"name":"Standard",
"number":"1"
},
"taxPayments":[
{
"amount":4.47,
"taxRate":19,
"vat":true
}
],
"total":{
"gross":28,
"net":23.53,
"value":28
}
}
],
"total":{
"discount":0,
"gross":63.4,
"net":53.29,
"value":63.4
},
"voided":false
},
"systemCurrency":{
"isoCode":"EUR",
"name":"Euro",
"number":"1"
},
"zcounter":24
}
Java-Skript für die das Hinzufügen des Versands für 3 EUR.
korona_plugin_api.response.addSale({
recognitionCode : 1000,
quantity : 1,
price : 4.95
});
Response-Objekt nach der Aktion
application/json
response =
{
"actions": [
{
"type": "addSaleAction",
"price": "4.95",
"quantity": "1",
"recognitionCode": "1000",
"useAlternativSector": false
}
],
}
Neuer Beleg auf Basis der Antwort
BELEG 100575 Datum: 29.12.2014 15:48:13 Kassierer: Max Mustermann Filiale: Store 1 Kasse: Kasse 3 12 * 2,95 EUR Coca Cola .................. 35,40 EUR(19%) 10 * 2,80 EUR Fanta ...................... 28,00 EUR(19%) Versand ..................... 4,95 EUR(19%) ________________________________________________________ Summe: 68,35 EUR Summe (Netto) 57,42 EUR 3 * 19% USt (Netto): 57,42 EUR 10,93 EUR ________________________________________________________