Moneybird anbinden: Versionen entscheiden, was sich geändert hat

Die Verbindung zu Moneybird ist die gewöhnliche Hälfte. Sie registrieren eine Anwendung, Ihr Kunde autorisiert sie, und Sie halten ein Bearer-Token. Moneybird bietet ein persönliches Token als Abkürzung an und beschreibt dessen Reichweite unumwunden: Es „ähnelt einem Passwort und gewährt Zugang zu Ihrem gesamten Firmenkonto“. Für alles, in dem Kunden stecken, ist der OAuth-Weg der richtige.

Zwei Details dieses Flusses prägen, was Sie danach bauen. Das erste ist, wer zustimmen darf: Moneybird hält fest, dass der Benutzer Eigentümer der Verwaltung sein sollte, die Zustimmung kann also kein beliebiger Kollege geben. Das zweite ist, wem zugerechnet wird, was danach passiert.

Bei der Autorisierung „erzeugt Moneybird einen speziellen API-Benutzer“, und „alle Aktionen Ihrer Anwendung werden nach der Anwendung benannt, die Sie registriert haben“. Ihre Schreibvorgänge erscheinen in der Historie des Kunden unter dem Namen Ihres Produkts und nicht unter der Person, die es verbunden hat, was meistens das Gewünschte ist und immer gut zu wissen, bevor ein Supportgespräch darüber geführt wird.

Zwischen dem Token und dem ersten nützlichen Aufruf steht noch eines: eine Verwaltungs-ID. Sie ist Teil jedes Pfades, und ein Kunde kann mehrere haben. Über uns gehört diese Auswahl zum Verbindungsfluss, Sie sammeln sie also nicht als Feld ein, denn Moneybird gehört zu den Systemen, bei denen der interaktive Fluss die Wahl speichert und bei späteren Anfragen wieder einsetzt.

Sie müssen diesen Weg nicht nehmen. Den Auswahlschritt gibt es, damit Ihr Kunde die Verwaltung einmal festlegt, Sie können ihn aber überspringen und die Firma bei jedem Aufruf benennen, und das ist der Weg, wenn Ihr eigenes Produkt schon weiß, welche Verwaltung es meint. Beide Wege enden am selben Konto-Schlüssel, und die Wahl liegt bei Ihnen.

Welche Objekte eine Verbindung erreicht, Feld für Feld, steht auf der Seite zur Moneybird Schnittstelle und wird hier nicht wiederholt. Worum es im Rest dieses Textes geht, ist der Teil, der keine Liste ist: wie Sie herausfinden, dass sich etwas geändert hat.

Moneybird veröffentlicht sechs Scopes. Fünf davon benennen einen Arbeitsbereich und einer einen Datentyp, und das Objekt, um das die meisten Integrationen gebaut sind, steht überhaupt nicht in der Liste.

Die Dokumentation benennt die Folge eindeutig: „Für den Zugriff auf Kontakte ist einer der Scopes sales_invoices, documents, estimates, bank oder settings erforderlich … Nur Zugriff auf time_entries erlaubt Ihnen nicht, auf Kontakte zuzugreifen.“ Kontakte kommen also als Nebenwirkung davon, dass Sie etwas anderes anfragen.

Das zählt auf dem Zustimmungsbildschirm, und Ihr Code merkt davon nichts. Ein Kunde, der nach dem Scope bank gefragt wird, damit Ihr Produkt einen Kontaktdatensatz lesen kann, liest diese Anfrage als eine Anfrage zu seiner Bank. Eine engere Anfrage gibt es nicht, der ehrliche Weg ist also, die zu erklären, die Sie stellen.

Der fehlende Kontakt-Scope nimmt auch eine Entwurfsmöglichkeit weg. Manche Systeme lassen Sie eine nur lesende Integration auf Scope-Ebene von einer schreibenden trennen. Hier tragen dieselben fünf Scopes beides, die Grenze zwischen Lesen und Schreiben ziehen Sie also auf Ihrer Seite.

