Lexware Office anbinden: Zwei Anfragen pro Sekunde und kein Polling

Bei Lexware Office führt ein großer Teil der deutschen Kleinunternehmen, Freiberufler und ihrer Steuerberater die Bücher. Wenn Ihr Produkt in diesen Markt verkauft, entscheidet die Abdeckung oft darüber, ob Sie in Deutschland ausliefern oder erklären müssen, warum nicht.

Das Protokoll ist der leichte Teil: Es ist eine REST-API, und einen einzelnen Datensatz zu erreichen ist unspektakulär. Die Schwierigkeit liegt darin, dass das deutsche Buchhaltungsrecht im Datenmodell steckt und dass die Plattform sich mit Regeln schützt, die an Ihrer Architektur ansetzen und nicht an Ihren Request-Bodies.

In diesem Leitfaden geht es um diese Regeln. Wenn Sie das Datenmodell, die Authentifizierungsoptionen und die Marktplatz-Stufen an einer Stelle suchen, finden Sie das auf der Seite zur Lexware Office Schnittstelle. Hier geht es darum, wie Sie gegen die Plattform bauen, ohne in die drei Einschränkungen zu laufen, die die meisten ersten Implementierungen erwischen.

Zwei Dinge entscheiden, ob Ihre Kunden sich überhaupt verbinden können, und beide liegen außerhalb Ihres Codes: der Tarif, in dem sie sind, und Ihre eigene Beziehung zu Lexware.

Der Weg, der allen offensteht, ist die öffentliche API, authentifiziert mit einem API-Schlüssel. Lexware gibt an, dass sie ab Version XL bereitsteht; Kunden in einem kleineren Tarif haben also keinen Schlüssel, den sie Ihnen geben könnten.

Der Schlüssel wird innerhalb von Lexware Office von einem Benutzer mit Administratorrechten erzeugt, auf der Add-on-Seite der öffentlichen API. Er gehört zu diesem einen Konto, Ihre Kunden gehen also je einmal für ihre eigene Umgebung hindurch.

Es gibt einen zweiten Weg, und er öffnet sich über eine Partnerschaft mit Lexware. Das ist eine manuelle Qualifizierung mit deren Partnerteam. Sie erreicht einen größeren Satz an Endpunkten und Operationen, sie authentifiziert sich anders, und sie läuft unter einem höheren Ratenlimit.

maesn unterstützt beide Wege, die Endpunkte ebenso wie die Authentifizierung, Ihre Implementierung ändert sich also nicht mit dem Weg, auf dem Ihre Kunden landen. Die Qualifizierung führen wir gemeinsam mit Ihnen durch.

Lexware veröffentlicht das Programm selbst, einschließlich der Vorteile, die über den API-Zugang hinausgehen. In der Praxis zählen kaufmännisch vor allem zwei: Co-Marketing und ein Eintrag im Lexware-Marktplatz. maesn hat es durchlaufen: Lexware führt uns auf der eigenen Seite als Partner, und das ist für eine solche Aussage der einzige Beleg, der nicht von uns kommt.

Ein Client darf zwei Anfragen pro Sekunde senden. Die wichtige Hälfte dieses Satzes ist der Geltungsbereich: Lexware dokumentiert, dass sich das Limit auf alle Endpunkte gleichzeitig bezieht. Ein Budget deckt Ihre ganze Integration ab; je Ressource gibt es keines.

Dieses Budget gehört zum öffentlichen Weg. Eine Partnerschaft hebt es an, und das ist zu wissen, wenn Volumen der Grund ist, aus dem Sie diesen Abschnitt überhaupt lesen.

Der Mechanismus ist ein Token Bucket, und wer ihn überschreitet, bekommt 429 zurück, ohne dass der Aufruf ausgeführt wird. Lexware empfiehlt, auch auf Ihrer Seite einen Token Bucket zu betreiben, mindestens aber eine Pause zwischen aufeinanderfolgenden Aufrufen mit exponentiellem Backoff bei 429. Sie weisen außerdem darauf hin, dass schon Netzwerk-Jitter einen Client auslöst, der das Limit exakt einhält. Planen Sie deshalb unterhalb davon.

