Schnittstellen planen: Was vor der Entwicklung klar sein sollte

Womit beginnt die Planung einer Schnittstelle?

„Shop und Warenwirtschaft verbinden“ beschreibt ein Ziel, aber noch keinen umsetzbaren Auftrag. Welche Daten sollen wann wohin fließen? Ein hilfreicher Start ist ein einzelner Ablauf: Eine bezahlte Bestellung wird mit Positionen und Lieferadresse an die Warenwirtschaft übertragen, die spätere Sendungsnummer kommt zurück in den Shop.

Schreibe auch auf, was zunächst außerhalb des Umfangs liegt. Retouren, Teillieferungen oder mehrere Lager können einen eigenen Umsetzungsschritt benötigen. Ein klarer erster Ablauf macht Aufwand und Abnahme greifbar.

Warum braucht jedes Feld ein führendes System?

Lege fest, welches System Preise, Bestände, Adressen und Statuswerte verbindlich pflegt. Wenn beide Seiten denselben Wert ändern dürfen, braucht es eine Konfliktregel. „Die letzte Änderung gewinnt“ kann fachlich falsch sein, etwa wenn ein verzögerter Import einen aktuellen Lagerbestand überschreibt.

Erstelle eine Feldliste mit Quelle, Ziel, Format und Pflichtangaben. Beispiel: Die Artikelnummer aus dem ERP wird dem SKU-Feld im Shop zugeordnet. Zusätzlich muss geklärt werden, ob Varianten eigene Nummern besitzen und wie unbekannte Artikel behandelt werden.

Diese Liste ist der eigentliche Kern der Absprache. Sie zeigt schnell die offenen Punkte:

• Wie werden Varianten abgebildet?
• Welche Währung und welche Steuersätze gelten?
• Wie lang darf ein Feld sein und was passiert bei längeren Werten?
• Bedeutet ein leerer Wert „unbekannt“ oder „bewusst leer“?

Wie oft müssen Daten übertragen werden?

Nicht jede Information muss sofort übertragen werden. Für einen Tagesbericht kann ein nächtlicher Abgleich reichen; ein knapper Lagerbestand benötigt möglicherweise deutlich kürzere Intervalle. Definiere die fachlich zulässige Verzögerung und prüfe dann, ob die beteiligten APIs sie ermöglichen.

Für die Planung zählen typische Mengen und Spitzen:

• Wie viele Bestellungen entstehen an einem normalen Tag und an einem Spitzentag?
• Wie groß ist ein vollständiger Produktabgleich?
• Welche API-Limits gelten auf beiden Seiten?

Erstimport und laufende Aktualisierung sollten dabei getrennt betrachtet werden.

Fehler sind Teil des Ablaufs

Was passiert, wenn das Zielsystem eine Stunde nicht erreichbar ist? Daten müssen nachvollziehbar erneut verarbeitet werden können. Dabei darf dieselbe Bestellung nicht ein zweites Mal angelegt werden. Eine stabile externe Referenz und eine klar definierte Wiederholungsstrategie gehören deshalb zur Planung.

Der Fachbegriff dafür ist Idempotenz: Dieselbe Anfrage mehrfach zu senden, muss denselben Zustand ergeben wie ein einzelner Aufruf. RFC 9110 beschreibt, welche HTTP-Methoden diese Eigenschaft von sich aus mitbringen und warum ein wiederholtes POST sie eben nicht hat. Praktisch heißt das: Der Sender führt je Vorgang einen stabilen Schlüssel mit, und das Zielsystem erkennt daran einen bereits verarbeiteten Fall.

Wie schnell wiederholt werden darf, entscheidet nicht der Sender allein. Antwortet die Gegenseite mit einer Begrenzung, nennt sie den frühestmöglichen nächsten Versuch üblicherweise im Retry-After-Header. Eine Wiederholung mit wachsenden Abständen, die diesen Wert beachtet, verhindert, dass aus einer kurzen Störung eine dauerhafte Überlastung wird.

