tfm_sevdesk

4TFM SevDesk Rechnungsschnittstelle

Das Plugin verbindet Ihren xt:Commerce-Shop mit Ihrem sevDesk-Konto und legt dort automatisch Rechnungen zu Ihren Shop-Bestellungen an. Sie müssen Rechnungen also nicht mehr von Hand in sevDesk erfassen.

Plugin bestellen

Frage stellen

Hinweis: Sie benötigen neben diesem Plugin auch einen SevDesk-Zugang mit der Funktion "REST API"

Der Ablauf im Überblick

Eine Bestellung erreicht einen von Ihnen festgelegten Bestellstatus (z. B. „bezahlt“).
Das Plugin sucht den passenden Kontakt in sevDesk – oder legt ihn neu an.
Es erstellt eine Rechnung mit allen Positionen, Versandkosten und Rabatten.
Je nach Modus bleibt die Rechnung ein Entwurf – oder sie wird direkt über sevDesk per E-Mail an den Kunden versendet.
Jede Übertragung wird protokolliert und ist im Backend nachvollziehbar.

Was zusätzlich mitgeliefert wird

Ein Button „An SevDesk senden“ in jeder Bestellung im Backend – für den manuellen Versand oder eine erneute Übertragung.
Eine eigene Textverwaltung (Kopf-/Fußtext der Rechnung, Betreff und Text der Rechnungsmail) – mehrsprachig, passend zur Sprache der jeweiligen Bestellung.
Ein Log mit den letzten 300 Übertragungen inklusive Fehlermeldungen.

Was das Plugin nicht tut: Es überträgt ausschließlich in Richtung sevDesk. Zahlungen, Mahnungen oder Stornos aus sevDesk werden nicht zurück in den Shop gespielt.

Installation

1. Führen Sie die generelle Installationsanleitung für 4tfm-Plugins aus.

2. Nachdem das Plugin installiert und aktiviert ist, laden Sie den Administrationsbereich mit der F5-Taste neu.

Plugin-Optionen & Konfiguration

Zu finden unter Plugins → installierte Plugins → 4TFM SevDesk Bestellrechnungen.

Option	Bedeutung
Für Mandant aktivieren	Schaltet die Schnittstelle für den aktuell gewählten Mandanten/Shop ein (`true`) oder aus (`false`). Bei `false` passiert nichts – auch der Button in der Bestellung bleibt wirkungslos.
SevDesk API-Key	Ihr persönlicher API-Token aus sevDesk. Ohne gültigen Key schlägt jede Übertragung fehl (Meldung im Log).
Bestellstatus-IDs, ‚bezahlt‘	Kommagetrennte Liste von Bestellstatus-IDs. Erreicht eine Bestellung einen dieser Status, wird sie automatisch übertragen – mit dem Fußtext für bereits bezahlte Rechnungen. Standard: `23`.
Bestellstatus-IDs, ‚offen‘	Dasselbe für noch offene Rechnungen – hier wird der normale Fußtext mit der Zahlungsaufforderung verwendet.
Modus	`Entwurf-Modus` oder `Auto-Modus` – siehe unten.
BCC-Adresse(n)	Nur im Auto-Modus: Diese Adressen erhalten jede an den Kunden versendete Rechnungsmail in Blindkopie. Mehrere Adressen kommagetrennt.

Die Bestellstatus-IDs richtig setzen

Die IDs finden Sie unter Bestellungen/Kunden → Bestellstatus; maßgeblich ist die Zahl in der Spalte ID, nicht der angezeigte Name. Pro Feld sind mehrere Angaben möglich, z. B. 23,45.

Steht ein Status in beiden Listen, gewinnt „offen“.
Steht ein Status in keiner Liste, passiert beim Statuswechsel nichts – die Bestellung kann aber weiterhin manuell über den Button übertragen werden.

Entwurf-Modus vs. Auto-Modus

	Entwurf-Modus	Auto-Modus
Rechnung wird in sevDesk angelegt	ja	ja
Status in sevDesk	Entwurf	offen / versendet
Versand an den Kunden	Sie versenden selbst aus sevDesk	automatisch per Mail über sevDesk
Nachträglich änderbar	ja	nein – sevDesk sperrt versendete Rechnungen

Empfehlung: Starten Sie im Entwurf-Modus. Wenn Sie einige Rechnungen kontrolliert haben und mit Layout und Texten zufrieden sind, wechseln Sie auf den Auto-Modus.

Wichtig für den Auto-Modus: Betreff und Text der Mail müssen unter „SevDesk Schnittstelle - Texte“ gepflegt sein. Sind sie leer, wird die Rechnung zwar erstellt, der Mailversand aber übersprungen – mit entsprechendem Warnhinweis im Log.

Weitere Optionen

Texte der Rechnung und der Rechnungsmail

Plugins → 4TFM SevDesk Schnittstelle - Texte

Für jede im Shop aktive Sprache pflegen Sie hier fünf Felder:

Feld	Verwendung
Rechnung Kopftext	Einleitung oberhalb der Rechnungspositionen.
Rechnung Fußtext	Wird verwendet, wenn die Bestellung über die „offen“-Statusliste übertragen wurde (Zahlungsaufforderung).
Rechnung Fußtext (bezahlt)	Wird stattdessen verwendet, wenn die Übertragung über die „bezahlt“-Statusliste lief.
Mail Betreff	Betreff der Rechnungsmail – nur im Auto-Modus.
Mail Text	Text der Rechnungsmail – nur im Auto-Modus.

