API-Integration: Best Practices aus der Praxis

Eine gute API-Integration beruht auf sechs Gewohnheiten: festlegen, welches System welche Daten besitzt, das passende Muster wählen, jede Verbindung absichern, mit Fehlern rechnen, geschäftliche Ergebnisse statt Serverstatus überwachen und alles schriftlich festhalten. Dieser Leitfaden zeigt, wie Sie jede dieser Gewohnheiten anwenden, und was sich ändert, wenn eines der Systeme ein ERP ist und die Daten Schweizer Vorgaben unterliegen.

Kurzfassung

• Legen Sie für jedes Datenobjekt (Kunde, Rechnung, Lagerbestand) ein führendes System fest, bevor Sie eine Zeile Code schreiben.
• Wählen Sie das Muster passend zur Aufgabe: Anfrage-Antwort für Abfragen in Echtzeit, Webhooks für Ereignisse, Stapelverarbeitung für Volumen und feste Zeitpläne.
• Betrachten Sie Fehler als Normalfall: Idempotenzschlüssel, Wiederholungen mit wachsendem Abstand und eine einsehbare Warteschlange.
• Sichern Sie mit minimalen Berechtigungen, sicher abgelegten Zugangsdaten und einem API-Gateway. In der Schweiz kommen bei Personendaten rechtliche Pflichten dazu.
• Überwachen Sie Ergebnisse (Bestellungen, die nie im ERP ankamen), nicht bloss die Verfügbarkeit, und dokumentieren Sie die Integration für alle, die sie später betreuen.

Was API-Integration in der Praxis bedeutet

Eine API (Programmierschnittstelle) lässt eine Software standardisiert mit einer anderen sprechen, damit Daten automatisch fliessen statt neu getippt zu werden. Swiss Innovation Hub describes it als Weg, Datensilos und manuelle Erfassung zu beseitigen. Für ein Unternehmen heisst das meist: ein Webshop, der Bestellungen ins ERP überträgt, ein CRM, das neue Leads aus einem Formular erhält, oder eine Buchhaltungslösung, die Rechnungen ohne Zwischenschritt übernimmt.

Der Code für den Aufruf ist der kleinste Teil. Die meisten Integrationen scheitern an unklaren Entscheidungen, die vorher getroffen wurden: Wem gehören die Daten, was passiert bei einem abgelehnten Datensatz, wer wird informiert. Die folgenden Praktiken folgen der Reihenfolge, in der diese Entscheidungen anfallen.

Mit den Anforderungen beginnen, nicht mit Endpunkten

Bevor Sie eine Dokumentation lesen, halten Sie in einfacher Sprache fest, was passieren soll. Eine brauchbare Anforderungsnotiz beantwortet fünf Fragen:

1. Welches Ereignis löst den Ablauf aus? Eine bezahlte Bestellung, ein neuer Kontakt, ein geänderter Preis.
2. Welche Felder wandern, und in welche Richtung? Abgleich in eine oder in beide Richtungen sind sehr unterschiedliche Projekte.
3. Welches System ist für welches Feld die Wahrheit? Wenn beide die Adresse einer Kundin ändern können, haben Sie den Konflikt bereits eingebaut.
4. Wie schnell müssen die Daten ankommen? In Sekunden, Minuten oder über Nacht.
5. Was geschieht im Fehlerfall, und wer erfährt davon?

Die übliche Reihenfolge der Planung: Anforderungen definieren, die Dokumentation des Anbieters lesen, in einer Testumgebung bauen und prüfen, die Fehlerbehandlung entwerfen und das Ergebnis dokumentieren, so outlined by Merge. Den ersten Schritt zu überspringen ist der häufigste Grund, warum Projekte auf halbem Weg neu gebaut werden.

Die Grenzen des Anbieters früh prüfen

