Inhalt

  1. Einleitung
    1.1 Zweck des Dokuments
    1.2 Zweck der API
  2. 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
  3. 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
  4. 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.

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 an diese Webseite die Request-Daten (Kassen/Belegdaten) per HTTP-POST im JSON-Format übermittelt werden oder nur ein HTTP-GET-Aufruf ohne Request-Datenübermittlung ausgeführt wird.

Referenziert diese Webseite die Datei „korona-plugin-api.js“ wird, wenn die Webseite geladen wurde, zusätzlich noch von der Kassenanwendung die Request-Daten (Kassen/Belegdaten) per JavaScript-Aufruf in den Script-Context der Webseite eingefügt. Eine Rückgabe von Response-Daten ist hier nur über JavaScript möglich.

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,
amount: your.amount.value,
fixedAmount: your.fixedAmount.checked,
infoTexts: your.InfoTexts,
notRemovable: your.notRemovable.checked,
customData: your.customData.value
serialNumbers: your.serialNumbers.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

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

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
        },
        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
});
EigenschaftBeschreibungTyp
descriptionBezeichnung des ArtikelsText
amountWert des Rabatts für den PostenVariant
percentDefiniert ob der Wert als prozentualer Rabatt
berechnet wird
Boolean
infoTextsInfotext zu einem 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

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,
        notRemovable: your.notRemovable.checked,
        customData: your.customData.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

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

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
        },
        infoTexts: your.InfoTexts,
        price: your.price.value,
        quantity: your.quantity.value,
        useAlternativeSector: your.useAlternativeSector.value,
        customData: your.customData.value
});
EigenschaftBeschreibungTyp
modifierID-der BelegpositionInteger
amountNeuer Wert des Rabatts für den PostenVariant
percentDefiniert ob der Wert als prozentualer Rabatt
berechnet wird
Boolean
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

3.9 printMessage

Druckt einen beliebigen Inhalt inkl. Barcode oder QR-Code auf dem Belegdrucker.

korona_plugin_api.response.printMessage({
        text: your.text.value,
        title: your.title.value,
        qrCode: your.qrCode.value,
        code39Barcode: your.code39Barcode.value,
        printFooter: your.printFooter.checked),
        printHeader: your.printHeader.checked),
});
EigenschaftBeschreibungTyp
textZu druckender TextText
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

4 Demo & Beispiel

4.1 Integrierte Demo

In den Kassenclient ist eine Demowebseite 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.

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

________________________________________________________