Pennylane anbinden: Vorab vereinbarte Scopes und vier Wochen Changelog

Bei den meisten Buchhaltungsplattformen registrieren Sie eine Anwendung selbst, klicken sich durch einen Zustimmungsdialog und haben innerhalb von zehn Minuten funktionierende Zugangsdaten. Pennylane arbeitet anders. Für Integrationspartner gibt es keine Selbstregistrierung, und der erste Schritt beim Bauen ist eine E-Mail statt eines Formulars.

Pennylane sagt es in seinem OAuth-Leitfaden deutlich: „Bevor Sie OAuth verwenden, registrieren Sie Ihre App bei Pennylane, indem Sie unser Partnerschaftsteam kontaktieren.“ Erst nach dieser Prüfung erhalten Sie eine Client-ID und ein Secret.

Dieselbe Voraussetzung steht in den Pennylane-Integrationsnotizen von maesn: Es ist „notwendig, eine direkte Beziehung zu Pennylane aufzubauen und Ihre Client-Zugangsdaten von dort zu erhalten“. Wie die Verbindung danach Objekt für Objekt aussieht, steht auf der Seite zur Pennylane-Schnittstelle.

Diese Wartezeit lässt sich nicht verkürzen, sie gehört also in den Projektplan statt in den Sprint. Sie ändert auch, wie Ihr Weg zur Sandbox aussieht, denn der Sandbox-Zugang folgt derselben Aufteilung.

Für Pennylane gibt es eine Sandbox von maesn, neben denen für DATEV, Fortnox und Twinfield, und sie zählt hier mehr als sonst, weil Pennylane keinerlei kostenlosen Testzugang veröffentlicht. Der dokumentierte Weg dorthin lautet „bitte kontaktieren Sie uns“, sie verkürzt die Wartezeit bei Pennylane also, ohne das Gespräch zu ersetzen.

Die Scope-Liste ist der Teil des Gesprächs, der es überdauert. Pennylane bittet Sie, „ihnen die Details Ihrer Integration einschließlich der benötigten Scopes zu übermitteln“, und was Sie dort benennen, trägt Ihr Token später im Produktivbetrieb.

Die Grammatik ist bewusst grob. Ein Scope ist entweder resource:readonly, was Pennylane als „Nur-Lese-Zugriff (nur GET-Endpunkte)“ definiert, oder resource:all, also „Vollzugriff (Lesen + Schreiben + Löschen)“. Ein Nur-Anlegen und ein Nur-Aktualisieren gibt es nicht. Sie wählen je Ressource, nicht je Verb.

Die Verbindung von maesn ist gegen elf davon konfiguriert. Acht sind :all, zwei sind nur lesend und einer trägt gar kein Suffix:

Stellt man diese elf dem gegenüber, was die Verbindung tatsächlich freigibt, wird die Form der Integration sichtbar, bevor Sie eine Zeile schreiben. Zwei Objekte sind heute unterstützt, neunzehn weitere sind auf Anfrage lesbar und sechzehn sind hier gar nicht freigegeben.

Ihre Scope-Liste ist in einem Gespräch vereinbart worden, Ihr Code hat also keine Aufzeichnung darüber, was auf der anderen Seite tatsächlich gewährt wurde. Pennylane beantwortet das direkt: GET /me liefert die aktiven Scopes für Ihr Token zurück, und es ist der eine Endpunkt, der dafür keinen eigenen Scope braucht.

Sobald die Zugangsdaten existieren, ist der Ablauf ein gewöhnlicher Authorization Code Grant gegen app.pennylane.com. Der Token-Tausch ist unauffällig, und die Zahl, die Sie aus der Antwort lesen, ist expires_in.

Zwei Dauern, von derselben Seite: „Access-Tokens laufen nach 24 Stunden ab“ und „Refresh-Tokens sind 90 Tage gültig“. In Sekundärtexten über dieses System kursiert eine Gültigkeit von sieben Tagen, die zu keiner der beiden Zahlen passt und auch zu nichts anderem in der Dokumentation von Pennylane.

Die Rotation selbst ist gewöhnlich. Genau lesen sollte man, wie unmittelbar Pennylane sie vollzieht, denn das entscheidet, ob Ihre Refreshes serialisiert werden müssen.

Es gibt eine zweite Folge, die erst im Betrieb auftaucht. Ein Refresh-Token übersteht 90 Tage Inaktivität, eine Integration, die still wird, behält ihre Zugangsdaten also weit länger, als das Access-Token mit seinen 24 Stunden nahelegt. In Kombination mit dem Changelog-Fenster wird daraus ein Problem, und der Abschnitt zum Abgleich weiter unten arbeitet es durch.

Produkte mit mehreren Mandanten haben hier eine Entscheidung mehr. Pennylane stellt Tokens in zwei Kontexten aus: Ein Unternehmens-Token erreicht ein einzelnes Unternehmen, während ein Kanzlei-Token „auf Ressourcen über mehrere von der Kanzlei betreute Mandantenunternehmen hinweg zugreifen kann“.

