FreshBooks anbinden: Zwei Kennungen, zwei Datumsfilter

Jeder FreshBooks-Aufruf braucht eine von zwei Kennungen, und welche davon ist keine Geschmacksfrage. Buchhaltungsressourcen erreichen Sie unter /accounting/account/{accountId}/, Zeiterfassung und Projekte dagegen unter /timetracking/business/{businessId}/.

FreshBooks erklärt den Grund, statt ihn Sie erschließen zu lassen: „Aus historischen Gründen ist FreshBooks vom Account-Konzept auf ein Business-Konzept gewechselt, viele Ressourcen verwenden aber weiterhin accountIds.“ Die Migration hat stattgefunden, die alte Adressierung ist geblieben und beide sind aktiv.

Beide Werte kommen aus einem einzigen Aufruf von /me, und zwar innerhalb von business_memberships. Jede Mitgliedschaft hat eine eigene ID und ein verschachteltes Business-Objekt, und dieses Business-Objekt trägt die Account-ID und die Business-ID, die Sie tatsächlich brauchen.

Diese Verschachtelung ist die erste Falle, und die Dokumentation weist darauf hin: „Verwechseln Sie die ID des Business nicht mit der ID des business_membership-Objekts selbst.“ Zwei der drei IDs in diesem Ausschnitt sind plausibel und eine ist richtig.

Falls diese Trennung weiterhin nach einer erfundenen Unterscheidung klingt, entscheidet FreshBooks sie aus einer anderen Richtung. Jedes ausgelieferte Webhook trägt beide Werte, und die Begründung ist das Modell selbst: „Weil einige FreshBooks-Ressourcen account verwenden und andere business (siehe Identity Model), werden sowohl account_id als auch business_id mitgeliefert.“ Ein Hersteller, der eine Kennung unter zwei Namen ausliefert, hätte keinen Grund, beide in jede Benachrichtigung zu legen.

Welche Objekte eine Anbindung erreicht, Feld für Feld, steht auf der Seite zur FreshBooks-Schnittstelle. Worum es im Rest dieses Texts geht, ist das, was die Trennung der Kennungen entscheidet, nachdem Sie sie aufgelöst haben, denn die Antwort beschränkt sich nicht auf das Routing.

Fragen Sie beide Hälften von FreshBooks, was sich seit einem Zeitpunkt geändert hat, bekommen Sie zwei verschiedene Antworten, weil sie zwei verschiedene Arten von Zeitpunkt annehmen. Die Buchhaltungsseite nimmt ein Datum. Die Projektseite nimmt einen Zeitstempel.

Auf Buchhaltungsressourcen tragen die Between-Filter einen Vorbehalt, in den Worten von FreshBooks: „Ein besonderer Hinweis zu Betweens auf Datums-Zeit-Spalten wie ‚updated‘: diese haben in der Regel nur tagesgenaue Auflösung und nehmen die Eingabeform YYYY-MM-DD.“

Auf der Projektseite ist dieselbe Idee ein vollständiger Zeitstempel. FreshBooks dokumentiert updated_since auf Zeiteinträgen als Wert, der „im ISO-8601-Format vorliegen muss“, und das eigene Beispiel trägt Sekunden.

Der praktische Unterschied ist die Größe der kleinsten Frage, die Sie stellen können. Ein Abgleich, der alle fünfzehn Minuten läuft, kann die Projektseite nach den letzten fünfzehn Minuten fragen. Auf der Buchhaltungsseite ist das schmalste verfügbare Fenster der heutige Tag, und der wird den ganzen Tag über größer.

Das ist der Teil der Naht, den keine Schicht entfernt. Die Kennungen aufzulösen ist echte Arbeit, und sie lässt sich einmal hinter einer Schnittstelle erledigen. Einen Zeitstempel zu erfinden, den die Buchhaltungsseite nie erfasst hat, ist eine andere Art von Anfrage, und die kann niemand bedienen.

