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
});


		
EigenschaftBeschreibungTyp
accountNumberNummer des Kontos für die BuchungID
amountBetragVariant
descriptionBezeichnung des KontosText
fixedAmountDer Betrag kann durch den Kassierer nicht geändert
werden
Boolean
infoTextsInfotext an der KontobuchungText
notRemovableDie Buchung kann durch den Kassierer nicht
storniert werden
Boolean
customDataNicht sichtbare Daten zur freien VerwendungText
serialNumbersSeriennummer an der Buchung für die Erfassung
einer Gutscheinnummer oder Kostenstelle
Integer
customReferencesBenutzerdefinierte ReferenzenVariant

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
});
EigenschaftBeschreibungTyp
inputAmountBetrag der ZahlungVariant
paymentMethodNumberNummer der ZahlungsmethodeID
customDataNicht sichtbare Daten zur freien VerwendungText
balanceInfoKontostandinformationenInteger
paymentCardInformationKarteninformation zur BezahlungText
customReferencesBenutzerdefinierte ReferenzenVariant

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
});
EigenschaftBeschreibungTyp
descriptionBezeichnung des ArtikelsText
amountWert des Rabatts für den PostenVariant
percentDefiniert ob der Wert als prozentualer Rabatt
berechnet wird
Boolean
categoryNameName der TicketkategorieString
printCopiesAnzahl zu druckender TicketkopienInteger
mergedTicketPrintoutZusammengefügter TicketdruckBoolean
infoTextsNeuer Infotext für das TicketText
eventInfoNeue Eventinformationen auf dem TicketText
ticketValidityDescriptionBeschreibung zur Gültigkeit des TicketsText
infoTextsInfotext zu dem ArtikelText
notRemovableDer Posten kann nicht storniert werdenBoolean
priceArtikelpreisVariant
quantityArtikelmengeVariant
recognitionCodeArtikelnummer oder EANID
useAlternativeSectorAlternativsteuer verwendenBoolean
customDataNicht sichtbare Daten zur freien VerwendungText
serialNumbersSeriennummer oder Ticketnummer des ArtikelsVariant
customReferencesBenutzerdefinierte ReferenzenVariant

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
});
EigenschaftBeschreibungTyp
levelINFO, WARN, ERRORString
textNachricht die angezeigt werden sollText
titleÜberschrift der MeldungText

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
});
EigenschaftBeschreibungTyp
levelINFO, WARN, ERRORString
textNachricht die angezeigt werden sollText

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
});
EigenschaftBeschreibungTyp
modifierID-der BelegpositionID
amountNeuer Betrag der BuchungVariant
fixedAmountMarkiert den Betrag als nicht änderbarBoolean
infoTextsNeuer Infotext an der BuchungText
notRemovableMarkiert die Buchung als nicht stornierbarBoolean
customDataNicht sichtbare Daten zur freien VerwendungText
serialNumbersSeriennummer oder GutscheinnummerVariant
customReferencesBenutzerdefinierte ReferenzenVariant

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
});
EigenschaftBeschreibungTyp
modifierID-der BelegpositionID
customDataNicht sichtbare Daten zur freien VerwendungText
customReferencesBenutzerdefinierte ReferenzenVariant

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
});
EigenschaftBeschreibungTyp
modifierID-der BelegpositionInteger
amountNeuer Wert des Rabatts für den PostenVariant
percentDefiniert ob der Wert als prozentualer Rabatt
berechnet wird
Boolean
categoryNameName der TicketkategorieString
printCopiesAnzahl zu druckender TicketkopienInteger
mergedTicketPrintoutZusammengefügter TicketdruckBoolean
infoTextsNeuer Infotext für das TicketText
eventInfoNeue Eventinformationen auf dem TicketText
ticketValidityDescriptionBeschreibung zur Gültigkeit des TicketsText
infoTextsNeuer Infotext für den PostenText
priceNeuer Preis am PostenVariant
quantityNeue Menge des PostensVariant
useAlternativeSectorAlternative Steuer verwendenBoolean
serialNumbersSeriennummer oder Ticketnummer des ArtikelsVariant
customDataNicht sichtbare Daten zur freien VerwendungText
customReferencesBenutzerdefinierte ReferenzenVariant

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
});
EigenschaftBeschreibungTyp
textZu druckender TextText
linesLegt Formatierung des Textes festVariant
titleDrucktitel (wird fett gedruckt)Text
qrCodeWert der als QR-Code gedruckt werden sollText
code39BarcodeWert der als Code39 Barcode gedruckt werden sollText
printFooterLegt fest ob der Standardbelegfuß gedruckt wirdBoolean
printHeaderLegt fest ob der Standardbelegkopf gedruckt wirdBoolean

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
});
EigenschaftBeschreibungTyp
modifierID-der BelegpositionInteger

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
});
EigenschaftBeschreibungTyp
valueWert für die EingabezeileVariant

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
});
EigenschaftBeschreibungTyp
cityStadtText
countryLandText
line1Anschrift Zeile 1Text
line2Anschrift Zeile 2Text
postalCodePLZText
stateBundeslandText
alternativePhoneTelefon 2Text
birthdayGeburtsdatumText
companyFirmaText
faxFaxText
firstNameVornameText
genderGeschlechtText
lastNameNachnameText
numberKundennummerText
phoneTelefonText
salutationAnredeText
titleTitelText