Prüfen Sie Aufruflimits, Seitenaufteilung, Anmeldeverfahren, Versionspolitik und das Vorhandensein einer Testumgebung, bevor Sie sich auf ein Design festlegen. Ein System mit 60 Aufrufen pro Minute lässt sich nicht mit einem Design bedienen, das bei einem Import von 20'000 Artikeln pro Position einen Aufruf absetzt. In der ersten Woche kostet diese Erkenntnis einen Nachmittag, beim Start kostet sie einen Neuentwurf.

Das richtige Integrationsmuster wählen

Drei Muster decken die meisten geschäftlichen Bedürfnisse ab, wie Gusto’s developer guide zusammenfasst: synchrone Anfrage-Antwort, ereignisgesteuerte Webhooks und Stapelverarbeitung.

Muster	Funktionsweise	Geeignet, wenn	Achten Sie auf
Anfrage-Antwort	Ihr System ruft die API auf und wartet auf die Antwort	Sie sofort ein Ergebnis brauchen: Preisabfrage, Adressprüfung, Zahlungsfreigabe	Die Nutzerin wartet, wenn das andere System langsam oder ausgefallen ist
Webhook (ereignisgesteuert)	Das andere System ruft Sie auf, wenn etwas passiert	Sie auf Änderungen reagieren: Bestellung bezahlt, Ticket geschlossen, Abo gekündigt	Ereignisse können doppelt, verspätet oder in falscher Reihenfolge eintreffen
Stapelverarbeitung	Ein geplanter Lauf bewegt viele Datensätze auf einmal	Grosse Mengen oder nicht dringende Daten: nächtliche Bestände, monatliche Auswertungen	Zwischen den Läufen sind Daten veraltet; ein fehlerhafter Datensatz kann eine ganze Datei blockieren

Die meisten echten Integrationen mischen diese Muster. Ein Shop prüft den Bestand beim Bezahlen mit einer Live-Abfrage, erhält Versandmeldungen über Webhooks und gleicht Buchhaltungsdaten nachts im Stapel ab.

Orchestrierung oder Choreografie

Wenn mehrere Systeme an einem Prozess beteiligt sind, gibt es zwei Arten der Koordination. Bei der Orchestrierung ruft eine zentrale Komponente jeden Schritt der Reihe nach auf und entscheidet, was im Fehlerfall geschieht. Bei der Choreografie reagiert jedes System auf Ereignisse und erledigt seinen Teil selbst. Die Entwickler von Gusto empfehlen Orchestrierung für komplexe, voneinander abhängige Abläufe und Choreografie für parallele, unabhängige Aufgaben. Für ein kleines Team ist Orchestrierung meist leichter nachzuvollziehen und zu analysieren, weil der ganze Ablauf an einem Ort liegt. Wählen Sie Choreografie, wenn die Schritte wirklich unabhängig voneinander sind.

Vom ersten Tag an für den Fehlerfall entwerfen

Netzwerke brechen ab, Anbieter liefern Fehler aus und Warteschlangen laufen voll. Eine Integration, die nur funktioniert, wenn alles funktioniert, ist eine Demo. Vier Techniken machen den Unterschied.

Idempotenz

Wird eine Anfrage wiederholt, darf keine zweite Rechnung entstehen und keine doppelte Belastung erfolgen. HTTP bezeichnet einige Methoden als idempotent, das heisst, wiederholte identische Anfragen haben dieselbe Wirkung wie eine einzige; RFC 9110 sets this out. Datensätze werden typischerweise per POST angelegt, und POST ist standardmässig nicht idempotent. Wichtige Schreibvorgänge sollten deshalb eine eindeutige Kennung (einen Idempotenzschlüssel) mitführen, an der das empfangende System Duplikate erkennt und ignoriert. Erzeugen Sie den Schlüssel einmal pro Geschäftsvorfall, nicht einmal pro Versuch.

Wiederholungen mit wachsendem Abstand

