Shop, Warenwirtschaft und interne Tools verbinden: Was vor einer Schnittstelle geklärt sein muss

„Die Systeme haben eine API, also können wir sie verbinden.“ Technisch ist das ein guter Anfang. Für einen zuverlässigen Geschäftsprozess fehlt damit aber noch die wichtigste Vereinbarung: Welche Information gilt, wer darf sie verändern und was soll passieren, wenn die Übertragung nicht klappt?

Eine Schnittstelle übersetzt fachliche Regeln in technische Abläufe. Sind die Regeln unklar, transportiert sie diese Unklarheit schneller zwischen den Systemen. Deshalb beginne ich die Planung bei einem konkreten Vorgang und seinen Ausnahmen. Dieser Artikel zeigt, welche Antworten vor der Umsetzung vorliegen sollten.

Erst den Vorgang beschreiben, dann die Verbindung

Ein hypothetisches Beispiel: Eine Bestellung entsteht im Shop, wird in die Warenwirtschaft übernommen und erhält später eine Versandmeldung. Ein internes Tool ergänzt Informationen für den Kundenservice.

Die grobe Richtung ist einfach. Offen bleibt trotzdem viel: Wird jede angelegte Bestellung übertragen oder erst eine bezahlte? Was passiert bei einer Teilstornierung? Darf die Lieferadresse nach der Übergabe noch geändert werden? Und welches System entscheidet, ob ein Auftrag bereits versendet wurde?

Beschreiben Sie zunächst einen normalen Durchlauf mit Anfang und Ende. Danach folgen die Abweichungen. Eine Liste aller verfügbaren API-Endpunkte ist dafür weniger hilfreich als ein gemeinsam verstandener Auftrag mit seinen möglichen Zuständen.

Für jede Information braucht es eine führende Quelle

Datenhoheit bedeutet: Für eine bestimmte Information ist festgelegt, welches System die verbindliche Quelle ist. Das muss nicht für alle Daten dasselbe System sein.

Die folgende Tabelle ist ein Planungsbeispiel, keine allgemeingültige Empfehlung:

„Wir synchronisieren in beide Richtungen“ beantwortet diese Fragen nicht. Ohne Konfliktregel kann eine ältere Änderung eine neuere überschreiben. Legen Sie daher auch fest, welche Felder nie zurückgeschrieben werden und wann eine Entscheidung durch einen Menschen nötig ist.

Gleiche Bezeichnungen bedeuten nicht gleiche Daten

Ein Artikelname eignet sich selten als dauerhafter Schlüssel. Namen können sich ändern, mehrfach vorkommen oder in verschiedenen Sprachen vorliegen. Für eine stabile Zuordnung braucht es geeignete Kennungen und eine gespeicherte Beziehung zwischen den Datensätzen der beteiligten Systeme.

Prüfen Sie außerdem Varianten, Einheiten und Formate. Ist die Menge eine Stückzahl oder ein Gewicht? Bezieht sich ein Betrag auf eine Position oder auf den ganzen Auftrag? Welche Zeitzone gilt? Wie werden leere Werte, gelöschte Datensätze und nachträgliche Änderungen dargestellt?

Besonders wichtig ist die Bedeutung von Zuständen. „Abgeschlossen“ kann im Shop etwas anderes heißen als in einem internen Tool. Eine ausdrücklich dokumentierte Zuordnung verhindert, dass fachlich unterschiedliche Zustände versehentlich gleichbehandelt werden.

Wie aktuell müssen die Daten wirklich sein?

Für einen Monatsbericht reicht unter Umständen ein geplanter Abruf. Bei Beständen oder einer verbindlichen Rückmeldung im Bestellablauf kann eine längere Verzögerung problematisch sein. Formulieren Sie deshalb die fachlich zulässige Verzögerung, bevor eine technische Lösung gewählt wird.

Webhooks melden Ereignisse, ohne dass ständig nach Änderungen gefragt werden muss. Sie sind jedoch nicht automatisch eine vollständige, geordnete Ereignishistorie. Shopify dokumentiert beispielsweise, dass die Zustellreihenfolge nicht garantiert ist und ein ergänzender Datenabgleich notwendig sein kann, weil Ereignisse fehlen oder nicht korrekt verarbeitet werden können. Shopify: Verhalten von Webhooks.

