Pennylane-Schnittstelle und API-Integration
Pennylane ist eine französische Buchhaltungsplattform für kleine und mittlere Unternehmen und für die Kanzleien, die mit ihnen arbeiten. Sie deckt Rechnungsstellung, Eingangsrechnungen, Mehrwertsteuer und das Hauptbuch ab und wächst im Heimatmarkt schnell. 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 Pennylane-Anbindung kostet
Pennylane ist das System in diesem Katalog, bei dem nicht der Bau die lange Stange ist. Es sind die Zugangsdaten, und die kommen, bevor Code läuft. Hier steht, was die Integration tatsächlich von Ihnen verlangt, und was Maesn davon abnimmt.
Der Partnerschritt, gemeinsam mit Ihnen gegangen
Pennylane gibt keine Zugangsdaten über ein Formular aus. Das Partnerteam prüft zuerst Ihre Integration, und Client-ID und Secret folgen, sobald diese Prüfung durch ist. Das Secret wird ein einziges Mal angezeigt und lässt sich später nicht abrufen. Es zu verlieren heißt also ein neuer Antrag und kein Zurücksetzen. Maesn geht diesen Schritt mit Ihnen, statt auf ein Formular zu zeigen, und stellt in der Zwischenzeit eine Sandbox bereit: Pennylane veröffentlicht kein kostenloses Testkonto, ohne sie gäbe es also nichts, wogegen man bauen könnte.
Die Obergrenze benannt, nicht beschönigt
Pennylane erlaubt 25 Anfragen alle 5 Sekunden, gezählt je Token und über alle Endpunkte, in der Sandbox wie in der Produktion. Eine einzige Ausgangsrechnung anzulegen kostet mehrere aufeinanderfolgende Aufrufe aus demselben Budget. Maesn übernimmt die Orchestrierung und gibt einen einheitlichen Fehlervertrag für den 429 zurück. Die Wiederholungslogik schreiben Sie also einmal und nicht einmal je System.
Ein Delta-Abruf auf dem Filter, den Sie schon geschrieben haben
Die Webhooks von Pennylane sind in der Beta, die eigene Dokumentation empfiehlt stattdessen die Changelog-Endpunkte, und hier ist heute kein Event freigeschaltet. An die Stelle tritt ein geplanter Lesezugriff auf demselben Filter und derselben Paginierung, die Sie für jedes andere System benutzen, und der Cursor verschwindet in der Vereinheitlichung.
In Ihrem Code kommen ein REST-Aufruf und ein Account-Key an. Das Langsame an Pennylane sind die Zugangsdaten und nicht der Bau, und das ist ein Schritt, den Sie einmal gehen und der für jeden Kunden danach gilt.
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 Pennylane-Ökosystem einem Produkt, das französische Unternehmen und ihre Kanzleien 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 Pennylane-Schnittstelle über Maesn anzubinden
Pennylane direkt anzubinden ist ein überschaubares Projekt, sobald die Zugangsdaten vorliegen. Es durch die Token-Rotation am Leben zu halten, innerhalb eines gemeinsamen Anfragebudgets zu bleiben und danach das nächste System hinzuzunehmen, entscheidet über Ihre Roadmap.
Die Pennylane-eigene Arbeit bleibt hier
Access-Tokens leben 24 Stunden, und jede Erneuerung macht das dabei benutzte Refresh-Token ungültig. Zwei Ihrer Worker, die in derselben Sekunde erneuern, heben sich damit gegenseitig auf und schicken diesen Kunden zurück auf den Zustimmungsbildschirm. Maesn erneuert jeden angebundenen Kunden an einer Stelle und der Reihe nach, das Wettrennen kann also nicht stattfinden, und sendet den Filter erneut, den der Cursor von Pennylane zwischen zwei Seiten fallen lässt. Nichts davon erreicht Ihren Code.
Was eingeschaltet ist, schriftlich
Kunden und Lieferanten kommen lesbar und schreibbar zurück, und das ist das Paar an Geschäftspartnern, mit dem jeder Ablauf für Verbindlichkeiten und Forderungen anfängt. Lesen und Schreiben decken hier dieselbe Liste ab. Ein Datensatz, der aus Pennylane kommt, lässt sich also ohne zweite Zuordnung nach Pennylane zurückschreiben. Alles jenseits dieser Liste ist auf Anfrage verfügbar.
Das nächste System kostet nichts
Sobald Pennylane 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.
Der Zugang zu Pennylane läuft über das Partnerprogramm
Die meisten Anbieter hören bei der API auf. Maesn übernimmt die technische Seite und die Beziehung, und bei Pennylane sind die beiden dasselbe Gespräch: Die Zugangsdaten, die Ihre Integration braucht, sind das Ergebnis der Partnerschaft und nicht etwas, das Sie vorher konfigurieren.
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 Partnerschritt bei Pennylane, von den technischen Anforderungen bis zur Einreichung, statt Ihnen ein Formular und einen Link zu geben.
Die Beziehung kommt vor den Zugangsdaten
Die Dokumentation von Pennylane schickt Entwickler zum Partnerteam, um eine Anwendung zu registrieren, und Client-ID und Secret kommen an, sobald dieser Antrag geprüft ist. Einen Weg in Selbstbedienung zu produktiven Zugangsdaten gibt es nicht, und keine der beiden Seiten veröffentlicht, wie lange die Prüfung dauert. Es gehört also als Vorlaufzeit in den Plan.
Produktive Einträge laufen über OAuth
Ein Firmen-API-Token genügt, um in einer Sandbox etwas auszuprobieren, und die Anleitungen von Pennylane benutzen genau dafür eines. Für eine Integration, die über den Marketplace veröffentlicht wird, verlangt Pennylane stattdessen OAuth 2.0. Der Ablauf, den Sie ausliefern, ist also der aus dem Abschnitt zur Authentifizierung weiter oben und nicht der, mit dem Sie den Prototyp gebaut haben. Das sollte man vor dem Prototyp wissen und nicht danach.
Das Publikum sind französische Unternehmen und ihre Kanzleien
Pennylane sitzt zwischen Unternehmen und den Kanzleien, die deren Bücher führen, und das Partnerprogramm wird aus Frankreich heraus auf Französisch geführt. Vor dieses Publikum stellt ein Eintrag Ihr Produkt, und es lohnt sich zu wissen, welcher der beiden Seiten Sie verkaufen.
Die Integration läuft unter dem Namen Ihres Produkts, und der Partnerstatus gehört Ihnen und nicht uns. Maesn ist die Schicht dahinter.
Wir gehen die Pennylane-Anforderungen und die Einreichung mit Ihnen durch.
Ein eigener Pennylane-Client, für Sie erneuert
Pennylane authentifiziert über OAuth 2.0, und die Anwendung, die Ihre Kunden freigeben, ist Ihre und nicht die von Maesn. Es ist der einfache Redirect-Ablauf: Ihr Kunde besucht einmal den Zustimmungsdialog von Pennylane, und der Account-Key kommt danach zu Ihnen zurück. Ein eigener Schritt zur Firmenauswahl ist nicht nötig, denn ein Pennylane-Token nennt die Firma, auf die es ausgestellt ist, bereits.
- OAuth 2.0
- Client-Zugangsdaten, von Pennylane ausgegeben
Eine Integration, jeder Kunde. Maesn verwahrt die Zugangsdaten und führt Handshake, Rotation und erneute Authentifizierung dahinter aus.
- Ihre Client-Zugangsdaten
- Client-ID und Secret, die Pennylane 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, und das ist der Teil, der beißt
- Access-Tokens leben 24 Stunden. Jede Erneuerung macht das verbrauchte Refresh-Token sofort ungültig und gibt ein neues zurück, und das Erneuerungsfenster schließt nach 90 Tagen. Maesn hält das aktuelle Paar für jeden angebundenen Kunden und erneuert immer nur eines nach dem anderen. Ein Wettrennen zwischen zwei Ihrer Worker kann also niemanden stranden lassen.
Pennylane bindet ein Token entweder an eine Firma oder, bei Kanzleien, an alle Firmen, die diese Kanzlei betreut, und im zweiten Fall muss jeder Aufruf trotzdem die Firma nennen, für die er gilt. Das ist eine Eigenschaft des Tokens und nicht des Ablaufs. Es lohnt sich also, vor dem Entwurf des Verbindungsschritts zu klären, welches der beiden Ihre Kunden halten.
- 1
Ihr Kunde startet in Ihrem Produkt
Sie schicken ihn in den Ablauf, und Maesn öffnet den Zustimmungsbildschirm von Pennylane. 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
Pennylane kehrt zu Maesn zurück
Der Callback Ihres Clients zeigt auf Maesn. Maesn empfängt also den Authorization Code und tauscht ihn gegen das erste Access- und Refresh-Token. Dieser Tausch läuft nie in Ihrem Backend, und Ihr Kunde landet in Ihrem Produkt, ohne etwas einfügen 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.
Jedes System im Katalog authentifiziert anders, und bei Pennylane sind die Zugangsdaten schwer zu bekommen und danach leicht zu verlieren: Ein Refresh-Token, das zweimal benutzt wird, ist weg, und der Endnutzer, der den Account angebunden hat, muss die Zustimmung erneut durchlaufen. Dafür ist Unified Authentication da. Die Rotation, die Speicherung des aktuellen Paares und das serialisierte Refresh werden einmal für alle Systeme erledigt und nicht einmal je System, nichts am Token-Zyklus erreicht also den Code, den Sie schreiben.
Änderungen aus Pennylane kommen nach Ihrem Zeitplan
Die Änderungserkennung bei Pennylane ist ein geplanter Lesezugriff, und es ist derselbe, den Sie für jedes andere System im Katalog ohnehin fahren. Die eigenen Webhooks von Pennylane sind in der Beta, und die Dokumentation empfiehlt für diese Zeit die Changelog-Endpunkte, hier abzurufen ist also die Empfehlung des Herstellers und kein Behelf.
Drei Events, alle in der Beta, und Pennylane rät selbst, solange auf die Changelog-Endpunkte auszuweichen. Ein Changelog-Eintrag meldet eine Ressourcen-ID und eine Operation statt des Datensatzes selbst. Etwas muss das Objekt danach also trotzdem lesen.
Ein geplanter Lesezugriff, mit demselben Filter und derselben Paginierung, die Sie für jedes andere System benutzen. Der Code, der Änderungen auf Pennylane erkennt, ist der Code, den Sie bereits geschrieben haben, nur auf einen anderen Account-Key gerichtet.
Das Intervall ist eine Produktentscheidung mit einer harten Kante dahinter: Pennylane hält vier Wochen Änderungshistorie vor und antwortet auf nichts Älteres. Innerhalb dieses Fensters holt ein Delta-Abruf nach einem Ausfall sauber nach, was ein verpasster Push nie tut. Außerhalb davon bleibt ein vollständiger Abgleich.
Änderungserkennung einmal je System zu schreiben ist die Stelle, an der die Kosten einer direkten Integration am deutlichsten sichtbar werden: eine Schleife für Pennylane, dann noch eine für das nächste System, mit eigener Filtersyntax und einer eigenen Vorstellung davon, was eine Seite ist. Pennylane paginiert mit einem Cursor, der Ihre Position trägt und nicht Ihren Filter, eine Anfrage, die ihn erneut zu senden vergisst, kommt also mit ungefilterten Zeilen zurück statt mit einem Fehler. 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 gehört heute zu Pennylane.
Was Pennylane vorab verlangt
Das meiste auf dieser Liste betrifft die Zugangsdaten und nicht den Code, denn bei Pennylane kommen die Zugangsdaten zuerst. Vier Dinge sollten entschieden sein, bevor Sie anfangen.
- Ein Pennylane-OAuth-Client, ausgestellt von deren Partnerteam
- Keine Registrierung in Selbstbedienung. Pennylane prüft die Integration zuerst und übergibt danach Client-ID und Secret, und das Secret lässt sich hinterher nicht abrufen. Es zu verlieren heißt ein neuer Antrag und kein Zurücksetzen.
- Die elf Scopes, die dieser Client tragen muss
- Kunden, Lieferanten, Ausgangs- und Eingangsrechnungen, das Hauptbuch, Dateianhänge, Kategorien, Produkte und Angebote, dazu Bankkonten und Transaktionen nur lesend. Die Liste steht in der Dokumentation, und sie zu lesen lohnt sich vor der Einreichung und nicht danach.
- Ein Ort für die Bezeichner je Firma
- Die IDs von Kunden, Produkten und Sachkonten sind von einer Pennylane-Firma zur nächsten verschieden, und die Sachkonten folgen dem französischen Kontenrahmen. Verwahren Sie sie je angebundener Firma, denn dasselbe Produkt trägt bei jedem Kunden, den Sie anbinden, eine andere ID.
- Ein Zeitplan, und ein Fenster, in dem er bleiben muss
- Die Änderungserkennung ist ein Lesezugriff, den Sie in einem Intervall fahren. Pennylane hält seine Änderungshistorie vier Wochen und sieht nicht weiter zurück. Eine Integration, die länger stillsteht, braucht also einen vollen Abgleich statt eines Nachholens.
Wir gehen die Zugangsdaten und den Partnerschritt mit Ihnen durch.
Eine Form für Pennylane, und für das nächste System
Pennylane bucht auf dem französischen Kontenrahmen, und seine Bezeichner unterscheiden sich von einem angebundenen Unternehmen zum nächsten. Eine gemeinsame Form hält beides aus Ihrem Code heraus.
Alles Lesbare ist auch schreibbar, und nichts lässt sich aktualisieren
Kunden und Lieferanten sind in beide Richtungen freigeschaltet. Aktualisierungen an Ort und Stelle nicht: Sie können einen Lieferanten anlegen, und es gibt keinen freigeschalteten Weg, ihn danach zu ändern, planen Sie Korrekturen also, bevor Sie den ersten Schreibzugriff planen.
Die Scope-Liste ist breiter als das, was eingeschaltet ist
Der Client, den Sie bei Pennylane registrieren, trägt elf Scopes, von den Rechnungen bis zum Hauptbuch. Über Maesn sind heute Kunden und Lieferanten freigeschaltet. Der Rest dieser Liste ist auf Anfrage verfügbar, sagen Sie uns also, welche Objekte Ihr Anwendungsfall braucht.
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.
Was die Anbindung trägt, kommt im gemeinsamen Common Data Model zurück, ein Kontakt aus Pennylane hat also dieselbe Form wie ein Kontakt aus einem zehnmal so großen System, und der Code, den Sie hier schreiben, ist der Code, den Sie für das nächste wiederverwenden.
Für die Obergrenze entwirft man besser, als sie zu entdecken. Pennylane erlaubt 25 Anfragen alle 5 Sekunden je Token über alle Endpunkte hinweg, und eine einzelne Rechnung braucht mehrere Aufrufe, bis sie zusammen ist, ein Massenlauf trifft die Grenze also lange vor einem einzelnen Abgleich. Wenn das passiert, kommt der 429 mit den Headern, die sagen, wann Sie wiederkommen sollen, und ein Fehlerkontrakt verhindert, dass daraus eine Pennylane-förmige Verzweigung in Ihrem Code wird.
Sagen Sie uns, welche Objekte Ihr Anwendungsfall braucht, und wir bestätigen, was möglich ist.