Wiederholen Sie vorübergehende Fehler (Zeitüberschreitungen, Antworten 429 und 5xx), warten Sie nach jedem Fehlversuch länger und fügen Sie etwas Zufall hinzu, damit nicht viele Clients im selben Moment erneut anfragen. Wiederholen Sie keine Fehler, die nie erfolgreich sein werden, etwa ein abgelehntes Feld oder eine fehlende Berechtigung. Diese gehören in eine Prüfliste.

Schutzschalter und Warteschlangen

Ist ein nachgelagertes System ausgefallen, hören Sie auf, es zu bombardieren. Ein Schutzschalter pausiert die Aufrufe nach wiederholten Fehlern und prüft später erneut. Legen Sie ausgehende Aufgaben in eine Warteschlange, damit ein einstündiger Ausfall beim Anbieter eine Verzögerung bedeutet und keine verlorenen Bestellungen.

An der Schnittstelle prüfen

Kontrollieren Sie eingehende Daten, bevor sie Ihr Kernsystem erreichen: Pflichtfelder, Formate, Längen, erlaubte Werte. Weisen Sie fehlerhafte Datensätze mit klarer Begründung ab oder stellen Sie sie zurück, und lassen Sie nie eine fehlerhafte Zeile einen ganzen Stapel zerstören.

Jede Verbindung absichern

Eine Integration ist eine dauerhaft offene Tür zwischen zwei Systemen, oft mit weitreichenden Berechtigungen. Behandeln Sie sie wie ein Benutzerkonto mit sehr langer Lebensdauer.

• Richtige Anmeldung verwenden. Bevorzugen Sie OAuth 2.0, wo der Anbieter es unterstützt, sonst API-Schlüssel, die Sie wechseln können.
• Minimale Rechte vergeben. Wenn die Integration nur Bestellungen liest, darf sie keine Kunden löschen können.
• Zugangsdaten sicher ablegen. Schlüssel gehören in eine Geheimnisverwaltung oder eine verschlüsselte Umgebungskonfiguration, nie in Quellcode, Tickets oder Chats.
• Aufrufe begrenzen und protokollieren. Halten Sie fest, wer was aufgerufen hat, mit einer Korrelations-ID, die eine Anfrage über Systeme hinweg begleitet, damit Sie ein Problem lückenlos nachverfolgen können.
• Ein Gateway davorschalten. Die API architecture for the federal administration der Schweizerischen Bundeskanzlei empfiehlt ein API-Gateway zwischen Clients und Backend-Diensten, um die Kommunikation zu vermitteln und den Zugriff zu steuern, und verlangt ein Identitäts- und Zugriffsmanagement für Partner-APIs und registrierte öffentliche APIs. Dieselbe Logik gilt für ein privates Unternehmen, das Partnern Endpunkte bereitstellt.

Eine konkrete Liste dessen, was Angreifer bei APIs ins Visier nehmen, etwa fehlerhafte Objektberechtigungen, liefert die OWASP API Security Top 10, die Referenz für Sicherheitsteams. Wenn Sie Ihre Massnahmen zusätzlich gegenüber Prüfstellen oder Kundinnen belegen müssen, hilft eine Plattform wie Guardiso’s security and compliance tools dabei, Nachweise zu Zugriffssteuerung und Umgang mit Zugangsdaten gemeinsam mit Normen wie ISO 27001 zu verwalten.

Schweizer Pflichten zum Datenschutz

Bewegt eine Integration Personendaten wie Kundennamen, Adressen oder Bestellhistorie, gilt Schweizer Recht. Nach der Data Protection Ordinance (SR 235.11) müssen Verantwortliche und Auftragsbearbeiter technische und organisatorische Massnahmen treffen, die dem Risiko angemessen sind und Vertraulichkeit, Verfügbarkeit, Integrität und Nachvollziehbarkeit schützen. Bei automatisierter Bearbeitung gehören dazu eine Zugriffssteuerung, damit berechtigte Personen nur die benötigten Daten erreichen, sowie der Umgang mit Störungen samt rascher Wiederherstellung. In der Praxis entspricht das genau den minimalen Rechten, den Protokollen und der oben beschriebenen Fehlerbehandlung. Für Ihren konkreten Fall, etwa Daten an einen Anbieter im Ausland, fragen Sie Ihre Datenschutzberatung oder Ihre Rechtsberatung.