Die Entwurfsentscheidung landet also so oder so bei Ihnen. Entweder Ihr Buchhaltungsdurchlauf greift einen ganzen Tag zurück und Sie nehmen in Kauf, Datensätze erneut zu lesen, die Sie schon haben, oder er greift weiter zurück und Sie nehmen mehr davon in Kauf.

Die Naht taucht auf derselben Dokumentationsseite noch zweimal auf, und beide Male ist es ein Wechsel der Syntax und kein Wechsel der Fähigkeit. Sortiert wird für Buchhaltungs-Endpunkte anders geschrieben als für projektartige.

FreshBooks benennt die Trennung direkt: „Die Form der Sortierung unterscheidet sich leicht zwischen /accounting-Endpunkten und projektartigen Endpunkten.“ Die Buchhaltung nimmt ein Suffix, ?sort=field_name_asc oder ?sort=field_name_desc. Projektartige Endpunkte nehmen ein führendes Minus, ?sort=field_name gegen ?sort=-field_name.

Die Suche trennt sich genauso. Buchhaltungsressourcen nehmen Parameter in eckigen Klammern, die url-kodiert werden müssen, in der Form ?search[key]=value. Projektartige Ressourcen nehmen einfache Query-Parameter, etwa ?complete=true oder ?billed=true.

Nichts davon ist für sich genommen schwierig. Schwierig ist es im Kopf zu behalten, denn ein Helfer, der eine Sortierung oder einen Filter baut, ist genau die Art Code, die man einmal schreibt und überall wiederverwendet, und hier ist derselbe Helfer auf der halben Fläche falsch.

FreshBooks sendet native Events. Acht Ressourcen sind über uns angebunden, und sie tragen drei Verben: created, updated und deleted.

Ein Abonnement ist schmal, und es gilt je Kunde. Unser Create-Aufruf nimmt eine resource und einen eventType je Abonnement, der Bestand, den Sie betreiben, ist also ein Raster aus Ressourcen und Verben, multipliziert mit jedem verbundenen Account.

Die eigene Event-Tabelle von FreshBooks ist breiter als die angebundene Menge. Sie führt fünfzehn Substantive, darunter project und time_entry, Events gibt es also auf beiden Seiten der Naht, auch wenn die acht angebundenen alle auf der Buchhaltungsseite liegen.

Sie hat außerdem ein viertes Verb. sendByEmail existiert auf Rechnungen und Angeboten, und dass eine Rechnung an einen Kunden gemailt wird, ist ein echter Moment in einer Forderung. In einem Vokabular aus created, updated und deleted hat es keine Entsprechung.

Die Zustellung hat drei Kanten, die vor dem ersten Kunden in den Code gehören, und FreshBooks dokumentiert alle drei. Eine Zusage zur Geschwindigkeit gibt es überhaupt nicht: „die Zustellung kann zwischen wenigen Sekunden und mehreren Minuten liegen.“

Die zweite Kante ist die, die Teams erwischt. Alles außer einem 2xx zählt als Fehlschlag, und FreshBooks benennt den Fall, an den man nicht denkt: „einschließlich 3xx-HTTP-Weiterleitungscodes“. Ein Endpunkt, der eine Weiterleitung auf seinen kanonischen Host beantwortet, ist die ganze Zeit still gescheitert.

Die dritte ist ein Timeout von zehn Sekunden, und das Gegenmittel steht im selben Absatz: „erwägen Sie, die Verarbeitung in der Anwendung zurückzustellen, bis eine Antwort auf das Webhook gesendet wurde.“ Wiederholte Fehlschläge verwerfen die Nachricht, und eine lange Serie davon kann das Webhook deaktivieren, bis Sie den Verifizierungs-Token erneut senden.

Jeder Callback trägt einen X-FreshBooks-Hmac-SHA256-Header, und ihn zu prüfen ist die Stelle, an der eine korrekte Implementierung trotzdem scheitert. Der Digest wird nicht über die Bytes gebildet, die Sie empfangen haben.

