Die sevDesk API: Einstieg, erster Aufruf, DATEV-Export

Die sevDesk API ist eine REST-Schnittstelle unter https://my.sevdesk.de/api/v1, über die nahezu alles läuft, was auch die Weboberfläche kann: Kontakte, Rechnungen, Angebote, Belege, Bankkonten und der Export zur Steuerkanzlei. Sie brauchen dafür zwei Dinge — den Tarif Buchhaltung Pro und ein Token, das Sie sich unter „Erweiterungen" einblenden lassen.

Ein Detail sorgt gleich beim ersten Aufruf für Verwirrung, deshalb steht es hier oben: Das Token wird ohne den Zusatz „Bearer" übergeben. Wer aus Gewohnheit Authorization: Bearer <token> schreibt, bekommt einen Autorisierungsfehler — und sucht ihn dann beim Token, obwohl das Token stimmt.

Wie kommen Sie an das Token für die sevDesk API?

Aus Ihrem eigenen Konto, nicht über ein Entwicklerportal. Es gibt keinen Antrag, kein Partnerprogramm und keine Freischaltung durch den Support — Sie lassen sich das Token einblenden, und es gilt sofort.

Der Weg führt laut der sevDesk Wissensdatenbank im Hauptmenü über „Erweiterungen" zu „Integrationen". Oben auf der Seite steht der Bereich für das API-Token; zum Einblenden verlangt sevDesk Ihr Zugangspasswort. Je nach Tarif findet sich das Token zusätzlich unter „Erweiterungen und API". Wer noch nach „Einstellungen, Benutzer" sucht, folgt einer veralteten Anleitung.

Das Token ist eine 32-stellige hexadezimale Zeichenfolge, besteht also nur aus Ziffern und den Buchstaben a bis f. Es hängt am Administrator: Laut offizieller Dokumentation hat jeder sevDesk-Administrator genau ein Token. Entsprechend gilt dieselbe Sorgfalt wie beim Passwort — wer es hat, hat vollen Zugriff auf die Buchhaltungsdaten.

Ein eigener technischer Benutzer, wie man ihn aus anderen Systemen kennt, ist hier kein naheliegender Weg: Laut Preisübersicht enthalten die Bezahltarife jeweils einen Benutzer, weitere kosten als Zusatzoption extra. Und die Dokumentation warnt ausdrücklich davor, einen Benutzer zu löschen: Das Token lebt so lange wie der Benutzer und ist mit dessen Konto unwiederbringlich verloren. Wenn im Unternehmen jemand ausscheidet und sein Zugang aufgeräumt wird, antwortet die Anbindung von einem Tag auf den anderen mit einem Autorisierungsfehler, ohne dass jemand am Code etwas geändert hätte.

Wenn Sie einen Zugang entziehen müssen, erzeugen Sie deshalb das Token neu, statt den Benutzer zu löschen — in derselben Ansicht, in der Sie es einblenden, bestätigt mit Ihrem Passwort. Alle Anbindungen, die darauf laufen, müssen Sie dann allerdings gleichzeitig umstellen.

Welcher Tarif nötig ist, sagt die Wissensdatenbank klar: Die Schnittstelle ist im Tarif Buchhaltung Pro enthalten. Zum Entwickeln gibt es eine Testphase von 14 Tagen, die laut Preisübersicht alle Funktionen umfasst; für Integrationsprojekte verlängert sevDesk sie laut der offiziellen API-FAQ auf Anfrage. Für den Dauerbetrieb führt kein Weg am passenden Abonnement vorbei.

Wie sieht der erste Aufruf aus?

Drei Kopfzeilen, ein GET, fertig. Die dritte ist keine Pflicht, wird von sevDesk aber ausdrücklich erbeten: ein sprechender User-Agent, an dem sich Ihre Integration erkennen lässt. Das folgende Beispiel holt die ersten zehn Rechnungen und liefert zusätzlich die Gesamtzahl mit:

GET https://my.sevdesk.de/api/v1/Invoice?limit=10&offset=0&countAll=true

Authorization: 32STELLIGES_TOKEN_OHNE_BEARER
Accept: application/json
User-Agent: Ihre-Integration by Firmenname

