Schnittstellen im Shop-Umfeld: API, CSV, Webhook, Middleware

Zwischen Shop und Warenwirtschaft, Warenwirtschaft und Versand oder Shop und Marktplatz laufen Daten über eine von vier technischen Formen. Welche zu Ihrem Betrieb passt, entscheidet nicht der Funktionsumfang im Angebot, sondern der Auslöser jedes Vorgangs und die Zeit, die ein Vorgang warten darf. Die Form bestimmt auch, welcher Fehler zu erwarten ist und woran Sie ihn bemerken.

Worauf es ankommt

Eine Schnittstelle ist hier jede geregelte Übergabe von Daten zwischen zwei Systemen. Vier Formen lassen sich unterscheiden:

• API-Abruf (Pull): Ihr System fragt an und bekommt die Antwort im selben Aufruf; den Takt bestimmt, wer fragt.
• Dateiaustausch: Ein System legt eine Datei ab, das andere liest sie in einem eigenen Lauf; die Übergabe hängt am Lauf, nicht am Vorgang.
• Webhook (Push): Das Fremdsystem ruft beim Eintreten eines Ereignisses eine Adresse auf, die Sie ihm vorher genannt haben.
• Middleware: Ein Dienst steht zwischen den Systemen, spricht mit jedem eine eigene Form und übersetzt die Daten.

Ein Callback ist nach der OpenAPI Specification eine Adresse, die erst mit einem bestimmten Aufruf bekanntgegeben wird und die nur wegen dieses Aufrufs aufgerufen wird (Abschnitt 4.18); Webhooks werden unabhängig von einem vorherigen Aufruf zugestellt (Abschnitt 4.1.1). Die Antwort 202 bestätigt dagegen nur die Annahme eines Auftrags, nicht seine Ausführung (RFC 9110 Abschnitt 15.3.3).

Diese Dokumente sind Techniknormen und binden, soweit Vertrag, Anbindung oder Werkzeug sie verlangen. RFC 9110 ist als STD 97 ein Internetstandard. RFC 4180 für CSV ist dagegen informativ und hält in Abschnitt 2 selbst fest, dass es keine formale Spezifikation gibt. Die OpenAPI Specification ist eine Spezifikation der OpenAPI Initiative.

Die vier Wege im Vergleich

Die Tabelle stellt Auslöser, Zeitverhalten, Fehlerbild und Prüfung gegenüber. Die Prüfspalte lässt sich ohne Mitwirkung des Anbieters ausführen.

