Moneybird-Schnittstelle und API-Integration
Moneybird ist eine niederländische Buchhaltungsplattform für Freiberufler, kleine Unternehmen und die Buchhalter, die daneben arbeiten. Sie deckt Rechnungsstellung, Ausgaben, Umsatzsteuererklärungen und Bankabstimmung ab, und sie ist eines der Systeme, nach denen ein Produkt, das in die Niederlande verkauft, namentlich gefragt wird. Binden Sie sie über Maesn an, und Sie erreichen sie mit derselben REST API und demselben Datenmodell wie jedes andere unterstützte System.
Was eine Moneybird-Anbindung kostet
Moneybird ist eine saubere REST API mit drei Eigenschaften, die die Form Ihres Codes bestimmen, und alle drei landen, bevor Sie eine einzige Geschäftsregel schreiben. Hier steht, was die Integration von Ihnen verlangt, und was Maesn davon abnimmt.
Ein Discovery-Aufruf, danach reist er für Sie mit
Moneybird adressiert alles als /api/v2/{administration_id}/{resource}.{format}. Die eigene OpenAPI-Spezifikation beschreibt 211 Pfade, und einer davon funktioniert ohne diese ID: der Aufruf, der die Administrationen auflistet, die ein Token erreichen kann. Maesn klärt sie beim Onboarding je Kunde und setzt sie danach auf jede Anfrage, kein Teil Ihres Codes muss also wissen, zu welcher Administration ein Aufruf gehört.
Die Obergrenze, und worauf sie zählt
Moneybird erlaubt 150 Anfragen alle 5 Minuten und fällt für die Report-Endpunkte auf 50, und gezählt wird je IP-Adresse statt je Token oder je Kunde. Moneybird schreibt, dass Partner mit stark genutzten OAuth-Anwendungen stattdessen eine Grenze je Administration anfragen können. Maesn gibt den 429 in einer einheitlichen Fehlerform mit den Retry-Headern zurück, die Moneybird sendet. Das Backoff schreiben Sie also einmal und nicht einmal je System.
Ein Kontakt, für Sie abgebildet
Moneybird hält jede Geschäftsbeziehung in einem einzigen Kontaktdatensatz, und die Abdeckungsmatrix bildet das ab: Kunden und Lieferanten sind als nicht unterstützt gekennzeichnet, während Kontakte das eine Objekt sind, das zum Lesen, Anlegen und Aktualisieren freigeschaltet ist. Maesn bildet es in das gemeinsame Datenmodell ab. Ein Moneybird-Kontakt kommt also in derselben Form an wie ein Kunde aus einem System, das die beiden trennt, und die Abfrage in Ihrem Code bleibt ein Pfad statt zweier.
In Ihrem Code kommen ein REST-Aufruf und ein Account-Key an. Die Administrations-ID, das Formatsuffix und die Retry-Header bleiben auf dieser Seite der Linie, und das nächste niederländische System, nach dem Ihre Kunden fragen, antwortet auf derselben Schnittstelle.
Ein kurzes Gespräch genügt meist, um zu klären, ob Maesn zu Ihrem Anwendungsfall passt.
Clockin hat aus Integrationen einen Weg in neue Märkte gemacht
Clockin digitalisiert die Zeiterfassung für kleine und mittlere Unternehmen. Die Integrationen, die sie gebaut haben, sind kein Supportkosten-Posten mehr, sondern bringen Kunden, und genau diesen Tausch bietet ein Platz im Moneybird-App-Verzeichnis einem Produkt, das niederländische Unternehmen und ihre Buchhalter erreichen will.
“Wir nutzen Maesn, um Integrationen und Partnerschaften erfolgreich als wichtigen Treiber für Leadgenerierung und für den Schritt in neue Märkte und Kundensegmente einzusetzen.”
Drei Gründe, die Moneybird-Schnittstelle über Maesn anzubinden
Moneybird direkt anzubinden ist ein kurzes Projekt. Es korrekt zu halten, durch eine ID, die bei jedem Aufruf stimmen muss, einen Filter, der sich still selbst ersetzt, und Bezeichner, die Ihr JSON-Parser runden könnte, ist der Teil, der im dritten Monat auftaucht.
Die Moneybird-eigene Arbeit bleibt hier
Die Administrations-ID in jedem Pfad, die Endung .json, die eigenen Filter-Endpunkte, deren teilweiser Filter die Voreinstellungen überschreibt, statt sie zu ergänzen, und Bezeichner, die so groß sind, dass Moneybird selbst darum bittet, sie als Zeichenketten zu lesen. Maesn nimmt alle vier auf, und keines davon erreicht den Code, den Sie schreiben.
Was eingeschaltet ist, schriftlich
Kontakte kommen lesbar, schreibbar und aktualisierbar zurück, und das ist das Objekt, auf das eine Kundenabfrage auf diesem System zeigt. Alles darüber hinaus ist auf Anfrage verfügbar statt abwesend. Die Verbindung zu erweitern ist also ein Gespräch darüber, welche Objekte Ihr Ablauf braucht.
Das nächste System kostet nichts
Sobald Moneybird läuft, antwortet jedes andere unterstützte Buchhaltungs- und ERP-System auf derselben Schnittstelle mit demselben Datenmodell. Die zwei Header bleiben dieselben, und die Schleife zur Änderungserkennung, die Sie hier geschrieben haben, läuft weiter. Ihre zweite Integration ist ein Konfigurationsschritt und kein zweites Projekt.
Was ein Moneybird-Eintrag verlangt
Die meisten Anbieter hören bei der API auf. Maesn übernimmt die technische Seite und die Beziehung, und bei Moneybird lassen sich beide gut einplanen, denn es veröffentlicht, was ein Eintrag verlangt, statt einen Prozess zu beschreiben.
Technische Unterstützung
Eine Integration gegen die Unified API und ein Datenmodell, identisch zu jedem anderen System, das Maesn unterstützt. Ihre Entwickler treffen hier auf dieselbe Schnittstelle wie beim nächsten System.
Unterstützung bei der Partnerschaft
Maesn führt Sie durch die Anforderungen von Moneybird und die Einreichung, von der Scope-Liste, die Sie begründen müssen, bis zum Testkonto, das sie verlangen, statt Ihnen ein Formular und einen Link zu geben.
Größe und Alter, beide gezählt und beide veröffentlicht
Moneybird verlangt mindestens 25 aktive Administrationen und mindestens zwei Monate Produktivbetrieb, bevor es eine Integration listet. Diese Schwelle erreichen Sie mit Kunden und nicht mit Code. Ein Eintrag gehört also in den Plan für die Monate nach dem Start und nicht in den Start selbst.
Technische Bedingungen, vorab veröffentlicht
OAuth mit möglichst knappen Scopes statt Moneybird-Logins, Refresh-Tokens statt jedes Mal eines neuen Access-Tokens, Einhaltung der Grenze von 150 Anfragen je 5 Minuten und Webhooks statt dauerndem Abfragen. Moneybird prüft außerdem, ob die Buchungen, die Sie schreiben, buchhalterisch korrekt sind, bevor es Sie listet.
Eine Einreichung, einmal zusammengestellt
Die Anfrage geht an den Support von Moneybird, mit vier Anlagen: dem Nachweis des API-Tokens, einem Testkonto, einem Link auf die Dokumentation, die Ihre Nutzer sehen, und einer Begründung je Scope. Maesn stellt die technische Hälfte mit Ihnen zusammen, denn das Token und die Scope-Liste liegen auf unserer Seite der Integration. Über den Eintrag selbst entscheidet Moneybird, und es sagt das unumwunden.
Die Integration läuft unter dem Namen Ihres Produkts, und der Eintrag gehört Ihnen und nicht uns. Maesn ist die Schicht dahinter.
Wir gehen die Moneybird-Anforderungen und die Einreichung mit Ihnen durch.
Ein Moneybird-Client, eine Administration je Kunde
Moneybird authentifiziert über OAuth 2.0, und die Anwendung, die Ihre Kunden freigeben, ist Ihre und nicht die von Maesn. Eine Moneybird-Anmeldung kann mehr als eine Administration erreichen. Die Verbindung muss also klären, welche sie meint, und Moneybird steht in der Authentifizierungsdokumentation auf der interaktiven Liste: Die Wahl geschieht auf einer Auswahlseite, die Sie mit Ihrer Marke versehen können, und sie wird an der Verbindung gespeichert, statt als Parameter bei jedem Aufruf mitzureisen.
- OAuth 2.0
- Client-Zugangsdaten aus einer App, die Sie bei Moneybird registrieren
Eine Integration, jeder Kunde. Maesn verwahrt die Zugangsdaten, führt den Handshake aus und hält fest, auf welche Administration die Verbindung zeigt.
- Ihre Client-Zugangsdaten
- Client-ID und Secret aus der App, die Sie registriert haben, werden einmal eingereicht und danach für jede Verbindung benutzt. Der Code-Tausch läuft also hier statt in Ihrem Backend. Was Ihr Code hält, ist ein Account-Key je Kunde.
- Die Administration, auf die die Verbindung zeigt
- Moneybird hört mit dem Ausstellen eines Tokens auf und verlangt bei der nächsten Anfrage schon eine Administrations-ID. Maesn verwahrt die gewählte Administration an der Verbindung und setzt sie in den Pfad ein, nach dem Verbindungsschritt muss sie also nichts mehr mittragen.
Moneybird stellt auch persönliche API-Tokens aus, die schneller zu bekommen sind und jedem, der eines hält, Zugriff auf diesen ganzen Account geben. Sie sind nützlich für einen ersten Blick auf die API, und sie sind nicht der Weg für eine Integration, die Ihre Kunden selbst verbinden, und deshalb läuft der Ablauf oben durchgehend über OAuth.
- 1
Ihr Kunde startet in Ihrem Produkt
Sie schicken ihn in den Ablauf, und Maesn öffnet den Zustimmungsbildschirm von Moneybird. Er trägt den Namen Ihrer Anwendung, denn der Client ist auf Ihr Unternehmen registriert. Die Verbindung liest sich also als Ihre und nicht als die eines Dritten.
- 2
Er wählt die Administration
Moneybird kehrt zu Maesn zurück, und wo eine Anmeldung mehr als eine Administration erreicht, zeigt der interaktive Ablauf eine Auswahlseite in Ihrem Erscheinungsbild. Die Wahl wird an der Verbindung gespeichert. Sie wird also einmal getroffen statt bei jeder Anfrage.
- 3
Sie arbeiten mit einem Account-Key
Maesn speichert die Verbindung und gibt einen Account-Key zurück. Ab da trägt jede Anfrage Ihren API-Schlüssel und diesen Account-Key, dieselben zwei Header, die Sie für jedes andere System im Katalog ohnehin schon senden.
Jedes System im Katalog authentifiziert anders, und bei Moneybird ist der Handshake gewöhnlich und der Schritt danach nicht: Das Token allein kann nichts adressieren, denn die Administration muss vor dem ersten Ressourcenaufruf feststehen. Dafür ist Unified Authentication da. Die Auswahlseite, die gespeicherte Wahl und die Zugangsdaten dahinter werden einmal für alle Systeme erledigt und nicht einmal je System, was Ihr Code hält, ist also ein Account-Key.
Was Moneybird zu Webhooks dokumentiert, und was heute freigeschaltet ist
Moneybird dokumentiert Webhooks ausführlich, und kein Moneybird-Objekt ist heute als Event-sendend über Maesn markiert. Beide Hälften sollte man vor sich haben, bevor man die Änderungserkennung entwirft.
Die Entwicklerdokumentation führt 343 Event-Typen und registriert Abonnements je Administration. Jeder Push trägt einen Idempotenzschlüssel, der für diese Zustellung eindeutig ist, und einen Signatur-Header, eine fehlgeschlagene Zustellung wird zehnmal mit wachsendem Abstand wiederholt, und der letzte Status und Rumpf bleiben zur Fehlersuche erhalten.
Die Moneybird-Dokumentation beschreibt ein Abonnement, das je Kunde für Kontakte, Rechnungen, Zahlungen und Steuersätze angelegt wird, mit angelegt, aktualisiert und gelöscht als Event-Typen, geprüft über eine Signatur am Callback. In der Abdeckungsmatrix auf derselben Seite trägt heute kein Objekt ein Event.
Die Schleife zur Änderungserkennung, die Sie jetzt für Moneybird schreiben, ist also ein geplanter Lesezugriff auf demselben Filter und derselben Paginierung wie bei jedem anderen System, und sie ist die Schleife, die nach einem Ausfall sauber nachholt, statt zu verlieren, was gesendet wurde, während Sie ausgefallen waren. Sagen Sie uns, welche Objekte Ihr Anwendungsfall braucht, und wir bestätigen, was möglich ist.
Ein Lesezugriff nach Zeitplan ist die Schleife, die es übersteht, falsch zu liegen. Ein Push, der ankommt, während Ihr Endpunkt nicht erreichbar ist, ist weg, sofern ihn nichts wiederholt, und ein Lesezugriff fragt einfach noch einmal mit einem breiteren Fenster. Was er dafür braucht, sind ein Filter und ein Seitenmodell, denen Sie trauen, und Moneybird gibt Ihnen beides nicht umsonst: Es filtert über eigene Endpunkte, bei denen ein unvollständiger Filter die Vorgaben ersetzt, statt sie einzuengen, und es paginiert, ohne Ihnen je zu sagen, wie viele Seiten es gibt. Ein Weg, zu filtern und zu paginieren nimmt diese Fehlerklasse weg. Was Sie über das Event-Modell verarbeiten und was Sie nach Zeitplan abholen, bleiben zwei Wege, und nur einer davon ist bei Moneybird heute eingeschaltet.
Was Moneybird vorab erwartet
Vier Dinge sollten vor dem ersten Aufruf entschieden sein, und zwei davon sind Entscheidungen und keine Zugangsdaten.
- Eine Moneybird-App, registriert vom Inhaber einer Administration
- Sie legen sie unter Ihrem Moneybird-Konto an, setzen die Redirect-URL auf den Callback von Maesn für Moneybird und reichen Client-ID und Secret einmal bei uns ein. Moneybird prüft beim Zustimmungsschritt, ob die freigebende Person die Administration tatsächlich besitzt. Ein Kollege mit eingeschränkten Rechten kann die Verbindung also nicht abschließen.
- Die Scopes, die Ihr Client anfragt, und der eine, der nicht genügt
- Moneybird veröffentlicht sechs Scopes: Ausgangsrechnungen, Dokumente, Angebote, Bank, Zeiterfassung und Einstellungen. Um an Kontakte zu kommen, braucht es einen der ersten vier oder die Einstellungen, und ein Client, der nur die Zeiterfassung hält, sieht überhaupt keinen Kontakt. Weil Kontakte hier das Objekt mit der vollsten Abdeckung sind, sollten Sie das vor der Einreichung klären und nicht danach.
- Ein Ort für Bezeichner, die große Ganzzahlen sind
- Moneybird warnt in der eigenen Dokumentation, dass seine IDs große Ganzzahlen sind, und empfiehlt, sie als Zeichenketten zu lesen, und unser Webhook-Beispiel trägt eine achtzehnstellige. Ein Parser, der sie still in Fließkommazahlen verwandelt, verliert die letzten Stellen, und den Datensatz, nach dem er dann fragt, gibt es nicht.
- Ein Zeitplan, und die Gewohnheit, nicht mit einem Lesezugriff nachzuprüfen
- Die Änderungserkennung ist ein Lesezugriff, den Sie in einem Intervall fahren, denn heute sendet kein Moneybird-Objekt über Maesn ein Event. Moneybird hält API-Antworten außerdem im Cache und rät davon ab, mit einem GET zu bestätigen, dass ein Schreibzugriff angekommen ist, denn die Antwort kann unvollständig sein. Die Bestätigung ist der Statuscode des Schreibzugriffs.
Wir gehen die App-Registrierung und die Scope-Liste mit Ihnen durch.
Ein Kontaktsatz, eine Form am Ende
Moneybird führt jede Geschäftsbeziehung in einem einzigen Kontaktdatensatz und klärt die Rollen erst am Beleg. Das entscheidet, worauf eine Kundenabfrage zeigt.
Lesen und Schreiben treffen sich in einem Objekt
Konten, Kontakte und Steuersätze sind lesbar. Kontakte und Buchungsvorschläge sind schreibbar. Kontakte sind das einzige Objekt auf beiden Listen. Ein Buchungsvorschlag lässt sich hier also anlegen und nicht zurücklesen, und ein Konto lesen und nicht schreiben. Planen Sie den Rundlauf um die Kontakte herum und behandeln Sie den Rest als je eine Richtung.
Ein unvollständiger Filter ersetzt die Vorgaben
Moneybird filtert über eigene Endpunkte, die mit Komma getrennte Schlüssel-Wert-Paare annehmen, und jeder Filter, den Sie senden, ersetzt die Vorgaben vollständig, statt sie einzugrenzen. Eine Anfrage, die einen Schlüssel auslässt, an den Sie nicht gedacht haben, kommt mit einer anderen Menge zurück statt mit einem Fehler, und das ist die Art Fehler, die einen Testlauf übersteht.
Standardmäßig löscht kein Objekt
Für kein Objekt ist Löschen freigeschaltet. Die Buchhaltungspraxis erwartet Korrekturen und Stornos ohnehin als neue Belege, planen Sie sie also so und nicht um ein Löschen herum, das Sie erst anfragen müssten.
Kunde und Lieferant sind hier keine getrennten Objekte, und das ist eine Eigenschaft von Moneybird und nichts, was die Integration weglässt: Die Beziehung liegt auf einem Kontaktdatensatz, und die Rolle wird am Beleg geklärt. Kontakte sind folglich das Objekt, auf das eine Kundenabfrage zeigt, und sie sind zum Lesen, Anlegen und Aktualisieren gleichermaßen freigeschaltet.
Das ist auch der Moment, in dem sich das gemeinsame Modell bezahlt macht. Ein Kontakt aus Moneybird kommt in derselben Form an wie ein Kunde aus einem System, das Kunden und Lieferanten in zwei Objekte trennt, denn das Common Data Model nimmt den Unterschied auf. Der Code, den Sie hier schreiben, ist der Code, den Sie für das nächste System wiederverwenden. Alles jenseits des freigeschalteten Satzes ist auf Anfrage verfügbar, also nicht standardmäßig eingeschaltet statt außer Reichweite.
Für die Obergrenze entwirft man besser, als sie zu entdecken. Moneybird erlaubt 150 Anfragen alle 5 Minuten und 50 für seine Report-Endpunkte, und es zählt sie je IP-Adresse statt je Token, ein Massenabzug trifft die Grenze also lange vor einem einzelnen Kundenabgleich. Wenn das passiert, kommt der 429 mit den Headern, die sagen, wann Sie wiederkommen sollen, und ein Fehlerkontrakt verhindert, dass daraus eine Moneybird-förmige Verzweigung in Ihrem Code wird.
Sagen Sie uns, welche Objekte Ihr Anwendungsfall braucht, und wir bestätigen, was möglich ist.