In unseren Coverage-Daten hat Moneybird kein lesbares Customers-Objekt und kein lesbares Suppliers-Objekt. Beide stehen in allen fünf Spalten auf nicht unterstützt. So ist das System gebaut: Moneybird führt einen Parteien-Datensatz und unterscheidet die Rollen auf den Dokumenten, die ihn referenzieren.

Einen eigenen Abschnitt wert ist die zweite Hälfte: Contacts ist hier auch das einzige Objekt, das wir zugleich für Lesen, Anlegen und Ändern unterstützen.

Liest man die zwei Hälften zusammen, schreibt sich die Integration in Umrissen von selbst. Ihre Partnerdaten machen den Rundlauf: Sie lesen Kontakte, Sie legen sie an, Sie ändern sie. Alles andere ist bestenfalls ein Lesevorgang, ein Produkt, das Dokumente in dieses System schieben will, plant also gegen die Auf-Abruf-Spalte und nicht gegen das, was freigeschaltet ist.

Die Mapping-Frage, die daraus folgt, ist die Stelle, an der ein einheitliches Modell seinen Wert zeigt. Wenn Ihr Produkt Kunden und Lieferanten als getrennte Typen führt, muss etwas sie auf dem Weg hinein auf einen Datensatz falten und auf dem Weg hinaus wieder auseinander. Das gemeinsame Datenmodell ist der Ort dafür, und es ist derselbe Code, ob das System darunter einen Parteien-Datensatz führt oder drei.

Moneybird hat ein Webhook-System, und zwar ein gründliches. Die Prämisse steht so da, wie man es sich wünscht: „Statt die Schnittstelle in einem bestimmten Intervall abzufragen, benachrichtigt Moneybird Sie über Änderungen an Informationen in der Buchhaltung.“

Der Katalog hinter diesem Satz ist groß. Die Ereignisseite listet 343 Ereignistypen für das Feld enabled_events, verteilt über 49 Gruppen oberster Ebene, und Sie können eine ganze Gruppe über ihr Präfix abonnieren, ohne ihre Mitglieder aufzuzählen.

Die Zustellmechanik ist ebenso vollständig. Ihr Endpunkt wird bei der Registrierung auf ein 200 geprüft. Ein Fehlschlag wird zehnmal in wachsenden Abständen wiederholt. Jede Zustellung trägt einen Idempotency-Key, der je Zustellung eindeutig ist, und genau das macht es sicher, dieselbe Zustellung zweimal anzunehmen.

Eine Eigenschaft hebt dieses System von den meisten ab, mit denen man es vergleichen würde. Der Payload trägt den ganzen Datensatz: entity_type, entity_id, action und dann die vollständige entity, und in Moneybirds eigenem Beispiel kommt eine Rechnung mit ihrem Kontaktobjekt darin an, Adressen und Mandatsfelder eingeschlossen.

Das ist bequem, und es ist eine Entscheidung, die Sie erben. Eine vollständige Entität in einem Webhook-Body heißt, dass Kundendaten in Ihren Logs landen, sofern Sie sie nicht heraushalten, und das ist eine Frage der Aufbewahrung und keine der Integration.

In welchem Zustand jede Zustellung endete, steht am Webhook selbst, denn Moneybird hält den letzten Statuscode und Body zur Fehlersuche vor. Das ist dieselbe Information, die das Logging-Modell für Aufrufe über uns bereitstellt.

Alles darüber beschreibt, was der Hersteller veröffentlicht. Was eine Verbindung über uns heute nutzt, ist der Versionsindex im nächsten Abschnitt, und Ereignisse werden auf diesem System auf Anfrage freigeschaltet.

Unsere eigene Dokumentation steht zwischen diesen zwei Tatsachen und sollte vollständig gelesen werden, bevor Sie um eine von beiden herum planen. Sie beschreibt das Abonnement für dieses System konkret, benennt vier Ressourcen und drei Ereignistypen, und sie nennt den Aufruf, der je Kunde eines anlegt.

