Spiris anbinden: ROT, RUT und wer die Verbindung hält

Das erste Problem einer schwedischen Anbindung ist meist eines mit Namen, und das Nützliche an diesem hier ist, dass der Hersteller es datiert hat. Die Änderung ist ein Changelog-Eintrag vom 28. Mai 2025 und kein Gerücht, das ein Interessent weitererzählt.

Zwei Dinge haben sich in diesem Eintrag geändert. Aus der Firma Visma Spcs wurde Spiris, und in Schweden wurde aus dem Produkt Visma eEkonomi Bokföring & Fakturering, auf Englisch Bookkeeping & Invoicing. In jedem anderen Markt blieb der Produktname eAccounting. Der Hersteller schließt den Eintrag mit dem Teil, der für eine bestehende Anbindung zählt: „Unsere API unterstützt Integrationen über Ländergrenzen hinweg weiterhin, und diese Namensänderungen wirken sich nicht auf Ihre bestehenden Setups aus.“

Ein schwedischer Kunde sagt also Spiris, Bokföring & Fakturering, eEkonomi oder Spcs, und alle vier führen auf dasselbe Zielsystem. Das Entwicklerportal trägt den Namen Spiris inzwischen in seiner eigenen Navigation, die Schnittstelle darunter nicht: der Host ist weiterhin eaccountingapi.vismaonline.com, die Pfade sind weiterhin /v2/… und das Zielsystem über maesn heißt weiterhin vismaeaccounting.

Welche Objekte diese Verbindung erreicht und welche davon auf Anfrage stehen, steht Objekt für Objekt auf der Seite zur Spiris-Schnittstelle. Die Marktaufteilung, die Scopes, die Token-Laufzeiten, die Paginierung und die Rate Limits sind auf jeder Marke gleich und einmal auf der Seite zur Visma eAccounting Schnittstelle und in ihrem Leitfaden beschrieben. Alles unterhalb dieser Linie gilt nur in Schweden.

In Schweden ist die Partei, die sich authentifiziert, häufig nicht Ihr Kunde. Kleine Firmen arbeiten mit einem Buchhaltungsbüro, und der Hersteller hält diese Annahme in seiner eigenen Empfehlung fest, Sie müssen das also nicht vor Ort wissen.

Der Grund ist der Plan. In den Worten des Herstellers hat „das Buchhaltungsbüro immer Bookkeeping & Invoicing+, während der Kunde jede der anderen Varianten haben kann“, und die Empfehlung folgt daraus: Um alle Endpunkte zu erreichen, sollte ein Benutzer „aus dem Buchhaltungsbüro, der auch Zugriff auf Bookkeeping & Invoicing des Endkunden hat, die Authentifizierung durchführen“.

Das hat eine Folge für Ihr Produkt, bevor es eine für Ihren Code hat. Die Person, die den Zustimmungsdialog durchklickt, kann eine dritte Partei sein, die Dutzende Ihrer Kunden betreut. Was Ihre Oberfläche beim Verbinden sagt, liest also das Buchhaltungsbüro und nicht das Unternehmen, dessen Daten es sind.

Und es kommt mit einer Falle, die eine Verbindung zur falschen Firma erzeugt statt einer Fehlermeldung. Der Benutzer des Büros muss die richtige Firma im Wähler auswählen, und der Wähler kann fehlen: Ist für ein Büro in Spiris eine Standardfirma gesetzt, wird er übergangen. Das dokumentierte Mittel dagegen ist, prompt=select_account in die Autorisierungsanfrage zu senden, was der Hersteller ohnehin empfiehlt, weil ein Weglassen „zu automatischen oder unvorhersehbaren Anmeldungen mit einer bereits ausgewählten Firma führen kann“.

Über maesn ist das ein Ablauf für jedes System: Unified Authentication übergibt den Scope-Satz mit den Zugangsdaten, sendet diese Parameter bei jeder Autorisierungsanfrage und gibt einen Kontoschlüssel für die Verbindung zurück, gleich wer sie hergestellt hat.

Die zweite schwedische Überraschung ist eine Einschränkung, und zwar die Sorte, die billiger zu wissen als zu entdecken ist. Sie können von außerhalb des Produkts nicht entscheiden, auf welche Konten eine Rechnung bucht.

