Schnittstellen und APIs integrieren: Datenverträge, Synchronisation und Betrieb

Das Beispiel Shop und ERP begleitet den gesamten Artikel. Dieselben Entscheidungen gelten für Anbindungen zwischen CRM, Buchhaltung oder eigener Software.

01Eine API-Verbindung ist noch keine Prozessintegration

Eine API ist ein Vertrag: Sie legt fest, welche Operationen ein System anbietet, welche Daten dabei übergeben werden und welche Fehlermeldungen möglich sind. Eine Schnittstelle ist der allgemeinere Begriff für jede Verbindung zwischen Systemen – eine API ist deren präzise, meist standardisierte Form.

Der verbreitete Fehler beginnt früher: Ein Aufruf des einen Systems im anderen ist noch keine Integration. Ein erreichbarer Endpunkt beantwortet nicht, welches System die Bestellung führend verwaltet, was bei einem Fehler im Ziel passiert, ob dieselbe Bestellung mehrfach ankommt oder wer im Betrieb merkt, wenn der Datenfluss stillsteht.

Eine Integration muss deshalb als durchgängiger Prozess entworfen werden. Erst wenn Datenhoheit, Ablauf, Fehlerbehandlung und Betrieb definiert sind, ist aus einer Verbindung ein Geschäftsprozess geworden.

02Die Integrationsform folgt dem Prozess

Vier Integrationsformen decken die meisten Anforderungen ab: der synchrone API-Aufruf, der Webhook, die Warteschlange und die Batch-Verarbeitung. Keine davon ist pauschal überlegen.

Die Entscheidung folgt dem Prozess, nicht der Technologie. Braucht der Aufrufer eine unmittelbare Antwort – etwa der Shop bei der Preisermittlung im Warenkorb –, ist der synchrone Aufruf die passende Form. Soll das ERP bei jeder Bestellung sofort informiert werden, ohne dass der Shop auf eine Antwort wartet, passt ein Webhook. Müssen Ausfälle beider Seiten überbrückt werden, puffert eine Warteschlange. Buchhaltungsdaten, die nächtlich gebündelt übertragen werden, sind ein legitimer Batch-Fall.

Webhooks verdienen besondere Aufmerksamkeit, weil ihre Vertragslage oft missverstanden wird. Zustellgarantien, Wiederholungsfristen und Ereignisreihenfolge sind keine Eigenschaften des Webhook-Mechanismus, sondern des jeweiligen Anbieters. Stripe dokumentiert, dass Endpunkte dasselbe Ereignis mehrfach erhalten können, und garantiert nicht, dass Ereignisse in Erzeugungsreihenfolge ankommen; Zeitstempel sind kein verlässliches Ordnungskriterium, und Stripe weist ausdrücklich darauf hin, das created-Feld nicht zur Bestimmung der Ereignisreihenfolge zu verwenden (Stripe). Ein Webhook-Endpunkt prüft zuerst die Authentizität der Nachricht, speichert das Ereignis dauerhaft – etwa in einer Inbox oder Warteschlange – und bestätigt erst danach den Empfang mit 2xx. Die fachliche Verarbeitung erfolgt anschließend asynchron; ein Duplikat ist dabei normaler Eingang, kein Störungsfall. Wer den Empfang bestätigt, ohne das Ereignis zuvor zu sichern, verliert es bei einem Absturz unmittelbar nach der Bestätigung.

03Datenhoheit, Identitäten und Mapping festlegen

Vor jeder technischen Umsetzung ist pro Datenobjekt zu klären, welches System es führend verwaltet. Im Beispiel: Der Shop führt den Warenkorb, das ERP führt Bestände, Belege und Artikelstamm. Widersprüchliche Schreibrechte auf dasselbe Objekt sind eine typische Quelle dauerhaft abweichender Daten.

Daraus folgen mehrere Festlegungen:

• Systemische und externe Identitäten. Der Shop kennt seine Bestellnummer, das ERP seine Belegnummer. Die Zuordnung wird als eigenes Mapping geführt, nicht durch Überschreiben einer der beiden Nummern.
• Statussemantik. Was bedeutet der Status im Quellsystem im Zielsystem? Ein „bezahlt“ im Shop kann im ERP erst eine Anzahlung abdecken.
• Fehlende Felder, Einheiten und Löschungen. Ein fehlendes optionales Feld ist eine Information; ein fehlendes Pflichtfeld ist ein Vertragsfehler. Der Vertrag legt fest, was ein fehlendes Feld, ein null-Wert und ein leerer Wert jeweils bedeuten. Löschungen werden vereinbart: endgültig löschen, als gelöscht markieren oder nicht übertragen.
• Synchronisationsschleifen. Meldet ein System jede übernommene Änderung zurück, kann daraus eine Schleife entstehen. Entscheidend sind Schreibhoheit und Regeln, selbst ausgelöste oder bereits übernommene Änderungen nicht erneut zu übertragen; die Herkunftskennzeichnung einer Änderung hilft dabei, ist für sich genommen aber keine Kontrolle.

Ein Mapping-Datensatz kann so aussehen:

{  "external_id": "order_20260741",  "local_id": "ERP-BELEG-41872",  "entity": "order",  "source_system": "shop",  "mapped_at": "2026-10-26T09:14:00Z"}

Bei einer Neuanlage existiert die Ziel-ID vor dem ersten Schreibaufruf noch nicht. Die Integration speichert den Vorgang deshalb vor dem Aufruf unter einer stabilen Kennung der logischen Operation und ordnet die Ziel-ID erst nach bestätigter Anlage zu. Geht die Antwort verloren, gilt der Wiederanlauf nach Abschnitt 7.

04Datenverträge beschreiben und kontrolliert ändern

Ein Datenvertrag beschreibt, welche Felder mit welchen Typen, Pflichten und Wertebereichen ausgetauscht werden. Für HTTP-APIs ist die OpenAPI-Spezifikation das verbreitete Beschreibungsformat (OpenAPI Initiative). Der Vertrag ist die Grundlage für drei Prüfungen: die Validierung eingehender Daten gegen das Schema, die Prüfung ausgehender Daten vor dem Versand und die Erkennung, wenn sich die Gegenseite ändert.

Eine schema-konforme Nachricht kann dennoch fachlich unzulässig sein – eine Bestellung für einen Artikel ohne Bestand erfüllt jeden Datentyp. Der Vertrag muss deshalb neben der Struktur auch fachliche Regeln dokumentieren: gültige Statusübergänge, Pflichtkombinationen von Feldern, Behandlung leerer Werte.

Ob eine Änderung verträglich ist, hängt von Richtung, Vertrag und Verbraucherverhalten ab. Neue optionale Felder sind nur dann unproblematisch, wenn die Verbraucher unbekannte Felder tolerieren. Neue Werte in bestehenden Aufzählungen können Clients mit geschlossener Fallunterscheidung überfordern – besonders in Antworten, die ein Verbraucher nicht kontrolliert. Entfernte Felder, geänderte Typen, neue Pflichtfelder oder geänderte Semantik sind Brüche. Ob ein Bruch tatsächlich wirkt, wird an den tatsächlichen Verbrauchern geprüft: Nutzt der eine Partner das Feld, ist es belegt. Eine Versionsnummer allein beantwortet das nicht. Für Brüche gelten angekündigte Fristen und Übergangszeiten, in denen beide Varianten funktionieren.

05Adapter trennen Systemdetails von Prozesslogik

Die belastbare Struktur einer Integration ist unabhängig davon, ob zwei oder zehn Systeme verbunden werden. Jedes externe System erhält einen eigenen Adapter, der dessen Datenmodell, Authentisierung und Fehlermeldungen übersetzt. Dazwischen liegen Mapping und Prozessschritte in einer eigenen Schicht, die keine Shop- oder ERP-Details kennen muss.

Die Trennung zahlt sich beim ersten Änderungsfall aus: Ein neues ERP oder ein geändertes Shop-Datenmodell betreffen vornehmlich den jeweiligen Adapter. Die Prozesslogik – was mit einer Bestellung passiert, wenn das ERP sie ablehnt – bleibt davon meist unberührt.

Ein Gateway oder ein Nachrichten-Broker ist kein Selbstzweck. Bei wenigen Beteiligten und klaren Abläufen sind Adapter und Prozessschicht ausreichend. Ein Broker begründet sich durch Anforderungen wie mehreren unabhängigen Verbrauchern desselben Ereignisses, stark schwankenden Lasten oder unabhängigen Bereitstellungsrhythmen der beteiligten Teams.