Drei Dinge lohnen den zweiten Blick. Erstens die Ressourcennamen: Sie sind großgeschrieben und im Singular, also Invoice, Contact, Order, nicht invoices. Zweitens die Blätterung über limit und offset — ohne sie bekommen Sie nur die ersten Treffer und merken es nicht. Drittens countAll=true, das die Gesamtzahl mitliefert und Ihnen die Schleifensteuerung erspart.

Die vollständige Referenz mit allen Feldern liegt in der offiziellen API-Dokumentation. Antworten auf die wiederkehrenden Fragen zu Authentifizierung, Blätterung und Anfragemengen sammelt sevDesk in seiner API-FAQ.

Welche Bereiche deckt die Schnittstelle ab?

Praktisch den gesamten Beleg- und Zahlungsfluss. Das ist der eigentliche Unterschied zu vielen kleineren Buchhaltungsschnittstellen.

Besonders praktisch ist, dass die Rechnung nicht nur angelegt, sondern über die Schnittstelle auch als PDF erzeugt und per E-Mail versendet werden kann. Damit lässt sich der komplette Weg vom gewonnenen Auftrag bis zur zugestellten Rechnung abbilden, ohne dass jemand die Oberfläche öffnet.

Was bedeuten versenden, buchen und festschreiben?

Drei verschiedene Dinge — und wer sie verwechselt, baut den Ablauf falsch herum. Die Schnittstelle kennt dafür eigene Aktionen: versenden, Zahlung buchen, festschreiben, stornieren, zurücksetzen.

Solange die Rechnung Entwurf ist, können Sie Positionen, Beträge und Empfänger beliebig ändern. Zum offenen Beleg wird sie durch das Versenden — über den Versand per E-Mail oder die Meldung, dass sie auf anderem Weg hinausgegangen ist. Genau hier täuscht der Sprachgebrauch: Buchen heißt in sevDesk nicht „Entwurf abschließen", sondern eine Zahlung verbuchen. Der Aufruf verlangt Betrag, Datum, Zahlungsart und Bankkonto und verknüpft den Beleg mit einer Transaktion. Und das Festschreiben ist noch einmal etwas anderes: Danach ist der Beleg unveränderlich, endgültig und ohne Rückweg — die Anforderung ordnungsmäßiger Buchführung, die ein nachträgliches stilles Ändern ausschließt.

Für Ihre Anbindung heißt das: Die fachliche Prüfung gehört vor das Versenden, nicht vor das Buchen. Immerhin ist der Schritt hier umkehrbar — wer nach dem Versenden merkt, dass der Steuersatz falsch war, setzt den Beleg über die Schnittstelle wieder auf Entwurf zurück und korrigiert ihn. Das geht allerdings nur, solange er nicht festgeschrieben ist. Danach bleiben Storno und Neuausstellung, und Sie haben zwei Belege in der Buchhaltung, wo einer gereicht hätte.

Wie funktioniert der DATEV-Export über die Schnittstelle?

Als Auftrag, nicht als einfacher Download. Sie starten über die API einen Exportlauf, können dessen Fortschritt abfragen und laden anschließend das fertige Paket herunter — ein ZIP-Archiv mit den Daten im CSV- oder XML-Format für die Steuerkanzlei.

Ein Schritt geht dem voraus, und er kostet den ersten Versuch, wenn man ihn überspringt: In der Exportkonfiguration muss der Beginn des Wirtschaftsjahres hinterlegt sein. Fehlt er, scheitert der Export, bevor er anfängt.

Das klingt umständlicher als ein direkter Abruf, hat aber einen Grund: Ein Monatsexport mit Belegbildern ist nichts, was in einer Antwortzeit von zwei Sekunden entsteht. Der Umweg über den Auftrag verhindert, dass Ihr Skript in eine Zeitüberschreitung läuft.

Für Betriebe, deren Buchhaltung in der Kanzlei endet, ist das der wichtigste Teil der ganzen Schnittstelle. Wer diesen Schritt automatisiert, spart nicht einzelne Klicks, sondern den monatlichen Übergabetermin. Wie dieser Weg grundsätzlich aufgebaut ist, ordnet unser Beitrag zu den Wegen von Pipedrive zur Rechnung ein.