Der Hersteller beantwortet es als klares Nein: „Alle Artikel haben vordefinierte Kontierungen, die bestimmen, welche Konten auf der Rechnung verwendet werden. Diese können nur direkt in Bookkeeping & Invoicing hinzugefügt oder geändert werden, nicht über die API.“ Die Kontierung ist eine Eigenschaft des Artikels, erreichbar als CodingId und gelistet unter /v2/articleaccountcodings.

Der Hebel, den Sie haben, ist also die Artikelauswahl. Eine Zeile referenziert einen Artikel, der Artikel trägt die Kontierung, und die Kontierung entscheidet über die Konten. Eine schwedische Rechnung zu bauen heißt damit, den eigenen Produktkatalog auf Artikel abzubilden, die in diesem Mandanten schon vorhanden sind, statt Konten zusammen mit den Beträgen zu senden.

Eine Regel folgt aus derselben Seite und ist beim ersten Schreiben leicht zu übersehen: Eine Rechnung braucht mindestens eine Zeile mit einer Artikel-ID, um gültig zu sein. Zeilen ohne eine solche sind Textzeilen, gekennzeichnet durch IsTextRow, und eine Rechnung, die nur daraus besteht, ist keine Rechnung.

Der Kontenrahmen selbst wird je Geschäftsjahr adressiert, unter /v2/accounts/{fiscalyearId}, mit einem getrennten Standardsatz unter /v2/accounts/standardaccounts. Einzelne Mandanten benennen Konten um, legen welche an und entfernen welche, es ist also eine Referenz je Kunde und keine nationale Konstante, die Sie im Code halten können.

Kostenstellen sind die eine Stelle, an der dieses System großzügiger ist, als es zunächst aussieht. Ein Mandant kann bis zu drei Gruppen von Kostenstellen führen, und eine Zeile trägt für jede davon eine ID, eine Zuordnung, die Ihr Produkt ohnehin führt, hat also einen Platz ohne eigenes Feld.

Die Umsatzsteuer ist auf diesem System eine Referenz und keine Zahl, und der Grund ist an der Form des Objekts zu sehen. Ein Umsatzsteuerschlüssel trägt einen Code, eine Beschreibung und einen Satz, und er trägt die Konten, auf die dieser Satz bucht: AccountNumber1, AccountNumber2 und AccountNumber3.

Deshalb ist derselbe Prozentsatz zwischen zwei schwedischen Mandanten nicht austauschbar. Der Satz kann übereinstimmen, während die Konten dahinter sich unterscheiden, ein Umsatzsteuerschlüssel ist also eine Referenz je Kunde, zu lesen unter /v2/vatcodes oder unter /v2/vatcodesrates, wenn Sie die Sätze daneben haben wollen.

Zwei Schalter auf Kundenebene ändern die Berechnung, bevor es eine Zeile tut. DeliveryBasedVat macht die Lieferadresse zur Grundlage für Umsatzsteuer und OSS, womit Lieferort, Ländercode und Postleitzahl zur Pflicht werden. ForceBookkeepVat schließt Umsatzsteuer für einen Kunden außerhalb der EU ein und lässt sich für ein Land innerhalb der EU nicht setzen.

Und ein Kennzeichen entscheidet, ob eine schwedische Rechnung überhaupt einen Abzug tragen kann: IsPrivatePerson. Der nächste Abschnitt ist nur für diese Kunden erreichbar.

Das ist der Teil einer schwedischen Anbindung, der im norwegischen und im niederländischen Markt keine Entsprechung hat. ROT und RUT sind Steuerermäßigungen, die ein Privatkunde für Arbeiten am eigenen Zuhause geltend macht, ROT für Reparatur- und Umbauarbeiten an einer Immobilie, RUT für haushaltsnahe Dienstleistungen, und beide sind in der Schnittstelle ausdrücklich modelliert.

Modelliert an drei Stellen, und das ist die Einzelheit, für die sich Planung lohnt. Die Rechnung trägt den Abzug, die Zeile trägt die Arbeit, der Artikel trägt das Gewerk. Fehlt eine Ebene, erzeugen die anderen beiden eine Rechnung, die vollständig aussieht und nichts ermäßigt.