Weg	Wer beginnt	Zeitverhalten	Fehlerbild	So prüfen Sie es
API-Abruf	Ihr System	Der Stand ist so frisch wie der letzte Abruf; dazwischen bemerkt niemand eine Änderung	Ein Abbruch nach dem Senden lässt den Ausgang offen; ein automatischer Wiederholversuch eines POST kann den Vorgang doppelt anlegen (RFC 9110 Abschnitt 9.2.2). Für zu viele Aufrufe in kurzer Zeit sieht der Standard die Antwort 429 vor (Rate-Limiting, RFC 6585 Abschnitt 4), für vorübergehende Überlastung oder geplante Wartung die Antwort 503 (RFC 9110 Abschnitt 15.6.4). Beide sind mögliche, nicht garantierte Antworten: nach RFC 6585 Abschnitt 1 sind diese Codes optional, und bei Überlast kann der Dienst stattdessen auch die Verbindung abweisen (RFC 9110 Abschnitt 15.6.4)	Bestand ändern, Abruf auslösen, Dauer bis zum Zielsystem messen; denselben Vorgang zweimal senden und im Zielsystem zählen
Datei (CSV, XML)	Ein Zeitplan oder ein Export von Hand	Der Stand ist so alt wie die Datei	Trennzeichen, Zeichensatz, Kopfzeile und Zahlenformat legt jede Seite selbst fest, weil CSV keine verbindliche Spezifikation hat (RFC 4180, informativ, Abschnitte 2 und 3). Eine abgebrochene Datei fällt ohne Mengenvergleich nicht auf	Zeilenzahl und Summen je Lauf vergleichen; Umlaute, Anführungszeichen, Semikolon statt Komma und Dezimalkomma testen
Webhook	Das Fremdsystem	Der Aufruf kommt nach dem Ereignis; die Verzögerung gibt der Absender vor	Für das Verfahren WebSub gilt: Eine Zustellung ohne 2xx-Antwort gilt als gescheitert; der Absender soll sie nach eigener Vorgabe wiederholen (SHOULD), bis seine selbst gesetzten Grenzen an Zahl und Zeitraum erreicht sind, und versucht diese Zustellung danach nicht weiter (WebSub Abschnitt 7). Die Wiederholung ist eine Empfehlung des Verfahrens, keine Zustellgarantie. Antwortet der Empfänger mit 410, kann der Absender die Subscription beenden (Abschnitt 7). Bei anderen Anbietern stehen Wiederholung und Grenzen in deren eigener Dokumentation. Ohne Signaturprüfung kann jeder den Endpunkt aufrufen (Abschnitt 7.1)	Endpunkt absichtlich abschalten und prüfen, ob nachgeliefert wird; eine Nachricht mit falscher Signatur senden
Middleware	Der Dienst nach seinem Plan	Der Takt liegt bei einem Dritten	Ein weiterer Beteiligter im Pfad: Fällt der Dienst aus, stehen alle Flüsse; ein Zuordnungsfehler überträgt einen falschen Wert, ohne dass die Übergabe fehlschlägt	Ausfall des Dienstes nachstellen; fragen, wo die Zugangsdaten liegen, wie lange Protokolle bleiben und wie Sie ohne den Dienst weiterarbeiten

Ob alle Vorgänge angekommen und richtig zugeordnet sind, zeigt erst ein Abgleich, der Quell- und Zielsystem gegeneinander stellt. Fehlerbilder und Alarmschwellen beschreibt Datensynchronisation zwischen Systemen.

Wann welcher Weg passt

Die Zuordnung ist eine redaktionelle Empfehlung und keine Aussage über Anbieter; sie folgt aus der Wartezeit, die ein Vorgang höchstens haben darf, und aus der Zahl der beteiligten Systeme.

Ihr Fall	Naheliegender Weg	Was Sie zusätzlich brauchen
Bestand und Preis sollen fast gleichzeitig gelten	API-Abruf in kurzem Takt	gemessene Verzögerung je Lauf, Antwort auf die Mengenbegrenzung des Fremdsystems
Ein Ereignis muss sofort weitergehen, etwa die Freigabe einer bezahlten Bestellung	Webhook	ein zweiter Weg in festem Takt, der ausgefallene Zustellungen nachträgt
Massendaten ohne Zeitdruck, etwa Buchhaltungsexport oder Lieferantenbestand	Datei nach Zeitplan	schriftliche Festlegung von Trennzeichen, Zeichensatz, Kopfzeile und Zahlenformat
Mehrere Systeme und Partner mit je eigenem Format	Middleware prüfen	Auskunft über Ausfallverhalten, Zugangsdaten, Aufbewahrung der Protokolle und Export Ihrer Daten

Kurz: Ereignis mit Zeitdruck spricht für Push, ein selbst abgefragter Zustand für Pull, eine Menge ohne Zeitdruck für eine Datei, mehrere Paare für einen Vermittler. Die Prüfung ersetzt der Weg nicht: Auch ein Webhook braucht den Nachlauf. Wo die Verbindung in den Ablauf eingehängt wird, steht unter Bestellabwicklung automatisieren.

Ein Rechenbeispiel

Beispielrechnung mit erfundenen Zahlen. Ein Shop erhält 120 Bestellungen am Tag, gleichmäßig über den Tag verteilt; die Warenwirtschaft liest alle 15 Minuten ab.

