Schnittstellen zwischen Kasse und ERP: API, CSV, Webhook
Kurz gesagt
Wählen Sie die Schnittstelle in erster Linie nach der zulässigen Verzögerung und der Ausfallbehandlung, nicht nach der Datenmenge. Eine Datei im CSV-Format passt für Stapel wie Erstimport und Tagesabschluss, eine API für Abfragen und gezielte Änderungen, ein Webhook für Meldungen, sobald etwas geschieht. Die Zuordnung in der Tabelle ist eine redaktionelle Ausgangsannahme, keine Norm.
Das Wichtigste
- RFC 4180 (Oktober 2005) beschreibt das CSV-Format als Informational-Memo und hält fest, dass sich Implementierungen deutlich unterscheiden; Trennzeichen, Zeichensatz und Kopfzeile sind daher zu vereinbaren.
- RFC 8259 verlangt UTF-8 für JSON-Text, der zwischen Systemen außerhalb eines geschlossenen Umfelds ausgetauscht wird; ganze Zahlen bis 9.007.199.254.740.991 gelten als genau austauschbar.
- Nach RFC 9110 (Abschnitt 9.2.2) dürfen Anfragen mit idempotenten Methoden wie PUT und DELETE nach einem Verbindungsabbruch automatisch wiederholt werden, eine POST-Anfrage grundsätzlich nicht.
- OpenAPI 3.1.0 (15. Februar 2021) beschreibt Webhooks, also Anfragen, die der Anbieter von sich aus an den Nutzer sendet, im Feld webhooks.
Für den Austausch zwischen Kasse und ERP kommen drei Arten in Frage: Das eine System lädt eine Datei ab, ruft Daten über eine Programmierschnittstelle ab oder bekommt eine Meldung zugeschickt. Welche Art passt, hängt davon ab, wie aktuell die Daten sein müssen und was geschieht, wenn der Empfänger nicht erreichbar ist. Welche Datensätze überhaupt wandern, steht in Kasse mit ERP verbinden.
Die drei Arten in einem Satz
Eine CSV-Datei ist eine Textdatei, in der jeder Datensatz auf einer eigenen Zeile steht und durch Trennzeichen in Felder gegliedert ist. RFC 4180 beschreibt Komma als Trenner, Zeilenende CRLF und Anführungszeichen für Felder mit Komma oder Zeilenumbruch; ein Feld in Anführungszeichen darf selbst einen Zeilenumbruch enthalten, ein Datensatz kann also mehrere Zeilen belegen; das Dokument ist ein Informational-Memo und nennt erhebliche Unterschiede zwischen Implementierungen. Eine API (Glossar) ist eine Schnittstelle, an der ein System Anfragen eines anderen beantwortet; über HTTP kann sie JSON austauschen, und OpenAPI beschreibt sie maschinenlesbar. Ein Webhook ist eine Anfrage, die der Anbieter von sich aus an eine Adresse des Nutzers sendet, wenn ein Ereignis eintritt; OpenAPI 3.1.0 führt dafür das Feld webhooks.
Entscheidungstabelle: Art nach Menge, Verzögerung und Ausfall
Ausgangsannahme: ein Betrieb mit einem bis fünf Standorten und einem ERP, das alle drei Arten dokumentiert anbietet. Die Zuordnung ist unsere Einschätzung. Prüfen Sie sie gegen die Dokumentation Ihres Anbieters.
| Aufgabe | Menge je Lauf | Zulässige Verzögerung | Bei Ausfall des Empfängers | Passende Art |
|---|---|---|---|---|
| Erstimport von Artikeln, Kunden, Lieferanten | Tausende Zeilen, einmalig | Stunden | Datei bleibt liegen, Import wird wiederholt | CSV |
| Tagesabschluss und Zahlartensummen an die Buchhaltung | Wenige Zeilen je Tag | bis zum Tagesende | Datei liegt bereit, Übergabe wird nachgeholt | CSV |
| Artikelstamm nachts abgleichen | Alle Artikel, ein Lauf | bis zum nächsten Morgen | Der nächste Lauf holt auf, wenn der Abgleich vollständig ist | CSV oder API |
| Preisänderung mit Gültig-ab-Zeitpunkt | Einzelne Artikel | Minuten | Aufrufer wiederholt, bis der Empfänger antwortet | API |
| Bestand für den Onlineshop | Je Verkauf ein Datensatz | Sekunden bis Minuten | Meldung wird wiederholt; zusätzlicher Abgleich per Abruf | Webhook, ergänzt durch API |
| Verkaufspositionen je Bon an das ERP | Je Bon ein Datensatz | Sekunden bis Minuten | Kasse puffert und sendet später; ERP erkennt Doppelte | API oder Webhook |
Ausfall und Wiederholung: wer wiederholt, was ist doppelt?
Jede Art braucht eine Regel für den Fehlerfall, bevor sie in Betrieb geht.
- CSV: Wiederholen heißt, die Datei erneut einzulesen. Enthält die Datei keinen eindeutigen Schlüssel je Zeile (Bonnummer, Artikelnummer), entstehen Doppelte. Vereinbaren Sie, ob eine Zeile bestehende Datensätze ersetzt oder neue anlegt.
- API: Der Aufrufer sieht einen Fehler oder bekommt keine Antwort und entscheidet, ob er wiederholt. Nach RFC 9110 (Abschnitt 9.2.2) sind PUT und DELETE idempotent; ein Client darf sie nach einem Abbruch automatisch wiederholen. Eine POST-Anfrage soll er ohne Mittel, die Wirkung zu erkennen, nicht automatisch wiederholen. Fordern Sie daher für das Anlegen von Verkäufen eine eindeutige Bonnummer, die der Empfänger auf Doppelte prüft.
- Webhook: Ob und wie oft der Sender eine nicht angenommene Meldung wiederholt, steht in der Dokumentation des Senders; fragen Sie danach. Rechnen Sie damit, dass dieselbe Meldung mehr als einmal ankommt, und legen Sie fest, wie der Empfänger das erkennt.
Was Sie in der Schnittstelle vereinbaren sollten
Die Punkte sind Vorschläge und gelten für jede der drei Arten.
- Zeichensatz. RFC 8259 verlangt UTF-8 für JSON-Text, der außerhalb eines geschlossenen Umfelds zwischen Systemen ausgetauscht wird, und untersagt bei der Übertragung über ein Netz eine Byte-Order-Mark am Anfang. Für CSV gibt RFC 4180 den Zeichensatz über den optionalen Parameter charset an; vereinbaren Sie ihn schriftlich.
- Trennzeichen, Kopfzeile, Anführungszeichen bei CSV. RFC 4180 erlaubt eine Kopfzeile, deren Vorhandensein über den Parameter header angezeigt wird. Halten Sie fest, ob sie vorhanden ist.
- Zahlen. RFC 8259 nennt ganze Zahlen im Bereich von −9.007.199.254.740.991 bis 9.007.199.254.740.991 als genau austauschbar und warnt bei höherer Genauigkeit. Vereinbaren Sie, ob Beträge als Cent in ganzen Zahlen oder als Text mit festen Nachkommastellen laufen.
- Schlüssel als Text. Artikelnummer und GTIN sind Kennungen, keine Rechengrößen. Übertragen Sie sie als Text, damit führende Nullen erhalten bleiben (Artikelnummern im ERP).
- Eindeutiger Name je Feld. RFC 8259 sagt, dass die Namen innerhalb eines JSON-Objekts eindeutig sein sollen; bei Duplikaten verhalten sich Empfänger unterschiedlich.
Beispielrechnung: Muss es eine schnelle Art sein?
Beispiel (erfundene Zahlen): Ein Laden bucht an einem Tag 300 Bons in 10 Stunden. Das sind 300 ÷ 10 = 30 Bons je Stunde, also im Durchschnitt ein Bon alle zwei Minuten. Für die Anzahl der Übertragungen ist das kein Entscheidungsgrund: Ein Aufruf je Bon ist machbar. Entscheidend ist, ob der Shop nach Minuten oder erst am nächsten Morgen den richtigen Bestand kennen muss. Wer morgens abgleicht, kann eine Datei verwenden; wer im Lauf des Tages verkauft, braucht Meldungen oder Aufrufe je Bon.
Typische Fehler
- Zeichensatz nicht vereinbart. Anzeichen: Umlaute erscheinen als Sonderzeichen. Legen Sie UTF-8 fest.
- Beträge mit Komma und Punkt gemischt. Anzeichen: Ein Preis wird falsch gelesen. Vereinbaren Sie das Dezimalzeichen oder übertragen Sie Cent.
- Keine Doppelten-Erkennung. Anzeichen: Nach einem Ausfall liegen Bons zweimal im ERP. Verlangen Sie eine eindeutige Nummer je Datensatz.
- Der Webhook ist die einzige Quelle. Anzeichen: Nach einem Ausfall fehlen Meldungen. Ergänzen Sie ihn um einen regelmäßigen Abgleich per Abruf.
Wann Sie Hilfe holen sollten
Lassen Sie die technische Dokumentation vom Anbieter oder einer IT-Betreuung prüfen, wenn Kasse und ERP von verschiedenen Anbietern stammen. Verlangen Sie vor der Vertragsunterschrift eine Beschreibung der Schnittstelle mit Fehlerfällen.