06Initialübernahme und laufende Synchronisation unterscheiden

Zwei Vorgänge werden häufig vermischt, obwohl sie unterschiedliche Anforderungen haben: die Initialübernahme des Datenbestands und die laufende Synchronisation.

Die Initialübernahme überträgt vorhandene Datenmengen – Artikelstamm, Bestände, offene Bestellungen. Sie arbeitet mit Pagination und speichert Checkpoints, damit ein Abbruch nicht von vorn beginnt. Sie muss mit einem sich ändernden Bestand umgehen können: Während der Übernahme werden weiter Bestellungen aufgegeben. Die Übergabe zur laufenden Verarbeitung wird ebenfalls definiert: Für einen lückenlosen Übergang müssen Datenbestand und anschließende Änderungen aufeinander abgestimmt sein, etwa durch einen konsistenten Snapshot mit zugehöriger Änderungsposition nach dem Vertrag der Quell-API. Ein erst am Ende der Übernahme gesetzter Marker reicht nicht aus: Er kann zwischenzeitliche Änderungen überspringen. Fehlt eine entsprechende API-Unterstützung, braucht es eine ausdrücklich begrenzte Ersatzstrategie mit anschließendem Abgleich. Pagination und Checkpoints allein garantieren keinen lückenlosen Datenbestand.

Die laufende Synchronisation verarbeitet Änderungen. Sie muss mit Duplikaten, verspäteten Ereignissen und Ereignissen ohne Vorgänger umgehen. Welche Zustellgarantien gelten, bestimmt der jeweilige Anbieter: Bei Stripe können Ereignisse mehrfach und außerhalb der Erzeugungsreihenfolge eintreffen (Stripe). Tritt ein Ereignis ohne sein Vorgängerereignis auf, kann der Adapter den aktuellen Zustand über die API nachlesen, statt den Vorgang als fehlerhaft zu verwerfen. Das ersetzt ein eigenständiges Geschäftsereignis mit definierten Folgeschritten allerdings nicht: Für die Zustandsreplikation eines Objekts genügt der aktuelle Stand; für einen auszulösenden Prozessschritt braucht es das Ereignis selbst oder eine ausdrücklich vereinbarte Ersatzregel.

Unabhängig von der Form der Übermittlung gehört ein regelmäßiger Abgleich dazu: Werden die Daten beider Systeme verglichen – Zählungen, Summen, Stichproben abweichender Datensätze –, findet er auch Lücken, die keine Fehlermeldung erzeugt haben. Fehlende Webhooks sind sonst erst an fachlichen Symptomen sichtbar, etwa an Bestellungen ohne Folgebeleg. Der Abgleich ist kein Eingeständnis eines Fehlers, sondern Teil des Betriebs.

07Fehler und Teilerfolge ausdrücklich modellieren

Drei Fehlerkategorien verlangen unterschiedliche Reaktionen:

• Technischer Fehler. Das Zielsystem ist nicht erreichbar, antwortet mit 5xx oder bricht ab. Das beschreibt zunächst die beobachtete Störung, nicht zwingend das Ausführungsergebnis – auch nach einem 5xx kann die Änderung bereits erfolgt sein. Automatische Wiederholungen setzen einen vorübergehenden Fehler und entweder eine nachgewiesene Nichtausführung oder vertraglich abgesicherte Idempotenz voraus; sie sind zeitlich begrenzt, mit Wartezeiten und, sofern das Ziel ein Retry-After-Verhalten dokumentiert, nach dessen Regeln.
• Fachliche Ablehnung. Das Ziel hat den Aufruf verstanden und abgelehnt – ein fehlender Bestand, ein ungültiger Status. Ein erneuter identischer Aufruf wird ebenfalls abgelehnt, solange die Ursache unverändert besteht. RFC 9457 definiert mit application/problem+json ein Format für maschinenlesbare Fehlerdetails; anwendungsspezifische Angaben lassen sich als Erweiterungen ergänzen (RFC 9457).
• Unbekannter Ausgang. Der Aufruf wurde abgesetzt, die Antwort ging verloren. Das ist kein bewiesener Fehlschlag, und eine blinde Wiederholung kann die Aktion doppelt ausführen.