Die sichtbare Menge „hängt davon ab, wer den Zugriff gewährt hat und welche internen Berechtigungen gelten“. Für ein Produkt, das an Kanzleien verkauft, entscheidet dieser Unterschied zwischen einer Verbindung und hunderten.

Ein Geschäftsdokument in v2 anzulegen heißt einen Aufruf je Objekt, und Pennylane bindet das direkt an die Scope-Liste zurück, die Sie am Anfang vereinbart haben: „jedes Objekt muss separat angelegt werden, über einen eigenen Endpunkt. Das wird auch durch die Granularität der Scopes erzwungen.“

Pennylane nennt das Beispiel, auf das es bei der Fakturierung ankommt. Ein Kunde lässt sich nicht zusammen mit einer Rechnung anlegen: Es ist „zwingend, zuerst den Kunden anzulegen“ und dann dessen ID zu übergeben. Dateianhänge laufen genauso: an /file_attachments hochladen, die ID nehmen, und sie beim Import als file_attachment_id referenzieren.

Die Zahl der Roundtrips je Geschäftsdokument ist also eine Funktion davon, wie viele Objekte es berührt, und jedes dieser Objekte braucht seinen eigenen Scope. Das ist derselbe Satz wie im Scope-Abschnitt, von der Schreibseite her erreicht.

Zwei Dinge übernimmt v2 laut den unterstützten Anwendungsfällen von Pennylane überhaupt nicht: eine Anzahlungsrechnung oder einen Lieferschein anlegen. Steht eines davon in Ihrem Produktablauf, klären Sie es vor dem zweiten Sprint.

Die Fehlerbehandlung von Pennylane ist wirklich gut, mit einem konsistenten JSON-Schema, einem nützlichen details-Objekt und einer dokumentierten Retry-Matrix. Teuer sind die Fälle, die sie nie erreichen, weil sie mit einem Erfolgscode antworten.

Der erste ist die Paginierung. Version zwei ist auf Cursor umgestiegen, und der Cursor trägt weniger, als es aussieht:

Der zweite ist der Changelog-Checkpoint, und Pennylane hebt ihn als ausdrückliche Warnung hervor: „Aktualisieren Sie Ihren start_date-Checkpoint erst, wenn Sie vollständig durch alle Seiten paginiert haben (has_more: false). Brechen Sie mitten in der Paginierung ab, setzen Sie bei Ihrem letzten next_cursor wieder auf.“ Wer den Checkpoint nach Seite eins von vier weiterstellt, verliert die Seiten zwei bis vier, und nirgends meldet etwas eine Lücke.

Der dritte ist die Dublette beim Schreiben. Pennylane sagt es direkt: „Wird dieselbe Anfrage zweimal gesendet, können Sie Dubletten erzeugen“, und Idempotenz wird „an Anlage-Endpunkten nicht erzwungen“, etwa an /customer_invoices und /ledger_entries. Es gibt genau eine Ausnahme, und sie ist eigentümlich spezifisch.

Was bleibt, ist der gewöhnliche Teil, und der ist gut gebaut. Ein 403 heißt, dem Token fehlt der Scope, mit dem fehlenden Namen in der Meldung. Ein 422 heißt, eine Geschäftsregel ist verletzt, mit dem auslösenden Feld in details.

Pennylane veröffentlicht außerdem, welche Codes einen Retry verdienen, 429 und 500 und 503, und welche nie, 400 und 401 und 403 und 404 und 422. Sie über Systeme hinweg auf ein Verhalten abzubilden, dafür gibt es ein Fehlermodell.

Pennylane sendet Events. Es sendet drei, sie sind in der Beta, und Pennylane rät selbst davon ab, sich heute schon auf sie zu stützen: „Die Webhook-Funktion ist in der Beta. Wir empfehlen, in dieser Phase auf die Changelog-Endpunkte zurückzugreifen.“

Die drei sind customer_invoice.e_invoicing_status_updated, dms_file.created und supplier_invoice.e_invoicing_received. Alle drei drehen sich um den E-Rechnungs-Status oder den Eingang eines Dokuments, alles sehr französische Anliegen und angesichts der Rechnungsstellungsregeln des Landes ein sinnvoller Anfang.

Achten Sie darauf, was in dieser Liste fehlt. Keines der zwei Objekte, die diese Verbindung heute unterstützt, Kunden und Lieferanten, meldet seine eigenen Änderungen. Dafür fragen Sie ab, und dafür gibt es die Changelog-Endpunkte. Genau das muss das Event-Modell umgehen, wenn ein System für ein Objekt kein Event anbietet.

Die Changelog-Endpunkte decken sieben Ressourcen ab, darunter beide Live-Objekte: customer_invoices, supplier_invoices, customers, suppliers, products, ledger_entry_lines und transactions. Jede Änderung liefert Ihnen eine ID und eine Operation, das Muster ist also ein Delta-Lesezugriff gefolgt von einem Batch-Abruf.