Platzhalter

{invoiceNumber} – die Rechnungsnummer, z. B. RE-3859
{ordersId} – die Bestellnummer aus dem Shop
[%KONTAKTPERSON%] – wird von sevDesk selbst mit Ihrem hinterlegten Ansprechpartner ersetzt (nur in den Rechnungstexten sinnvoll)

Standard-Sprache (Fallback): Die per Radiobutton markierte Sprache wird immer dann verwendet, wenn für die Sprache einer Bestellung keine Texte gepflegt sind.

Ihre im Shop hinterlegte E-Mail-Signatur (Shop-Einstellungen → E-Mail-Fußzeile) wird im Auto-Modus automatisch an den Mailtext angehängt, damit die Rechnungsmail optisch zu Ihren übrigen Shop-Mails passt.

Log – Übertragungen prüfen

Plugins → 4TFM SevDesk Schnittstelle - Log

Log-Ansicht

Zeigt die letzten 300 Vorgänge mit Zeitpunkt, Status, Bestellnummer und Meldung. Einträge älter als 90 Tage werden automatisch gelöscht.

StatusBedeutung

`SUCCESS`	Rechnung wurde erstellt bzw. versendet – Rechnungsnummer und sevDesk-ID stehen in der Meldung.
`SKIPPED`	Bestellung war bereits übertragen und wurde deshalb nicht erneut gesendet.
`WARNING`	Übertragung lief, aber etwas fehlt – z. B. nicht gepflegte Mailtexte oder ein unbekanntes Land.
`ERROR`	Übertragung fehlgeschlagen. Die Meldung enthält die Antwort von sevDesk – häufigste Ursachen: falscher API-Key, fehlende Pflichtangaben am Kontakt.

Manuell an sevDesk senden

In jeder Bestellung (Bestellungen/Kunden → Bestellungen → Bestellung öffnen) finden Sie im Memo-Bereich den Button:

„An SevDesk senden“ – die Bestellung wurde noch nicht übertragen.
„Erneut an SevDesk senden“ – es existiert bereits eine sevDesk-Rechnung dazu.

Der Button überträgt immer, auch wenn bereits eine Rechnung existiert. Dadurch entsteht in sevDesk eine zweite Rechnung mit neuer Nummer – die alte müssen Sie dort gegebenenfalls selbst löschen. Nutzen Sie den Button also gezielt, etwa nach einem behobenen Fehler.

Was genau in sevDesk ankommt

Kontakt: Das Plugin sucht in dieser Reihenfolge – Kundennummer des Shop-Kunden → E-Mail-Adresse → sonst wird ein neuer Kontakt inklusive Rechnungsadresse angelegt. Bei Firmenbestellungen dient der Firmenname als Kontaktname, sonst Vor- und Nachname. Eine hinterlegte USt-IdNr. wird mit übernommen.
Positionen: alle Artikel mit Menge, Netto- und Bruttopreis sowie Steuersatz; Artikeloptionen (z. B. Lizenzschlüssel) landen im Beschreibungstext der Position. Versandkosten und Gutscheine/Rabatte werden als eigene Positionen ergänzt.
Steuer: Deutschland 19 %, übriges EU-Ausland und Drittland mit 0 % und der jeweils passenden sevDesk-Steuerregel.
Rechnungsnummer: wird direkt aus der laufenden sevDesk-Nummernfolge gezogen (Format RE-<Nummer>), sodass keine Lücken oder Dubletten entstehen.
Zahlungsziel: 14 Tage ab Bestelldatum.
E-Rechnung: Die Rechnungen werden als E-Rechnung markiert; Adressfelder und Käuferreferenz werden entsprechend befüllt.

Doppelte Rechnungen sind ausgeschlossen

Nach erfolgreicher Übertragung merkt sich der Shop die sevDesk-Rechnungs-ID an der Bestellung. Weitere automatische Statuswechsel lösen dann keine zweite Rechnung mehr aus (Log-Eintrag SKIPPED). Nur der manuelle Button umgeht diese Sperre bewusst.

Erster Test & Fehlersuche

Erster Test

Modus auf Entwurf stellen, API-Key und Status-IDs eintragen, speichern.
Eine bestehende Testbestellung öffnen und den Button „An SevDesk senden“ klicken.
In sevDesk unter Rechnungen → Entwürfe das Ergebnis prüfen: Adresse, Positionen, Summen, Kopf- und Fußtext.
Erst danach eine echte Bestellung über den Statuswechsel testen.

Häufige Fragen

Problem	Prüfen Sie
Beim Statuswechsel passiert nichts	Steht „Für Mandant aktivieren“ auf `true`? Ist die Status-ID (nicht der Name) in einer der beiden Listen eingetragen?
Log zeigt `ERROR` mit HTTP 401	API-Key falsch, abgelaufen oder mit Leerzeichen kopiert.
Rechnung erstellt, aber keine Mail	Modus steht auf „Entwurf“ – oder Mail-Betreff/-Text sind unter „Texte“ leer (dann steht ein `WARNING` im Log).
Kontakt doppelt in sevDesk	Der Shop-Kunde hat keine Kundennummer und eine andere E-Mail-Adresse als der bestehende sevDesk-Kontakt. Kontakte in sevDesk zusammenführen.
Warnung „Kein SevDesk-Land für ISO-Code“	Das Rechnungsland ist sevDesk unbekannt; ersatzweise wird Deutschland eingetragen. Rechnung in sevDesk manuell korrigieren.