BuchhaltungsButler anbinden: Vier Ratenbegrenzungen auf 48 POST-Pfaden

Für die Anbindung braucht es drei Werte aus dem Konto Ihres Kunden: einen API Client, ein API Secret und einen API Key. Fast jede Beschreibung dieses Systems, unsere eingeschlossen, nennt sie drei Zugangsdaten und geht weiter. Die Referenz gruppiert sie anders, und der Unterschied entscheidet, wie Ihr Code für viele Konten geschnitten ist.

Unter der Überschrift Authentication wird die Referenz bei zweien davon konkret: „Die Authentifizierung erfolgt über HTTP Basic Auth nach RFC 2617. Das ist so umzusetzen, dass daraus der Request-Header ‚Authorization‘ entsteht, der den folgenden Wert enthält: ‚<Api Client>:<Api Secret>‘.“ Das ist das Paar aus Zugangsdaten, und es reist bei jeder Anfrage im Header mit.

Der dritte Wert bekommt eine eigene Überschrift, Customer Selection, und eine andere Aufgabe: „Um die API-Methoden zu nutzen, müssen Sie das BB-Kundenkonto angeben, das Sie verwalten wollen. Das geschieht über das Formularfeld ‚api_key‘, das den API-Schlüssel des Zielkunden enthält.“

Der API Key wählt das Konto aus. Er benennt, wessen Bücher Sie anfassen, und er reist im Rumpf der Anfrage mit, als Formularfeld.

Für ein Skript, das ein einziges Kundenkonto bedient, ist diese Unterscheidung Nebensache. Für ein Produkt mit tausend angebundenen Unternehmen entscheidet sie den Zuschnitt Ihres Codes: Die Auswahl gehört zur Nutzlast statt zu den Zugangsdaten im Header und muss bei jeder einzelnen Anfrage stimmen. Wer sie falsch setzt, bekommt keine 401, sondern die Bücher eines anderen.

Es gibt hier keine OAuth-Weiterleitung, also auch keine gehostete Seite, auf die Sie jemanden schicken. Ihr Kunde schaltet den Zugang in seinen eigenen Einstellungen frei, alle drei Werte erscheinen gemeinsam, und sie lassen sich aus Ihrer eigenen Oberfläche heraus übergeben.

Unified Authentication verhindert, dass daraus ein Zweig je System wird: Eine Weiterleitung beim nächsten System und ein Datenbankzugang beim übernächsten kommen am selben Account-Key an, und Ihr Code sieht immer nur den Schlüssel.

Aus der veröffentlichten Referenz gezählt: 48 verschiedene Operationen, und alle 48 sind POST. Darunter die zwölf, deren Pfad ein get-Segment trägt, die zwei, die löschen, und die vier, die aktualisieren. Was der Aufruf tut, steht im Pfad.

Es liegt nahe, das unter Kosmetik abzulegen, und es wäre ein Fehler. Ein gewöhnlicher HTTP-Client leitet drei Dinge aus der Methode ab, ohne dass man es ihm sagt: ob ein Aufruf gefahrlos zu wiederholen ist, ob eine Antwort zwischengespeichert werden darf und ob eine fehlgeschlagene Anfrage blind erneut gesendet werden kann.

Auf einer Schnittstelle, auf der Lesen und Löschen beide POST sind, trägt keine dieser Ableitungen, und jede davon ist hier je Pfad zu entscheiden.

Auch die Operationen verteilen sich ungleich, und die Verteilung sagt, wofür das Produkt da ist. Zwei Tags tragen je elf Operationen, und eines davon ist die Einstellungsoberfläche, auf der die Geschäftspartner liegen.

Das ist der Teil, der Ihre Architektur entscheidet, und es ist der Teil, den weder unsere eigene Systemseite noch der Artikel nennt, den sie ersetzt. Die Referenz veröffentlicht eine Obergrenze in einem Satz: „Es ist nur erlaubt, maximal 100 Anfragen je Kunde und Minute an die API zu stellen.“ Die Obergrenze gilt je Kunde, und das ist die gute Nachricht: Ihr hundertstes Kundenkonto bremst Ihr erstes nicht.

