sevdesk anbinden: Zwei Buchhaltungsversionen in einem Mandanten

Der Zugang ist der einfache Teil. Jeder sevdesk-Administrator hat ein Token, eine Hexadezimalzeichenkette aus 32 Zeichen, und sie geht bei jedem Aufruf in den Authorization-Header. Es gibt kein OAuth-Verfahren, keinen Erneuerungszyklus und keinen Ablauf, um den herum Sie planen müssten.

Die Einschränkung liegt darin, woran das Token hängt. In der Referenz steht es deutlich: „Die API-Tokens haben eine unbegrenzte Lebensdauer und existieren mit anderen Worten so lange, wie der sevdesk-Benutzer existiert.“ Die nächste Zeile ist eine Warnung in Grossbuchstaben, dass dieser Benutzer niemals gelöscht werden sollte. Nehmen Sie diese Person aus dem Konto, steht die Anbindung still, mit 401 und ohne Vorwarnung.

Eine weitere Zeile lohnt den zweiten Blick, weil sie Ihren Onboarding-Text entscheidet. Die Referenz warnt, dass ein Token sich nach dem Anlegen nicht erneut anzeigen lässt: „Es ist ratsam, das API-Token zu speichern, da wir es nachträglich NICHT abrufen können.“ Wer es beim Kunden einsammelt, hat genau einen Versuch.

Das ist der Teil, den die älteren Darstellungen auslassen, und es ist der, der eine Woche kostet. 2024 hat sevdesk seine Buchhaltung in einer Version umgestellt, die sevdesk-Update 2.0 heisst, und die Umstellung hat die Vergangenheit nicht mitgenommen. Datensätze aus dem alten System liefern weiter die alte Form, neue die neue, aus demselben Konto und über denselben Endpunkt.

Konkret: Aufträge, Rechnungen, Belege und Gutschriften, die unter System 1.0 entstanden sind, kommen weiter mit einem taxType wie default zurück. Dieselben Objekte seit der Umstellung kommen mit einer nummerierten taxRule. Ihr Parser trifft auf beide, und nichts in der Antwort sagt, welche davon vorliegt.

sevdesk bietet dabei eine Brücke an. Wo Sie weiter taxType mit den Werten default, eu oder ss senden, werden diese für eine Übergangszeit auf die neuen Regeln abgebildet. Die Empfehlung lautet trotzdem umzustellen, weil der neue Satz Möglichkeiten hat, die der alte nie hatte.

Ohne Brücke weggefallen ist taxType: custom zusammen mit einem eigenen taxSet. sevdesk hat es aus einem Grund entfernt, den es direkt nennt, einer hohen Wahrscheinlichkeit nicht regelkonformer Buchführung, und derselbe Durchgang hat auch eigene Buchungsarten entfernt.

Ein normalisiertes Datenmodell ist die naheliegende Antwort auf ein System mit zwei Vokabularen, und genau das leistet das Common Data Model für dieses und für die 30+ Systeme daneben.

Das Lesen verträgt beide Welten. Das Schreiben nicht, denn das neue Modell bindet drei Dinge aneinander: die Regel, den Satz, den diese Regel erlaubt, und das Konto dahinter. Stimmt die Kombination nicht, kommt der Schreibzugriff als 422 zurück, statt still angenommen zu werden.

Die Form dieser Einschränkung wird leicht unterschätzt. Von den zehn Erlösregeln für einen Regelbesteuerer erlauben genau zwei die Sätze, die eine deutsche Rechnung gewöhnlich trägt: die gewöhnliche Regel und innergemeinschaftliche Lieferungen. Fünf lassen einen einzigen Wert zu, und dieser Wert ist null. Die drei One-Stop-Shop-Regeln hängen am Bestimmungsland.

Zwei weitere Regeln haben ihre Form geändert und nicht ihren Wert, und beide greifen am Ende eines Ablaufs. Ein Beleg lässt sich nicht mehr direkt als bezahlt anlegen, nur noch als DRAFT oder UNPAID, mit einem eigenen Aufruf, der den Betrag danach bucht. Und enshrined ist keine Eigenschaft mehr, die Sie setzen: Es hat jetzt einen eigenen Endpunkt, einmal für Belege und einmal für Banktransaktionen.

Abschlags- und Teilrechnungen tragen eine eigene Einschränkung, und sie ist eng. Sie lassen sich nur unter der gewöhnlichen Erlösregel anlegen, oder unter der Kleinunternehmerregel bei einem Kleinunternehmer. Die One-Stop-Shop-Regeln schliessen sie ganz aus, ebenso E-Rechnungen und eigene Erlöskonten.

