Visma eAccounting anbinden: Drei Markennamen, Token für sechzig Minuten und Seiten zu fünfzig Datensätzen

Die erste Frage zu diesem System ist eine nach dem Namen: Welches Produkt sehen Sie sich eigentlich an. Dieselbe Software wird in jedem ihrer Märkte unter einem anderen Namen verkauft, und die Dokumentation ist gerade dabei, den Namen zu wechseln, den sie benutzt.

Die Integrationsdokumentation von maesn beantwortet das in einer Zeile, direkt unter der Kennung des Zielsystems: „Beachten Sie, dass das System in den Niederlanden und in Norwegen unter dem Markennamen eAccounting bekannt ist und in Schweden als Spiris (früher SPCS).“

Der Hersteller ist weiter gegangen. Seine Entwicklerdokumentation heißt inzwischen Spiris/eAccounting, die Client-ID, die Sie erhalten, wird beschrieben als „bei der Registrierung für das Spiris-Partnerprogramm bereitgestellt“, das Produkt wird durchgehend als Bookkeeping & Invoicing/eAccounting geschrieben, und schwedische Partner werden unter einer Adresse auf der Spiris-Domain beantwortet.

Was sich nicht bewegt hat, ist alles, was Sie tippen. Die Scopes heißen ea:api, ea:sales, ea:accounting und ea:purchase, der Host ist eaccountingapi.vismaonline.com, die Pfade sind /v2/…, und das Zielsystem über maesn heißt vismaeaccounting. Eine Umbenennung über der Schnittstelle und ein stabiler Stand darunter ist die brauchbare Art, sich dieses System zu merken.

Welche Objekte diese Verbindung heute erreicht und welche auf Anfrage bereitstehen, steht Objekt für Objekt auf der Seite zur Visma eAccounting Schnittstelle. Sie ist schmaler, als die Marktabdeckung vermuten lässt.

Drei Märkte auf einer Schnittstelle sind das kommerzielle Argument dieses Systems, und es trägt. Was dabei nicht gesagt wird: Die Märkte werden darunter getrennt geführt, und das zeigt sich beim ersten Mal, wenn Sie einen Partnerkontakt brauchen.

Die Supportstruktur des Herstellers bildet die Trennung ab, und sie ist das deutlichste Signal dafür, wie getrennt diese Märkte unter einer Schnittstelle laufen:

Drei getrennte Kontakte auf zwei Domains für eine Schnittstelle. Lesen Sie das als Planungsgröße und nicht als Urteil: Es sagt Ihnen, an welche Tür Sie je Markt klopfen, und dass es nicht dieselbe Tür ist.

Das größere Muster ist eine Eigenschaft der Gruppe. Visma kauft Software und lässt sie unter ihrem eigenen Namen weiterlaufen, weshalb ein einzelnes Herstellerlogo in einer Präsentation darunter immer noch eine eigene Integration je Produkt bedeuten kann.

Die Authentifizierung ist OAuth 2.0 mit dem Authorization Code Flow, und damit ist sie die vertraute Hälfte dieses Systems. Die unvertraute Hälfte ist, dass die Scope-Liste zweimal festgelegt wird, und das zweite Mal in jeder Autorisierungsanfrage, die Sie senden.

Zwei Scopes sind Pflicht. ea:api gewährt überhaupt Zugang zur Schnittstelle, und offline_access sorgt dafür, dass ein Refresh-Token zurückkommt. Alles Weitere geht je Ressourcenbereich, jeweils mit einer Nur-Lese-Variante, und das heißt: Die Grenze dessen, was Ihre Integration je erreichen kann, wird gezogen, bevor Ihr erster Kunde einen Zustimmungsdialog sieht.

Auch ea:accounting und ea:purchase haben _readonly-Varianten, nach demselben Muster wie sales. Und ein Scope gehört zu einem anderen Produkt: vls:api erreicht Vismas Lohnschnittstelle, die sich denselben Identity Server teilt, sodass ein Token beide bedienen kann, solange die Scopes autorisiert wurden.

Zwei Anfrageparameter empfiehlt der Hersteller ungewöhnlich nachdrücklich, und beide gibt es, damit der Ablauf nicht die falsche Firma verbindet:

• prompt=select_account erzwingt die Firmenauswahl, statt die bereits in Visma Online gewählte zu übernehmen. Die Dokumentation nennt ihn „dringend empfohlen“ und sagt, ein Weglassen „kann zu automatischen oder unvorhersehbaren Anmeldungen mit einer bereits ausgewählten Firma führen“.
• acr_values filtert die Auswahl auf Firmen, die tatsächlich Zugang zu diesem Produkt haben, und hält einen Kunden davon ab, ein fremdes Visma-Abonnement zu wählen.

Die praktische Folge dessen, dass Scopes vorab erklärt werden, ist eine Produktfrage und keine Entwicklungsfrage. Sie später zu erweitern heißt, zu jedem verbundenen Kunden für eine neue Zustimmung zurückzugehen, also gehört das, was Ihr Produkt in einem Jahr brauchen könnte, in das Gespräch, bevor der erste Kunde sich verbindet.

