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.

Parameter	Typ	Beschreibung	DEFAULT	PFLICHT
auth_token	char	Sicherheits-Token für die Schnittstelle (wird in ETRON onR konfiguriert)		x
station	char	ID des Kassenplatzes (zB. “01”) (Es muss entweder der Parameter station oder der Parameter user befüllt sein.)		(x)
user	char	Verkäufer des Kassenplatzes (username) (Es muss entweder der Parameter station oder der Parameter user befüllt sein.)		(x)
autoprint	boolean	Wenn gesetzt, dann wird der Beleg automatisch bezahlt und ausgedruckt. Dazu müssen die Zahlungen korrekt übergeben werden. Beim Ausdruck wird das bei dem Kassenplatz hinterlegte Papierformat verwendet. Zulässige Werte: true, false	false
autonext	boolean	Wenn gesetzt, dann wird automatisch auf „Nächster Auftrag“ geklickt nach der Druckvorschau. Ist noprint und autonext auf true gesetzt, so wird weder eine Beleg- noch eine Druckvorschau angezeigt. Dies hat zur Folge, dass die Aufrufe auf keine Antwort warten müssen und sehr schnell abgearbeitet werden. Ist autoprint und autonext gesetzt und es wird ein USB-Drucker verwendet, so sollte der Browser im Kiosk-Printing Modus betrieben werden (–kiosk-printing) um die Druckvorschau zu unterdrücken. Zulässige Werte: true, false Neu in onR Version 1.13	false
noprint	boolean	Wenn gesetzt, dann wird kein Beleg ausgedruckt und die Druckvorschau übersprungen. Zulässige Werte: true, false Neu in onR Version 1.13	false
create_products	boolean	Wenn gesetzt, dann werden übergebene Produkte angelegt, sofern Sie noch nicht existieren. Die Übereinstimmung ist dabei mit dem Feld 'product_nr' und der externen Artikelnummer in Etron onR. Zulässige Werte: true, false	false
order	ORDER	Es muss genau 1 Auftrag übergeben werden.		x
customer	CUSTOMER	Kunde, der auf dem Beleg angedruckt werden soll. Der Kunde wird erstellt sofern noch kein Kunde mit dieser Kundennummer existiert.
payments	PAYMENT[]	Wenn angegeben, dann muss die Summe der Zahlungen gleich der Brutto-Auftragssumme sein. Zahlungen (1-n)

ORDER

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

Parameter	Typ	Beschreibung	DEFAULT	PFLICHT
ref	char	Externe Referenz (Auftragsnummer) Eindeutige ID des Externen Auftrags (Berichtswesen > Externe Aufträge). Bei wiederholter Übermittlung desselben externen Auftrages verhält sich die Schnittstelle je nach Status: * Neu: Auftrag wird wiederholt ans POS zur Verarbeitung übermittelt, sofern das noch nicht passiert ist. * Erledigt: Auftrag wird abgelehnt (Status Code 6). * Abgebrochen: (wenn der Auftrag im POS abgebrochen wurde) Ein neuer externer Auftrag wird erstellt. Validierung neu in onR Version 1.15		x
line_items	ORDER_LINE[]	Positionen des Auftrag (min. 1 Position). Folgende Ausprägungen werden unterstützt: „T“, „K“, „P“		x
amount_total	float	Brutto-Gesamtsumme des Belegs		x
payment_terms	char	Zahlungsbedingung (wird angelegt, sofern sie noch nicht in onR existiert)
footer_text	char	Text wird am Beleg ganz unten angedruckt

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.

Parameter	Typ	Beschreibung	DEFAULT	PFLICHT
type	char	'P': Produktbeschreibung mit Menge, Einzelpreis und Gesamtpreis wird angdruckt sofern nicht no_print spezifiziert ist		x
product_nr	char	Produktcode / Produktnummer in onR		x
product_name	char	Wird als Produktbezeichnung angedruck (anstatt der Bezeichnung des originalen Produkts		bei Anlage
product_note	char	Zusatztext wird unterhalb des Produktnamens am Beleg angedruckt
quantity	float	Menge / Anzahl		x
unit_price	float	Brutto-Einzelpreis		x
tax_code	char	Steuercode (AT: 0, 10, 12, 13, 20. DE: 0, 7, 19.)		bei Anlage
no_print	boolean	Wenn gesetzt, dann wird diese Position nicht auf den Beleg gedruckt. (sollte nur in Spezialfällen verwendet werden) Zulässige Werte: true, false	false

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.

Parameter	Typ	Beschreibung	DEFAULT	PFLICHT
type	char	'T': Freitext als eigene Position		x
text	char	Wird angedruckt, wenn die Felder “product_nr”, “product_name” und “product_note” nicht befüllt sind		x
amount	float	Wird als Preis angedruckt, hat jedoch keine Logik hinterlegt. Wird benötigt, wenn darauffolgende Produkte mit dem Flag no_print gekennzeichnet sind. So lassen sich Produkte mit mehreren Steuersätze abbilden wobei nur eine Position angedruckt wird. Wird nur angedruckt wenn es nicht 0 ist.	0

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.

Parameter	Typ	Beschreibung	DEFAULT	PFLICHT
type	char	'K': Externe Rechnung aus Vorsystem		x
ext_ref	char	Externe Referenz (Belegnummer)		x
amount	float	Betrag		x

CUSTOMER

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

Parameter	Typ	Beschreibung	DEFAULT	PFLICHT
id	char	Kundennummer		x
title	char	Anrede – Zulässige Werte: Frau;Herr
name	char	Kundenname
street	char	Adresszeile
street2	char	Adresszeile 2
zip	char	PLZ
city	char	Ort
country	char	Land (wenn in onR keine Zuordnung möglich ist, dann wird ein Fehler returniert)
phone	char	Telefon
mobile	char	Mobiltelefon
fax	char	Fax
email	char	E-Mail
payment_term	char	Zahlungsbedingung (wird angelegt, sofern sie noch nicht in onR existiert)
vat	char	UID-Nummer (muss entweder leer oder gültig sein)

PAYMENT

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

Parameter	Typ	Beschreibung	DEFAULT	PFLICHT
type	char	Zulässige Werte: BAR,UNBAR		x
method	char	Zahlmethode (Gutschein, Kreditkarte, …), Pflichtfeld bei Methode UNBAR		(bei UNBAR)
amount	char	Bezahlter Betrag / Gegebenes Geld		x

Rückgabewert

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

Parameter	Typ	Beschreibung	DEFAULT	PFLICHT
status_code	integer	Status Code		x
message	char	Fehlermeldung
order_nr	char	Belegnummer
order_date	char	Belegdatum
payments	PAYMENT[]	Zahlungen (1-n)
signature	char / null	Signatur-Zeichenkette null bei Ausfall der Sicherheitseinrichtung oder Signaturerstellungseinheit, sowie wenn dem Kassenplatz kein RKSV-Modul zugeordnet ist.

Status Codes

Anbei eine Auflistung aller Status Codes Rückmeldungen.

Status Code	Fehlermeldung
0	Ok
1	Zugriff verweigert
2	Validierungsfehler (spezifisch)
3	Ein Pflichtfeld wurde nicht korrekt angegeben (spezifisch)
4	Zeitüberschreitung
5	Manueller Abbruch des Auftrags
6	Auftrag mit Referenz wurde bereits verarbeitet
98	Technischer Fehler
99	Technischer Fehler

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
                }
            ]
        }
    }
}