Drei dieser Felder haben Regeln und nicht nur Typen. Der Name der Immobilie wird Pflicht, sobald ein Immobilientyp gesetzt ist, die Personennummer des Käufers ist auf elf Zeichen begrenzt, und die Ermäßigung wird für Sie berechnet, solange Sie nicht selbst einen Betrag senden.

Die Gewerkeliste ist länger, als sie klingt, und sie ist nicht lückenlos. Es gibt 26 Werte, zwölf auf der ROT-Seite und dreizehn auf der RUT-Seite plus einen für keines von beidem, und sie laufen bis 29 mit Lücken bei 8, 11, 16 und 17. Eine Schleife über einen Zahlenbereich erzeugt deshalb Werte, die die Schnittstelle nicht kennt, und dieselbe Liste steht am Artikel als HouseWorkType und an der Zeile als WorkCostType.

Grüne Technologie steht daneben als eigenes kleines Enum an der Zeile, mit Solarzellen, Speichern für elektrische Energie und einem Ladepunkt für Fahrzeuge. Sie teilt sich das Feld für den Namen der Immobilie mit ROT, beides zu setzen macht dieses Feld also zur Pflicht.

Alles oben ist die schwedische Fläche, die eine direkte Anbindung lernen muss. Über maesn kommt sie als eine Verbindung auf derselben Schnittstelle an wie jedes andere Buchhaltungssystem, das Sie unterstützen, und die Objekte, die Ihr Anwendungsfall braucht, sind dafür freigeschaltet.

Kunden und Lieferanten werden auf dieser Verbindung heute gelesen, und der Rest der Objektliste wird freigeschaltet, wenn ein Anwendungsfall ihn braucht. Die produktive Frage ist eine enge: Welche Objekte berührt Ihr schwedischer Anwendungsfall? Nennen Sie sie, und sie werden für Ihre Verbindung freigeschaltet.

Die Aktualität läuft über einen geplanten Lesezugriff, und die Paginierung dahinter liegt auf unserer Seite, ein Lesezugriff liefert also den vollständigen Satz und nicht die ersten fünfzig Datensätze. Alles, was Sie lesen, kommt im selben Common Data Model an wie bei jedem anderen angebundenen System, und genau das verhindert, dass ein schwedischer Kunde in Ihrem Produkt zu einer zweiten Form wird.

Was maesn Ihnen abnimmt:

• Die ganze schwedische Fläche von oben. Die Abzugsfelder auf drei Ebenen, die Gewerkeliste mit ihren Lücken, der Umsatzsteuerschlüssel, der auf drei Konten führt, und die Regeln der Kontierung liegen bei uns. Ihr Produkt sendet eine Form.
• Die Verbindung, gleich wer sie herstellt. Ein Buchhaltungsbüro, das im Auftrag eines Mandanten verbindet, ist hier der Normalfall, und der Ablauf, die Firmenauswahl und der Lebenszyklus des Tokens laufen auf unserer Seite.
• Drei Märkte auf einer Anbindung. Spiris und eAccounting in Norwegen und den Niederlanden sind ein Zielsystem. Ein schwedischer Kunde kostet keine zweite Implementierung.
• Paginierung und Reconnects. Sammlungen werden für Sie paginiert, und ein Token, das ohne Vorwarnung stirbt, erscheint als Zustand der Verbindung und nicht als 401 in Ihren Logs.

Was bei Ihnen bleibt:

• Die Artikelzuordnung. Die Kontierung reist mit dem Artikel, Ihren Katalog auf die Artikel eines Mandanten abzubilden ist also Ihre Modellierung.
• Welche Objekte Sie nennen. Zwei werden heute gelesen und der Rest steht auf Anfrage, die Liste, die Ihr Anwendungsfall braucht, gehört also vor eine Zusage an einen Kunden ins Gespräch.
• Wer sich authentifiziert. Ob Sie ein Buchhaltungsbüro oder das Unternehmen selbst durch den Verbindungsschritt führen, ist eine Produktentscheidung, und sie entscheidet, was Ihr Zustimmungsschritt sagen muss.