3.13 setReceiptCustomerGroup

Setzt eine Kundengruppe anhand der Kundengruppennummer am Beleg.

korona_plugin_api.response.setReceiptCustomerGroup({
        customerGroupNumber: your.customerGroupNumber.value,
});
EigenschaftBeschreibungTyp
customerGroupNumberNummer der gewünschten KundengruppeVariant

3.14 setReceiptDiscount

Setzt eine Kundengruppe anhand der Kundengruppennummer am Beleg.

korona_plugin_api.response.setReceiptDiscount(
        amount: your.amount.value,
        percent: your.percent.checked
);
EigenschaftBeschreibungTyp
amountWert des RabattsVariant
percentDefiniert 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
});
EigenschaftBeschreibungTyp
customDataNicht 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
});
EigenschaftBeschreibungTyp
displayUrlURL zur Anzeige im BrowserString
displayUrlPostSoll der Aufruf als POST Request gesendet
werden?
Boolean
systemUrlURL zum Aufruf im Hintergrund ohne InteraktionString
loginNutzername (falls notwendig)String
passwordPasswort (falls notwendig)String
connectTimeoutMillisVerbindungs-Timout in msInteger
readTimeoutMillisLesen-Timeout in msInteger

3.17 unsetReceiptCustomer

Löscht einen vorhandenen Kunden vom Beleg, der Beleg wird wieder auf den anonymen Standardkunden gesetzt.

korona_plugin_api.response.unsetReceiptCustomer();
EigenschaftBeschreibungTyp
keine--

3.18 unsetReceiptCustomerGroup

Löscht eine gesetzte Kundengruppe am Beleg, es gilt dann wieder die Standard-Kundengruppe.

korona_plugin_api.response.unsetReceiptCustomerGroup();
EigenschaftBeschreibungTyp
keine--

3.19 setReceiptOrderNumber

Setzt eine Auftragsnummer oder Buchungsnummer am Beleg.

korona_plugin_api.response.setReceiptOrderNumber({
        orderNumber: your.orderNumber.value
});
EigenschaftBeschreibungTyp
orderNumberNummer des Auftrags oder der BuchungVariant

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 
}); 
EigenschaftBeschreibungTyp
displayUrlWebseite für KassiererString
customerDisplayUrlWebseite für KundendisplayString
loginLogindatenString
passwordPasswortString

3.21 setCustomerDisplayMediaUrl

Zeigt eine URL auf dem digitalen Kundendisplay an.

korona_plugin_api.response.setCustomerDisplayMediaUrl({ 
       mediaUrl: your.mediaUrl.value
}); 
EigenschaftBeschreibungTyp
MediaUrlUrl auf dem KundendisplayString

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 
});
EigenschaftBeschreibungTyp
titleTitel des ButtonsText
buttonsBeschriftungText
buttonLayoutNumberInteger

3.23 switchButtonBadges

Wechselt das Tastenlayout auf Basis von Voreinstellung im Backoffice.

korona_plugin_api.response.switchButtonBadges({ 
        badges: your.badges.value 
}); 
EigenschaftBeschreibungTyp
badgesTastaturlayoutInteger

3.24 setAdditionalReceiptInfo

Zusätzliche Beleginformationen abrufen.

korona_plugin_api.response.setAdditionalReceiptInfo({ 
        additionalReceiptInfoTypeNumber: your.additionalReceiptInfoTypeNumber.value, 
        info: your.info.value 
});
EigenschaftBeschreibungTyp
additionalReceiptInfoTypeNumberInfotypnummerInteger
infoInformationText

3.25 setReceiptInfotexts

Setzt dem Beleg einen Infotext.

korona_plugin_api.response.setReceiptInfotexts({ 
        infoTexts: your.infoTexts.value
)};
EigenschaftBeschreibungTyp
infoTextsNeuer Infotext für den BelegText

3.26 addCouponItem

Externe Couponnummer hinzufügen.

korona_plugin_api.response.addCouponItem({ 
        number: your.number.value 
)};
EigenschaftBeschreibungTyp
numberCouponnummerInteger

3.27 setReceiptFinishBlockingIndicator

Setzt Belegabschlusssperre, verhindert Belegabschluss.

korona_plugin_api.response.setReceiptFinishBlockingIndicator({ 
        blockingIndicatoryour.blockingIndicator.checked 
}); 
EigenschaftBeschreibungTyp
blockingIndicatorSoll Belegabschluss verhindert werden?Boolean

3.28 unsetReceiptFinishBlockingIndicator

Hebt Belegabschlusssperre auf.

korona_plugin_api.response.setReceiptFinishBlockingIndicator(); 
EigenschaftBeschreibungTyp
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 RequestObjektes 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

________________________________________________________