Die Kategorie entscheidet über den weiteren Weg. Technische Fehler gehören nur unter diesen Voraussetzungen in die zeitlich begrenzte Wiederholung. Fachliche Ablehnungen gehören nicht in die Wiederholung, sondern in eine Klärungsliste mit benanntem Verantwortlichen: Eine Bestellung ohne Bestand löst sich nicht durch den fünften identischen Aufruf, sondern durch eine fachliche Entscheidung. Unbekannte Ausgänge werden vor jeder Wiederholung geklärt – über die Idempotenzfunktion der Ziel-API, soweit sie dokumentiert ist, oder über eine eindeutige externe Referenz im Zielsystem. Vorgänge, die nach Ablauf der Wiederholungsfrist weiterhin offen sind, wandern in eine gesonderte Ablage und werden gezählt; sie sind die Kennzahl „ausstehende Vorgänge“ in Abschnitt 10.

Bei Integrationen unabhängiger APIs steht in der Regel keine gemeinsame atomare Transaktion zur Verfügung. Ein mehrstufiger Ablauf – Bestellung annehmen, Bestand buchen, Bestätigung an den Shop – kann teilweise erfolgreich sein. Jeder Schritt erhält deshalb einen eigenen Zustand, und die Fortsetzung nach einem Abbruch erfolgt ab dem ersten nicht bestätigten Schritt. Idempotenzschlüssel für schreibende Aufrufe, der Umgang mit verlorenen Antworten und der Abgleich mit dem Zielsystem vor einer Wiederholung sind im Artikel KI-Agenten produktiv integrieren ausführlich beschrieben; die Regeln gelten für jede Systemverbindung, mit oder ohne Sprachmodell.

08Identität und Berechtigungen an Systemgrenzen prüfen

Authentisierung und Autorisierung sind unterschiedliche Prüfungen. Die erste klärt, wer oder was anruft; die zweite, was dieser Aufrufer auf dieser Ressource darf. Das Zielsystem muss Zugriffe selbst prüfen; die Integrationsanwendung ergänzt diese Kontrolle, indem sie ihre eigenen Zugänge, Berechtigungen und die Weitergabe von Identitäten begrenzt.

Für die Autorisierung zwischen Systemen ist OAuth 2.0 der etablierte Rahmen (RFC 6749); für System-zu-System-Verbindungen, in denen ein vertraulicher Client im eigenen Namen handelt, eignet sich der Client-Credentials-Flow, sofern die Zielplattform ihn anbietet. Die zugehörige Sicherheitsleitlinie empfiehlt, die Berechtigungen eines Access-Tokens auf das erforderliche Minimum zu beschränken, untersagt den Resource-Owner-Password-Credentials-Grant, rät vom Implicit Grant ab und empfiehlt sender-gebundene Access-Tokens, etwa über mutual TLS oder DPoP (RFC 9700). API-Schlüssel in Abfrageparametern oder dauerhaft gültige Token sind dementsprechend zu vermeiden. Client-Secrets und Token liegen im Secret-Store der Plattform – nicht im Quelltext, nicht in Protokollen, nicht im Frontend.

Zusätzlich gilt:

• Berechtigungen folgen dem Prinzip der minimalen Rechte. Der Shop-Adapter, der nur Bestellungen sendet, braucht keine Schreibrechte auf Artikelstämme. Die OWASP API Security Top 10 führen verletzte objektbezogene Autorisierung (Broken Object Level Authorization) an erster Stelle (OWASP, API1:2023).
• Webhook-Endpunkte prüfen die Signatur. Die Nachricht wird gegen den Absender authentisiert, nach dem vom Anbieter definierten Verfahren – häufig ein HMAC über den unveränderten Nachrichtenkörper – bevor irgendein Feld verarbeitet wird.

09Verträge, Fehlerfälle und Wiederanlauf testen

Tests einer Integration prüfen mehr als die Erfolgspfade. Drei Ebenen sind zu trennen:

• Vertragstests. Nachrichten am Rand des Vertrags senden und empfangen: fehlende Pflichtfelder, falsche Typen, unbekannte Felder einer neueren Version, neue Werte in einer Aufzählung. Diese Tests laufen gegen die Adapter, ohne die Gegensysteme zu beteiligen.
• Integrationstests mit Testdaten. Der Shop-ERP-Abgleich wird mit vereinbarten Testdaten geprüft – Bestellungen, Bestandsänderungen, Preisänderungen – und die erwarteten Werte in beiden Systemen verglichen.
• Fachliche End-to-End-Abnahme. Der vollständige Prozess inklusive der Fehlerfälle, die im Betrieb sicher auftreten.