Ergebnisse überwachen, nicht nur Server

Eine grüne Statusseite beweist nicht, dass Daten fliessen. Eine Integration kann «verfügbar» sein, während jede dritte Bestellung abgelehnt wird, weil sich ein Feld geändert hat. Verfolgen Sie beide Ebenen:

• Technisch: Fehlerquoten, Antwortzeiten, Anzahl Wiederholungen, Länge der Warteschlange, fehlgeschlagene Anmeldungen.
• Geschäftlich: freigegebene Bestellungen, die nie im ERP ankamen, fehlende Sendungsnummern, nicht zugeordnete Produkte, Bestandsabweichungen und Transaktionen, die in einer Warteschlange hängen, also jene Prüfungen, die Midrocket’s integration guide auflistet.

Schicken Sie Meldungen an eine Person mit klarer Verantwortung, nicht an ein geteiltes Postfach, das niemand liest. Ergänzen Sie einen täglichen oder wöchentlichen Abgleich, der Mengen zwischen den Systemen vergleicht (Bestellungen im Shop gegenüber Bestellungen im ERP). So finden Sie die Fehler, für die niemand eine Meldung eingerichtet hat.

Die Schnittstelle dokumentieren und versionieren

Halten Sie fest, was die Integration sendet, empfängt, voraussetzt und im Fehlerfall tut. Dazu gehören Feldzuordnungen, Einrichtung der Anmeldung, Regeln für Wiederholungen, die verantwortliche Person je System und eine Anleitung für die drei wahrscheinlichsten Fehler. Dokumentation erlaubt einer anderen Entwicklerin, am Montag um 8 Uhr zu analysieren, ohne die Person anzurufen, die es gebaut hat.

Versionieren Sie auch Ihre eigenen Schnittstellen. Wenn Sie ein Feld ändern, führen Sie eine neue Version ein und geben Sie den Nutzenden Zeit für den Wechsel, statt sie über Nacht lahmzulegen. Und verfolgen Sie die Abkündigungen des Anbieters: Die meisten Ausfälle nach dem Start sind keine Programmfehler, sondern ein Anbieter, der still und leise eine alte Version abschaltet.

ERP-Integration: Wo Projekte meist stolpern

Eine ERP-Integration folgt denselben Praktiken, doch es steht mehr auf dem Spiel, weil im ERP die Finanzdaten liegen. Die wiederkehrenden Probleme sind immer dieselben:

• Unklare Zuständigkeit für gemeinsame Daten. Kunden-, Produkt- und Preisdaten liegen oft an drei Orten, und niemand hat entschieden, welcher gewinnt.
• Schwache Datenzuordnung. Unterschiedliche Formate für Namen, Einheiten, Steuercodes und Kostenstellen erzeugen Duplikate und Fehlbuchungen. In Schweizer Installationen sind fest einprogrammierte Mehrwertsteuersätze und uneinheitliche Kundennamen die Klassiker.
• Keine Kontrollen für Fehler und Duplikate. Ohne Idempotenz kann eine Wiederholung eine Rechnung zweimal buchen.
• Mangelnde Sichtbarkeit. Verzögerte oder abgelehnte Transaktionen bleiben bis zum Monatsabschluss unbemerkt.
• Kein Plan für Veränderungen. Eine Seite aktualisiert, und die Integration bricht stillschweigend.