Beide Tatsachen gehören in denselben Absatz, weil ein Plan, der nur auf einer steht, schiefgeht. Ein dokumentierter Katalog heißt noch nicht, dass heute Ereignisse ankommen, und was heute keines trägt, kann morgen eines tragen. Das Ereignismodell ist der Ort für diese Unterscheidung, und auf diesem System ist die Pull-Hälfte derzeit das Ganze.

Die nützliche Frage ist also, worauf der Pull steht. Auf den meisten Systemen lautet die Antwort: ein Zeitstempel seit der letzten Änderung. Hier ist es etwas Besseres, und Moneybird dokumentiert es für genau diesen Zweck, Sie müssen es sich nicht zusammensetzen.

Die Synchronisationsendpunkte machen das konkret. Ein GET liefert jeden Datensatz der Verwaltung als ID und Versionsnummer. Sie vergleichen diese mit dem, was Sie halten. Dann liefert ein POST an denselben Pfad die Datensätze, die Sie benennen.

In Moneybirds veröffentlichter OpenAPI-Beschreibung gezählt, tragen 11 seiner 211 dokumentierten Pfade dieses Muster, Kontakte und Ausgangsrechnungen darunter, dazu Angebote, Finanzbewegungen und die Dokumenttypen. Es deckt also die Objekte ab, die eine Buchhaltungsintegration bewegt, und es deckt nicht alles ab.

Zwei Eigenschaften machen es tragfähig. Ein Versionsvergleich kümmert sich nicht um Uhrabweichungen oder Zeitzonen, und auf einem System, das Zeitstempel über einen Header, dann eine Verwaltungseinstellung und dann UTC auflöst, ist das eine Fehlerklasse, die Sie sich schlicht nie einhandeln.

Und es holt auf. Ein Worker, der einen Tag ausgefallen war, stellt beim nächsten Lauf dieselbe Frage und bekommt eine vollständige Antwort, ohne dass ein Cursor erhalten geblieben sein muss.

Moneybirds Drosselung ist großzügig in ihrer Rahmung und genau in ihrer Einheit. Die Nutzung ist innerhalb des Abonnements und der Berechtigungen des verbundenen Kontos unbegrenzt, und dann setzt ein Satz die Einheit: „Um Betrug und Missbrauch zu verhindern, werden Anfragen an die Schnittstelle je IP-Adresse gedrosselt.“

Die Zahl ist 150 Anfragen je fünf Minuten, und 50 je fünf Minuten für alles unterhalb der Reporting-Endpunkte. Lesen Sie die Einheit noch einmal, denn sie ist der Teil, der eine Architektur entscheidet. Das Budget gehört der Adresse. Token, Kunde und Verwaltung spielen dabei keine Rolle.

Für ein Skript mit einem Mandanten ist das reichlich. Für eine direkte Integration, die viele Kunden von einer Ausgangsadresse aus bedient, ist es ein einziger Topf, und weitere Kunden bringen keine zusätzliche Kapazität: 150 je fünf Minuten sind 30 je Minute, ob eine Verwaltung dahintersteht oder vierhundert.

Über maesn ist diese Rechnung nicht mehr Ihre. Die Aufrufe an Moneybird kommen aus unserer Infrastruktur, die Adresse, die das Limit zählt, ist also unsere, und die Planung dagegen läuft auf unserer Seite der Schnittstelle. Bei Ihnen kommt der standardisierte Fehler unten an. Ein Budget für Ihren eigenen Ausgang müssen Sie nicht bemessen.

Es gibt einen dokumentierten Ausweg, und er ist ein Gespräch und kein Parameter: „Partner mit beliebten OAuth-Anwendungen können ein Limit je Verwaltung statt der Limits je IP-Adresse beantragen.“ Gut, das früh zu wissen, denn der Antrag ist leichter gestellt, bevor das Limit der Grund dafür ist.