Daraus folgt für die Planung: Eine schnelle Meldung und ein regelmäßiger Kontrollabgleich können unterschiedliche Aufgaben erfüllen. Ob diese Kombination benötigt wird, hängt vom System und von den Folgen einer Abweichung ab.

Fehlerfälle gehören in den Leistungsumfang

Die Frage „Was passiert bei einem Fehler?“ braucht konkrete Antworten. Eine Fehlermeldung im technischen Log allein hilft der Person im Tagesgeschäft noch nicht.

Der technische Begriff für eine wiederholbare Operation ohne zusätzliche fachliche Wirkung lautet Idempotenz. Für das Beispiel heißt das: Ein wiederholter Übertragungsversuch darf nicht versehentlich einen zweiten Auftrag erzeugen. Die konkrete Umsetzung hängt vom Zielsystem ab; eine beliebige Kennung im Request macht einen Endpunkt noch nicht idempotent.

Shopify beschreibt für unterstützte APIs eigene Mechanismen für idempotente Anfragen. Diese Unterstützung muss am tatsächlich verwendeten Endpunkt geprüft werden. Shopify: Idempotente Anfragen.

Zugriffe und Betrieb brauchen Verantwortliche

Für jedes angebundene System sollte geklärt sein, welcher Zugang verwendet wird, welche Rechte er benötigt und wer ihn verwaltet. Ein persönliches Administratorkonto als dauerhafter Integrationszugang schafft unnötige Abhängigkeiten. Zugangsdaten gehören in eine geeignete serverseitige Konfiguration und nicht in Browsercode oder ein öffentliches Repository.

Auch Protokolle brauchen eine bewusste Gestaltung. Eine technische Vorgangskennung und der Bearbeitungszustand sind für die Fehlersuche hilfreich. Vollständige Kundendatensätze in jedem Logeintrag können dagegen unnötige Datenkopien erzeugen. Welche Informationen gespeichert werden und wie lange, muss zum tatsächlichen Bedarf passen.

Vereinbaren Sie außerdem, wer einen hängenden Vorgang bemerkt und wer fachlich entscheiden darf. Technische Betreuung kann eine fehlerhafte Verbindung reparieren; sie kann nicht eigenständig entscheiden, ob ein unvollständiger Auftrag trotzdem ausgeliefert werden soll.

So lässt sich die Abnahme vorbereiten

Wählen Sie vor der Implementierung repräsentative Beispieldaten. Dazu gehören ein normaler Vorgang, ein Sonderfall und mehrere gezielt provozierte Fehler. Prüfen Sie nicht nur, ob ein Datensatz ankommt, sondern ob er fachlich korrekt ankommt und danach weiterbearbeitet werden kann.

Ein guter Abnahmekatalog enthält auch doppelte Zustellung, Ausfall des Zielsystems, Wiederanlauf und nachträgliche Korrektur. Für jeden Fall sollte feststehen, welcher Zustand erwartet wird und wie eine zuständige Person ihn erkennt. Eine sichtbare Liste fehlgeschlagener Vorgänge kann dabei wertvoller sein als ein pauschales „Synchronisierung erfolgreich“.

Planen Sie den ersten produktiven Lauf ebenfalls: Startbestand, bereits vorhandene Zuordnungen, Nachübertragung und Kontrollabgleich. Sonst treffen sauber übertragene neue Daten auf ungeklärte Altbestände.

Was für ein erstes Gespräch reicht

Sie brauchen noch keine fertige technische Spezifikation. Hilfreich sind die beteiligten Systeme, ein konkreter Vorgang, die heute manuell übertragenen Informationen und die wichtigsten Ausnahmen. Ergänzen Sie, wer die Systeme fachlich betreut und ob Testzugänge oder Dokumentationen verfügbar sind.

Auf dieser Grundlage lässt sich der Umfang einer Schnittstelle zwischen Ihren Systemen sinnvoll eingrenzen. Wenn noch offen ist, ob eine Erweiterung des Bestands genügt, hilft auch die Abwägung Standardsoftware oder eigene Web-App. Integration besprechen.