cbird - JSON-Schnittstelle
Bonierungen in cbird können über folgende JSON-Schnittstelle automatisiert werden. Die Schnittstelle funktioniert folgendermaßen:
Aktivierung der Schnittstelle
Es muß folgendes Import-Verzeichnis für die Kasse angelegt werden:
USERHOME\cbirdWatch\KASSENNUMMER
Die Kassennummer ist bei cbird "weltweit" eindeutig. Daher ist es auch kein Problem, wenn mehrere Kassensticks angeschlossen sind.
Die Demokasse der cbird Versionen 1.XXX haben die Kassennummer: "0"
Demokassen der cbird Versionen N.XXX haben die Kassennummer: "N"
Sobald das Verzeichnis USERHOME\cbirdWatch existiert und cbird danach gestartet wird, wird das "automatische Bonieren" aktiviert (Kann dann im Menüpunkt "Kassa->Automatisches Bonieren" ein- und ausgeschaltet werden).
Automatisches Bonieren
In obiges Kassenverzeichnis können Textdateien mit den Bondaten im JSON-Format geschrieben werden. Der Dateiname muß folgender Konvention entsprechen:
JJJJ-MM-TT-xxxxxxx.json
xxxxxxx ist frei wählbar und kann "beliebig" lang sein. cbird importiert die Dateien aufgrund des Dateinamens per Stringsortierung aufsteigend.
Das ist wichtig, weil in der Kassa chronologisch boniert werden muß.
In der JSON-Datei gibt es folgende Felder:
- "zahlungsmittel": Erlaubte Werte sind "Bar", "Bankomat", "Kreditkarte" und ab Version 3.072: "Kartenterminal"
- optional "nachbonieren": true oder false
- optional (ab Version 3.020) "drucken": true
- "positionen": Ein Array aus Text oder Produktpositionen
Eine Textposition beinhaltet nur das Feld "bezeichnung"
Eine Produktposition besteht aus folgenden Feldern:
- "bezeichnung": Text mit maximal 200 Zeichen ohne Tab, Newline, Carriage Return. Ein leerer Text, oder ein Text der nur aus Leerzeichen oder Zeilenumbrüchen besteht, ist nicht erlaubt.
- "menge": Integerzahl zwischen -99999 und 99999
- "einzelpreis": Betrag in Eurocent. Integerzahl zwischen -99999999 und 99999999
- "ust": 0, 10, 12, 13, 20. Ab Version 2.006: "DB", "KB", "VR".
Menge * Einzelpreis muß zwischen -99999999 und 99999999 liegen. Auch die Gesamtsumme muß in diesem Bereich liegen.
Falls das Dateidatum älter als der heutige Tag ist, wird eine Nachbonierung gemacht (wäre ein Kassenausfall). Das könnte passieren, falls cbird nicht gestartet wurde oder der Import deaktiviert wurde. Ist gesetzlich dann aber nicht mehr korrekt, weil sofort bei Zahlung boniert werden muß! Der Unternehmer ist verantwortlich, dass das nicht passiert.
Wenn das Datum der heutige Tag ist, dann wird normal boniert außer in der JSON Datei wird der boolean Wert "nachbonieren" auf true gesetzt.
Stornos müssen in cbird gemacht werden, weil nur cbird weiß welche Bons es wirklich gibt.
Im Fehlerfall oder wenn eine Bonierung aufgrund der Chronologie (z.b. es existiert schon ein späteres Datum) nicht möglich ist, dann wird der automatische Import gestoppt und in cbird erscheint eine Fehlermeldung.
Tagesabschluß und Monatsabschluß werden automatisch vor der ersten Bonierung am nächsten Tag/Monats gemacht. Ohne Benutzerinteraktion.
Encoding der json-Datei
Das Encoding der json-Datei hängt vom Default-Encoding von java auf dem jeweiligen Betriebssystems (und den Spracheinstellungen auf diesem) ab. Dieses Encoding können Sie folgendemaßen herausfinden:
- unter Windows in einem cmd-Fenster: STICKLAUFWERK:\java\win32\bin\java.exe -XshowSettings:properties
- unter MacOSX in einem terminal-Fenster: /Volumes/cbird/java/macosx64/bin/java -XshowSettings:properties
Der Wert vom Property "file.encoding" bestimmt das Encoding der json-Datei.
Ändern Sie bitte nicht die Startskripts von cbird um das Encoding zu verändern. Diese Skripts könnten bei einem cbird-Update automatisch ausgetauscht werden!
Beispiele
Umleiten des Import-Verzeichnisses
Das Import-Verzeichnis kann auch "umgeleitet" werden. Erstellen Sie dazu im Import-Verzeichnis der Kasse eine Datei "watch.config". In dieser Datei können Sie das andere Verzeichnis eintragen, die Pfadtrennzeichen "\" müssen verdoppelt werden:
{
"watchverzeichnis": "XXXX"
}
Statt XXXX geben Sie das Verzeichnis an, in dem Ihre JSON-Dateien abgelegt werden.
Das Watchverzeichnis sollte am selben Computer liegen und nicht "remote" eingebunden sein um Probleme durch Netzwerkverzögerungen zu vermeiden. Und es dürfen nicht mehrere cbird-Kassen auf dasselbe Watchverzeichnis zugreifen.
Definieren des Verhaltens von cbird bei einem Abbruch einer Kartenzahlung (nur bei Verwendung des Kartenterminalmoduls, ab Version 3.078)
Mit der Option "handleATMAbort" in der Datei watch.config kann das Verhalten von cbird bei Abbruch einer Kartenzahlung gesteuert werden.
Im Fall eines Abbruchs am Kartenterminal wird dem Benützer in cbird ein Dialog angezeigt mit der Möglichkeit den Vorgang zu wiederholen (der Zahlungsbetrag wird nochmals an das Kartenterminal gesendet), den Vorgang manuell durchzuführen (d.h. in cbird wird die Zahlung abgespeichert, der Zahlungsbetrag muß aber vom Benützer am Terminal manuell eingegeben werden) oder den Vorgang abzubrechen.
Mit der Option "handleATMAbort" kann das Verhalten von cbird im Fall "Abbrechen" gesteuert werden.
- "handleATMAbort": "stop"
bedeutet cbird bricht den automatischen Import ab. Dies ist der default Wert und entspricht dem Verhalten von cbird bis zur Version 3.078
- "handleATMAbort": "storno"
bedeutet cbird boniert den Beleg mit dem in der Import-Datei übergebenen Zahlungsmittel und erstellt einen Storno-Beleg für diese Zahlung (Storno-Beleg wird nicht ausgedruckt). Der Bediener der Kasse muß danach die Zahlung mit dem neuen Zahlungsmittel erneut durchführen.
- "handleATMAbort": "stornoprint"
bedeutet cbird boniert den Beleg mit dem in der Import-Datei übergebenen Zahlungsmittel und erstellt einen Storno-Beleg für diese Zahlung (Storno-Beleg wird ausgedruckt). Der Bediener der Kasse muß danach die Zahlung mit dem neuen Zahlungsmittel erneut durchführen.
Erstellen einer Ergebnis-Datei mit den Daten des letzten Imports (ab Version 3.075)
Wenn in der Datei "watch.config" ein Parameter "showresult" mit dem Wert true (Achtung: ohne Anführungszeichen) existiert, dann wird nach jedem Import die Datei result.json erstellt bzw. überschrieben. Diese Datei wird im Import-Verzeichnis abgelegt und enthält z.B. folgende Daten (das Feld "result" existiert seit der Version 3.078):
{
"datei": "2020-05-08-0001.json",
"kassanummer": "1107",
"belegnummer": "2020-33",
"qrcodeinhalt": "_R1-AT1_cbird-1107_2020-33..."
"result": "ok"
}
"result" kann folgende Werte annehmen:
- "ok": Zahlung wurde verarbeitet
- "zahlung abgebrochen": wenn bei Verwendung des Kartenterminalmoduls die Kartenzahlung abgebrochen wurde handleATMAbort = "Stop"). Der automatische Import wurde beendet und die Import-Datei liegt unverändert im Watch-Verzeichnis.
- "zahlung abgebrochen und storniert": wenn bei Verwendung des Kartenterminalmoduls die Kartenzahlung abgebrochen und storniert wurde (handleATMAbort = "Storno" oder StornoPrint")