Schnittstellen sauber denken: Was bei Integrationen oft zu spät auffällt

Die erste erfolgreiche API-Anfrage fühlt sich wie ein Erfolg an. Zwei Systeme reden miteinander, Daten fließen, der Proof of Concept funktioniert. Und dann beginnt der eigentliche Teil der Arbeit: der Betrieb.

In der Praxis scheitern Integrationen selten daran, dass REST schlecht ist oder Webhooks nicht funktionieren. Sie scheitern daran, dass niemand im Vorfeld geklärt hat, welches System die führende Datenquelle ist. Oder daran, dass beide Systeme gleichzeitig schreiben dürfen, ohne eine Konfliktlogik zu haben. Oder daran, dass Fehler still verschwinden und die Daten desynchronisiert sind, bevor jemand es bemerkt.

Das ist keine Ausnahme. Das ist der Regelfall in Projekten, in denen Schnittstellenintegration als nachgelagerte Aufgabe behandelt wird – als technisches Detail, das man löst, wenn alles andere fertig ist. Wer so denkt, unterschätzt, was eine Schnittstelle eigentlich ist: ein Systemvertrag, der Datenhoheit, Fehlerverantwortung und Betriebslogik festlegen muss, bevor die erste Zeile Code entsteht.

Der häufigste Fehler bei Integrationsprojekten: Man fängt mit der API an, statt mit dem Datenmodell. Zwei Systeme werden verbunden, bevor klar ist, was eigentlich übertragen werden soll – und vor allem: in welcher Form, mit welchen Pflichtfeldern, mit welchem Wertebereich.

Ein konkretes Beispiel aus der Praxis: Ein Online-Shop übergibt Bestellungen an ein ERP-System. Das ERP erwartet eine Kundennummer als numerischen Wert. Der Shop übergibt sie als String mit vorangestelltem Buchstaben. Die Schnittstelle läuft technisch – nur landen 30 % der Bestellungen nie im ERP, weil die Validierung still schlägt und niemand eine Fehlermeldung bekommt.

Solche Probleme sind nicht schwer zu lösen. Aber sie entstehen fast ausschließlich dann, wenn das Datenmodell nicht vor der API-Entwicklung abgestimmt wird. Welche Felder sind Pflicht? Welche Typen sind erlaubt? Was passiert bei leeren Feldern? Was, wenn ein Wert im Quellsystem existiert, aber im Zielsystem kein Gegenstück hat? Diese Fragen müssen beantwortet sein, bevor Code entsteht – nicht danach.

Ein sauberes Integrationsdatenmodell dokumentiert nicht nur Feldnamen und Typen, sondern auch Semantik: Was bedeutet 'Lieferstatus = offen' im CRM gegenüber 'Auftragsstatus = eingegangen' im ERP? Sind das dasselbe? Fast immer: nein.

Die Wahl zwischen REST-API, Webhooks und einem Event-basierten Ansatz ist keine rein technische Entscheidung – sie hängt davon ab, wie Daten entstehen und wie zeitkritisch die Übertragung ist.

REST-APIs sind synchron: System A fragt an, System B antwortet sofort. Das funktioniert gut, wenn Daten auf Abruf benötigt werden – etwa für einen Produktdatenimport, eine Lagerstandsabfrage oder das Abrufen von Kundendaten vor dem Checkout. Problematisch wird REST, wenn daraus permanentes Polling entsteht: System A fragt alle 30 Sekunden, ob sich etwas geändert hat. Das erzeugt unnötige Last und reagiert trotzdem zu langsam.

Webhooks kehren die Logik um: System B benachrichtigt System A aktiv, wenn ein Ereignis eintritt – eine neue Bestellung, ein Statuswechsel, ein bezahltes Abo. Das ist deutlich effizienter, aber es braucht eine zuverlässige Empfangsinfrastruktur. Wenn System A den Webhook-Call nicht quittiert oder offline ist, muss System B das Ereignis wiederholen können. Nicht alle Dienste tun das zuverlässig.

Event-basierte Architekturen – mit Tools wie Kafka, RabbitMQ oder Cloud-Pub/Sub – sind dann sinnvoll, wenn viele Systeme dasselbe Ereignis verarbeiten müssen oder wenn Reihenfolge und Zuverlässigkeit kritisch sind. Sie sind aufwändiger aufzubauen, aber deutlich stabiler unter Last und bei komplexen Systemlandschaften.

Integrationsfehler sind oft unsichtbar. Kein Crash, keine Fehlermeldung – nur Daten, die leise falsch werden. Hier sind die Muster, die in Projekten immer wieder auftauchen:

