Warenkorbschnittstelle

Allgemeine Beschreibung

Mit der ETRON onR Warenkorbschnittstelle können Sie Daten aus Ihrem externen System übernehmen und damit registrierkassenpflichtkonforme Belege über ETRON onR erstellen.

Warenwirtschafts- oder Kassensysteme, die nicht der Registrierkassenpflicht entsprechen, können damit schnell und einfach für die Registrierkassenpflicht aufgerüstet werden. Das externe System muss dazu die Daten in einem vordefinierten Format anliefern, ETRON onR übernimmt diese Informationen und erstellt den Beleg.

Vorteile

• schnell, einfach und unkompliziert

• entspricht der Registrierkassenpflicht

• kostengünstig

• sichere Übertragung

Voraussetzungen

Folgende Voraussetzungen müssen für einen erfolgreichen Schnittstellenaufruf erfüllt sein:

• Ein ETRON onR Abo

• Das Modul „Warenkorbschnittstelle“ aktiviert

Funktionsübersicht

Anbei eine Auflistung der Funktionsübersicht, was alles mit der Warenkorbschnittstelle möglich ist.

• Vordefinierte Produkte übergeben oder unbekannte Produkte automatisch erstellen.

• Produkte, Rechnungen aus Vorsystem oder Text-Positionen in Bestellung sind definierbar.

• Kundendaten übergeben, dabei werden unbekannte Kunden automatisch angelegt.

• Bezahlmittel und Beträge übergeben der Bezahlung manuell in der onR Kasse.

• Automatischer Belegdruck (keine Druckvorschau).

• Belegdruck deaktivieren (Beleg wird nicht gedruckt).

• Vollautomatischer Betrieb (nach Abschluss eines Beleges automatisch auf nächsten Beleg warten).

Externe Aufträge

Alle Requests an die Warenkorbschnittstelle sind unter Berichtswesen > Externe Aufträge einsehbar und werden anhand der identifiziert.

In den Externen Aufträgen sind zur Referenz die JSON Daten von Request und Response erfasst. Die Objekte bleiben immer bestehen.

Sollte ein Request vom Vorsystem mehrfach gesendet werden, so wird der Externe Auftrag anhand seiner ref validiert. Siehe Parameter: ORDER/ref für Details.

Benutzung

Beschreibung der Funktionsweise

ETRON onR muss im Browser geöffnet sein. Zwischen dem Extern-Modus der Warenkorbschnittstelle und dem ETRON onR Warenkorb, kann jederzeit gewechselt werden bzw. können diese in eigenen Warenkorb Tabs geöffnet sein.

1. Konfiguration

Im ETRON onR zuerst den Hauptmenü-Reiter Konfiguration und danach den Unter-Menüpunkt Unternehmensdaten aufrufen. Mit dem Button „Neues Token erstellen“, den Sicherheitstoken generieren (siehe Abbildung darunter).

Den generierten Token (in der Abbildung gelb umrandet) in die Software eintragen, von der der Auftrag zu ETRON onR gesendet wird. Wie vorher oben beschrieben, muss der Sicherheitstoken übereinstimmen. Sollte der Token neu generiert werden, dann muss dieser auch in die Zweit-Software nachgetragen werden.

2. POS starten

Über den Hauptmenü-Reiter Point of Sale eine neue Sitzung starten. Nähere Infos zum Öffnen einer ETRON onR Point of Sale Sitzung finden Sie hier.

3. Extern-Modus starten

Um Aufträge über die Schnittstelle übertragen zu können, muss zum Extern-Modus gewechselt werden. (siehe Abbildung darunter)

Jetzt können Aufträge an ETRON onR gesendet werden. Je nachdem wie ein Auftrag gesendet wird, kann im nächsten Schritt die Zahlung bzw. der nächste Auftrag abgewickelt werden.

4. Abbrechen

Über den Button „Zurück“ gelangen Sie wieder zum Normalen ETRON onR Warenkorb.

API Dokumentation

• Endpunkt: POST auf https://<ihre-wunschdomain>.on-etron.at/external/order

• Content-Type: application/json

• Grundstruktur JSON-RPC Request:

POST /external/order HTTP/1.1
Host: <ihre-wunschdomain>.on-etron.at
Content-Type: application/json