Auch fachliche Fehler brauchen einen Weg: Eine unbekannte Artikelnummer wird durch bloßes Wiederholen nicht korrekt. Lege fest, wer solche Fälle sieht, korrigiert und erneut anstößt. Protokolle sollten den Vorgang über beide Systeme hinweg auffindbar machen, ohne unnötig personenbezogene Inhalte zu speichern.

Wie planst du Retouren, Teillieferungen und Stornierungen ein?

Der erste Ablauf endet meist bei der versendeten Bestellung. Der Alltag endet dort nicht. Diese drei Fälle verändern einen bereits übertragenen Vorgang und brauchen deshalb eigene Regeln, auch wenn sie bewusst später umgesetzt werden.

• Teillieferungen: Wird eine Bestellung in mehreren Sendungen ausgeliefert, gehört zu jeder Sendung ihre eigene Nummer und ihr Positionsumfang. Der Shop braucht dann einen Status je Position, sonst wirkt eine Bestellung vollständig versendet, obwohl noch Artikel offen sind.
• Retouren: Eine Rücksendung betrifft Bestand, Beleg und Erstattung zugleich. Kläre, welches System die Retoure erfasst, ob der Bestand sofort oder erst nach der Prüfung wieder verkaufbar ist und wie eine Gutschrift zum ursprünglichen Vorgang zugeordnet wird.
• Stornierungen und nachträgliche Änderungen: Bis zu welchem Zeitpunkt darf eine Bestellung geändert werden? Danach braucht es einen Nachfolgevorgang statt einer stillen Korrektur, damit beide Systeme denselben Verlauf zeigen.

Für jeden dieser Fälle gilt dieselbe Frage wie oben: Welches System entscheidet und welches folgt nur? Wenn das offen bleibt, entstehen später widersprüchliche Bestände und Belege, die sich nur noch von Hand aufklären lassen.

Wie bereitest du die Abnahme anhand von Beispielen vor?

• Eine normale Bestellung wird vollständig und genau einmal angelegt.
• Ein wiederholt zugestellter Vorgang erzeugt keine zweite Bestellung.
• Ein Ausfall wird sichtbar; die Verarbeitung kann danach fortgesetzt werden.
• Ungültige Daten werden nachvollziehbar zurückgewiesen.
• Eine Teillieferung lässt offene Positionen als offen stehen.
• Änderungen und Stornierungen folgen den vereinbarten Regeln.

Halte je Beispiel fest, welcher Ausgangszustand gilt und welches Ergebnis in beiden Systemen sichtbar sein muss. Damit wird aus der Abnahme eine Prüfung statt einer Diskussion.

Für ein Erstgespräch helfen die Namen und Versionen der Systeme, Links zur API-Dokumentation und ein anonymisiertes Datenbeispiel. Auf dieser Grundlage lässt sich die Schnittstellenentwicklung sinnvoll eingrenzen. Wie größere Datenbestände geprüft und schrittweise übernommen werden können, erklärt der Fachartikel zu Datenimporten in Laravel.

Die Planung einer Schnittstelle folgt damit sechs Schritten:

1. Einen konkreten Ablauf beschreiben. Nicht „Shop und Warenwirtschaft verbinden“, sondern ein einzelner Vorgang mit Auslöser, Daten und Ziel.
2. Je Feld ein führendes System bestimmen. Preise, Bestände, Adressen und Statuswerte brauchen genau eine verbindliche Quelle.
3. Aktualität und Datenmenge festlegen. Definiere je Datenbereich die fachlich zulässige Verzögerung statt „möglichst schnell“.
4. Fehlerfälle und Wiederholbarkeit klären. Eine stabile Referenz je Vorgang verhindert, dass dieselbe Bestellung zweimal entsteht.
5. Sonderfälle einplanen. Retouren, Teillieferungen und Stornierungen verändern bereits übertragene Vorgänge und brauchen eigene Regeln.
6. Abnahme anhand von Beispielen vorbereiten. Je Beispiel Ausgangszustand und erwartetes Ergebnis in beiden Systemen festhalten.