API-Integration: Datenvertrag und Fehlerbehandlung

Was ist eine API-Integration? Vereinfacht gesagt verbindet sie zwei Anwendungen, damit diese nach festgelegten Regeln Daten austauschen können. So lassen sich etwa Bestellungen aus Ihrem Onlineshop an die Buchhaltung übergeben, Bestände aus dem ERP in den Shop übertragen oder Kundendaten aus dem CRM im Support anzeigen.

Eine erfolgreiche Integration ist jedoch mehr als eine technische Verbindung. Legen Sie von Anfang an fest, welche Daten wann übertragen werden, welches System die führende Quelle ist, wie Fehler behandelt und wie Ergebnisse kontrolliert werden.

Welche Probleme löst eine API-Integration im Unternehmen?

Wenn dieselben Informationen immer wieder in verschiedene Anwendungen eingegeben werden, entstehen Fehler, Verzögerungen und zusätzlicher Kontrollaufwand. Eine passend konzipierte API-Integration kann solche Wiederholungen reduzieren und die Datenkonsistenz zwischen Systemen unterstützen.

Bestellablauf: Bestellungen aus dem Onlineshop an Lager-, Versand- oder Buchhaltungssysteme übertragen.
Bestands- und Preisaktualisierung: Zentrale Bestände oder Preise an die Vertriebskanäle senden.
Kundensicht: CRM, Support und Vertrieb einen konsistenteren Zugriff auf denselben Kundendatensatz ermöglichen.
Statusmeldungen: Zahlungs-, Bestell-, Liefer- oder Freigabestatus an das zuständige System melden.
Berichte vorbereiten: Daten aus getrennten Anwendungen sinnvoll für Auswertungen zusammenführen.

Ein B2B-Vertriebsteam kann beispielsweise kundenspezifische Preise im ERP, Bestellungen im Shop und Zahlungseingänge in der Buchhaltung verwalten. Ziel ist nicht, alle Daten in jedes System zu kopieren, sondern benötigte Informationen zur richtigen Zeit in der richtigen Ansicht bereitzustellen.

API, Webhook, Dateitransfer und manueller Prozess im Vergleich

Nicht jeder Datenaustausch benötigt eine API. Häufigkeit, Datenmenge, Kritikalität des Vorgangs und technische Möglichkeiten bestimmen die geeignete Methode.

Methode	Wie funktioniert sie?	Passendes Beispiel	Worauf kommt es an?
API	Ein System sendet eine Anfrage an ein anderes oder ruft Daten ab.	Bestellung anlegen, Bestand abfragen, Kundendaten aktualisieren.	Authentifizierung, Anfragelimits und Fehlerantworten müssen geklärt sein.
Webhook	Bei einem Ereignis sendet das Quellsystem eine Meldung an das Zielsystem.	Neue Bestellung, Zahlungsbestätigung oder Kündigung eines Abonnements.	Mehrfachmeldungen und die Erreichbarkeit des Zielsystems müssen berücksichtigt werden.
Dateitransfer	CSV-, XML- oder ähnliche Dateien werden in festgelegten Abständen ausgetauscht.	Produktlisten, periodische Preislisten oder Datenübernahme aus Altsystemen.	Dateischema, Zeichencodierung und Aktualisierungszeit müssen geprüft werden.
Manueller Prozess	Eine Person gibt Daten über die Benutzeroberfläche ein oder bestätigt sie.	Ausnahmen, geringe Fallzahlen oder Vorgänge mit menschlicher Entscheidung.	Berechtigungen, Kontrollschritte und eine nachvollziehbare Vorgangshistorie sind erforderlich.

API und Webhook werden häufig verwechselt. Über eine API kann Ihre Anwendung bei Bedarf fragen: „Welchen Status hat diese Bestellung?“ Bei einem Webhook meldet das andere System von sich aus: „Der Bestellstatus hat sich geändert.“ In vielen Projekten ergänzen sich beide Verfahren.

Geeignete Prozesse für die Integration auswählen