Der Autorisierungsserver hat eigene Limits, und die sind nicht veröffentlicht. Die Folge ist dort härter als ein abgewiesener Aufruf: Ein Client, der weiter sendet, wird für Sekunden bis Minuten gesperrt, und wer nicht langsamer wird, bleibt gesperrt, bis er es tut.

Wiederholverhalten, Backoff und der Unterschied zwischen einem abgewiesenen Aufruf und einem gesperrten Client sind auf jedem System, das wir unterstützen, dasselbe Problem. Genau deshalb liegt es im einheitlichen Fehlerhandling und nicht in jeder einzelnen Integration.

Lexware arbeitet mit optimistischem Sperren, ein Datensatz wird also nie gesperrt, bevor Sie ihn ändern. Dafür muss jedes PUT die version tragen, die Sie beim letzten GET dieses Datensatzes erhalten haben. Hat etwas anderes ihn zwischenzeitlich geändert, ist Ihre Version veraltet und der Schreibvorgang wird abgewiesen.

version ist schreibgeschützt und steigt bei jeder Änderung. Sie können den Wert weder berechnen noch lange zwischenspeichern, und genau das kostet Sie etwas.

Lexware ist darin deutlich. Ihr Cookbook sagt, dass das Pollen von Ressourcen zu vermeiden ist, und nennt Webhooks als den Weg, zwei Systeme im Gleichstand zu halten. Zusammen mit dem Budget von oben ist das eine Design-Vorgabe: Es gibt keine Rate, bei der Polling gleichzeitig innerhalb des Limits bleibt und die Daten frisch hält.

Nativ sendet Lexware ein Event wie invoice.status.changed an eine Callback-URL, die Sie registriert haben, mit dem Konto, der Ressourcen-ID und dem Zeitpunkt der Änderung. Fehlgeschlagene Zustellungen werden über 48 Stunden wiederholt, und Lexware empfiehlt, den Aufruf in eine Warteschlange aufzunehmen und asynchron zu verarbeiten.

Über maesn abonnieren Sie je Kunde eine Ressource und einen Event-Typ und erhalten dieselbe Form, die Sie für jedes andere System erhalten. Das ist es, was einheitliche Webhooks in der Praxis bedeuten: eine Nutzlast, ein Abo-Aufruf, was auch immer die Plattform darunter aussendet.

Zwei Dinge bleiben bei Ihnen. Das Abo wird je Kunde angelegt, ein neu verbundenes Konto bedeutet also ein neues Abo, und filterDate sowie userId kommen bei Lexware leer an. Eine vereinheitlichte Nutzlast erfindet keine Daten, die die Quelle nie gesendet hat, und eine Integration, die auf diese zwei Felder verzweigt, verzweigt hier falsch.

Ein API-Schlüssel gilt nicht dauerhaft. Lexware setzt seine Lebensdauer auf 24 Monate und erneuert ihn in derselben Schlüsselverwaltung, in der er erzeugt wurde. Eine Verbindung, die zwei Jahre lang funktioniert hat, ist damit eine Verbindung, die kurz davor ist, es nicht mehr zu tun.

Kunden können sie auch früher beenden, und dafür gibt es ein Signal. maesn sendet eine TOKEN-Ressource mit dem Event-Typ REVOKED, wenn Kunden den Zugriff zurückziehen oder das Token sich nicht mehr erneuern lässt. Ob Sie es behandeln, entscheidet darüber, ob Sie Ihren Kunden sagen, dass die Verbindung weg ist, oder es aus deren Support-Ticket erfahren.

Eine Sache lohnt es noch, von vornherein einzuplanen: Kunden können mehrere Schlüssel anlegen und einschränken, was ein Schlüssel erreichen darf. Schränken sie ihn enger ein, als Sie brauchen, scheitern Ihre Aufrufe mit 403 und nicht mit 401. Die Zugangsdaten sind gültig und die Berechtigung ist zu eng, sagen Sie also im Moment der Schlüsselerzeugung, welchen Umfang Sie benötigen. Wie sich das systemübergreifend in einen Ablauf fügt, steht bei einheitlicher Authentifizierung.

