FreeAgent-Schnittstelle und API-Integration
FreeAgent ist eine britische Buchhaltungsplattform für Freiberufler, Auftragnehmer und kleine Unternehmen und für die Kanzleien, die ihre Bücher führen. Sie deckt Rechnungsstellung, Ausgaben und Bankabstimmung ab und meldet an HMRC: MTD-fähige Umsatzsteuererklärungen, Self Assessment und MTD for Income Tax. Binden Sie sie über Maesn an, und Sie erreichen sie mit derselben REST API und demselben Datenmodell wie jedes andere unterstützte System.
Drei FreeAgent-Eigenheiten, die nie in Ihrem Code ankommen
FreeAgent ist eine kleine API zum Lernen und eine, die man leicht auf subtile Weise falsch macht. Drei seiner Eigenheiten kosten ein Team normalerweise eine Runde Nacharbeit. Hier stehen sie, und was Maesn davon abnimmt.
Die Partnerebene, in beide Richtungen abgebildet
FreeAgent führt einen Kontaktdatensatz und behandelt Kunde und Lieferant als Sichten darauf statt als getrennte Objekte. Sie lesen die zwei Rollen getrennt und schreiben den Datensatz darunter, und der Bezeichner, der zurückkommt, ist eine vollständige API-URL. Maesn bildet das auf das gemeinsame Datenmodell ab, hier kommen also dieselben Felder an wie auf jedem anderen System.
Die Ratengrenzen, abgefangen
FreeAgent erzwingt 120 Anfragen je Minute, 3.600 je Stunde und 15 Token-Erneuerungen je Minute, gezählt je angebundenem Nutzer und zurückgesetzt zur Minute oder zur Stunde. Über der Grenze antwortet es mit 429 und einem Retry-After-Header. Maesn hält den Takt und gibt Ihnen dafür einen einheitlichen Fehlervertrag. Das Backoff schreiben Sie also einmal und nicht einmal je System.
Paging, das nicht still zu früh aufhören kann
FreeAgent gibt 25 Datensätze je Seite zurück, deckelt per_page bei 100 und legt die Links auf die nächste und die letzte Seite in einen Link-Header der Antwort statt in den Rumpf. Wer nur den Rumpf liest, hält einen Abgleich für fertig, der es nicht ist. Maesn blättert jeden FreeAgent-Endpunkt und vereinheitlicht das weg, in Ihrem Code kommt also die vollständige Menge an.
In Ihrem Code kommen ein REST-Aufruf und ein Account-Key an. Die Eigenheiten von FreeAgent bleiben auf dieser Seite der Schnittstelle, und das nächste System, das Sie hinzunehmen, verhält sich genauso.
Ein kurzes Gespräch genügt meist, um zu klären, ob Maesn zu Ihrem Anwendungsfall passt.
Drei Gründe, die FreeAgent-Schnittstelle über Maesn anzubinden
FreeAgent direkt anzubinden ist ein kurzes Projekt. Es korrekt zu halten, durch drei Ratenbegrenzungen, einen Pager über Header und ein Partnermodell, das beim Lesen trennt und beim Schreiben nicht, ist der Teil, der immer wiederkommt, und er kommt beim nächsten System wieder.
Die FreeAgent-eigene Arbeit bleibt hier
Das Lesen des Link-Headers, das Anfragebudget je Nutzer, das Backoff beim 429 und die Auflösung von URL-Bezeichnern in stabile Schlüssel liegen alle hinter der Schnittstelle. Nichts davon erreicht Ihren Code, und nichts davon wird ein zweites Mal geschrieben, wenn das nächste System kommt.
Was eingeschaltet ist, schriftlich
Kunden und Lieferanten sind heute lesbar und Kontakte schreibbar. Die Geschäftspartnerebene funktioniert also von Anfang bis Ende: Sie lesen die Rolle, Sie schreiben den Datensatz. Der Rest des Katalogs ist auf Anfrage verfügbar statt abwesend, ihn zu erweitern ist also ein Gespräch darüber, welche Objekte Ihr Anwendungsfall braucht, und keine zweite Integration.
Das nächste System kostet nichts
Sobald FreeAgent läuft, antwortet jedes andere unterstützte Buchhaltungs- und ERP-System auf derselben Schnittstelle mit demselben Datenmodell. Die zwei Header bleiben dieselben, und die Änderungserkennung, die Sie hier geschrieben haben, läuft weiter. Ihre zweite Integration ist ein Konfigurationsschritt und kein zweites Projekt.
FreeAgent authentifiziert eine Firma je Konto
FreeAgent authentifiziert über OAuth 2.0, und die Anwendung, die Ihre Kunden freigeben, ist Ihre und nicht die von Maesn. Ein FreeAgent-Firmenkonto hält genau eine Buchhaltung. Die Zustimmung ist also die einzige Frage, die die Verbindung klären muss, und der Redirect bringt alles zurück, was Maesn braucht.
- OAuth 2.0
- Eine App, die Ihr Unternehmen bei FreeAgent registriert
Eine Integration, jeder Kunde. Maesn verwahrt die Zugangsdaten und führt Handshake, Refresh und erneute Authentifizierung dahinter aus.
- Ihre Client-Zugangsdaten
- OAuth-Kennung und Secret, die FreeAgent Ihnen ausgestellt hat, 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.
- Der Token-Zyklus, kurz, aber nicht scharf
- Der Authorization Code gilt 15 Minuten und das Access-Token eine Stunde, und wann Sie darin erneuern, überlässt FreeAgent Ihnen. Gezählt wird gegen die Grenze je Nutzer die Erneuerung selbst, und Maesn hält die Tokens, damit nicht Ihr Code diese Grenze bezahlt.
FreeAgent betreibt zwei API-Produkte hinter einer Marke: die Firmen-API, die die meisten Integrationen nutzen, und eine eigene für Kanzleien, die die Mandanten einer Kanzlei über einen zusätzlichen Subdomain-Header erreicht. Sie brauchen auf FreeAgents Seite verschiedene Apps, und die Einrichtung, die Maesn heute unterstützt, ist die für Firmen. Wenn Ihre Kunden Kanzleien statt Unternehmen sind, lohnt es sich, das anzusprechen, bevor Sie etwas registrieren.
- 1
Ihr Kunde startet in Ihrem Produkt
Sie schicken ihn in den Ablauf, und Maesn öffnet den Zustimmungsbildschirm von FreeAgent. Er trägt den Namen Ihrer Anwendung, denn die App ist auf Ihr Unternehmen registriert.
- 2
FreeAgent kehrt zu Maesn zurück
Die Redirect-URL Ihrer App zeigt auf Maesn. Der Code-Tausch und das erste Token passieren also hier statt in Ihrem Backend. Ihr Kunde landet in Ihrem Produkt, ohne etwas einrichten zu müssen.
- 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.
Was Ihr Kunde hier sieht, ist ein Zustimmungsdialog und danach nichts mehr, denn ein FreeAgent-Account ist eine einzige Firma, und die Frage, welche Bücher erreicht werden sollen, ist damit bereits beantwortet. Unified Authentication macht diese Form zum Normalfall statt zum Glücksfall. Wo ein System mehrere Umgebungen oder Firmen erreicht, stellt Maesn diese Wahl im selben Ablauf vor Ihren Kunden, speichert die Antwort an der Verbindung und gibt denselben Account-Key zurück wie hier. Es gibt also einen Verbindungsablauf zu bauen, und welche Systeme eine zusätzliche Frage brauchen, wird dahinter geklärt statt in Ihrem Code verzweigt.
Wie Sie eine Änderung in FreeAgent bemerken
Kein FreeAgent-Objekt sendet heute ein Event über Maesn. Die Änderungserkennung ist hier also ein Lesezugriff, den Sie planen. FreeAgent bietet auf seinen Ressourcen einen eigenen Zeitstempelfilter, und sein Changelog datiert, wann dieser Filter für Kontakte kam, und lässt ihn mit einem Datumsbereich kombinieren.
Einen Zeitstempelfilter auf der Ressource selbst, der nur Datensätze zurückgibt, die seit dem von Ihnen genannten Zeitpunkt angefasst wurden. Es ist ein Lesezugriff, den Sie machen, und kein Aufruf, den Sie empfangen, und er antwortet genau für das Fenster, nach dem Sie fragen.
Einen Delta-Filter auf der vereinheitlichten Schnittstelle, und Maesn bildet ihn auf das ab, was jedes System darunter erwartet. Sie schreiben den geplanten Lesezugriff einmal gegen denselben Filter und dieselbe Paginierung, und er bemerkt Änderungen im nächsten System ohne eine zweite Umsetzung.
Gemessen ist, dass heute kein FreeAgent-Objekt über Maesn Events freigeschaltet hat, und dass der größte Teil der Webhook-Spalte auf Anfrage steht statt auf einer Absage. Was das über FreeAgents eigene Event-Unterstützung sagt, ist eine andere Frage, und keine, die diese Seite in die eine oder andere Richtung beantwortet.
Ein Zeitstempelfilter ist ein schwächeres Signal als ein Event und ein nachsichtigeres. Ein Event kommt einmal an, und ein Endpunkt, der beim Auslösen nicht erreichbar war, bekommt keine zweite Kopie. Ein Filter ist eine Frage, die Antwort ist also dieselbe, ob Sie alle zehn Minuten fragen oder einmal nach einem langen Ausfall, und Aufholen heißt, den Zeitstempel zurückzusetzen, statt abzugleichen, was verpasst wurde. FreeAgent erlaubt zusätzlich, diesen Filter mit einem Datumsbereich zu verbinden, und das ist der Unterschied zwischen einem Aufholzugriff und einem vollständigen Neuimport.
Was langfristig über die Kosten entscheidet, ist nicht FreeAgent, sondern wie viele Fassungen der Schleife Sie am Ende besitzen. Ein Weg, zu filtern und zu paginieren hält diese Zahl bei eins: Derselbe Lesezugriff bedient auch das nächste System, ob es Events sendet oder darauf wartet, gefragt zu werden. Der Zeitstempel, das Paging und der Wiederholungsversuch bleiben, wo sie sind.
Eingetragen im FreeAgent-Verzeichnis
Die meisten Anbieter hören bei der API auf. Maesn übernimmt die technische Seite und die Beziehung, und bei FreeAgent steht die zweite Hälfte bereits: FreeAgent veröffentlicht ein öffentliches Verzeichnis der Produkte, die sich anbinden, und Maesn hat darin einen Eintrag.
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 den FreeAgent-Eintrag, statt Ihnen ein Formular und einen Link zu geben, und tut das als Unternehmen, das in diesem Verzeichnis bereits steht.
Ein öffentliches Verzeichnis, auf der eigenen Domain von FreeAgent
FreeAgent betreibt ein Integrationsverzeichnis, in dem seine Kunden stöbern, mit einer Seite je Produkt darüber, was die Integration tut und wer sie gebaut hat. Diese Seite liegt auf freeagent.com und nicht auf der Website des Anbieters, und genau das macht einen Eintrag wertvoll.
Maesn hat in diesem Verzeichnis bereits einen Eintrag
Der Maesn-Eintrag beschreibt die FreeAgent-Integration und die Schritte, um eine zu starten, und er liegt auf der eigenen Domain von FreeAgent und nicht auf unserer. So weit zu kommen ist der Teil einer Partnerschaft, der meist am längsten dauert, und bei diesem System liegt er bereits hinter uns.
Das Publikum sind britische Unternehmen und ihre Kanzleien
FreeAgent verkauft an Freiberufler, Auftragnehmer und kleine Unternehmen im Vereinigten Königreich und getrennt davon an die Kanzleien, die deren Bücher führen. Ein Eintrag stellt Ihr Produkt vor beide, und es lohnt sich zu entscheiden, welcher der zwei Seiten Sie verkaufen, bevor Sie den Eintrag schreiben.
Die Integration läuft unter dem Namen Ihres Produkts, und der Eintrag gehört Ihnen und nicht uns. Maesn ist die Schicht dahinter.
Wir bereiten die technische Seite der Anforderungen mit Ihnen vor.
Was FreeAgent vorab verlangt
Vier Dinge sollten entschieden sein, bevor Sie Code schreiben, und zwei davon betreffen, wer sich verbindet, und nicht, was Sie bauen.
- Eine FreeAgent-App, von Ihnen registriert
- Sie legen sie im Entwickler-Dashboard von FreeAgent an und setzen die Redirect-URL auf den Callback von Maesn, danach übergeben Sie uns einmal OAuth-Kennung und Secret. Ihre Kunden sehen auf dem Zustimmungsbildschirm den Namen Ihrer Anwendung. Die Verbindung liest sich also als Ihre.
- Ein zweiter Satz Zugangsdaten für die Sandbox
- FreeAgent betreibt Produktion und Sandbox auf verschiedenen URLs mit verschiedenen Zugangsdaten. Die Sandbox ist also ein eigenes Zielsystem mit eigener Callback-Adresse und kein Schalter am ersten. Registrieren Sie beide, solange Sie im Dashboard sind, das ist ein Weg statt zweier.
- Die Zugriffsstufe der Person, die sich verbindet
- FreeAgent stuft Berechtigungen von keinem Zugriff bis zum vollen ab und nennt je Ressource eine Mindeststufe, und die Stufe entscheidet außerdem, welche Felder zurückkommen. Bei Kontakten gibt die Grundstufe einen Namen zurück, während E-Mail-Adresse, Anschrift, Zahlungsbedingungen und die Steuernummer die Kontaktberechtigung verlangen. Eine Verbindung, die ein eingeschränkter Nutzer herstellt, ist eine dünnere Verbindung, und das sollte man wissen, bevor es wie ein Fehler aussieht.
- Ein Zeitplan, denn nichts ruft Sie an
- Die Änderungserkennung ist hier ein Lesezugriff, den Sie in einem Intervall fahren, und kein Event, auf das Sie warten. FreeAgent bietet auf seinen Ressourcen einen Zeitstempelfilter an, und Maesn steuert ihn aus demselben Delta-Filter, den Sie schon auf die anderen Systeme im Katalog richten. Es gibt also eine Schleife und nicht eine je System.
Wir gehen die App-Registrierung, die Sandbox und die Berechtigungsstufen mit Ihnen durch.
Ein Datensatz, zwei Rollen, eine Form am Ende
Die Partnerebene von FreeAgent liest sich wie eine Inkonsistenz, bis Sie wissen, was darunter liegt. Die Erklärung ist eine Regel darüber, wann ein Kontakt überhaupt eine Rolle übernimmt.
Das Lesen trennt den Geschäftspartner, das Schreiben nicht
Kunden und Lieferanten kommen als zwei lesbare Rollen an, weil FreeAgent sie als Sichten bereitstellt, während Anlegen und Aktualisieren auf dem einen Kontaktdatensatz darunter passieren. Planen Sie den Schreibweg gegen die Kontakte und nicht gegen die Rolle, die Sie lesen.
Bezeichner sind URLs, keine Zahlen
FreeAgent benennt den eindeutigen Bezeichner eines Kontakts oder einer Rechnung als URI, und Verweise zwischen Datensätzen tragen die vollständige API-Adresse. Maesn löst sie in stabile Schlüssel auf, nachgelagert muss also nichts eine Adresse zerlegen, um eine ID zu finden.
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.
Ein Kontakt in FreeAgent beginnt weder als Kunde noch als Lieferant. Er wird das erste Mal zu einem, wenn eine Rechnung Sie beide verbindet, und die Richtung dieser Rechnung entscheidet, welche Rolle er annimmt: Eine, die Sie stellen, macht den Kontakt zum Kunden, eine, die Sie erhalten, macht ihn zum Lieferanten. Ein Kontakt, der keines von beidem getan hat, bleibt genau das, als was er angelegt wurde, ein FreeAgent-Account hält also drei Gruppen statt zwei. Deshalb sind Kunde und Lieferant Sichten auf einen einzigen Kontaktdatensatz statt eigener Objekte, und deshalb lesen Sie die Rolle, die Sie brauchen, und schreiben den Datensatz darunter.
Sobald das klar ist, hört der Schreibweg auf zu überraschen. Es gibt eine Stelle, an der ein Geschäftspartner angelegt wird, und keine Möglichkeit, ihn als Rolle anzulegen, denn die Rolle ist eine Folge von Aktivität und keine Eigenschaft, die Sie setzen. Was Sie danach lesen, kommt im gemeinsamen Common Data Model zurück, ein Kontakt aus FreeAgent hat also dieselbe Form wie ein Kontakt aus einem System, das Kunden und Lieferanten tatsächlich trennt, und der Code, den Sie hier schreiben, ist der Code, den Sie für das nächste wiederverwenden.
Eine weitere Sache entscheidet, was eine FreeAgent-Anbindung in der Praxis wert ist, und sie steht in keiner Objektliste. FreeAgent stuft Nutzerberechtigungen ab und nennt je Ressource eine Mindeststufe, und die Stufe wählt zugleich aus, welche Felder zurückkommen: Ein Kontakt, auf der Basisstufe gelesen, trägt einen Namen, während die E-Mail-Adresse, die Postanschrift, die Zahlungsbedingungen und die Steuernummer die Kontaktberechtigung brauchen. Derselbe Lesezugriff liefert also unterschiedlich viele Daten, je nachdem, wer die Verbindung freigegeben hat, und dafür zu entwerfen ist besser, als es zu entdecken.
Sagen Sie uns, welche Objekte Ihr Anwendungsfall braucht, und wir bestätigen, was möglich ist.