Das Lesen ist gewöhnlich, mit zwei Einzelheiten, die das Verhalten Ihres Parsers entscheiden. Paginiert wird mit limit und offset, das Limit liegt zwischen 1 und 1000, und Cursor gibt es nicht. Die Gesamtzahl der Datensätze kommt nur mit, wenn Sie sie mit countAll=true anfordern, und der Standardwert ist false.

Wenn sie kommt, kommt sie als Zeichenkette. Die Antwort lautet {"total": "157", "objects": [...]} mit der Zahl in Anführungszeichen, ein streng typisierter Parser, der dort eine Ganzzahl erwartet, scheitert daran, statt sie umzuwandeln. Deklarieren Sie das Feld als Zeichenkette und wandeln Sie selbst um.

Gegen das Maximum gehalten lohnt ein Hinweis: sevdesk rät selbst dazu, „die Limit-Werte in einem vernünftigen Rahmen zu halten (zwischen 10 und 100), um Leistungsprobleme zu vermeiden“. Die Obergrenze liegt bei 1000, die Empfehlung bei einem Zehntel davon, und das Offset-Modell wird langsamer, je tiefer Sie in eine grosse Menge laufen.

Ein Parameter lohnt es, früh zu lernen. embed holt verschachtelte Ressourcen vollständig heraus statt als id und Namen, und er nimmt mehrere Namen durch Kommas getrennt. Eine Rechnung, die Sie sonst einen zweiten Aufruf je Kontakt kostet, kommt damit vollständig an, und das zählt hier mehr als auf Systemen mit grosszügigen Grenzen, weil der zusätzliche Umlauf ganz auf Ihrer Seite anfällt.

Wie sich das liest, sobald es über Systeme hinweg normalisiert ist, auch über die, die mit Cursorn statt mit Offsets paginieren, steht auf der Seite zu Unified Pagination & Filtering.

Versioniert werden einzelne Ressourcen statt der Schnittstelle als Ganzes, über einen X-Version-Header an der Anfrage. Lassen Sie ihn weg, bekommen Sie default, und default ist in der Referenz der Wert, der „immer auf die älteste Version verweisen“ soll.

Das ist die Umkehrung dessen, was die meisten Plattformen einem beibringen. Anderswo hält einen das Weglassen auf der aktuellen Form; hier friert es einen auf der ältesten ein, die eine Ressource hat, still und so lange, wie niemand hinsieht. Setzen Sie den Header bewusst, je Ressource, und schreiben Sie den Wert dorthin, wo Ihr Team ihn findet.

Die Referenz fügt eine Bedingung darunter: Eine Ressource kann unter default existieren und unter 1.0 nicht, eine Versionsnummer ist also nicht automatisch sicherer als der Standardwert. Und jede Antwort trägt einen Deprecation-Header, entweder true oder einen Zeitstempel. Dieser Header ist die früheste Warnung, die Sie bekommen, wenn eine Ressource verschwindet, und sonst sagt es Ihnen nichts.

sevdesk sendet keine Events. Das Wort Webhook kommt in der Referenz nirgends vor, und kein Objekt in unseren eigenen Abdeckungsdaten trägt ein natives Event. Was Sie über die Bücher eines Kunden erfahren, erfahren Sie durch Fragen.

Die zweite Hälfte ist die, die den Entwurf ändert. sevdesk veröffentlicht auch keine Ratenbegrenzung. Es gibt keine dokumentierte Obergrenze, kein Kontingent und keine 429 in der Statuscode-Tabelle. Die Plattform sagt Ihnen also weder, wann etwas passiert ist, noch, wie oft Sie fragen dürfen.

Praktisch heisst das: Den Abgleich entwerfen Sie, und Sie begründen ihn auch. Fragen Sie die Objekte, die sich oft ändern, in einem Rhythmus ab, der dazu passt, wie schnell Ihr Produkt es wissen muss, und halten Sie den Rest langsam. Jeder Durchlauf kostet einen Aufruf, ob sich etwas bewegt hat oder nicht.

Wie dasselbe Problem aussieht, wenn ein Event-Modell über Systeme mit und ohne Events gelegt wird, steht auf der Seite zum Unified-Webhook-Modell.