Kein Fehler-Logging auf Empfängerseite: System A schickt Daten, System B verarbeitet sie – oder auch nicht. Wenn es kein aktives Monitoring gibt, das Fehlschläge protokolliert und meldet, weiß niemand, wie viel verloren geht. In einem realen E-Commerce-Projekt fehlten so über drei Monate hinweg rund 200 Bestellungen im ERP, bevor jemand es bemerkte – weil Kunden sich über Lieferverzögerungen beschwerten, nicht weil das System Alarm schlug.

Doppelschreiben ohne Konfliktlogik: Wenn zwei Systeme denselben Datensatz ändern dürfen, entsteht eine Race Condition. Welche Änderung gewinnt? Der letzte Schreibvorgang? Der mit dem neueren Timestamp? Ohne explizite Konfliktlogik sind beide Antworten falsch – und die Daten desynchronisieren sich mit der Zeit.

Kein Retry-Mechanismus: Eine API ist kurzfristig nicht erreichbar, ein Timeout tritt auf – und das Ereignis ist weg. Jede produktiv genutzte Integration braucht einen zuverlässigen Retry-Mechanismus mit exponentiellem Backoff. Das gilt besonders für Webhooks, aber auch für kritische REST-Aufrufe.

Harte Abhängigkeiten bei Systemausfällen: Wenn der Checkout im Shop abbricht, weil das ERP gerade nicht antwortet, ist die Kopplung zu eng. Lose Kopplung mit asynchroner Verarbeitung schützt vor Kaskadenausfällen.

Fehlendes API-Versioning: System A wird geupdatet, die Feldstruktur ändert sich, System B bekommt keine Nachricht. Ohne API-Versioning bricht die Integration still. Und ohne Tests, die das prüfen, fällt es erst auf, wenn Kunden sich beschweren.

Die klassische Systemlandschaft in wachsenden E-Commerce-Unternehmen: ein Shop-System (Shopify, Shopware), ein ERP (SAP, Navision, JTL, Sage) und ein CRM (HubSpot, Salesforce, Pipedrive). Alle drei Systeme haben eigene Datenmodelle, eigene Feldbezeichnungen und oft eigene Vorstellungen davon, was ein 'Kunde' oder eine 'Bestellung' ist.

Shop → ERP: Bestellungen, Lagerbestände, Preise und Kundenstammdaten müssen zuverlässig synchronisiert werden. Der Knackpunkt ist meist Richtung und Frequenz: Lagerbestände müssen nahezu in Echtzeit aus dem ERP in den Shop fließen – ein veralteter Bestand bedeutet Überverkäufe. Bestellungen müssen sofort ins ERP, damit Picking und Versand starten können.

Shop → CRM: Kaufhistorie, Warenkorbdaten und Kundensegmente wandern ins CRM – aber wann? Nur nach abgeschlossenem Kauf? Auch bei Warenkorbabbrüchen? Welche Daten darf das CRM überhaupt speichern (DSGVO)? Diese Fragen werden in Integrationsprojekten regelmäßig zu spät gestellt.

ERP → CRM: Rechnungen, Lieferstatus, Retourenquoten – all das ist für Vertrieb und Kundenservice wertvoll. Aber ERP-Systeme haben oft keine nativen Webhooks. Hier braucht es Middleware oder einen individuellen Adapter, der Ereignisse aus dem ERP erkennt und weiterleitet.

Die Herausforderung ist nicht die technische Anbindung – die ist in den meisten Fällen lösbar. Die Herausforderung ist das Datenmodell: Was ist die Kundennummer? Gibt es sie in allen drei Systemen? Ist sie identisch? Wenn nicht – welches System ist führend?

Viele Integrationen entstehen reaktiv: System A und System B sollen verbunden werden, es gibt Zeitdruck, jemand baut schnell einen Connector. Das funktioniert – bis zur ersten größeren Änderung an einem der Systeme, bis zur ersten Last-Spitze oder bis zum ersten ungeklärten Fehlerfall.

Der Unterschied zwischen einer schnell gebauten und einer sauber geplanten Integration zeigt sich nicht am ersten Tag. Er zeigt sich nach sechs Monaten im Betrieb.

Die technische Anbindung zweier Systeme ist in vielen Fällen die einfachere Hälfte einer Integrationslösung. Die schwierigere Hälfte ist der Betrieb: Wie weißt du, dass die Schnittstelle gerade fehlerfrei läuft? Was passiert, wenn sie es nicht tut? Wer ist verantwortlich?

Monitoring bedeutet mehr als ein grünes Dashboard. Es bedeutet, dass jeder fehlgeschlagene API-Call protokolliert wird, dass Fehlerhäufungen automatisch gemeldet werden und dass es eine definierte Eskalationslogik gibt. Ohne das merkt niemand, wenn die Lagerbestandssynchronisation seit zwei Stunden stumm schlägt.