Worin unterscheidet sich die sevDesk API von der Lexware-Schnittstelle?

In vier Punkten, die bei einer Anbindung sofort spürbar werden. Wer beide Systeme unterstützen will, sollte sie kennen, bevor die Architektur steht.

• Authentifizierung: sevDesk erwartet das rohe Token im Authorization-Header, Lexware Office ein Bearer-Token. Derselbe Code funktioniert nicht für beide.
• Adressen: sevDesk führt Kontakte mit mehreren Adressen als eigene Ressourcen. Bei Lexware Office lässt sich über die Schnittstelle nur je eine Rechnungs- und Lieferadresse pflegen.
• Zustände: Bei sevDesk ist der Übergang ein eigener Aufruf — versenden macht aus dem Entwurf einen offenen Beleg, zurücksetzen macht ihn wieder zum Entwurf. Bei Lexware Office fällt die Entscheidung schon beim Anlegen über den Parameter finalize=true und ist danach über die Schnittstelle nicht mehr änderbar. Und Vorsicht beim Wort: „buchen" meint bei sevDesk bereits die Zahlung, nicht den Beleg.
• Tarif: Buchhaltung Pro bei sevDesk, XL bei Lexware Office. In beiden Fällen ist die Schnittstelle kein Bestandteil der Einstiegspakete.

Den Gegenpart haben wir gesondert beschrieben: Einstieg, erste Rechnung und Grenzen der Lexware Office API. Welche Software im Alltag zu welchem Vertrieb passt, vergleicht der Überblick zur Faktura-Software am CRM.

Was bedeutet das für eine CRM-Anbindung?

Dass die Buchhaltungsseite mehr Entscheidungen verlangt als die CRM-Seite. sevDesk führt Buchungskonten, Steuerregeln und Nummernkreise — Felder, für die es im CRM schlicht keine Entsprechung gibt und die trotzdem an jedem Beleg hängen.

Drei Punkte kosten dabei erfahrungsgemäß die meiste Zeit. Der erste ist die Kontenzuordnung: Welche Buchungskategorie bekommt welcher Umsatz, und wer entscheidet das — der Vertrieb im CRM oder die Buchhaltung? Der zweite ist die Steuerregel bei Auslandskunden, die sich nicht aus dem Deal ableiten lässt, sondern aus Sitz und Umsatzsteuer-Identifikationsnummer des Kunden. Der dritte ist der Dublettenfall: Ein Kunde, der im CRM zweimal existiert, wird über die Schnittstelle klaglos zweimal angelegt — und fällt erst der Buchhaltung auf.

Die technische Seite der anderen Hälfte — also was Pipedrive selbst über seine Entwicklerschnittstelle anbietet — ist dabei der unkompliziertere Teil.

Häufige Fragen

Ist die sevDesk API in jedem Tarif enthalten? Nein. Sie gehört zum Tarif Buchhaltung Pro. Zum Ausprobieren gibt es die 14-tägige Testphase mit allen Funktionen, die sevDesk für Integrationsprojekte auf Anfrage verlängert.

Warum schlägt meine Authentifizierung fehl, obwohl das Token stimmt? Vermutlich wegen des Zusatzes „Bearer". sevDesk erwartet den reinen Token-Wert im Authorization-Header.

Wo finde ich mein API-Token? Im Hauptmenü unter „Erweiterungen" und dort bei „Integrationen"; je nach Tarif auch unter „Erweiterungen und API". Zum Einblenden verlangt sevDesk Ihr Zugangspasswort.

Kann ich über die API auch Rechnungen versenden? Ja. Die Schnittstelle erzeugt das PDF und kann die Rechnung per E-Mail zustellen.

Lässt sich eine festgeschriebene Rechnung noch ändern? Nein. Korrekturen laufen über Storno und Neuausstellung.

Wie viele Anfragen pro Sekunde sind erlaubt? sevDesk nennt dazu keine feste Grenze. Es gibt aber eine andere Folge, die man kennen sollte: Wer dauerhaft Anfragen schickt, die Fehler auslösen, riskiert eine Sperre des Tokens. Fangen Sie Fehler also ab, statt sie im Sekundentakt zu wiederholen.