Versuchen Sie nicht, sofort alle Abläufe zu automatisieren. Machen Sie zunächst Prozesse sichtbar, die Datenfehler, Wartezeiten oder hohen Nachverfolgungsaufwand verursachen. Bewerten Sie jeden Ablauf anhand dieser Fragen:

Was startet den Vorgang: eine neue Bestellung, Zahlung, ein Formular, eine Freigabe oder eine geplante Aufgabe?
Aus welchem System stammen die Daten und wohin sollen sie gelangen?
Ist eine menschliche Freigabe oder Beurteilung erforderlich?
Wie aktuell müssen die Daten sein: sofort, in kurzen Intervallen oder täglich?
Wie beeinflussen fehlerhafte oder fehlende Daten den Ablauf?
Welches Team soll nach Abschluss informiert werden?

„Bei einer neuen Bestellung einen Versandauftrag anlegen“ eignet sich häufig für eine Integration: Auslöser, Datenfelder und Ergebnis sind klar. „Bei hochpreisigen Bestellungen einen Sonderrabatt prüfen“ enthält dagegen eine menschliche Entscheidung und sollte nicht vollständig automatisiert werden. Das System kann hier Informationen vorbereiten und eine Aufgabe oder Freigabe an die zuständige Person senden.

Für die getrennte Gestaltung von Freigaben hilft der Leitfaden zu Workflow-Automatisierung und Freigabeprozessen (auf Türkisch).

Checkliste für Datenfelder und Datenhoheit

Ein häufiges Problem ist, dass gleich benannte Felder in zwei Systemen unterschiedliche Bedeutungen haben. „Kundenname“, „Produktcode“, „Bestellstatus“ oder „Bestand“ können sich in Format, Umfang und Aktualisierungsregel unterscheiden.

Was Sie für jedes Datenfeld klären sollten

Name und Bedeutung: Meint „Bestand“ die verkaufbare Menge oder den physischen Lagerbestand?
Datentyp: Handelt es sich um Text, Zahl, Datum, Währung, Liste oder Datei?
Pflichtfeld: Darf das Feld leer bleiben? Muss der Vorgang dann stoppen?
Eindeutige Kennung: Welches System erzeugt Produktcode, Kunden-ID oder Bestellnummer?
Umwandlungsregel: Welchem Wert im Zielsystem entspricht ein Status im Quellsystem?
Führende Datenquelle: Welches System liefert den maßgeblichen Wert?
Aktualisierungsrichtung: Werden Daten in einer oder in beiden Richtungen übertragen?

Die Zuordnung der führenden Quelle ist besonders wichtig. Wenn Sie Produktbeschreibungen im PIM, Bestände im ERP und den Veröffentlichungsstatus im Shop verwalten, bestimmen Sie für jedes Feld genau eine maßgebliche Quelle. Andernfalls können Systeme gegenseitig ihre Daten überschreiben.

Praktische Regel: Betrachten Sie bidirektionalen Datenaustausch nicht als Standard. Prüfen Sie zuerst, ob ein einseitiger Datenfluss den Bedarf bereits erfüllt.

Fehlerbehandlung, Protokollierung und Testszenarien

Die Qualität einer Integration zeigt sich nicht nur im Normalbetrieb, sondern besonders im kontrollierten Umgang mit unerwarteten Situationen. Verbindungen können ausfallen, externe Dienste vorübergehend nicht antworten oder Quellsysteme unvollständige Daten liefern. Planen Sie die Fehlerbehandlung deshalb nicht erst nach der Entwicklung.

Kontrollen für Ihren Integrationsplan