Ein weiterer Satz derselben Seite ändert, wie Sie Arbeit überprüfen. Moneybird speichert Lesevorgänge zwischen: „Wir raten dringend davon ab, GET-Methoden zur Überprüfung zu verwenden, da das zu einem unvollständigen Ergebnis führen kann. Zur Überprüfung von Anfragen können Entwickler die Statuscodes der Antwort prüfen.“

Der Statuscode ist also das, was einen Schreibvorgang bestätigt. Wo ein Schreibvorgang eingereiht wird, statt sofort zu laufen, meldet der asynchrone Weg das Ergebnis, ohne dass Sie danach fragen müssen.

Das Filtern läuft über einen eigenen Pfad und nicht über Query-Parameter am Listen-Aufruf. Sie fragen /contacts/filter.json an und übergeben eine filter-Zeichenkette aus kommagetrennten key:value-Begriffen. So weit hatte die vorige Fassung dieses Artikels recht, und der Satz daneben in der Referenz ist der, der Zeit kostet.

Moneybird sagt es unumwunden: „Jeder Filter, den Sie übergeben, ersetzt die Vorgaben unten vollständig, nehmen Sie also jeden Schlüssel auf, den Sie brauchen.“ Ein Filter ersetzt die Vorgaben, er engt sie nicht ein. Ein einziger übergebener Schlüssel lässt jede Bedingung fallen, die Sie für selbstverständlich hielten, und die Antwort sieht plausibel aus, während sie falsch ist.

Die Seitenaufteilung ist konventionell, und eine Erwartung daran ist es nicht. Sie bekommen page und per_page, die voreingestellte Seitengröße ist 50 und das Maximum 100. Was Sie nicht bekommen, ist eine Gesamtzahl. Moneybird liefert einen Link-Header mit rel="next" und rel="prev", die Größe einer Ergebnismenge erfahren Sie also, indem Sie an ihr Ende kommen.

Das ist eher ein Fortschrittsbalken-Problem als eines der Richtigkeit, und es hat eine naheliegende Wechselwirkung mit dem Abschnitt darüber: jede Seite abzulaufen, um zu erfahren, wie viele es waren, kostet dasselbe Adressbudget wie die Synchronisation selbst. Beide Zahlen beschreiben eine direkte Integration. Über maesn senden Sie ein limit und ein page gegen einen Paginierungsvertrag, und Moneybirds Seitengröße, seine Obergrenze und seine fehlende Gesamtzahl müssen Sie sich nicht mehr merken.

Was wir von der Liste nehmen:

• Die Auswahl der Verwaltung. Welche Verwaltung ein Token betrifft, gehört zum Verbindungsfluss und wird für spätere Aufrufe gespeichert, es ist also kein Feld, das Sie einsammeln, prüfen und durch jede Anfrage fädeln.
• Die Zuordnung der Parteien. Ein Kontaktdatensatz kommt in derselben Form an, die Ihre anderen Systeme liefern, ein Produkt, das Kunden und Lieferanten getrennt führt, bekommt also keinen Moneybird-förmigen Zweig.
• Die Form der Antwort. Das Format im Pfad, IDs, die als Zeichenketten überleben müssen, und ein eigener Filtervertrag enden an unserer Grenze und erreichen Ihre Modelle nicht.

Was bei Ihnen bleibt, und zwei davon sind Entscheidungen und keine Aufgaben:

• Die Taktung und die Rechnung dahinter. Heute macht nichts aus dieser Verbindung eine Ereignisquelle. Wie frisch Ihr Produkt sein muss, gegen ein Budget, das einer Adresse gehört und keinem Kunden, entscheiden Sie.
• Was Sie einem Kunden sagen, was die Zustimmung abdeckt. Es gibt keinen Kontakt-Scope, nach dem man fragen könnte, die Erklärung auf Ihrer Seite leistet also Arbeit, die der Berechtigungsbildschirm nicht leisten kann.
• Die Aufbewahrung dessen, was ein Ereignis tragen würde. Wenn Abonnements später Teil Ihres Entwurfs werden, ist der Payload eine vollständige Entität. Wo die landet und wie lange sie bleibt, entscheidet keine Schnittstelle für Sie.