Spesen & Belege über die API anlegen

Über die API erzeugst du Belege – also Spesen, Eingangsrechnungen, Kilometergeld, Material, Provisionen, Verpflegungsmehraufwand, Überstundenauszahlungen und Zuschläge. Ein Beleg besteht immer aus zwei Teilen:

Belegart (expenseCategory) – liefert die Rahmenbedingungen, etwa die Währung, und unterscheidet die Belegtypen. Diese verwaltest du in teamspace unter „Belegarten”.
Beleg (expense) – das eigentliche Belegelement mit allen Daten.

Beim Anlegen eines neuen Belegs musst du immer die ID der Belegart mitgeben. Fehlt sie, gibt die API einen Fehler zurück.

1. Belegart und ihre ID ermitteln

Die Belegarten liest du über den Endpunkt der Belegart-Collection aus. Er unterstützt nur GET und dient zum Nachschlagen – du findest darüber die Belegart mit dem gesuchten Typ:

GET  server/api/expensecategory

Die Belegart trägt unter anderem Name, internen Namen, Beschreibung, Aktiv-Status, Typ, Währung sowie Standard-Zahlungsart und Standard-Fahrzeug. Die genauen Felder stehen in der Feldreferenz.

ID alternativ über die Oberfläche auslesen: Bearbeite eine Belegart und aktiviere den Debug-Modus mit der Tastenkombination STRG + # bzw. STRG + ^. Anschließend kannst du den ID-Wert kopieren.

Belegart im Debug-Modus – die ID auslesen (STRG + #)

2. Beleg anlegen

Mit der ID der Belegart legst du den Beleg über den Beleg-Endpunkt an:

POST  server/api/expense

Über diesen Endpunkt lassen sich folgende Belegarten erzeugen: Beleg, Eingangsrechnung, Kilometergeld, Material, Provision, Verpflegungsmehraufwand, Überstundenauszahlung und Zuschlag. Welcher Typ entsteht, bestimmt die zugeordnete Belegart.

Ein Kilometergeld-Beleg sieht zum Beispiel so aus:

POST /api/expense
{
  "date": "2025-03-03",
  "expenseCategory": 11582821,
  "coworker": 54967,
  "distance": 100,
  "vehicle": "PRIVATE"
}

Welche Felder du je Belegart mitgeben musst und welche optional sind – samt Beispielen für alle acht Belegarten – steht vollständig in der Feldreferenz: Spesen- und Belegfelder.

3. Beträge und Abrechenbarkeit verstehen

Pflichtfelder sind in der Feldreferenz mit * markiert und für das Anlegen zwingend erforderlich.
Beträge, die nicht als Pflichtfeld markiert sind, berechnet das System selbst. Du kannst sie überschreiben – es besteht aber das Risiko, dass sie beim manuellen Bearbeiten im System erneut überschrieben werden.
Für die Abrechenbar-Optionen (externalBillable, projectBillable, coworkerBillable) gilt der Wert der Belegart als Fallback. Die Automatik addiert den Betrag – analog zum System – immer dann, wenn „Abrechenbar” nicht auf „NEIN” steht. Willst du abweichende Werte, musst du sie manuell angeben.
Sind bei einem Beleg sowohl Netto als auch Brutto leer, wird der Basispreis der Belegart herangezogen. Ist keiner definiert, kommt ein Fehler zurück. Ist nur das Brutto angegeben, wird das Netto berechnet.

Typische Fragen & Anforderungen

Du möchtest …	So geht’s
die ID einer Belegart finden	`GET server/api/expensecategory` abfragen oder die Belegart in der Oberfläche im Debug-Modus (`STRG + #`) öffnen und den ID-Wert kopieren.
einen Kilometergeld-Beleg anlegen	`POST server/api/expense` mit `expenseCategory`, `coworker`, `distance` und `vehicle`.
die Pflichtfelder einer Belegart nachschlagen	In der Feldreferenz: Spesen- und Belegfelder – dort sind Pflichtfelder mit `*` markiert.
abweichende abrechenbare Beträge setzen	Die Abrechenbar-Felder (`externalBillable`, `projectBillable`, `coworkerBillable`) manuell angeben – sonst gilt der Wert der Belegart als Fallback.

Häufige Probleme

Warum gibt die API beim Anlegen einen Fehler zurück? Beim Anlegen eines Belegs musst du immer die ID der Belegart (expenseCategory) mitgeben. Fehlt sie, antwortet die API mit einem Fehler. Die ID ermittelst du über GET server/api/expensecategory oder im Debug-Modus.

Warum wird mein Belegbetrag nicht übernommen oder ist falsch? Beträge, die nicht als Pflichtfeld markiert sind, berechnet das System selbst. Überschreibst du sie manuell, können sie beim späteren Bearbeiten im System erneut überschrieben werden. Setze nur dort eigene Werte, wo du sie wirklich brauchst.

Warum kommt bei einem Beleg ein Fehler, obwohl Netto und Brutto leer sind? Sind sowohl voucherNetto als auch voucherGross leer, greift der Basispreis der Belegart. Ist keiner definiert, gibt die API einen Fehler zurück. Gib entweder einen Betrag an oder hinterlege einen Basispreis an der Belegart.

Hinweise

Die Belegart-Collection (expensecategory) ist rein informativ (nur GET) – Belegarten selbst pflegst du in der Oberfläche unter „Belegarten”.
Achte auf das Datumsformat ISO (YYYY-MM-DD); ohne Datum wird der aktuelle Tag verwendet.
Konkrete Request-Beispiele je Belegart liefert der API Compact Guide (PDF & PowerPoint zum Download).