SAP weist darauf hin, dass die manuelle Verwaltung von APIs bei wachsender Anwendungszahl creates complex, hard-to-maintain code, und dass moderne Cloud-ERP-Systeme vorkonfigurierte Konnektoren und Integrationsplattformen (iPaaS) für skalierbarere und sicherere Anbindungen bieten. Wo ein fertiger Konnektor existiert und Ihren Fall abdeckt, nutzen Sie ihn; eigener Code ist für das da, was Konnektoren nicht können.

So vermeiden Sie diese Probleme

1. Zeichnen Sie den Ablauf und die Zuständigkeit je Objekt auf, bevor Sie Werkzeuge auswählen.
2. Halten Sie die Integrationslogik ausserhalb des ERP. Legen Sie Umwandlungen in eine eigene Schicht, damit ein ERP-Update nicht bedeutet, Geschäftsregeln neu zu schreiben, und damit Sie ein angebundenes System tauschen können, ohne das ERP anzufassen.
3. Prüfen Sie mit echten Daten, bevor Sie automatisieren. Lassen Sie einen ersten Stapel echter Rechnungen oder Bestellungen durchlaufen und jemanden aus der Buchhaltung jede einzelne gegen die Quelle kontrollieren. Anhalten und prüfen ist besser, als Hunderte Fehlbuchungen zu bereinigen.
4. Bauen Sie Fehlerkontrollen ein: Idempotenz, eine Warteschlange für abgelehnte Datensätze und klare Fehlermeldungen, welche die Buchhaltung lesen kann.
5. Überwachen Sie geschäftliche Ergebnisse wie oben beschrieben.

Schweizer Standards, die Sie kennen sollten

Manche Schweizer Integrationen werden von offiziellen Standards geprägt. Der eBilanz standard from Swissdec nutzt die Taxonomie XBRL-CH und das Format eCH-0276 für die elektronische Übermittlung der Jahresrechnung von Unternehmen an die Steuerbehörden. Swissdec hat zudem am 6. März 2026 published new major versions seiner Standards veröffentlicht (ELM 6.0, KLE 2.0, EO-Standard 1.0 und eBilanz 1.0), mit Richtlinien gültig ab 1. April 2026. Wenn Ihre Lohn- oder Buchhaltungssoftware diese Kanäle bedient, klären Sie mit Ihrem Softwareanbieter, welche Version zertifiziert ist, und planen Sie die Aktualisierung, statt sie zum Jahresende zu entdecken.

Checkliste vor dem Start

Gehen Sie diese Liste durch, bevor eine Integration produktiv geht.

Bereich	Zu beantwortende Frage
Zuständigkeit	Gibt es pro Datenobjekt ein führendes System, und ist es festgehalten?
Muster	Passt das Muster (Live-Aufruf, Webhook, Stapel) dazu, wie schnell die Daten wirklich gebraucht werden?
Grenzen	Sind Aufruflimits, Seitenaufteilung und Versionspolitik jeder API berücksichtigt?
Sicherheit	Sind Berechtigungen minimal, Zugangsdaten sicher abgelegt, Schlüssel wechselbar und Aufrufe protokolliert?
Datenschutz	Wissen Sie, welche Personendaten fliessen, wohin sie gehen und wer verantwortlich ist?
Fehlerfall	Sind Wiederholungen sicher (Idempotenz), und landen abgelehnte Datensätze an einem sichtbaren Ort?
Überwachung	Decken die Meldungen geschäftliche Ergebnisse ab, mit einer namentlich verantwortlichen Person?
Prüfung	Wurde in einer Testumgebung und mit einem kleinen Stapel echter Daten geprüft?
Dokumentation	Könnte eine andere Fachperson den Fehler beheben, ohne die Autorin zu fragen?
Veränderung	Wer beobachtet Abkündigungen der Anbieter und Zeitpläne für ERP-Updates?

Wann Sie Unterstützung holen sollten