Da jeder Aufruf Ihrer ist, ist auch jeder Fehlschlag Ihrer zu deuten, und eine Zeile in der Statuscode-Tabelle von sevdesk sollte Ihre Wiederholungslogik ändern. Dort steht, eine 500 bedeute normalerweise, dass auf der Gegenseite etwas schiefgegangen sei, „manchmal erscheint dieser Fehler jedoch, wenn wir einen Fehler nicht abgefangen haben, der normalerweise ein 400er-Statuscode ist“.

Eine 500 ist damit kein verlässlicher Beleg dafür, dass das Problem vorübergehend ist. Ein blindes exponentielles Zurückweichen wiederholt manche fehlerhaften Anfragen endlos, mit wachsender Wartezeit, gegen eine Nutzlast, die nie angenommen worden wäre. Protokollieren Sie den Anfragerumpf zum Fehlschlag, und hören Sie auf, eine 500 zu wiederholen, die unverändert zurückkommt.

Nach DATEV liest sich das wie eine andere Branche. sevdesk verlangt nichts, bevor Sie bauen, und nichts, bevor Sie live gehen. In den eigenen Worten darf jeder eine Integration gegen die dokumentierte Schnittstelle bauen, und „eine Freigabe oder Zustimmung durch sevdesk ist nicht notwendig“.

Das Partnerprogramm ist ein eigener Weg, und es beginnt, sobald die Integration steht. Sie veröffentlichen sie selbst und betreiben sie mit zehn Nutzern im Produktivbetrieb, und dort erwartet sevdesk, dass Sie die rauen Kanten gemeinsam mit ihnen finden und abschleifen.

Erst danach erscheint ein Antragsformular, und mit ihm die eine Prüfung im ganzen Ablauf: sevdesk gleicht die Integration gegen buchhalterische Anforderungen ab. Ein kurzes Onboarding stimmt beide Seiten aufeinander ab, und die Partnerschaft startet mit Sichtbarkeit im sevdesk-Ökosystem.

Für einen Testzugang gibt es einen Weg, und er kostet nichts. sevdesk empfiehlt, einen Testzugang anzulegen, statt gegen ein Produktivkonto zu entwickeln, und hält fest, dass ein Testzugang im höchsten Tarif liegt, sodass sich jede sevdesk-Funktion damit prüfen lässt.

Die Anbindung selbst ist hier schnell erledigt, und genau deshalb verdient der Rest die Aufmerksamkeit. Was wir von der Liste nehmen:

• Die zwei Vokabulare fallen in eines zusammen. Ob ein Datensatz vor der Umstellung von 2024 entstanden ist oder nicht, er erreicht Ihren Code in derselben Form wie eine Rechnung aus jedem anderen System, die Versionstrennung hört also auf, ein Zweig in Ihrem Parser zu sein.
• Die Paginierung ist normalisiert. Die Gesamtzahl, die Sie anfordern müssen, die Zeichenkette und der Lauf über Offsets liegen hinter einer Schnittstelle, die für jedes System gleich paginiert.
• Der Schlüssel muss nie per E-Mail reisen. Ihr Kunde gibt ihn in einem gehosteten Schritt ein oder über den Headless-Weg in Ihrer eigenen Oberfläche, und das Token liegt je Mandant. Wie die Anbindung Objekt für Objekt aussieht, steht auf der Seite zur Sevdesk-Schnittstelle.

Was bei Ihnen bleibt, und eines davon ist eine Entscheidung statt einer Aufgabe:

• Das Abrufintervall. Wie aktuell Ihr Produkt sein muss und was das an Aufrufen kostet, ist eine Produktentscheidung, zu der wir beitragen können.
• Die Steuerregel, die Ihr Schreibzugriff trägt. Receipt Guidance sagt Ihnen, welche Kombinationen aus Regel und Satz sevdesk für einen bestimmten Mandanten annimmt. Welche davon die richtige für den Beleg vor Ihnen ist, sagt es nicht. Das ist eine buchhalterische Beurteilung des Geschäfts Ihres Kunden, und sie bleibt bei Ihnen.
• Der Partnerantrag, und die Person hinter dem Token. Zehn Produktivnutzer zu erreichen und das Partnerformular einzureichen, ist Ihre Aufgabe. Den sevdesk-Benutzer, dessen Konto das Token ausgestellt hat, am Leben zu halten, ist die Ihres Kunden, und löscht er diese Person, steht die Verbindung still. Beides lässt sich nicht über eine Schnittstelle erledigen, beides gehört also in Ihr Onboarding und nicht in Ihre Integration.