Die Nutzlast kommt form-urlencoded an, als Parameter in Query-Form. Die Signatur wird beschrieben als HMAC über „eine UTF-8-kodierte JSON-Zeichenkette der Parameter unter Verwendung des Verifier-Keys“. Sie kodieren die Parameter also erneut als JSON, und der genaue Wortlaut dieses JSON ist die Eingabe.

Zwei Details entscheiden, ob Ihr Digest passt. FreshBooks wandelt jeden Wert zuerst in eine Zeichenkette um, die numerischen IDs stehen also in Anführungszeichen. Und die Serialisierung trägt Leerzeichen, was die Dokumentation ausschreibt, weil sie es muss.

Das Signatur-Secret wird nie als solches ausgegeben. Wenn Sie einen Callback registrieren, sendet FreshBooks einen Verifizierungscode an die URL, und Sie senden ihn zurück, um den Besitz zu bestätigen. Derselbe Code ist danach der Signaturschlüssel: „er wird als Secret verwendet, um die Signaturen zu berechnen, mit denen geprüft wird, ob Webhooks von FreshBooks stammen“.

Der Wert, den Sie für einen einmaligen Handshake-Token halten könnten, ist also das langlebige Secret für jedes folgende Event. Ihn zu speichern ist nicht optional, und er gehört dorthin, wo Ihre anderen Signaturschlüssel liegen, statt in eine Logzeile über das Onboarding. Wie Fehlschläge dieser Art aussehen, sobald sie vereinheitlicht sind, steht auf der Seite, auf der ein Fehlermodell beschrieben ist.

FreshBooks deckelt eine Seite bei 100 Datensätzen und sagt Ihnen nicht, wenn es das getan hat. Die Dokumentation benutzt das Wort selbst: „per_page wird stillschweigend bei 100 gedeckelt“.

Das eigene Beispiel ist eindeutig. Eine Anfrage mit ?per_page=2000 ist kommentiert mit „gibt nur 100 Rechnungen zurück“. Es gibt keinen Fehler, keine Warnung und keinen Header, der sagt, dass die Anfrage geändert wurde.

Damit ist der Fehlschlag ein Korrektheitsproblem und kein Performance-Problem. Ein Abgleich, der nach allem fragt und liest, was zurückkommt, ist im Test vollständig, wo der Kunde vierzig Rechnungen hat, und im Produktivbetrieb still falsch, wo er viertausend hat.

Das Zweite, was ein Sammelaufruf standardmäßig nicht liefert, sind die verknüpften Daten. In den Worten von FreshBooks „erfordern einige Beziehungen zusätzliche Aufrufe, damit wir sie vollständig füllen“, und eine Anfrage muss sie ausdrücklich benennen.

Eine Rechnung, die ohne ?include[]=lines gelesen wird, liefert den Kopf und keine Positionen zurück, und das ist die zweite Fassung derselben stillen Lücke: eine Antwort, die korrekt geformt und unvollständig ist. Mehrere Includes lassen sich in einem Aufruf kombinieren.

FreshBooks fährt gewöhnliches OAuth 2.0 mit dem Authorization-Code-Flow, und eine Regel darin ist nicht gewöhnlich. Refresh Token rotieren, und je Nutzer und Anwendung existiert zu jedem Zeitpunkt nur einer davon.

Die Dokumentation ist zu allen drei Teilen präzise: „Refresh Token leben ewig, sind aber einmalig verwendbar, und je Nutzer und Anwendung kann immer nur ein Refresh Token aktiv sein … alle alten Refresh Token werden sofort ungültig.“

Die Asymmetrie darunter macht daraus ein Nebenläufigkeitsproblem statt eines Speicherproblems. Bearer Token verhalten sich anders: „Sie könnten zu einem gegebenen Zeitpunkt mehrere gültige Bearer Token haben.“