Einige Felder sind nicht optional, und sie sind aus rechtlichen Gründen verpflichtend. Drei davon erreichen Ihr eigenes Modell, ob Sie sie eingeplant haben oder nicht.

Es gibt eine zweite Ebene dessen, was bestimmte Kunden tatsächlich dürfen, und sie wird leicht falsch verstanden: Die Funktionen, die ihr Lexware-Vertrag einräumt, sind dokumentiert als orthogonal zu den Berechtigungen des Schlüssels, und sie ändern sich über die Zeit. Lexware gibt den verfügbaren Satz deshalb über den Profil-Endpunkt aus. Lesen Sie ihn aus.

Wir nehmen Ihnen die Form der Integration ab, nicht die Regeln der Plattform. Fünf Dinge bleiben bei Ihnen, und es ist billiger, das jetzt zu wissen als nach dem ersten Kundengespräch.

• Die Steuerrechnung ist Ihre. Wir liefern Sätze und Strukturen so aus, wie das System sie veröffentlicht; was Sie schulden und auf welcher Grundlage, bleibt Ihr Modell.
• Die Währungsumrechnung ist Ihre. Lexware unterstützt ausschließlich EUR, der umgerechnete Wert und der verwendete Kurs sind also Entscheidungen auf Ihrer Seite.
• Die Tarifvoraussetzung ist Lexwares. Wir können Ihnen sagen, dass es sie gibt und wo sie greift. Aufheben können wir sie für Kunden nicht, die den Tarif nicht haben.
• Die Partner-Qualifizierung ist Lexwares Entscheidung. Wir bereiten sie vor und gehen sie mit Ihnen durch; erteilen können wir sie nicht.
• Abos je Kunde bleiben je Kunde. Ein verbundenes Konto, ein Abo. Das ist das Modell der Plattform und nichts, was sich wegabstrahieren lässt.

An Anhängen sieht man diese Linie am klarsten, deshalb hier der ganze Vorgang: Ein Dokument an eine Buchung zu hängen, sind auf dieser Plattform vier Schritte. Die Transaktion anlegen, den Saldo des zugehörigen Finanzkontos aktualisieren, die Datei hochladen, dann die Datei mit der Transaktion verknüpfen. Es sind mehr als vier Aufrufe, weil die Saldo-Aktualisierung aus den Gründen von oben ein Lese- und ein Schreibvorgang ist. Gegen unseren eigenen Endpunkt ist es eine Anfrage: POST /accounting/transactions, die Transaktion als JSON und bis zu sechs Dateien im selben Multipart-Body. Den Datei-Endpunkt, die Beleg-ID, die er zurückgibt, und den Aufruf, der beide verknüpft, bekommen Sie nie zu sehen.

Drei Grenzen kommen damit, und Sie entwerfen um sie herum.

• Es endet bei einem Vorschlag. Der Aufruf, der eine Datei an eine Transaktion bindet, heißt Hinweis, und genau das tut er. Das Dokument erscheint in der Lexware-Weboberfläche als vorgeschlagen, und eine Person bestätigt es. Lexware stellt nichts Stärkeres bereit, diesen letzten Schritt kann also niemand automatisieren, wir eingeschlossen.
• Es braucht eine externe Referenz von Ihnen. Die Verknüpfung hängt an einer Referenz, die Sie mit der Transaktion mitsenden. Die zurückgelieferte ID trägt sie nicht. Keine Referenz, keine Verknüpfung.
• Es ist Best Effort, keine atomare Operation. Eine Kette von Aufrufen hat keine gemeinsame Transaktion und kein Rollback. Scheitert der Upload, nachdem die Buchung geschrieben ist, bleibt die Buchung geschrieben, und Ihr Wiederholversuch muss damit rechnen.

Eine Sache noch zum Einplanen, weil sie in keiner der beiden Dokumentationen steht. Schritt eins braucht die ID des Finanzkontos, und es gibt keinen Endpunkt, der sie auflistet. Sie können eines per ID abrufen, mehr nicht; die ID stammt also aus dem Anlegen des Kontos oder daraus, dass eine Person sie aus der Lexware-Oberfläche abliest. Achten Sie dabei auf die Benennung: Unser Accounts-Endpunkt liefert Buchungskategorien, und das ist etwas ganz anderes.