Weg	Rechnung	Wartezeit
API-Abruf alle 15 Minuten	im Mittel die halbe Taktzeit, also 7,5 Minuten je Bestellung: 120 × 7,5 Minuten	900 Minuten, also 15 Stunden Wartezeit am Tag aufsummiert
Ein Lauf je Tag um 8 Uhr	bei Eingang zwischen 8 und 22 Uhr wartet eine Bestellung im Mittel (24 + 10) ÷ 2 = 17 Stunden	120 × 17 Stunden = 2.040 Stunden Wartezeit am Tag aufsummiert
Webhook	die Zustellung dauert im Beispiel 2 Sekunden	120 × 2 Sekunden = 240 Sekunden, also 4 Minuten am Tag

Die Wartezeit bestimmt, wie viele Bestellungen abends noch offen sind. Dazu der Fehlerfall: Angenommen, bei jeder der 2.500 Bestellungen im Monat wiederholt das System einen Aufruf, und einer von 200 Wiederholungen erzeugt eine zweite Bestellung: 2.500 × 1/200 = 12,5, also rund 12 Doppelbestellungen im Monat. Bei 15 Euro Nacharbeit je Fall sind das 187,50 Euro (12,5 × 15). Prüfen Sie den Fall selbst: denselben Vorgang zweimal senden und im Zielsystem zählen.

Typische Fehler

• Die Übergabe für das Ergebnis halten. Eine 202-Antwort bestätigt nach RFC 9110 Abschnitt 15.3.3 nur die Annahme, eine 2xx-Antwort auf einen Webhook nach WebSub Abschnitt 7 nur den Empfang.
• Wiederholen, ohne die Wirkung zu kennen. Nach RFC 9110 Abschnitt 9.2.2 kann ein Wiederholversuch bei einer nicht idempotenten Methode wie POST einen zweiten Vorgang erzeugen. Der Idempotency-Key-Entwurf der IETF-HTTPAPI-Arbeitsgruppe beschreibt dafür einen Schlüssel je Vorgang (Abschnitte 2 und 2.6); er ist ein Internet-Draft und kein RFC.
• Zwei Systeme ändern denselben Datensatz. Wer Preise im Shop und im ERP pflegt, überschreibt die Änderung der anderen Seite. Die Versionsprüfung der HTTP-Semantik bricht einen Aufruf ab, wenn sich der Stand geändert hat (ETag und If-Match, RFC 9110 Abschnitte 8.8 und 13.1.1).
• Beim Dateiaustausch nichts vereinbaren. Weil CSV keine verbindliche Form hat, entscheiden die Parameter charset und header allein die beiden Seiten (RFC 4180 Abschnitt 3).
• Keinen stillen Ausfall einplanen. Ein Lauf, der nie startet, und eine Zustellung, die ausbleibt, melden sich nicht; ohne Mengen- und Summenvergleich fällt beides erst auf, wenn Kundschaft nachfragt.

So gehen Sie vor

1. Schreiben Sie die Vorgänge auf: Richtung, wer heute beginnt, Menge je Tag.
2. Legen Sie je Vorgang die höchstzulässige Wartezeit fest. Sie ist der Vergleichsmaßstab für alle vier Wege.
3. Wählen Sie den Weg nach der Tabelle oben und halten Sie fest, was daran Annahme ist (redaktionelle Empfehlung).
4. Fahren Sie die Fehlerfälle vor dem Livegang: Empfänger abschalten, denselben Vorgang zweimal senden, einen ungültigen Datensatz übertragen, einen Lauf mitten im Vorgang abbrechen.
5. Richten Sie den Abgleich ein: Anzahl und Summe je Lauf in beiden Systemen, eine Warnung bei Abweichung und ein Name, der die Abweichung bearbeitet. Welche Felder jede Verbindung einzeln braucht, steht in Schnittstellen eines Shopsystems prüfen.