FreshBooks-Schnittstelle und API-Integration
FreshBooks ist eine Cloud-Buchhaltungsplattform für Freiberufler, Selbstständige und kleine Dienstleister, im Einsatz in den Vereinigten Staaten, Kanada, dem Vereinigten Königreich und Australien. Rechnungsstellung, Ausgaben, Zeiterfassung und Projektabrechnung liegen an einer Stelle, und deshalb begegnet ihr ein Produkt, das abrechenbare Arbeit berührt, meistens. Binden Sie sie über Maesn an, und Sie erreichen sie mit derselben REST API und demselben Datenmodell wie jedes andere unterstützte System.
Drei FreshBooks-Eigenheiten, die nie in Ihrem Code ankommen
FreshBooks ist keine schwierige API. Sie hat drei Eigenheiten, die eine erste Implementierung leise bestrafen statt laut, und das ist die teure Sorte. Maesn fängt alle drei ab, bevor Sie eine Zeile Code schreiben.
Je Mandant rotiert und gespeichert
FreshBooks stellt jedes Mal, wenn es ein Access-Token ausstellt, auch ein neues Refresh-Token aus und macht das vorige sofort ungültig. Je Kunde lebt immer nur eines. Geht es bei einem fehlgeschlagenen Schreibzugriff verloren, führt der einzige Weg zurück darüber, diesen Kunden erneut um die Freigabe Ihrer App zu bitten. Maesn hält die Rotation und verwahrt das aktuelle Token je Mandant.
Beide beim Onboarding aufgelöst
Die Buchhaltungsrouten sprechen einen Kunden über seine accountId an, Zeiterfassung und Projekte über seine businessId. Beide kommen aus einem einzigen Identitätsaufruf zurück, und nicht jeder Nutzer hat hinter seinem Business überhaupt ein Konto. Maesn klärt das Paar, wenn Ihr Kunde sich verbindet, und baut bei jedem späteren Aufruf die richtige Route.
Für Sie paginiert und eingebunden
Fragen Sie FreshBooks nach mehr als 100 Zeilen, gibt es 100 zurück, ohne einen Fehler zu melden, und zugehörige Zeilen wie Rechnungspositionen bleiben draußen, bis Sie sie ausdrücklich anfordern. Ein Abgleich, der fertig aussieht, kann ein Bruchteil der Daten sein. Maesn blättert jede Sammlung bis zum Ende und sendet je Endpunkt die richtigen Includes.
Auf Ihrer Seite bleibt ein REST-Aufruf gegen ein Datenmodell, das Sie einmal implementieren. Teams gehen in Tagen live, statt ein Quartal damit zu verbringen, einen Hersteller zu lernen.
Ein kurzes Gespräch genügt meist, um zu klären, ob Maesn zu Ihrem Anwendungsfall passt.
Clockin hat aus Integrationen einen Leadkanal gemacht
Clockin digitalisiert die Zeiterfassung für kleine und mittlere Unternehmen, von den Arbeitsstunden bis zur Projektzeit, erfasst per App oder Terminal und offline, wo es keinen Empfang gibt. Die Projektdaten ihrer Kunden landen jetzt in dem Buchhaltungssystem, das jeder von ihnen ohnehin einsetzt.
“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 FreshBooks-Schnittstelle über Maesn anzubinden
FreshBooks direkt anzubinden ist ein Projekt, das Sie abschließen können. Es dann zu besitzen, und danach das nächste System, entscheidet über Ihre Roadmap.
Änderungen kommen an, statt geholt zu werden
Acht FreshBooks-Ressourcen erreichen Sie über Maesn als Events, von Rechnungen und Zahlungen bis zu Steuersätzen. Maesn registriert das Abonnement je angebundenem Kunden, erledigt den Bestätigungs-Handshake, den FreshBooks vor jeder Zustellung verlangt, und übergibt Ihnen dieselbe Event-Form, die Sie ohnehin verarbeiten.
Was eingeschaltet ist, und wie es breiter wird
Kunden und Lieferanten kommen heute lesbar, schreibbar und aktualisierbar zurück, und die Event-Seite reicht weiter als die Leseseite. Alles darüber hinaus ist auf Anfrage verfügbar statt abwesend, und weil FreshBooks die Scopes in dem Moment festlegt, in dem Ihre App registriert wird, sollten Sie diese Frage klären, bevor sich der erste Kunde verbindet.
Das nächste System kostet nichts
Sobald FreshBooks läuft, antwortet jedes andere unterstützte Buchhaltungs- und ERP-System auf derselben Schnittstelle. Ihre zweite Integration ist ein Konfigurationsschritt, und die Token-Behandlung und die Identitätsauflösung, die Sie hier bezahlt haben, zahlen Sie kein zweites Mal.
Das FreshBooks-Refresh-Token funktioniert genau einmal
FreshBooks authentifiziert über OAuth 2.0, und die App, die Ihre Kunden freigeben, ist Ihre und nicht die von Maesn. Eigen ist daran nicht der Handshake, sondern was danach kommt: Das Refresh-Token ist einmalig nutzbar, und welchen Bezeichner eine Anfrage braucht, hängt davon ab, welchen Teil des Produkts sie anspricht.
- OAuth 2.0
- Ihre eigene FreshBooks-App
Eine App, jeder Kunde. Maesn verwahrt die Zugangsdaten und hält Rotation und die beiden Bezeichner dahinter.
- Ihre App-Zugangsdaten und deren Scopes
- Client-ID und Secret werden einmal eingereicht und für jede Verbindung benutzt. Der Scope-Satz hängt an der App und nicht an der Anfrage. Er wird also bei der Einrichtung vereinbart und gilt für jeden Kunden, der sich danach verbindet.
- Der Token-Zyklus und die zwei IDs
- Jede Erneuerung gibt ein neues Refresh-Token zurück und macht das alte unbrauchbar, und Maesn schreibt den neuen Wert, bevor er gebraucht wird. Die accountId und die businessId des Business, das Ihr Kunde gewählt hat, werden im selben Ablauf geklärt und bleiben an der Verbindung.
Die Rotation ist der Grund, warum sich das einmal zu behandeln lohnt statt je Produkt. Ein Refresh-Token, das benutzt wurde, ist tot, und es gibt keine zweite Kopie: Wer es speichert, muss den neuen Wert jedes einzelne Mal erfolgreich schreiben, sonst autorisiert dieser Kunde erneut. Das ist eine Anforderung an die Dauerhaftigkeit und keine API-Frage.
- 1
Ihr Kunde startet in Ihrem Produkt
Sie schicken ihn in den Ablauf, und Maesn öffnet den Zustimmungsbildschirm von FreshBooks. Er trägt den Namen Ihrer App und listet die Scopes auf, die Sie registriert haben. Die Verbindung liest sich also als Ihre und nicht als die eines Dritten.
- 2
FreshBooks kehrt zu Maesn zurück
Der Redirect Ihrer App zeigt auf den Callback von Maesn. Der Code-Tausch und das erste Token-Paar passieren also hier. Der Identitätsaufruf läuft im selben Schritt und klärt die accountId und die businessId des Business, das Ihr Kunde freigegeben hat.
- 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.
Rotierende Zugangsdaten sind nichts Seltenes. Strukturell wird es hier dadurch, dass FreshBooks keine zweite Kopie führt: In dem Moment, in dem ein neues Refresh-Token ausgegeben wird, ist das vorherige tot, der Schreibvorgang, der es speichert, gehört also zur Authentifizierung und ist keine Aufräumarbeit danach. Einmal falsch gemacht, und dieser Kunde steht wieder vor Ihrem Zustimmungsdialog. Unified Authentication macht daraus einen einmaligen Aufwand. Die Rotation, die beiden Bezeichner und der Account-Key verhalten sich hier genauso wie ein API-Token und eine Tenant-ID beim nächsten System, die zweite Integration erbt die Arbeit also, statt sie mit anderem Vokabular zu wiederholen.
Acht FreshBooks-Ressourcen erreichen Sie als Events
FreshBooks sendet native Webhooks. Eine Änderung dort erreicht Sie also als Event statt über Abfragen. Maesn legt die Abonnements je angebundenem Kunden an, führt den Verifizierungsaustausch durch, den FreshBooks vor jeder Zustellung verlangt, und vereinheitlicht, was ankommt, in die Form, die jedes andere System liefert.
FreshBooks will ein Paar. Ein Abonnement deckt also eine Ressource und einen Event-Typ ab statt einer Ressource und allem, was mit ihr geschieht.
Was ein Event mitbringt, sollten Sie wissen, bevor Sie darauf bauen. FreshBooks füllt den Event-Typ, die Ressource und die ID des Datensatzes, der sich geändert hat, und das genügt, um ihn zu holen. Die zwei Felder, die manche Systeme ergänzen, ein Änderungszeitstempel und der Nutzer hinter der Änderung, bleiben hier leer. Der Umschlag ist überall derselbe, was ein System hineinlegt, nicht.
Wo ein Abonnement liegt, entscheidet darüber, wie viel davon Ihnen am Ende gehört. Bei Xero werden die Ressourcen einmal in der App gewählt, und die Events jedes Kunden kommen an einem Endpunkt an, den Sie danach verteilen müssen. Bei FreshBooks gehört ein Abonnement zu einem angebundenen Kunden, das trennt sie sauber und heißt, dass je Kunde und Paar eines anzulegen, zu verifizieren, zu beobachten und zu entfernen ist. FreshBooks hält die Zustellung außerdem zurück, bis die Callback-Adresse einen Verifizierungsaustausch beantwortet hat, und schaltet ein Abonnement ab, das wiederholt fehlschlägt. Maesn betreibt diese Seite und gibt ein Event-Modell aus, gleich welche Form das System darunter benutzt.
Was ein Event mitbringt und was nicht, klärt man besser früh. Sechs der acht Ressourcen, die hier eine Änderung melden, nämlich Rechnungen, Eingangsrechnungen, Gutschriften, Zahlungen, Artikel und Steuersätze, sind zum Lesen auf Anfrage freizuschalten, ab Werk kommt also die Benachrichtigung an und der Endpunkt, der den Datensatz liefert, ist noch nicht eingeschaltet. Das ist eine Anfrage und keine Grenze. Sie klärt man besser, bevor der Entwurf feststeht, und nicht, nachdem das erste Event eingegangen ist. Ein Weg, zu filtern und zu paginieren verhindert, dass aus der Zwischenzeit eine zweite Implementierung wird: Die Schleife zur Änderungserkennung, die Sie hier schreiben, ist dieselbe, die Sie schon gegen Systeme fahren, die gar nichts senden.
Eingetragen im FreshBooks AppStore
Die meisten Anbieter hören bei der API auf. FreshBooks betreibt einen eigenen AppStore, Einträge sind offen und werden vom Entwickler eingereicht statt verhandelt, und die Anforderungen sind veröffentlicht. Das macht den Eintrag planbar, und Maesn bereitet die technische Seite davon mit Ihnen vor.
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 hilft Ihnen, die Anforderungen an die Verbindung zu erfüllen, gegen die der Eintrag geprüft wird, und steht danach weiter hinter der Integration. Der Eintrag trägt den Namen Ihres Produkts, nicht unseren.
Die Bedingungen erfüllen, bevor Sie den Eintrag schreiben
FreshBooks verlangt eine eigene Integrationsseite auf Ihrer Website, einen Link, der die Integration einschaltet, ein Logo, einen Link zurück zu FreshBooks und Ihre Supportzeiten. Die Bedingung, die Entwicklungsarbeit kostet und kein Texten, ist das Onboarding in Selbstbedienung: Ein FreshBooks-Nutzer muss Ihre Integration einschalten können, ohne jemandem eine E-Mail zu schreiben.
Den Eintrag im Entwicklerportal anlegen
Der Eintrag liegt an derselben App, die Sie für den OAuth-Ablauf registriert haben, unter deren Reiter AppStore, und er lässt sich zuerst als Entwurf speichern und ansehen. Die Felder sind mit Absicht knapp: dreißig Zeichen für den Namen, hundertvierzig für die Kurzbeschreibung und höchstens fünfzehn Schritte in der Verbindungsanleitung.
Einreichen und die Prüfung beantworten
Sie reichen den Entwurf ein, und das AppStore-Team von FreshBooks meldet sich per E-Mail. FreshBooks verlangt außerdem die Angabe, welche seiner Tarife Ihre Integration bedient, denn die Kontostufen unterscheiden sich darin, wie viele Mandanten sie tragen, und eine Integration, die stillschweigend von der größten ausgeht, wird danach gefragt. Diese Frage beantwortet sich leichter, solange die Entscheidung über die Abdeckung noch offen ist.
Über den Eintrag hinaus veröffentlicht FreshBooks Wege zum Co-Marketing darum herum, von Newslettern bis zu Platzierungen im AppStore. Die Integration läuft unter dem Namen Ihres Produkts, und Maesn ist die Schicht dahinter.
Wir bereiten die technische Seite der Anforderungen mit Ihnen vor.
Was FreshBooks vorab verlangt
FreshBooks stellt vier Dinge vor eine Integration. Drei sind schnell erledigt, und das zweite entscheidet man besser, bevor sich der erste Kunde verbindet, als danach.
- Ihre eigene FreshBooks-App, als öffentlich registriert
- Sie legen die App im Entwicklerportal von FreshBooks an und setzen ihre Redirect-URL auf den Callback von Maesn. Der Code-Tausch passiert damit hier statt in Ihrem Backend. Ihre Kunden sehen auf dem Zustimmungsbildschirm den Namen Ihrer App, nicht unseren. Ein kostenloses FreshBooks-Konto genügt, um sie zu halten.
- Die Scopes werden vor der ersten Verbindung entschieden
- FreshBooks gewährt den Zugriff je Objekt und je Aktion und lässt es nicht zu, Scopes zu einem bestehenden Token hinzuzufügen. Den Zugriff später zu erweitern heißt, dass jeder angebundene Kunde widerruft und erneut freigibt. Listen Sie deshalb die Objekte auf, die Ihr Anwendungsfall in einem Jahr braucht, und nicht die, die er in diesem Sprint braucht.
- Die Ratenbegrenzung gilt, ohne veröffentlicht zu sein
- FreshBooks setzt keine Tagesobergrenze und bremst stattdessen Spitzen, ohne zu sagen, wo die Linie liegt. Man entwirft also dafür, statt sie auszurechnen. Maesn reiht Anfragen ein und taktet sie dagegen, damit eine Spitze auf Ihrer Seite auf deren Seite kein fehlgeschlagener Abgleich wird.
- Zwei Sandboxes, und Sie können wahlweise eine davon haben
- FreshBooks bietet ein kostenloses Testkonto an, für das Sie sich anmelden können, und Maesn stellt zusätzlich eine Sandbox bereit. Damit sind die zwei Fälle abgedeckt, die Teams tatsächlich treffen: die Integration überhaupt auszuprobieren und sie gegen Daten zu testen, die kaputtgehen dürfen.
Wir gehen die App-Registrierung, die Scopes und die Sandbox mit Ihnen durch.
Heute zwei Objekte, über den Rest entscheiden die Scopes
Was eine FreshBooks-Anbindung erreicht, entscheiden die Scopes, die bei der Registrierung Ihrer App vereinbart werden. Das ist eine Frage, die früh geklärt gehört und nicht spät.
Mehr Objekte melden, als antworten
Acht Ressourcen erreichen Sie über Maesn als Events, und zwei sind zum Lesen, Anlegen und Aktualisieren freigeschaltet. Die sechs dazwischen, Rechnungen, Eingangsrechnungen, Gutschriften, Zahlungen, Artikel und Steuersätze, sagen Ihnen, dass sich etwas geändert hat, bevor der Endpunkt, der es zurückgibt, für Sie freigeschaltet ist. Das klären Sie besser beim Entwurf als bei der Integration.
Nichts lässt sich löschen, zwei Dinge lassen sich bearbeiten
Für kein Objekt ist das Löschen freigeschaltet, und Kunden und Lieferanten sind die einzigen beiden, die Sie an Ort und Stelle bearbeiten können. Ein Produkt, das Datensätze korrigiert statt neue zu buchen, sollte das früh gegen seinen Anwendungsfall prüfen. Die Buchhaltungspraxis erwartet Korrekturen ohnehin als neue Belege.
Alles andere ist eine Anfrage und keine Sackgasse
Objekte, die in der Matrix oben mit auf Anfrage gekennzeichnet sind, fehlen nicht, sie sind nur nicht standardmäßig freigeschaltet. Siebenundzwanzig der siebenunddreißig stehen dort, darunter die Konten, Journale, Ausgaben und Buchungen, mit denen ein Anwendungsfall rund ums Hauptbuch anfängt. Sagen Sie uns, welche Sie brauchen, und sie kommen dazu.
Die Form einer FreshBooks-Anbindung liest man besser in zwei Richtungen statt in einer. Kunden und Lieferanten kommen lesbar, schreibbar und aktualisierbar zurück, das ist die Partnerebene und nichts darunter. Die Event-Seite reicht weiter als die Leseseite. Ein System, das mehr Arten von Änderung meldet, als es Arten von Datensatz herausgibt, ist kein Widerspruch, sondern sind zwei Schalter, die zu verschiedenen Zeitpunkten gesetzt wurden, und der zweite bewegt sich, wenn Sie fragen.
Daneben gehört eine zweite Liste. FreshBooks gewährt Zugriff je Objekt und je Aktion, die dokumentierte App-Registrierung fragt fünf Scopes ab, und diese fünf decken die Kunden- und Lieferantenobjekte ab plus den Profilaufruf, der die Account-ID und die Business-ID auflöst. Das ist dasselbe Paar, das heute freigeschaltet ist. Es erklärt auch, warum es sich lohnt, eine größere Abdeckung früh zu planen statt spät: FreshBooks erlaubt nicht, einen Scope zu einem Token hinzuzufügen, das es schon gibt, ein breiterer Satz wird also einmal vereinbart und gilt für alle, die sich danach verbinden.
Was nicht freigeschaltet ist, ist nicht außer Reichweite. Die Konten, Journale, Ausgaben und Transaktionen, bei denen ein Hauptbuch-Anwendungsfall anfängt, sind auf Anfrage verfügbar, und sobald sie es sind, kommt alles im gemeinsamen Common Data Model zurück. Für ein Produkt, das eine Kundenliste im Gleichstand hält, ist die Oberfläche heute da. Für eines, das das Hauptbuch liest, ist das ein Gespräch über das Freischalten von Objekten und keine Frage danach, ob die Integration sie überhaupt erreicht.
Sagen Sie uns, welche Objekte Ihr Anwendungsfall braucht, und wir bestätigen, was möglich ist.
