Procountor anbinden: Zwei Autorisierungswelten, und eine davon hat eine Decke

Das Erste, was man über Procountor wissen muss, ist nicht technisch. Sie können an dem Nachmittag, an dem Sie sich dafür entscheiden, nicht loslegen. Procountor gibt Zugangsdaten über ein Formular aus, und die Antwort kommt nach drei bis vier Tagen per E-Mail und per SMS zurück.

Das Formular fragt, was Ihre Integration tut, welche Objekte sie bewegt, in welche Richtung und für welche Länder, dazu die Weiterleitungsadresse, die der Ablauf benutzt. Nichts davon ist schwer. Alles davon liegt zwischen Ihnen und Ihrem ersten Aufruf.

Die Produktion ist ein zweiter Antrag derselben Art, mit eigener Wartezeit, und der Testzugang geht nicht in sie über. Unser eigener Entwickler hat gegen die Schnittstelle gebaut, während er auf die erste Antwort wartete, und konnte bis dahin keine einzige Anfrage ausführen.

Procountor bietet einen Authorization-Code-Ablauf für Anwendungen mit einem Nutzer davor und einen Client-Credentials-Ablauf für alles, was von allein läuft. Der zweite benutzt einen API-Key als Zugangsmittel, und dieser Key ist zugleich an einen Nutzer, eine Firma und eine Clientanwendung gebunden.

Bis hierhin ist das gewöhnlich. Der Satz, der Ihre Architektur entscheidet, ist der nächste, und Procountor schreibt ihn unverblümt hin: ein Access Token aus dem Client-Credentials-Ablauf erreicht keinen Endpunkt, der Zwei-Faktor-Authentifizierung verlangt, weil diese Endpunkte einen aktiv anwesenden Nutzer brauchen.

Procountor nennt das Beispiel selbst, und es ist das kommerziell entscheidende. Eine Integration darf eine Eingangsrechnung allein ändern. Die Zahlung zu dieser Rechnung muss eine Person freigeben, die Procountor Key besitzt, und der wird auf eine natürliche Person ausgestellt und lässt sich keinem Dienst übergeben.

Teuer wird es dadurch, dass die Grenze nicht maschinenlesbar ist. Über 192 Operationen der veröffentlichten Spezifikation wird Zwei-Faktor-Authentifizierung genau einmal genannt. Welche Endpunkte dahinterliegen, steht in Prosa, und ein Team, das mit voller Automatisierung plant, entdeckt die Linie deshalb meist zur Laufzeit.

Ein Procountor-Nutzer kann zu mehreren Firmen gehören, was auf den meisten Systemen eine Kennung bedeutet, die man nach dem Authentifizieren auflöst und danach in jeder Anfrage mitführt. Procountor klärt das früher. Während der Anmeldung zeigt es eine eigene Auswahlseite, und die Verbindung, die zurückkommt, ist an die Firma gebunden, die der Nutzer gewählt hat.

Das klärt das eine und begrenzt das andere. Es gibt nach dem Authentifizieren nichts aufzulösen und keine Firmen-ID, die Sie durch Ihre Aufrufe fädeln müssen. Dafür ist eine Verbindung genau eine Firma, und ein Kunde mit dreien sind drei Verbindungen, jede von einer Person im Browser angelegt.

Es erklärt auch etwas, das Ihnen beim Lesen unserer Dokumentation auffallen wird: Procountor steht dort auf keiner der beiden Ablauflisten, weil es weder eine Firmensuche noch einen Auswahlschritt von uns braucht. Der Hersteller erledigt das bereits.

Der Authorization-Code-Ablauf liefert ein Access Token mit einer Stunde Laufzeit und ein Refresh Token mit sechs Monaten. Das Refresh Token rotiert nicht, der Wert, den Sie am ersten Tag speichern, ist also derselbe, den Sie im fünften Monat noch halten.

Worauf es ankommt, ist die Liste der Dinge, die es vorzeitig beenden, denn nur das erste ist die Uhr. Die anderen vier sind Handlungen, ausgeführt von Ihrem Kunden, von dessen Administrator oder von Ihrem eigenen Authentifizierungsablauf.

Die letzte Zeile ist die, die ein Entwurf auslösen kann, ohne es zu merken. Bei jeder Authentifizierung entsteht ein Refresh Token, und das lässt sich nicht vermeiden, also steigt der Zähler, sooft derselbe Endkunde erneut durch den Ablauf geschickt wird. Jeden Kunden einmal zu authentifizieren und das Ergebnis zu behalten, ist das, was die Zahl dort hält, wo sie hingehört.

In allen fünf Fällen ist die Folge dieselbe, und sie gehört in Ihren Entwurf. Das gespeicherte Refresh Token ist ungültig, und weil Procountor im Autorisierungsschritt eine Person vorsieht, kann es nichts still erneuern. Ihr Kunde authentifiziert sich erneut. Was Sie das kostet, ist ein Weg in Ihrem Produkt für eine Verbindung, die neu autorisiert werden muss, und eine Meldung, die das sagt.

Procountor modelliert Ausgangsrechnung, Eingangsrechnung und Auftrag nicht als getrennte Dinge. Es modelliert ein Rechnungsobjekt mit einem Typ darauf, und dieser Typ nimmt sieben Werte an. Eine Ausgangsrechnung, eine Eingangsrechnung, beide Auftragsarten, eine Reisekostenabrechnung, eine Gebührenaufstellung und eine periodische Steuererklärung sind dieselbe Form mit einem anderen Etikett.

Der Buchungsbeleg macht dasselbe in größerem Maßstab, mit sechzehn Werten, darunter Lohn, Arbeitgeberbeiträge und ein Kontoauszug, der als Beleg dient. Den Typ falsch zu setzen, erzeugt einen gültigen Beleg der falschen Art.