Zwei Worker, die denselben Kunden gleichzeitig aktualisieren, bekommen also beide erfolgreich einen Bearer Token, und nur einer von beiden hält danach einen brauchbaren Refresh Token. Der andere hält einen toten, und der Weg zurück ist, dass der Kunde Ihre Anwendung erneut von Hand autorisiert. Refreshes gehören hinter eine Sperre je Kunde.

Scopes haben eine verwandte Eigenschaft, die umso mehr kostet, je später Sie ihr begegnen. Sie lassen sich nicht an Ort und Stelle erweitern: „Es ist nicht möglich, Scopes aus einem bestehenden Access Token zu entfernen. Der einzige Weg, zugestimmte Scopes zu reduzieren oder zu ergänzen, ist, den Token zu widerrufen und den App-Autorisierungsablauf erneut zu beginnen.“

Ein Scope, den Sie beim Onboarding nicht angefragt haben, ist ein Scope, den Sie bekommen, indem Sie einen bestehenden Kunden erneut durch die Zustimmung schicken. Die Scope-Grammatik lautet entity:object:action über 22 Objekte, mit zwei Aktionsklassen, wobei write das Anlegen, Bearbeiten, Archivieren und Löschen zusammen abdeckt.

Der größte Teil der Naht lässt sich abfangen, und die Teile, die es nicht tun, teilen sich sauber auf. Vier Dinge hören auf, Ihre zu sein:

• Das Routing der Kennungen. Beide Werte werden beim Verbinden aufgelöst und je Kunde gespeichert, keine Aufrufstelle muss also wissen, ob die gewünschte Ressource über Account oder über Business adressiert wird.
• Die zwei Query-Grammatiken. Eine Sortierform und eine Filterform erreichen Ihren Code, statt eines Suffix auf der einen Hälfte der Fläche und eines Minuszeichens auf der anderen.
• Paginierung und Includes. Der stille Deckel und die fehlenden Positionen sind dieselbe Fehlerklasse, und beide werden behandelt, bevor eine Antwort in das Common Data Model normalisiert wird.
• Die Token-Rotation und ihr Wettlauf. Ein einmalig verwendbarer Refresh Token je Nutzer und Anwendung ist ein Sperrproblem, und es wird hier einmal gelöst statt in jeder Anbindung.

Drei Dinge bewegen sich nicht, und zwei davon sind Entscheidungen statt Arbeit:

• Die Auflösung des Buchhaltungs-Deltas. Ein Tag ist das kleinste Fenster, das FreshBooks auf dieser Seite erfasst. Keine Schnittstelle kann aus einem Datum einen Änderungszeitstempel machen, wie weit jeder Durchlauf zurückgreift und wie viel erneutes Lesen Sie in Kauf nehmen, bleibt also Ihre Wahl.
• Ihr Empfänger. Das Budget von zehn Sekunden, die Warteschlange dahinter und die Signaturprüfung gehören Ihnen, weil sie auf Ihrer Infrastruktur laufen. Antworten Sie zuerst und verarbeiten Sie danach, und denken Sie daran, dass eine Weiterleitung als Fehlschlag zählt.
• Welche Berechtigungen Sie anfragen. Scopes lassen sich nicht erweitern, ohne einen Kunden erneut durch die Zustimmung zu schicken, die Liste, die Sie beim Onboarding anfragen, ist also eine Entscheidung über das Produkt, das Sie bauen wollen, und keine Einstellung.

Eine Anmerkung zu den Objekten selbst. Kunden und Lieferanten sind heute lesend und schreibend unterstützt, und der größte Teil des übrigen Katalogs ist als auf Anfrage markiert, was verfügbar auf Anfrage bedeutet statt nicht verfügbar. Wenn Eingangsrechnungen oder Gutschriften für Ihr Produkt zählen, fragen Sie den Lesezugriff zusammen mit dem Event an, denn das sind zwei getrennte Anfragen.