Über maesn wird der Scope-Satz einmal mit den Zugangsdaten eingereicht und auf jede Autorisierungsanfrage angewendet, und das ist dieselbe Form, die Unified Authentication jedem anderen System gibt.

Drei Zahlen beschreiben den gesamten Token-Lebenszyklus hier, und die dritte ist der Grund, aus dem Integrationen auf diesem System aufhören zu arbeiten, ohne dass jemand etwas ausgeliefert hätte.

Das Access-Token läuft 60 Minuten nach seiner Ausgabe ab, was die Token-Antwort als expires_in: 3600 angibt. Erneuert wird mit demselben Aufruf und grant_type=refresh_token, und die Antwort hat dieselbe Form, sodass eine Erneuerung neben dem neuen Access-Token auch ein neues Refresh-Token zurückgibt.

Das Refresh-Token selbst ist ab Ausgabe zwei Jahre gültig. Dann kommt die Ausnahme, in den Worten des Herstellers: „Das Refresh-Token bleibt ab dem Tag seiner Ausgabe zwei Jahre gültig. Beachten Sie jedoch, dass das Refresh-Token ungültig wird, wenn der Nutzer sein Passwort ändert.“

Zwei Dinge folgen daraus, und beim zweiten sitzt der Aufwand. Eine Passwortänderung ist in einem kleinen Unternehmen ein gewöhnliches Ereignis, also ist das ein normaler Zustand, für den man entwirft. Und die Dokumentation beschreibt keine Benachrichtigung dafür, also ist das erste Signal, das Ihr Code bekommt, ein 401 beim nächsten Aufruf, zu welcher Stunde auch immer Ihr Scheduler gerade läuft.

Damit wird die erneute Autorisierung eine Produktfläche und kein Fehlerzweig. Irgendetwas in Ihrer Oberfläche muss dem richtigen Kunden sagen können, dass diese Verbindung neu verbunden werden muss, und genau für diesen Zustand gibt es ein Fehlermodell, das ihn einheitlich sichtbar macht.

Es gibt außerdem einen Endpunkt zum Widerruf, der eine Verbindung von Ihrer Seite aus ausdrücklich beendet: POST /connect/revocation mit dem Token und einem optionalen token_type_hint, authentifiziert wie der Token-Tausch. Ein erfolgreicher Aufruf gibt 200 mit leerem Rumpf zurück.

Sammlungs-Endpunkte geben 50 Objekte je Seite zurück, solange Sie nicht mehr anfordern, und das Maximum ist 1.000. Erhöht wird mit $pagesize, durch die Seiten bewegt man sich mit $page, oder Sie folgen dem Link-Antwortheader, der die nächste und die letzte Seite trägt.

Der Teil, der entscheidet, ob ein Abgleich korrekt ist, ist der Umschlag. Eine paginierte Antwort kommt als zwei Felder, ein Meta-Objekt und ein Data-Array, und Meta meldet, wie viel es insgesamt gibt.

Das Filtern ist die andere Hälfte eines geplanten Lesevorgangs, und es ist oData v4 mit einem $filter-Parameter und keine eigene Syntax. Die Operatoren sind der gewöhnliche Satz, Zeichenketten werden ohne Rücksicht auf Groß- und Kleinschreibung verglichen und müssen in Anführungszeichen stehen, und Datumsangaben haben ein festes Format.

Für einen Delta-Abgleich ist das entscheidende Feld ChangedUtc, und der Hersteller führt es als Beispiel für einen Datumsfilter, was es zum natürlichen Gegenstück der Paginierung darüber macht: fragen, was sich bewegt hat, und dann durch die Seiten laufen, bis CurrentPage bei TotalNumberOfPages ankommt.

Über maesn kommen beide Hälften in der Form an, die jedes andere verbundene System benutzt, und genau das heißt ein Weg, zu filtern und zu paginieren in der Praxis: dieselbe Abfrage gegen ein System, das über einen Cursor paginiert, über eine Seitenzahl oder in Schritten von fünfzig Datensätzen.

Die Ratenbegrenzung ist eine Zahl mit einer ungewöhnlichen Einheit: 600 Anfragen pro Minute, und „die Begrenzung wird je Client und Endpunkt/URL geführt“.

Je Endpunkt ändert, wie ein Erstabgleich sich verhält. Ein Worker, der Kunden, Lieferanten und Artikel liest, teilt sich kein Budget über die drei, also bringt Parallelisieren über Ressourcen hinweg Durchsatz, den Parallelisieren innerhalb einer Ressource nicht bringt. Es heißt auch, dass ein einzelner heißgelaufener Endpunkt gedrosselt werden kann, während der Rest Ihrer Integration unberührt bleibt, und das ist in einem Log schwerer zu sehen als eine globale Begrenzung.

Ein Überschreiten gibt 429 zurück, mit einem Rumpf, der das Zeitfenster und die Wartezeit in klaren Worten nennt:

Es lohnt sich, das mit dem anderen Visma-Produkt im Katalog zu vergleichen, denn die beiden messen auf Achsen, die nichts gemeinsam haben. Die Visma e-conomic Schnittstelle führt einen Token-Bucket je Kundenvereinbarung, in dem verschiedene Endpunkte verschieden viel kosten, ihr Budget hängt also davon ab, welche Aufrufe Sie machen. Dieses hier zählt Aufrufe flach und teilt die Zählung je Endpunkt.

Ein Hersteller, zwei Produkte, zwei Modelle und kein gemeinsames Vokabular dazwischen. Das ist in dieser Gruppe der Normalfall, und es ist der Grund, aus dem eine Taktstrategie es wert ist, einmal auf einer Ebene darüber geschrieben zu werden.

Dieses System zu testen hat zwei Eigenschaften, die leicht zu übersehen und spät teuer zu entdecken sind. Die erste ist, dass die Sandbox keine eigene Adresse hat.

In den Worten des Herstellers: „Es sind dieselben URLs wie in der Produktion, aber mit einem IdentityServer-Client und einem Visma-Online-Konto, das einen bestimmten Sandbox-Typ hat.“ Nichts in einer Basis-URL und nichts in einem Hostnamen sagt Ihnen, mit welcher Umgebung Sie sprechen. Nur die Zugangsdaten tun das.

Die zwei Richtungen sind auch nicht symmetrisch: Eine Produktions-Client-ID kann eine Sandbox-Firma erreichen, während eine Sandbox-Client-ID nie eine Produktionsfirma erreicht.

Die zweite ist der Umfang. Eine Sandbox-Firma ist bei der Anlage an eine Region gebunden, die Region lässt sich danach nicht mehr ändern, und „Sie können maximal 1 Firma je E-Mail-Adresse haben“. Einen zweiten Markt zu testen heißt deshalb, ein zweites Konto unter einer anderen E-Mail-Adresse anzulegen. Der Hersteller merkt an, dass er daran arbeitet, das aufzuheben, womit es eine aktuelle Einschränkung ist und keine Festlegung.

Die letzte Zeile verdient einen Satz, denn der Hersteller ist offen über die Folge: Da einige interne Integrationen nachgebildet sind, „stoßen Sie womöglich auf seltsame Fehler, wenn Sie versuchen, auf diese Dienste zuzugreifen“. Ein Fehlschlag in der Sandbox ist deshalb nicht automatisch ein Fehlschlag in Ihrem Code.

Zwei Schritte in diesem Ablauf brauchen den Hersteller, und beide gehören in einen Plan, der vor der Startwoche geschrieben wird. Der Gang in die Produktion verlangt, Vismas Schnittstellen-Support zu kontaktieren. Und die Rückruf-URL wird vom Hersteller gesetzt und nicht von Ihnen: Die Dokumentation von maesn sagt ausdrücklich, dass „Sie Visma kontaktieren müssen, um die URL auf die richtige zu ändern“.

Was maesn hier ändert, ist die Sandbox selbst und nicht der Papierkram. Unsere Sandbox-Übersicht führt dieses System mit einer kostenlosen Testmöglichkeit und als von maesn bereitgestellt, sodass eine Testumgebung bereitsteht, ohne je Region eine eigene Visma-Registrierung. Die Regionen gibt es weiter; sie hören nur auf, getrennte Registrierungsprojekte zu sein.

Alles bisher beschreibt, was das System tut. Dies ist die Aufteilung: die Teile, die auf dieser Ebene enden, und die Entscheidungen, die Ihre bleiben, weil nur Sie Ihr Produkt kennen.

Was maesn von der Liste nimmt:

• Die Scope-Erklärung und die zwei Parameter. Einmal mit Ihren Zugangsdaten eingereicht und auf jede Autorisierungsanfrage angewendet.
• Die Erneuerung, je Mandant. Token werden auf dieser Seite erneuert, der Lebenszyklus ist also nichts, was Ihr Produkt je Kunde einplant oder speichert.
• Das Paginieren jeder Sammlung. Der Umschlag wird für Sie gelesen, sodass die vollständige Menge ankommt und nicht die ersten fünfzig.
• Drei Markennamen, reduziert auf eine Verbindung. Welchen Namen der Kunde auch benutzt, Ihr Code spricht ein Zielsystem an, abgebildet in ein Common Data Model mit jedem anderen System.

Was bei Ihnen bleibt:

• Die Scope-Entscheidung. Was Ihr Produkt in einem Jahr brauchen könnte, ist jetzt günstiger beantragt als nach der Zustimmung jedes Kunden.
• Das Abfrageintervall. Wie aktuell Ihr Produkt sein muss, ist Ihre Wahl, und Sie haben 600 Anfragen pro Minute je Endpunkt dafür.
• Welche Objekte freigeschaltet sein müssen. Benennen Sie sie aus Ihrem Anwendungsfall, und führen Sie dieses Gespräch vor einer Zusage an einen Kunden.