Die anderen drei sind leichter zu übersehen, weil sie gar nicht im Abschnitt zu den Grenzen stehen. Sie liegen als Implementierungshinweise an einzelnen Operationen, und über die Referenz gezählt sind es genau drei von 48: /receipts/upload trägt „Hinweis: maximal 10 Anfragen pro Minute“, während /receipts/addBatch und /transactions/addBatch je „Hinweis: eine Anfrage ist nur alle 5 Sekunden erlaubt“ tragen.

Hält man diese Fakten neben das, was dieses Produkt tut, zeigt sich die Form der Einschränkung. BuchhaltungsButler gibt es, um Belege aufzunehmen und daraus Buchungen zu machen, und jede Operation, die in Menge schreibt, ist unterhalb der globalen Obergrenze gedeckelt: der einzelne Upload bei einem Zehntel davon, die zwei Batch-Pfade bei je einer Anfrage alle fünf Sekunden. Die 100 pro Minute sind das Budget für das Lesen, das Schreiben hat ein eigenes und deutlich niedrigeres.

Die Migration des Altbestands eines Kunden ist deshalb nicht durch Ihre Zahl an Workern oder seinen Tarif begrenzt. Sie ist durch zehn Uploads pro Minute begrenzt, oder durch einen Stapel alle fünf Sekunden, wenn Sie diesen Weg gehen, und keine Parallelität bewegt eine der beiden Zahlen.

Es gibt hier kein Kontaktobjekt und kein Kundenobjekt. Die Geschäftspartner existieren als Debitoren und Kreditoren, und sie liegen nicht bei den Belegen, die auf sie verweisen. Alle acht Operationen, die einen Geschäftspartner lesen, anlegen und aktualisieren, liegen hinter einem settings-Pfad.

Das ist eine buchhalterische Sicht statt einer Produktsicht, und sie ist in sich stimmig: In einem System, dessen Aufgabe das Zuordnen von Belegen ist, ist ein Debitor ein Stück Konfiguration, das entscheidet, wo ein Beleg landet. Ihr Produkt hat eine andere Sicht, in der ein Kunde ein eigenständiges Objekt mit Namen und Anschrift ist.

Es ist zugleich der klarste Fall auf diesem System für das Lesen über eine normalisierte Schicht. Das Common Data Model gibt Ihnen Kunden und Lieferanten als Objekte mit denselben Feldern, die Sie auf jedem anderen angebundenen System benutzen, und dass ein Hersteller sie unter den Einstellungen führt und ein anderer unter den Kontakten, hört auf, etwas zu sein, das Ihr Code weiß.

Zwei Verhaltensweisen arbeiten hier anders als in einem Dokumentenspeicher. Beide stehen in den Hinweisen zu den Operationen, und beide ändern, was Ihr Code aushalten muss.

Die erste: Löschen löscht nicht. Die Referenz beschreibt die Operation als „einen Beleg für ein angegebenes Kundenkonto als gelöscht markieren“, und es gibt eine passende Operation, um „einen als gelöscht markierten Beleg wiederherzustellen“. Ein entfernter Beleg ist ein Zustand, und alles, was Sie schreiben und das liest, ohne diesen Zustand zu berücksichtigen, sieht ihn weiter.

Die zweite: Buchungen können unbeweglich werden. Alle drei unconfirm-Operationen, für freie Buchungen, Belegbuchungen und Transaktionsbuchungen, tragen denselben Satz: „Das funktioniert nur, wenn die Buchungssätze nicht festgeschrieben sind.“ Ist ein Buchungssatz einmal festgeschrieben, ist der Weg zurück ein neuer Buchungssatz, und das ist gewöhnliches Verhalten in der Buchhaltung und ungewöhnliches Verhalten in einer API.

