Spiris-Schnittstelle und API-Integration
Spiris ist der schwedische Name von Visma eAccounting, und früher hieß es SPCS. Hinter allen drei Namen sitzt ein Zielsystem an einer API, und deshalb erreicht eine Anbindung, die für einen norwegischen Kunden gebaut ist, bereits einen schwedischen. Maesn hält den Token-Lebenszyklus, das Paging und die regionale Einrichtung hinter einer einzigen REST-Schnittstelle, und Ihr Produkt muss nie wissen, welchen der Namen ein Kunde benutzt.
Spiris, SPCS und eAccounting meinen ein System
Die meiste Arbeit an diesem System sind nicht die Endpunkte. Es sind die Namen, die Scope-Deklaration, die sich später nicht erweitern lässt, ohne zu jedem Kunden zurückzugehen, und ein Token, das stirbt, ohne es jemandem zu sagen. Hier steht, was Sie nicht bauen.
Sie binden einmal an, nicht je Markt
Schweden sagt Spiris, Norwegen und die Niederlande sagen eAccounting, und ältere schwedische Unterlagen sagen SPCS. Sie führen auf dasselbe Zielsystem. Es gibt also keine zweite Umsetzung und keine Zuordnungstabelle in Ihrem Code.
Die Deklaration wird einmal gemacht, auf dieser Seite
Dieses System will seine Scopes genau benannt haben, bevor sich der erste Kunde verbindet, statt sie unterwegs anzufordern. Maesn reicht sie zusammen mit den Zugangsdaten ein. Die Entscheidung fällt also einmal statt je Verbindung.
Der ganze Satz kommt an, nicht seine erste Seite
Das System gibt standardmäßig 50 Ergebnisse je Seite zurück und hat nichts dagegen, wenn niemand nach dem Rest fragt. Ein Abgleich ohne ausdrückliches Blättern meldet also Erfolg und liefert einen Teil der Daten. Maesn blättert jeden Sammel-Endpunkt, was ankommt, ist also vollständig.
Für Sie bleibt der Lesezugriff, den Sie eigentlich wollten, in derselben Form, die Sie für jedes andere angebundene Buchhaltungssystem benutzen.
Ein kurzes Gespräch genügt meist, um zu klären, ob Maesn zu Ihrem Anwendungsfall passt.
Drei Gründe, die Spiris-Schnittstelle über Maesn anzubinden
Direkt gegen dieses System zu bauen ist nicht schwer, weil die API schwer wäre. Es ist schwer, weil drei Dinge daran erst sichtbar werden, nachdem Sie ausgeliefert haben.
Eine Anbindung deckt drei Märkte ab
Ein schwedischer Kunde auf Spiris und ein norwegischer Kunde auf eAccounting sind dieselbe Integration. Direkt gebaut, entdecken Sie das, nachdem Sie sie als zwei behandelt haben, und die Entdeckung kommt meist aus einem Vertriebsgespräch und nicht aus der Dokumentation.
Die Callback-URL setzen nicht Sie
Die Redirect-Adresse der Anwendung ändert Visma auf Anfrage und nicht ein Einstellungsbildschirm. Das ist ein Support-Gespräch mitten in Ihrem Bau, und es ist die Art Abhängigkeit, die sich leicht einplanen und teuer ungeplant erfüllen lässt.
Dieselbe Form wie bei den Systemen daneben
Einen Kundendatensatz hier zu lesen und einen auf einem deutschen oder niederländischen System zu lesen gibt über Maesn dasselbe Objekt zurück. Ohne das bringt jeder Markt, den Sie betreten, ein zweites Datenmodell in Ihr Produkt statt einer zweiten Verbindung.
Eine Spiris-Verbindung erreicht auch Norwegen und die Niederlande
Kommerziell ist das Wichtigste an diesem System, dass es nicht mehrere Systeme sind. Über die Märkte hinweg ändert sich der Name, den ein Kunde nennt, nicht die API dahinter.
In Schweden heißt es Spiris und hieß davor SPCS. In Norwegen und den Niederlanden heißt es eAccounting. Alle drei Namen führen auf ein Zielsystem an einer API, ein schwedischer und ein norwegischer Kunde sind damit dieselbe Integration und nicht zwei. Nichts in Ihrem Produkt muss sich danach verzweigen, welcher Name auf ihrer Rechnung steht.
Am meisten zählt das an der Stelle, an der es am leichtesten schiefgeht, und das ist die Planung. Teams kalkulieren regelmäßig eine zweite Integration für den schwedischen Markt ein und merken erst danach, dass die Arbeit längst getan war. Teurer ist die andere Richtung: anzunehmen, die Namen seien ein System, wenn sie es nicht sind. Visma betreibt mehrere Produkte, die tatsächlich getrennt sind, auf eigenen APIs, und auseinanderhalten lässt sie das Visma-Portfolio und nicht die Marke, die ein Interessent nennt.
Die technischen Einzelheiten hinter dieser Seite liegen deshalb beim Zielsystem, und ausführlich beschreibt sie die Visma-eAccounting-Anbindung. Alles Weitere unten gilt für einen Spiris-Account, weil es dasselbe System ist.
Spiris-Scopes werden erklärt, bevor der erste Kunde verbindet
Spiris authentifiziert über OAuth 2.0, und zwei Einzelheiten trennen es von den OAuth-Systemen daneben. Die Scopes werden genau und vorab deklariert, statt unterwegs angefragt zu werden, was Ihre Anwendung erreichen kann, ist also geklärt, bevor sich der erste Kunde verbindet. Und das Token wird still entwertet, wenn ein Nutzer sein Passwort ändert, ohne Benachrichtigung und ohne Fehler, bis etwas aufruft. Die Firmenauswahl liegt auf der Seite von Visma im Zustimmungsablauf, und in Schweden wählt regelmäßig eine Kanzlei.
- OAuth 2.0
- Scopes vorab deklariert, drei Werte einmal eingereicht
- Drei Zugangsdaten und die Scope-Deklaration
- Client-ID, Client Secret und Abonnementschlüssel, einmal eingereicht und für jeden Kunden wiederverwendet, gleich in welchem Markt er ist. Der Scope-Satz wird daneben deklariert und nicht je Verbindung ausgehandelt.
- Das Refresh, je Mandant
- Das Erneuern der Tokens läuft je Mandant auf dieser Seite. Der Lebenszyklus ist also nichts, was Ihr Produkt je Kunde plant oder verwahrt.
Scopes vorab zu deklarieren ist etwas, um das herum man planen sollte statt daran vorbei. Sie später zu erweitern heißt, zu jedem angebundenen Kunden für eine neue Freigabe zurückzugehen. Was Ihr Produkt in einem Jahr brauchen könnte, gehört also in das Gespräch, bevor der erste sich verbindet.
- 1
Ihr Kunde startet in Ihrem Produkt
Sie schicken ihn in den Ablauf, und Maesn öffnet den Zustimmungsbildschirm. Er trägt den Namen Ihrer Anwendung, denn die Anwendung ist auf Ihr Unternehmen registriert.
- 2
Er stimmt den deklarierten Scopes zu
Der Bildschirm zeigt, was vorab deklariert wurde, und fragt, für welche Firma die Verbindung gilt. Wo eine Kanzlei im Auftrag eines Mandanten verbindet, ist diese Wahl der eine Schritt, den man richtig machen sollte.
- 3
Sie arbeiten mit einem Account-Key
Maesn speichert die Verbindung und gibt einen Account-Key zurück. Jede Anfrage trägt Ihren Maesn-API-Schlüssel und diesen Schlüssel, gleich welche der regionalen Marken der Kunde betreibt.
Spiris-Daten bleiben frisch mit einem geplanten Abruf
Spiris sendet keine nativen Events. Die Aktualität ist hier also ein geplanter Lesezugriff, und dieser Lesezugriff läuft auf demselben Filter und derselben Paginierung wie bei jedem anderen System, das Sie anbinden. Events für ein bestimmtes Objekt sind auf Anfrage verfügbar.
Nichts: Das System führt keinen nativen Event-Strom. Eine Änderung im Konto eines Kunden wird also sichtbar, sobald etwas sie liest. Wo Events auf einem bestimmten Objekt für Ihr Produkt zählen, ist dafür die Spalte auf Anfrage da.
Ein geplanter Lesezugriff, auf demselben Filter und derselben Paginierung wie bei jedem anderen System, das Sie anbinden, und mit dem Blättern auf dieser Seite erledigt, statt es einer Voreinstellung zu überlassen, die nach der ersten Seite aufhört.
Das Paging zählt hier mehr als die fehlenden Events, denn es schlägt fehl, ohne es zu sagen. Ein Lesezugriff, der bei den ersten 50 Datensätzen aufhört, gibt eine gültige Antwort und ein unvollständiges Ergebnis zurück, und nichts in der Nutzlast kennzeichnet den Unterschied.
Das Paging ist der Teil, für den sich Planung lohnt, weil ein Lesezugriff, der bei fünfzig Datensätzen aufhört, eine gültige Antwort und ein unvollständiges Ergebnis zurückgibt. Ein Weg, zu filtern und zu paginieren macht daraus etwas, woran Sie nicht mehr denken müssen, und das Event-Modell ist der Ort, an dem ein Spiris-Objekt landet, sobald eines dieser Events eingeschaltet wird.
Was eine Spiris-Anbindung braucht, vor dem ersten Aufruf
Drei Dinge müssen vorhanden sein, bevor Code läuft, und eines davon dauert länger als die anderen, weil ein Dritter beteiligt ist.
- Ein aktives Spiris- oder Visma-eAccounting-Konto
- Die Verbindung entsteht gegen ein produktives Konto. Unter welchem der beiden Namen es verkauft wird, macht für die Einrichtung keinen Unterschied.
- Client-ID, Client-Secret und Abonnementschlüssel
- Drei Werte statt einem. Sie kommen bei der Registrierung der Anwendung an, werden einmal eingereicht und danach für jeden Kunden benutzt.
- Die Callback-URL, von Visma geändert
- Die Anwendung muss auf die Callback-Adresse von Maesn zeigen, und diese Änderung beantragt man bei Visma, statt sie selbst zu machen. Damit sollte man früh anfangen, denn bis sie durch ist, lässt sich nichts anderes testen.
Wir gehen die Registrierung und den Callback-Wechsel mit Ihnen durch.
Ein System, eine Form, welchen Namen der Markt auch benutzt
Spiris und Visma eAccounting sind dasselbe Zielsystem. Was Sie für das eine bauen, antwortet bereits für das andere.
Spiris ist Visma eAccounting unter seinem schwedischen Namen, es gibt also eine Anbindung hinter beiden und einen Satz Objekte, nicht zwei, die zufällig übereinstimmen. Eine Zahl, die sich zwischen ihnen unterschiede, hieße, dass eine der beiden falsch ist.
Was Sie lesen, kommt im selben Common Data Model an wie bei jedem anderen angebundenen System, ein Kundendatensatz aus einem schwedischen Account und einer aus einem norwegischen sind in Ihrem Produkt also dasselbe Objekt, mit denselben Feldern in derselben Form. Nennen Sie uns die Objekte, mit denen Ihr Anwendungsfall arbeitet, und wir schalten sie für Ihre Anbindung frei.
Sagen Sie uns, welche Objekte Ihr Anwendungsfall braucht, und wir bestätigen, was möglich ist.