Zu den Fehlerfällen gehören mindestens: dasselbe Ereignis zweimal; ein Ereignis vor seinem Vorgänger; ein Abbruch der Initialübernahme mit Wiederanlauf am Checkpoint, bei dem sich der Quellbestand zwischenzeitlich geändert hat; ein Abgleich, der eine absichtlich erzeugte Lücke finden muss; zwei Shop-Bestellungen, die auf dieselbe ERP-Belegnummer abgebildet werden sollen; ein neues Pflichtfeld auf der Gegenseite. Dazu kommen die Fälle, die jede schreibende API-Verbindung betreffen – ein Ziel, das mitten im Ablauf nicht mehr antwortet, und eine verlorene Antwort nach erfolgreichem Schreibaufruf (Abschnitt 7). Kein Integrationstest, der nur den Normalfall abbildet, prüft die Eigenschaften, die im Betrieb zählen.

10Betrieb braucht fachliche Nachweise und Verantwortliche

Eine Integration ist erst betrieben, wenn ihr Zustand ohne Studium von Protokollen beurteilbar ist. Technische Kennzahlen wie Fehlerraten und Latenz sind notwendig, aber nicht ausreichend. Die aussagekräftigeren Größen sind fachlich:

• Rückstand. Wie viele Änderungen warten auf Verarbeitung, und wie alt ist die älteste?
• Ausstehende Vorgänge. Bestellungen im Shop ohne Beleg im ERP – die zentrale fachliche Kennzahl des Beispiels.
• Ungeklärte Abweichungen. Datensätze, die im Abgleich beider Systeme nicht übereinstimmen, ohne dass ein Fehler vorliegt.

Eine Korrelations-ID begleitet jede Änderung durch alle Systeme und verbindet Shop-Ereignis, Adapter-Verarbeitung und ERP-Beleg. Ohne sie ist jede Störungssuche eine Rekonstruktion.

Mindestens ebenso wichtig wie das Monitoring sind benannte Verantwortlichkeiten: Wer wird bei einer API-Änderung der Gegenseite informiert und passt den Adapter an? Wer bearbeitet Störungen außerhalb der Geschäftszeiten? Wer entscheidet über die Wiederholung hängengebliebener Vorgänge? Diese Fragen vor dem Go-live zu beantworten, ist Teil der Integration – nicht ihr Nachtrag.

Quellen

• IETF: RFC 9457, Problem Details for HTTP APIs (öffnet in neuem Tab)
• IETF: RFC 6749, The OAuth 2.0 Authorization Framework (öffnet in neuem Tab)
• IETF: RFC 9700, Best Current Practice for OAuth 2.0 Security (öffnet in neuem Tab) (BCP 240)
• OpenAPI Initiative: OpenAPI Specification v3.2.1 (öffnet in neuem Tab)
• Stripe: Receive Stripe events in your webhook endpoint (öffnet in neuem Tab) (Duplicate events, Event ordering, Retries)
• Stripe: Idempotent requests (öffnet in neuem Tab) (API-Referenz)
• OWASP: API Security Top 10 (2023) (öffnet in neuem Tab), API1:2023 Broken Object Level Authorization

Alle Quellen am 26. Oktober 2026 abgerufen.

Technische Umsetzung mit Seovantis

Wenn Anbindungen zwischen bestehenden Systemen umgesetzt werden sollen, übernehmen wir die technische Umsetzung. Seovantis setzt Softwaremodule, APIs und Schnittstellen für bestehende Unternehmensanwendungen um – etwa zwischen Shop, Warenwirtschaft, CRM, ERP oder eigener Software.

Je nach Vorhaben gehören dazu die Anbindung vorhandener APIs, Adapter und Datenübertragung mit vereinbartem Abgleich, Backend-Komponenten für Zustand und Ausführung sowie Tests und Abnahmekriterien. Die Prüfung vor der Übergabe richtet sich nach den vereinbarten Anforderungen.

Verwandter Beitrag: KI-Agenten produktiv integrieren: Tool-Calling, Zustands­verwaltung und sichere API-Ausführung