{
   "jsonrpc":"2.0",
   "id":null,
   "method":"call",
   "params":{
      "order": ORDER CALL
   }
}

Betriebsmodus

Die Warenkorbschnittstelle kann in zwei Modi verwendet werden:

Blockierend

Synchrone Requests, die Response wird erst nach Fertigstellung und Druck des Beleges zurückgegeben.

Endpunkt: POST https://<ihre-wunschdomain>.on-etron.at/external/order

• Notwendig wenn alle Response-Daten im Vorsystem benötigt werden (z.B. RKSV-Signatur).

• Sinnvoll wenn Bezahlmittel direkt übergeben werden und automatisch per USB gedruckt werden soll, damit Requests nicht schneller geschickt werden können als Belege gedruckt werden können.

Nicht blockierend

Asynchrone Requests, die Response wird direkt nach Übergabe des Warenkorbes zurückgegeben. Einige Elemente, wie die RKSV Signatur, sind zu diesem Zeitpunkt noch nicht erstellt und daher in der Response nicht enthalten.

Endpunkt: POST https://<ihre-wunschdomain>.on-etron.at/external-nb/order

• Möglich wenn gar nicht oder automatisch per XML-Drucker gedruckt wird und die Bezahlmittel übergeben werden.

• Sinnvoll wenn manuell kassiert wird, damit das Vorsystem nicht auf den Abschluss des Belegs warten muss.

Parameter / Datenstruktur

ORDER CALL

Parameter für ORDER CALL. Diese sind im JSON-Objekt ORDER vom JSON-RPC Container. Wichtig für die Einstellungen und Zusatz Daten der Bestellung der Warenkorbschnittstelle.

ORDER

Parameter für ORDER. Diese sind im JSON-Objekt ORDER vom ORDER CALL Objekt. Steht für die gesamte Bestellung.

ORDER_LINE "P"

Parameter für ORDER_LINE. Diese sind im JSON-Objekt ORDER_LINE[] vom ORDER Objekt. Steht für ein Produkt in der Bestellung.

ORDER_LINE "T"

Parameter für ORDER_LINE. Diese sind im JSON-Objekt ORDER_LINE[] vom ORDER Objekt. Steht für eine Textzeile in der Bestellung.

ORDER_LINE "K"

Parameter für ORDER_LINE. Diese sind im JSON-Objekt ORDER_LINE[] vom ORDER Objekt. Steht für eine Rechnung aus einem Vorsystem (ehemals „Externe Kreditrechnung“) in der Bestellung.

CUSTOMER

Parameter für CUSTOMER. Diese sind im JSON-Objekt CUSTOMER vom ORDER CALL Objekt. Steht für einen Kunden.

PAYMENT

Parameter für PAYMENT. Diese sind im JSON-Objekt PAYMENT[] vom ORDER CALL Objekt. Steht für einen Bezahlvorgang.

Rückgabewert

Rückgabewert von der Warenkorbschnittstelle. Ein JSON-RPC Response besteht ausfolgenden Parametern:

Status Codes

Anbei eine Auflistung aller Status Codes Rückmeldungen.

Beispiel

Das result enthält dabei den applikationsspezifischen Rückgabewert. In unserem Fall:

{
   "jsonrpc": "2.0",
   "id": null,
   "result": {
      "status_code": 0,
      "message": null
   }
}

Gesamtbeispiel

Hier wird ein Fallbeispiel mit allen möglichen Parametern gezeigt. Hierbei zu beachten das alle Parameter in «(Text)» zu ändern sind.

{
    "jsonrpc": "2.0",
    "id": null,
    "method": "call",
    "params": {
        "order": {
            "auth_token": "<<Sicherheitstoken>>",
            "station": "<<Station>>",
            "autonext": true,
            "autoprint": true,
            "noprint": false,
            "create_products": true,
            "order": {
                "ref": "<<Eigene Referenznummer>>",
                "line_items": [
                    {
                        "type": "P",
                        "product_nr": "10101010",
                        "product_name": "Coca Cola",
                        "product_note": "Dieser Text wird eingerückt angedruckt",
                        "quantity": 1,
		        "unit_price": 6.00,
		        "tax_code": "10"
                    },
                    {
                        "type": "T",
                        "text":"Zusatztext"
                    },
                    {
                        "type": "K",
                        "ext_ref":"<<Externe Referenznummer>>",
                        "amount":"200.00"
                    }
                ],
                "amount_total": 206.00
            },
            "payments": [
                {
                    "type": "BAR",
                    "amount": 206.00
                }
            ],
	    "customer": {
		"id": 123456,
		"name": "Petra Mustermann",
		"street": "Hauptstrasse 143",
		"zip": "1050",
		"city": "Wien"
	    }
        }
    }
}

