Wie wir internationale Zahlungen mit der Buchhaltung verbunden haben – und wie der Prozess tatsächlich aussah.
Das Problem: zwei Systeme, die nicht miteinander kommunizieren
Schweizer KMU, die mit internationalen Lieferanten und Kunden arbeiten, kennen das Problem: amnis wickelt Zahlungen in mehreren Währungen hervorragend ab, Xero führt die Bücher präzise – aber die beiden Systeme kommunizieren nicht miteinander.
Das Ergebnis? Finanzteams, die Transaktionen manuell eingeben, Zahlungen von Hand abgleichen und Stunden mit Arbeit verbringen, die eigentlich die Software erledigen sollte.
Wir haben uns daran gemacht, eine echte amnis-Xero-Integration zu entwickeln – keine provisorische Notlösung, sondern einen robusten, produktionsreifen Konnektor, der mit Mehrwährungs-Komplexität umgehen kann, auf mehrere Kunden skaliert und bei Fehlern sauber abbricht.
Die APIs verstehen
Sowohl amnis als auch Xero bieten REST-APIs mit OAuth 2.0-Authentifizierung an – aber in der Praxis verhalten sie sich ziemlich unterschiedlich.
Die amnis-API ist gut dokumentiert und unkompliziert. Die wichtigsten Schnittstellen, die wir gebraucht haben:
- Transaktions-Schnittstelle – ruft abgeschlossene Zahlungen, eingehende Überweisungen und Kartenausgaben ab
- Konten-Schnittstelle – liefert Salden in mehreren Währungen und IBAN-Details
- Wechselkurs-Schnittstelle – für eine genaue Nachverfolgung historischer Umrechnungen
Token-Management war von Anfang an notwendig, da die API Refresh-Tokens verwendet.
Die Xero-API ist ausgereifter, aber auch komplexer. Wir haben uns auf folgende Bereiche konzentriert:
- Banktransaktionen – Erstellen von Aus- und Zahlungseingängen
- Bankkonten – Zuordnung von amnis-Konten zu Xero-Bankkonten
- Kontakte – Abgleichen oder Anlegen von Lieferanten- und Kundendatensätzen
- Tracking-Kategorien – Kostenstellen- und Projektzuordnung
Der wichtigste Knackpunkt: Xero-Tokens verfallen nach 30 Minuten, was eine robuste Handhabung der Token-Aktualisierung entscheidend macht – besonders bei Hintergrundprozessen.
Zwei unterschiedliche Datenmodelle verbinden
Hier wurde es wirklich interessant. amnis und Xero modellieren Finanzdaten grundlegend unterschiedlich.
| Konzept | amnis | Xero |
|---|---|---|
| Währungshandling | Native Multi-Currency-Konten | Eine Basiswährung mit FX-Umrechnung |
| Transaktionsarten | Flache Struktur mit Typfeld | Separate Endpunkte pro Typ |
| Kategorisierung | Minimal | Umfangreicher Kontenplan |
| Kontakte | Grundlegende Geschäftspartner-Infos | Vollständige Kontaktdatensätze mit Historie |
Wir brauchten eine Übersetzungsschicht, die diese Modelle aufeinander abbilden kann – mit Wahrung der Datenintegrität und Behandlung von Grenzfällen, nicht nur des Idealfalls.
Entwicklungsansatz: KI-gestütztes API-Mapping
Einer der nützlichsten Aspekte dieses Projekts war der Einsatz von KI-Automatisierung, um die API-Mapping-Arbeit zu beschleunigen – etwas, das normalerweise tagelange Entwicklerzeit frisst.
Wir haben beide API-Spezifikationen in Claude eingegeben und das System gebeten, folgende Punkte zu identifizieren: übereinstimmende Felder zwischen den beiden Systemen, erforderliche Transformationen (Datentypen, Formate, Enums), Grenzfälle und potenzielle Datenverlustpunkte sowie fehlende Felder, die Standardwerte oder Benutzereingaben benötigen.
So hatten wir innerhalb von Stunden statt Tagen ein solides erstes Mapping.
Für die repetitive Arbeit beim Schreiben von Transformationsfunktionen haben wir KI-Unterstützung genutzt, um erste Implementierungen zu generieren. Der Schlüssel dabei: die KI-Ausgabe als Ausgangspunkt zu betrachten, nicht als fertiges Produkt – jede generierte Funktion durchlief weiterhin Code-Review, Tests für Grenzfälle und Produktionsvorbereitung.
Architektur: Background-Workers und eine einheitliche Pipeline
Echtzeit-Synchronisierung war hier nicht sinnvoll. amnis-Transaktionen brauchen Zeit zur Abwicklung, Xero hat Rate Limits, und wir brauchten eine saubere Fehlerbehandlung. Eine Background-Worker-Architektur hat mehr Sinn ergeben.
Jeder Synchronisierungslauf folgt derselben sechsstufigen Pipeline:
- Abrufen – neue Transaktionen seit der letzten Synchronisierung von amnis holen
- Umwandeln – in das Xero-Format umwandeln, Kontakte abgleichen, Konten zuordnen
- Überprüfen – Daten auf Vollständigkeit prüfen, Anomalien markieren
- Übertragen – Transaktionen in Xero über die API erstellen
- Bestätigen – Erstellung bestätigen, Xero-Transaktions-IDs speichern
- Protokollieren – Synchronisierungsergebnisse, Zeitpunkte und etwaige Probleme aufzeichnen
Idempotenz war durchgehend entscheidend. Denselben Sync zweimal auszuführen darf keine doppelten Transaktionen erzeugen. Wir haben das folgendermassen gelöst:
- Transaktions-Fingerprinting – jede amnis-Transaktion erhält einen deterministischen Hash
- Sync-Status-Tracking – wir protokollieren, welche Transaktionen erfolgreich übertragen wurden
- Xero-Referenzabgleich, bevor neue Datensätze erstellt werden
Fehlerbehandlung: für die Realität entworfen
Es kann immer etwas schiefgehen. APIs laufen ab, Tokens verfallen, Daten sind fehlerhaft, Rate Limits werden erreicht. Wir haben Fehler in vier Kategorien eingeteilt, die jeweils eine andere Reaktion auslösen:
| Kategorie | Beispiele | Reaktion |
|---|---|---|
| Vorübergehend | Netzwerk-Timeout, 503-Fehler, Rate Limits | Wiederholen mit exponentiellem Backoff |
| Authentifizierung | Abgelaufenes Token, widerrufener Zugriff | Token aktualisieren, bei Fehlschlag warnen |
| Daten | Fehlendes Pflichtfeld, ungültiges Format | Transaktion überspringen, zur Überprüfung markieren |
| System | Datenbank ausgefallen, Worker-Absturz | Sofort warnen, Verarbeitung pausieren |
Bei vorübergehenden Fehlern verwenden wir exponentielles Backoff mit Jitter: 1 Minute, dann 5, dann 30, dann 2 Stunden. Nach vier Fehlversuchen wird die Transaktion als fehlgeschlagen markiert und zur manuellen Überprüfung gekennzeichnet.
Benachrichtigungen laufen über drei Kanäle – Slack für kritische Echtzeit-Warnungen und tägliche Sync-Zusammenfassungen, E-Mail-Digests für nicht dringende Wochenberichte und In-App-Dashboard-Warnungen für Tenant-Admins.
Frontend für die Multi-Tenant-Verwaltung
Da diese Tool-Integration mehrere Kunden über eine einzige Oberfläche bedienen musste, haben wir ein Management-Frontend entwickelt, das Konfiguration und Monitoring für alle Tenants abdeckt.
Das Tenant-Onboarding umfasst:
- OAuth-Verbindungsabläufe für amnis und Xero
- Kontenzuordnung (welche amnis-Konten welchen Xero-Bankkonten zugeordnet werden)
- Standard-Kategorisierungsregeln
- Einstellungen für den Kontaktabgleich
Das Monitoring-Dashboard zeigt:
- Sync-Status – letzte erfolgreiche Synchronisierung, ausstehende Transaktionen, Fehleranzahl
- Transaktionsvolumen – tägliche, wöchentliche und monatliche Transaktionsanzahl und -werte
- Zustandsindikatoren wie API-Konnektivität, Token-Status und Verarbeitungslatenz
Jeder Tenant erhält zudem konfigurierbare Einstellungen:
- Synchronisierungshäufigkeit – wie oft neue Transaktionen abgerufen werden
- Kategorisierungsregeln basierend auf Gegenparteien oder Beschreibungsmustern
- Benachrichtigungseinstellungen – wer wird wann benachrichtigt
- Schwellenwerte für die manuelle Überprüfung bei grossen oder ungewöhnlichen Transaktionen
Jede Aktion wird protokolliert – Konfigurationsänderungen, manuelle Eingriffe, Sync-Läufe, Fehler und deren Behebung. Dieser Prüfpfad hat sich als unverzichtbar erwiesen, nicht nur für die Fehlersuche, sondern auch für Kunden, die ihre Buchhaltungsprozesse gegenüber externen Prüfern erklären müssen.
Was wir gelernt haben
API-Dokumentation ist manchmal irreführend
Bei beiden APIs gab es Fälle, in denen das tatsächliche Verhalten von der Dokumentation abwich. Wir haben gelernt, Integrationstests mehr zu vertrauen als der Dokumentation – und defensive Prüfungen für unerwartete Antworten einzubauen.
Währungsumrechnung ist wirklich knifflig
Was passiert, wenn eine EUR-Zahlung auf einem CHF-Konto eingeht? Welchen Wechselkurs verwendest du – den von amnis oder den von Xero? Und was ist mit zeitlichen Abweichungen zwischen Transaktionsdatum und Valutadatum? Wir haben viel Zeit damit verbracht, das hinzubekommen – und die Grenzfälle hörten nicht auf.
Observability lohnt sich
Wenn um 2 Uhr morgens etwas schiefgeht, willst du das Problem anhand der Logs diagnostizieren, ohne es reproduzieren zu müssen. Wir protokollieren jeden API-Aufruf, jede Transformationsentscheidung, jeden Fehler – mit genug Kontext, um zu verstehen, was passiert ist. Das hat sich immer wieder ausgezahlt.
Nutzer haben bestehende Workflows
Die Integration existiert nicht im Vakuum. Finanzteams haben Genehmigungsprozesse und Berichtsanforderungen, die schon lange vor deinem Konnektor bestanden haben. Diese Workflows zu verstehen und sich in sie einzufügen – anstatt sie zu stören – ist genauso wichtig wie die technische Umsetzung.
Ergebnisse
Die Integration verarbeitet heute Tausende von Transaktionen pro Monat über mehrere Tenants hinweg. Die wichtigsten Ergebnisse:
- Zeitersparnis – Finanzteams berichten von 5–10 Stunden Ersparnis pro Woche bei der manuellen Dateneingabe
- Fehlerreduzierung – Abgleichabweichungen sind auf nahezu null gesunken, verglichen mit einer Fehlerquote von 3–5 % bei manueller Eingabe
- Echtzeit-Transparenz – die Buchhaltung ist innerhalb von 15 Minuten nach Zahlungsabschluss aktuell
- Skalierbarkeit – einen neuen Tenant hinzuzufügen dauert Minuten, nicht Tage
Was als Nächstes kommt
Wir verbessern die Integration laufend: mit intelligenterer Kategorisierung (auf Basis von Mustern aus der Transaktionshistorie für die automatische Kontenzuordnung), vorausschauenden Warnmeldungen bei ungewöhnlichen Transaktionen und einer erweiterten Abstimmung, die amnis-Transaktionen mit Xero-Rechnungen abgleicht, um Zahlungen automatisch zuzuordnen.
Wenn du mit isolierten Business-Tools und manueller Dateneingabe zwischen Systemen zu kämpfen hast, ist genau das die Art von Integration, die wir entwickeln. Schau dir unsere Tools Integration Services an, um zu sehen, wie wir Plattformen wie amnis und Xero miteinander verbinden – und wie das für dein Setup aussehen könnte.