Dann die Grenze, die Ihre Architektur entscheidet: „Änderungen werden 4 Wochen lang vorgehalten“, und Sie „können keine Änderungen anfordern, die älter als 4 Wochen sind“. Diese Zahl zählt neben dem Refresh-Token mit seinen 90 Tagen, weil beide unterschiedlich schnell ablaufen. Zugangsdaten überstehen 90 Tage Stille. Ein inkrementelles Nachholen ist nach 28 Tagen nicht mehr möglich. Eine Integration kann also fünf Wochen pausieren, sich ohne einen einzigen Fehler wieder verbinden und trotzdem zwei Wochen Änderungen vermissen, die sie nicht mehr anfordern kann.

Die Ratenbegrenzung gibt das Tempo dieser Wiederherstellung vor, und die dokumentierte Angabe ist ein Fenster statt einer Rate je Sekunde. Pennylane erlaubt „bis zu 25 Anfragen alle 5 Sekunden“, angewendet „auf Token-Ebene“, in der Sandbox wie im Produktivbetrieb, und „alle Endpunkte ... sind betroffen“. Je Token ist wichtig: Das Budget wächst mit der Zahl der angebundenen Unternehmen, statt sich über Ihre ganze Anwendung zu verteilen.

Was ein Wiederherstellungslauf kostet, folgt allein aus diesen zwei Zahlen. 10.000 Änderungen bei der Standard-Seitengröße von 20 zu lesen sind 500 Changelog-Aufrufe plus 500 Batch-Lesezugriffe, also 1.000 Anfragen, das sind 40 Fenster und rund 200 Sekunden.

Dieselbe Wiederherstellung kostet beim dokumentierten Maximum von 1.000 je Seite 20 Anfragen und passt in ein einziges Fenster. Der Standardwert ist die teure Wahl, und er ist der, den Sie bekommen, wenn Sie limit nicht mitgeben.

Ein hilfreiches Detail beim Justieren: Die Header ratelimit-limit, ratelimit-remaining und ratelimit-reset kommen auch bei erfolgreichen Antworten zurück, nicht nur bei einem 429. Das verbleibende Budget ist lesbar, bevor Sie die Obergrenze erreichen, Sie können sich also daran ausrichten.

Eine vereinheitlichte Schnittstelle übernimmt das meiste von dem, was die Abschnitte oben beschreiben. Die Partnerbeziehung übernimmt sie nicht, und diese Aufteilung entscheidet den Zeitplan eines Pennylane-Projekts, denn die Hälfte, die bei Ihnen bleibt, trägt die längste Vorlaufzeit.

Was die Verbindung Ihnen abnimmt:

• Der Token-Lebenszyklus samt Rotationsfalle. Der Ablauf nach 24 Stunden, das einmal verwendbare Refresh-Token und die Serialisierung, die verhindert, dass zwei Worker einander die Zugangsdaten zerstören.
• Eine Form für Kunden und Lieferanten. Die zwei unterstützten Objekte kommen in derselben vereinheitlichten Form an wie bei jedem anderen angebundenen System, die Zuordnung wird also einmal geschrieben.
• Das Takten gegen das Token-Budget. Anfragen werden gegen die Obergrenze von 25 je 5 Sekunden eingereiht und wiederholt, ein 429 erreicht Ihren Code also nie.
• Die Cursor-Behandlung mit dem Filter daran. Der Fehlerfall aus dem Leseabschnitt ist nichts mehr, woran sich jede Integration erinnern muss.
• Eine Sandbox für ein System ohne kostenlosen Testzugang. Pennylane bietet kein Testkonto an, und eine Umgebung von maesn gibt es auf Anfrage.

Was bei Ihnen bleibt, und der erste Punkt ist eine kaufmännische Aufgabe statt einer technischen:

• Die Beziehung zu Pennylane. Client-ID und Secret werden Ihnen ausgestellt, vom dortigen Partnerschaftsteam, gegen Ihre Scope-Liste. Dieses Gespräch kann niemand an Ihrer Stelle führen, und es ist die lange Vorlaufzeit im Plan.
• Die Entscheidung über die Scope-Liste. Welche Objekte Ihr Produkt braucht, ist eine Produktfrage. Sie ist zudem nahezu unumkehrbar, denn die Liste später zu erweitern heißt, zurück zum selben Team zu gehen.
• Ihre eigene Regel für den Abgleich jenseits von 28 Tagen. Das Changelog-Fenster gehört Pennylane, und was Ihr Produkt tut, wenn es überschritten ist, gehört Ihnen.
• Die Deduplizierung beim Schreiben. Da es außerhalb des Imports von Lieferantenrechnungen keinen Idempotenzschlüssel gibt, bleibt es Ihre Aufgabe, dieselbe Anlage nicht zweimal zu senden.