Vorgangsprotokoll: Zeitpunkt, betroffene Datensatzkennung, Ergebnisstatus und Fehlermeldung müssen nachvollziehbar sein.
Schutz vor Doppelverarbeitung: Wiederholte Webhooks oder Anfragen dürfen keine zweite Bestellung, Rechnung oder Sendung erzeugen.
Wiederholungsregel: Vorübergehende Fehler sollen kontrolliert erneut versucht werden; dauerhafte Fehler müssen für das Team sichtbar werden.
Benachrichtigung: Legen Sie fest, wer bei kritischen Fehlern über welchen Kanal informiert wird.
Korrektur bei Teilabschlüssen: Definieren Sie, wie ein nur teilweise abgeschlossener Vorgang über mehrere Systeme bereinigt wird.
Berechtigungen und Zugriff: Verwalten Sie API-Schlüssel, Rollen und Zugriffsprotokolle entsprechend Ihren Sicherheitsanforderungen.

Ein Test mit einer erfolgreichen Bestellung allein reicht nicht. Ergänzen Sie Fälle wie eine fehlende Adresse, eine doppelte Bestellung, einen ungültigen Produktcode, einen Timeout, eine stornierte Zahlung und eine Teilretoure. Der Abgleich von Beispieldatensätzen vor dem Produktivstart hilft, Unterschiede früh zu erkennen.

Für konsistente Produkt-, Kategorie- und Bilddaten ergänzen die Hinweise zur Inhalts- und Medienverwaltung im Leitfaden zur Optimierung von Produktbildern (auf Türkisch) die technische Planung.

Technische Fragen an den Softwareanbieter

Die Aussage „Integrationen werden unterstützt“ bedeutet nicht automatisch, dass Ihr benötigter Datenfluss bereits verfügbar ist. Mit diesen Fragen wird der Projektumfang konkreter:

Ist die API-Dokumentation aktuell und gibt es eine Testumgebung?
Welche Ressourcen sind zugänglich: Produkte, Bestände, Preise, Bestellungen, Kunden, Zahlungen oder Retouren?
Sind Lese- und Schreibrechte getrennt?
Welche Webhook-Ereignisse gibt es und wie werden Signaturen geprüft?
Welche Regeln gelten für Anfragelimits, Seitennavigation und Stapelabrufe?
Sind Fehlercodes und Fehlermeldungen dokumentiert?
Wie werden Änderungen der API-Version angekündigt?
Welche Authentifizierung wird verwendet und wie werden Zugangsschlüssel erneuert?
Sind Vorgangsprotokolle oder fehlgeschlagene Übertragungen im Verwaltungsbereich einsehbar?
Welche Einschränkungen gelten beim Löschen, Aktualisieren und Zuordnen von Daten?

Bewerten Sie die Antworten nicht nur im technischen Team, sondern auch mit den Prozessverantwortlichen aus Betrieb, Vertrieb und Finanzen.

Vorlage für einen umsetzbaren Integrationsplan

Halten Sie Ihren Plan kurz, aber so konkret, dass Entscheidungen möglich sind. Die folgende Struktur eignet sich als Ausgangspunkt für eine einzelne Anbindung ebenso wie für ein Projekt mit mehreren Systemen:

Geschäftliches Ziel: Welches operative Problem wollen Sie lösen?
Umfang: Welche Systeme, Datensätze und Vorgangstypen gehören zur ersten Phase?
Ablaufdiagramm: Was sind Auslöser, Quellsystem, Zielsystem und Abschluss?
Datenwörterbuch: Welche Feldzuordnungen, Pflichtfelder und Umwandlungsregeln gelten?
Verantwortung: Welches System ist führend und wer verantwortet den Prozess?
Technische Methode: Wo werden API, Webhook, Dateitransfer oder manuelle Freigabe eingesetzt?
Fehlerplan: Wie sind Wiederholungen, Warnungen, manuelle Eingriffe und Protokollaufbewahrung geregelt?
Test und Abnahme: Wer bestätigt erfolgreiche, fehlerhafte und außergewöhnliche Szenarien?

Dass ein Feld über die API verfügbar ist, reicht nicht aus: Ein leerer und ein unbekannter Wert können unterschiedliche Bedeutungen haben. Halten Sie diese Unterscheidung im Datenvertrag fest. Vereinbaren Sie außerdem ausdrücklich, ob ein im Quellsystem gelöschter Datensatz im Ziel gelöscht, deaktiviert oder erhalten bleibt.