Zwei kleinere Dinge gehören in denselben Abschnitt, weil sie dasselbe Schema betreffen. Erstens ist eine ID innerhalb einer Firma eindeutig und sonst nirgends, zwei Firmen können also Rechnungen mit identischen IDs führen. Procountor benennt die Firma und die Ressourcen-ID zusammen als das Paar, das im ganzen System eindeutig ist.

Zweitens verlangt das Ändern einer Rechnung eine invoiceVersion, ein Zeitstempel, der als Zeichenkette geführt wird. Sie senden den empfangenen Wert unverändert zurück, sonst wird der Schreibvorgang abgelehnt. Es ist optimistische Nebenläufigkeitskontrolle im Gewand eines Datums.

Über das Common Data Model erreicht nichts davon Ihr Produkt: die sieben Belegarten kommen als die Objekte an, die sie tatsächlich sind, und die Frage nach der Kennung ist beantwortet, bevor Sie den Datensatz sehen.

Die Aufteilung steht in keiner Dokumentation, und sie ist der Grund, aus dem es diesen Abschnitt gibt. Procountor nach Steuersätzen zu fragen, liefert eine Antwort mit zwei Arrays. Das eine hält die Prozentsätze. Das andere hält die Steuercodes. Nichts in der Antwort sagt, welcher Code zu welchem Prozentsatz gehört.

Die meisten Buchhaltungssysteme geben Ihnen einen Steuersatz und seinen Code als ein Objekt, und die meisten Datenmodelle sind so gebaut, unseres eingeschlossen. Gegen Procountor lässt sich dieses Modell aus einer einzelnen Antwort nicht füllen, und nachgelagert füllt es auch nichts. Die Zuordnung ist schlicht nichts, was die Antwort mitträgt.

Die Kosten der Aufteilung tauchen in keiner Schätzung auf, weil nichts sie ankündigt. Sie rufen einen Endpunkt auf, Sie bekommen eine gültige Antwort, und erst beim Mapping zeigt sich die Lücke.

Die Anbindung über die Procountor-Schnittstelle mit maesn ändert die Form, nicht die Tatsache. Steuerdaten kommen als eine Liste statt als zwei an, in derselben Form, die jedes andere angebundene System benutzt, und jeder Eintrag trägt den Satz oder den Code, mit dem er kam. Die Beziehung wird von Procountor nicht veröffentlicht, also erfindet sie nachgelagert niemand, und ein Anwendungsfall, der die Paarung braucht, stellt sie bewusst her.

Procountor veröffentlicht Webhooks, und die Liste ist kurz. Es gibt drei Ereignistypen: eine Zahlung wurde aktualisiert, eine Zahlung wurde gelöscht, ein Nutzer wurde aktualisiert. Abonnements werden mit HMAC über SHA512 authentifiziert, und je Ereignistyp ist ein Webhook erlaubt.

Für eine Buchhaltungsintegration, die Konten, Kontakte und Steuersätze liest, hilft keines dieser drei. Änderungserkennung ist ein Lesevorgang, den Sie einplanen, und das Intervall wählen Sie.

Die Paginierung ist dünner, als die Dokumentation auf den ersten Blick nahelegt. Über die Spezifikation ausgezählt tragen 22 von 101 Leseoperationen überhaupt Paginierungsparameter, in vier verschiedenen Kombinationen, und der Rest hat keine. Wo es Paginierung gibt, existieren zwei Mechanismen, ein Cursor und eine Seitennummer mit einer Größe, die oft auf fünfzig voreingestellt ist.

Unser Entwickler hat die praktische Hälfte davon ergänzt: manche Listen-Endpunkte liefern keine Gesamtzahl zurück, was ihm bei den Konten aufgefallen ist. Sie können durch sie paginieren, und Sie können vorher nicht sagen, wie weit Sie gehen müssen.

Das Anfragelimit in der Produktion liegt bei 60 pro Sekunde je Client, und Procountor schreibt, dass ein Überschreiten zur Aussetzung des Dienstes für diesen Client führen kann. Das ist eine härtere Folge als der übliche abgelehnte Aufruf, also muss der Zeitplan das Limit einhalten, bevor die Fehlerbehandlung es überhaupt zu sehen bekommt.

Geplant über einen Katalog von Systemen zu lesen, die alle anders paginieren, ist genau die Arbeit, die ein Weg, zu filtern und zu paginieren, abnimmt. Die Schleife, die Sie einmal schreiben, ist die Schleife, die Sie auf das nächste System richten.

Alles oben ist echte Arbeit, und das meiste davon ist dieselbe Arbeit für jeden Kunden, den Sie anbinden. Das ist der Teil, den man einmal macht.

Die Rollenfrage in dieser Spalte ist nur zur Hälfte Ihre. Der Endpunkt für Geschäftspartner führt auf Firmen einen Kunden- oder Lieferantentyp, und der kommt durch. Der Endpunkt für Personen hält Einzelpersonen und führt keinen solchen Typ, eine Kontaktperson kommt also ohne Rolle an. Zu entscheiden, was Ihr Modell mit einem Kontakt ohne Seite macht, ist der Teil, der Ihnen bleibt.

Die Anbindung ist in Schritten gewachsen. Konten, Kontakte und Steuersätze sind seit Juli lesbar, und das Buchen von Buchungsvorschlägen und Auslagen kam im August dazu. Procountor reicht weiter als das, mit einer Lohnabrechnungsfläche, die größer ist als der größte Teil seiner Buchhaltungsfläche, also lohnt es sich, die Objekte Ihres Anwendungsfalls gegen den aktuellen Umfang zu prüfen.