Eine einzelne Verbindung zwischen zwei gut dokumentierten Werkzeugen ist eine vernünftige Aufgabe für das eigene Team. Unterstützung lohnt sich, wenn die Integration ein ERP oder Finanzdaten berührt, wenn mehrere Systeme dieselben Datensätze teilen oder wenn das alte System keine brauchbare API hat und zuerst migriert werden muss.

Bei Ampersand bleiben erfahrene Entwickler:innen vom ersten Gespräch bis zur Übergabe am Projekt. So ist die Person, die Ihre Anforderungen versteht, auch jene, welche die Integration baut und dokumentiert. Wir arbeiten an Systemintegrationen und API-Anbindungen für Shops, CRM und ERP sowie an Migrationen von Altsystemen und laufender Betreuung. Unsere Preisübersicht listet die Optionen auf, darunter einzelne Verbindungen und ganze Integrationspakete. Unser Plan «Run & monitor» für die laufende Überwachung kostet CHF 750 pro Monat, unser Beratungsplan «Guidance» CHF 799 pro Monat. Wenn Sie unsicher sind, welches Muster oder Setup zu Ihnen passt, beginnen Sie dort.

Häufige Fragen

Was sind die wichtigsten Best Practices für API-Integrationen?

Legen Sie fest, welches System welche Daten besitzt, wählen Sie ein Muster, das zu den zeitlichen Anforderungen passt, und sichern Sie den Zugriff mit minimalen Rechten. Machen Sie dann Schreibvorgänge mit Idempotenzschlüsseln gefahrlos wiederholbar, überwachen Sie geschäftliche Ergebnisse und dokumentieren Sie die Integration. Damit decken Sie die meisten Fehler ab, die nach dem Start auftreten.

Welches Integrationsmuster soll ich verwenden?

Nutzen Sie Anfrage-Antwort, wenn eine Person oder ein Prozess sofort eine Antwort braucht. Nutzen Sie Webhooks, wenn Sie auf Ereignisse reagieren wollen, ohne laufend abzufragen, und die Stapelverarbeitung für grosse oder geplante Übertragungen, bei denen eine Verzögerung vertretbar ist. Die meisten geschäftlichen Integrationen kombinieren zwei oder drei davon.

Was sind die grössten Herausforderungen bei der ERP-Integration?

Unklare Zuständigkeit für Daten, schwache Feldzuordnung, fehlende Kontrollen für Duplikate und Fehler sowie mangelnde Sichtbarkeit abgelehnter Transaktionen verursachen die meisten Probleme. Danach folgt ein fehlender Plan für Änderungen an Anwendungen oder APIs. Zuständigkeit und Zuordnung vor dem Bauen zu klären, verhindert das meiste davon.

Gilt das Schweizer Datenschutzrecht auch für API-Integrationen?

Ja, sobald eine Integration Personendaten bearbeitet. Die Datenschutzverordnung verlangt technische und organisatorische Massnahmen, die dem Risiko angemessen sind und Vertraulichkeit, Verfügbarkeit, Integrität und Nachvollziehbarkeit abdecken. Ihre Datenschutzberatung kann bestätigen, was für Ihre Datenflüsse gilt.

Woran erkenne ich nach dem Start, dass eine Integration funktioniert?

Verfolgen Sie geschäftliche Ergebnisse, etwa Bestellungen, die nicht im ERP ankamen, oder Lagerbestände, die sich zwischen den Systemen unterscheiden, zusätzlich zu technischen Kennzahlen. Ein geplanter Abgleich zwischen beiden Systemen findet Probleme, die keine Meldung erfasst.

Quellen

• Swiss Innovation Hub describes it
• outlined by Merge
• Gusto’s developer guide
• RFC 9110 sets this out
• API architecture for the federal administration
• OWASP API Security Top 10
• Data Protection Ordinance (SR 235.11)
• Midrocket’s integration guide
• creates complex, hard-to-maintain code
• eBilanz standard from Swissdec
• published new major versions