API Beispiele

Neue Produkte anlegen

Um nicht jedes Produkt selbst in den Stammdaten anlegen zu müssen, kann man auch die Produkte per create_products Option automatisch über die Warenkorbschnittstelle anlegen lassen. Somit wird zuerst überprüft ob das Produkt mit der übergebenen product_nr existiert und falls nicht wird es angelegt.

{
    "jsonrpc": "2.0",
    "id": null,
    "method": "call",
    "params": {
        "order": {
            "auth_token": "QZb4fVW=8Iryr-c9xFtnIXNfpY1/8jiETjpH8YFldCbn+Fel",
            "station": "01",
            "create_products": true, <-------- WICHTIG für automatische Produktanlegung
            "order": {
                "ref": "Test-Ref 2000-123",
                "line_items": [
                    {
                        "type": "P",
                        "product_nr": "10101010",
                        "quantity": 1,
		        "unit_price": 6.00,
		        "tax_code": "10"
                    }
                ],
                "amount_total": 6.00
            }
        }
    }
}

Vollautomatischer Betrieb

Um onR vollautomatisch zu betreiben können die Optionen autoprint (oder noprint) und autonext verwendet werden um nach dem Druck automatisch auf den nächsten Auftrag zu warten. Die manuelle Betätigung des Buttons *Nächster Auftrag* entfällt damit.

{
    "jsonrpc": "2.0",
    "id": null,
    "method": "call",
    "params": {
        "order": {
            "auth_token": "QZb4fVW=8Iryr-c9xFtnIXNfpY1/8jiETjpH8YFldCbn+Fel",
            "station": "01",
            "autonext": true, <-------- WICHTIG für automatische Bestätigung
            "autoprint": true,
            "order": {
                "ref": "Test-Ref 2000-123",
                "line_items": [
                    {
                        "type": "P",
                        "product_nr": "10101010",
                        "quantity": 1,
		        "unit_price": 6.00,
		        "tax_code": "10"
                    }
                ],
                "amount_total": 6.00
            },
            "payments": [
                {
                    "type": "BAR",
                    "amount": 6.00
                }
            ]
        }
    }
}

Belegdruck deaktivieren

Deaktiviert man den Belegdruck so entfällt der Druck komplett, der Beleg wird aber in der Vorschau angezeigt.

{
    "jsonrpc": "2.0",
    "id": null,
    "method": "call",
    "params": {
        "order": {
            "auth_token": "QZb4fVW=8Iryr-c9xFtnIXNfpY1/8jiETjpH8YFldCbn+Fel",
            "station": "01",
            "noprint": true, <-------- WICHTIG für deaktivierten Belegdruck
            "order": {
                "ref": "Test-Ref 2000-123",
                "line_items": [
                    {
                        "type": "P",
                        "product_nr": "10101010",
                        "quantity": 1,
		        "unit_price": 6.00,
		        "tax_code": "10"
                    }
                ],
                "amount_total": 6.00
            }
        }
    }
}

Automatischer Belegdruck

Ist der automatische Belegdruck aktiv so werden die (in diesem Fall zwingend zu übergebenden) Bezahlmittel automatisch bestätigt und der Druck ausgelöst.

{
    "jsonrpc": "2.0",
    "id": null,
    "method": "call",
    "params": {
        "order": {
            "auth_token": "QZb4fVW=8Iryr-c9xFtnIXNfpY1/8jiETjpH8YFldCbn+Fel",
            "station": "01",
            "autoprint": true, <-------- WICHTIG für automatischen Belegdruck
            "order": {
                "ref": "Test-Ref 2000-123",
                "line_items": [
                    {
                        "type": "P",
                        "product_nr": "10101010",
                        "quantity": 1,
		        "unit_price": 6.00,
		        "tax_code": "10"
                    }
                ],
                "amount_total": 6.00
            },
            "payments": [
                {
                    "type": "BAR",
                    "amount": 6.00
                }
            ]
        }
    }
}