Es gibt eine dritte Gewohnheit, die eine Planung wert ist, weil sie eine Anfrage kostet. Sechs Operationen identifizieren ihr Ziel über id_by_customer, und die Referenz sagt, woher man sie bekommt: „Die ‚id_by_customer‘ erhalten Sie, indem Sie zuerst die Methode ‚/receipts/get‘ benutzen.“ Ein Löschen sind deshalb zwei Aufrufe, und beide gehen von denselben hundert ab.

BuchhaltungsButler kündigt seine eigenen Änderungen nicht an, es gibt also kein Abonnement einzurichten und keinen Callback zu prüfen. Aktuell zu bleiben ist ein geplanter Abruf. Das ist eine Eigenschaft des Systems und gehört deshalb von Anfang an in die Planung.

An seine Stelle tritt ein Delta-Abruf über dieselben Filter und dasselbe Paging, die Sie überall sonst benutzen: Sie fragen, was sich seit Ihrem letzten Lauf geändert hat, und bekommen es im gemeinsamen Modell zurück. Was hier arbeitet, ist die Pull-Hälfte, die das Event-Modell ohnehin vorsieht, und auf diesem System hat die Push-Hälfte nichts, was sie füllt.

Ein Abruf hat eine Eigenschaft, die ein Push nicht hat, und auf diesem System ist sie die wichtige: Er holt auf. Fällt Ihr Worker eine Stunde aus, liefert der nächste Lauf trotzdem alles, was sich in dieser Stunde bewegt hat, und auf einer Plattform, auf der Belege stapelweise aus einer Scan-App ankommen, zählt das mehr als Latenz.

Was er kostet, sind Anfragen, und Anfragen sind das, was gedeckelt ist. Jeder Abruf wird aus denselben hundert je Kunde und Minute bezahlt wie Ihre Schreibzugriffe, das Intervall ist damit eine Budgetentscheidung. Selten lesen und ein weites Fenster abfragen ist günstiger als oft lesen und ein enges.

Die Anbindung ist hier schnell erledigt, und genau deshalb verdient der Rest Aufmerksamkeit. Was wir von der Liste nehmen:

• Die Übersetzung der Methoden. Ihr Client benutzt die gewöhnlichen REST-Methoden, und die Abbildung auf 48 POST-Pfade liegt bei uns, die drei Ableitungen, die ein HTTP-Client sonst trifft, bleiben Ihnen also erhalten.
• Die zwei Ebenen der Zugangsdaten. Das Basic-Auth-Paar und der Schlüssel je Kunde liegen bei der Verbindung, die Kontoauswahl hört also auf, etwas zu sein, das Ihr Code beim Bauen einer Anfrage falsch setzen kann. Wie das Modell der Geschäftspartner abgebildet wird, steht auf der Seite zur BuchhaltungsButler-Schnittstelle.
• Das Modell der Geschäftspartner. Debitoren und Kreditoren unter den Einstellungen kommen als Kunden und Lieferanten an, mit den Feldern, die sie auf jedem anderen System haben.

Was bei Ihnen bleibt, und das erste davon ist eine Entscheidung statt einer Aufgabe:

• Wie Sie die hundert ausgeben. Wie aktuell Ihr Produkt sein muss und was das gegen eine Obergrenze je Kunde kostet, ist eine Produktentscheidung, zu der wir beitragen können.
• Das Tempo beim Nachladen. Zehn Uploads pro Minute ist die Zahl des Herstellers, und keine Schnittstelle davor lässt den elften Upload gelingen.
• Der Nettobetrag, falls Sie einen brauchen. Das Betragsfeld eines Belegs ist hier brutto, Netto und Steuer kommen leer zurück. Eine Nettobasis abzuleiten ist Rechnen auf Ihrer Seite oder eine Frage an eine andere Quelle.
• Der Klick im Konto Ihres Kunden. Den Zugang freizuschalten und drei Werte zu kopieren ist seine Aufgabe, und das in Ihrer eigenen Oberfläche klar zu sagen, ist der Unterschied zwischen einer Verbindung und einem Support-Ticket.