Retry-Mechanismen gehören in jede produktive Integration, die mit externen APIs arbeitet. Netzwerkfehler, Timeouts, temporäre Nichtverfügbarkeit – das alles passiert im Betrieb. Ob ein Ereignis verloren geht oder sicher zugestellt wird, entscheidet sich daran, ob es eine Retry-Queue mit exponentiellem Backoff gibt.

Dead-Letter-Queues sind der sicherste Weg, verlorene Events nicht zu verlieren: Ereignisse, die nach mehreren Versuchen nicht verarbeitet werden konnten, landen in einer separaten Queue zur manuellen oder automatisierten Nachverarbeitung.

Zuständigkeiten müssen explizit geklärt sein. Wer ist Ansprechpartner, wenn die ERP-Schnittstelle Fehler wirft? Der Shop-Dienstleister? Das ERP-Haus? Das interne IT-Team? Wenn das nicht schriftlich fixiert ist, kostet jeder Incident drei Mal so viel Zeit wie nötig.

Viele Integrationen lassen sich mit Standard-Konnektoren und iPaaS-Tools (Zapier, Make, n8n) sauber lösen – besonders wenn es um Standardsysteme geht und die Logik überschaubar ist. Zapier ist gut für einfache Trigger-Action-Flows. n8n bietet mehr Flexibilität für komplexere Workflows und läuft auch selbst gehostet.

Individuelle Schnittstellenentwicklung lohnt sich, wenn Standard-Tools an ihre Grenzen stoßen: wenn das Datenmodell zu komplex für No-Code-Mapper ist, wenn Volumen und Frequenz iPaaS-Plattformen überlasten, wenn eigene Geschäftslogik in den Datenfluss muss oder wenn Legacy-Systeme ohne API-Unterstützung angebunden werden sollen.

Ein typisches Szenario: Ein Hersteller betreibt ein ERP aus den 2000er Jahren ohne native REST-API. Bestellungen kommen über Shopware. Die Warenwirtschaft läuft im Altsystem. Und das ERP kann nur Dateien per SFTP empfangen. Hier braucht es einen individuellen Adapter, der Shopware-Bestellungen in das erwartete Dateiformat transformiert, zuverlässig überträgt und Fehlerfälle behandelt. Kein Zapier-Workflow der Welt baut das sauber.

Individuelle Entwicklung gibt dir außerdem volle Kontrolle über Versionierung, Monitoring, Deployment und Kosten – ohne Abhängigkeit von einem Drittanbieter, der sein Preismodell oder seine API ändern kann. Das ist ein entscheidender Vorteil überall dort, wo Schnittstellen geschäftskritisch sind.

Integrationsprojekte werden regelmäßig unterschätzt – nicht weil API-Entwicklung teuer ist, sondern weil der Aufwand rund um Analyse, Datenmodellierung, Testing und Betriebssetup oft nicht eingerechnet wird.

Die Entwicklung eines einzelnen REST-Endpunkts dauert Stunden. Die saubere Analyse des Datenmodells, die Abstimmung mit beiden Systemverantwortlichen, das Schreiben der Transformationslogik, das Aufsetzen von Monitoring und Fehlerbehandlung und das Testen mit realen Produktionsdaten dauert Wochen.

Typische Aufwände für Integrationsprojekte in 2026:

Eine Schnittstelle zu bauen ist technisch selten das Problem. Das Problem ist, was vor dem ersten Code passiert – oder eben nicht. Datenmodelle, die nicht abgestimmt sind. Führende Systeme, die nicht definiert wurden. Fehlerlogik, die niemand geplant hat. Zuständigkeiten, die im Betrieb unklar bleiben.

Die Integrationsprobleme, die Unternehmen am meisten Geld kosten, sind keine spektakulären Ausfälle. Es sind die stillen: die Bestellungen, die nie ankamen. Die Lagerbestände, die drei Tage alt waren. Die CRM-Daten, denen niemand mehr vertraut, weil sie manchmal stimmen und manchmal nicht.

Wenn du eine Integration planst – ob ERP, CRM, Shop oder ein internes Tool – starte mit den richtigen Fragen: Wer ist führendes System? Was passiert bei Fehlern? Wer ist zuständig? Wie erkennst du, wenn etwas schief geht? Wenn diese Fragen beantwortet sind, ist die technische Umsetzung das Einfachste am ganzen Projekt.

Wir bei Webcellent entwickeln individuelle Schnittstellen und Systemintegrationen – mit klarem Fokus auf Datenmodell, Betriebssicherheit und langfristige Wartbarkeit. Wenn du eine Integration planst oder eine bestehende Lösung stabilisieren willst, sprich uns gern an.