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.

ParameterTypBeschreibungDEFAULTPFLICHT

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.

ParameterTypBeschreibungDEFAULTPFLICHT

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.

ParameterTypBeschreibungDEFAULTPFLICHT

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.

ParameterTypBeschreibungDEFAULTPFLICHT

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.

ParameterTypBeschreibungDEFAULTPFLICHT

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.

ParameterTypBeschreibungDEFAULTPFLICHT

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.

ParameterTypBeschreibungDEFAULTPFLICHT

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:

ParameterTypBeschreibungDEFAULTPFLICHT

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 CodeFehlermeldung

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

Last updated

(c)2024 ETRON Softwareentwicklungs- und Vertriebs GmbH