API

Der invoiceR stellt eine REST-Schnittstelle mit JSON bereit. Jede Anfrage braucht eine Authentifizierung und läuft mit den Rechten des Benutzers, mit dem sich die Anwendung anmeldet.

Die Schnittstellen

Der invoiceR beschreibt seine Endpunkte in drei OpenAPI-Dokumenten:

Schnittstelle	Für wen	Swagger UI	OpenAPI-Datei
Public API	Anwendungen eines Mandanten, zum Beispiel ein Scan-Dienst oder ein eigenes Portal	`/docs/public`	`/docs/public.json`
Management API	Partner, die eine Installation verwalten (Benutzer, Rollen, Stammdaten, Einstellungen)	`/docs/management`	`/docs/management.json`
Interne API	Nur für die Oberfläche des invoiceR. Kann sich ohne Ankündigung ändern.	`/swagger`

Die Pfade gelten relativ zur Adresse des Backends, also zum Beispiel https://<server>/docs/public.

Swagger UI öffnen

Die Swagger-Dokumentation zeigt alle Endpunkte mit Parametern, Beispielen und den Schemas der Antworten.

Öffne https://<server>/Ui/Login und melde dich mit einem Benutzer des invoiceR an.
Auf der Startseite des Backends findest du unter anderem die Links Öffentlich (Public API) und Management (Management API). Alternativ öffnest du direkt https://<server>/docs/public oder https://<server>/docs/management.

Der Benutzer braucht die Berechtigung Swagger UI (unter Administration). Fehlt sie, antwortet der invoiceR mit dem Status 403. Bist du nicht angemeldet, leitet er dich auf die Anmeldeseite um.

Public API

Die Public API deckt den Lebenszyklus eines Belegs ab. Die Endpunkte verlangen dieselben Berechtigungen wie die entsprechenden Funktionen in der Oberfläche:

Funktion	Was sie tut	Benötigte Berechtigung
Beleg erstellen	Nimmt eine Rechnung als PDF entgegen und startet den Workflow.	Aufgaben und Dokument in Browser erfassen
Dokument hochladen	Legt ein Dokument mit Zusatzdaten (erkannter Text, gewähltes Formular, freie Zusatzdaten als JSON) für den Import bereit. Wird zum Beispiel für Spesen aus der Mobile-App verwendet.	Dokument in Browser erfassen
Beleg bearbeiten	Ändert einen bestehenden Beleg.	Aufgabe editieren
Beleg visieren	Erteilt das Visum für alle Positionen eines Belegs.	Visum erteilen
Beleg ablehnen	Lehnt alle Positionen eines Belegs mit einer Begründung ab.	Visum ablehnen
Workflow fortsetzen	Schliesst die offene Aufgabe eines Belegs ab und führt ihn in den nächsten Schritt. Die Validierungen laufen dabei wie in der Oberfläche.	Mit Beleg fortfahren

Die genauen Pfade, Methoden und Felder findest du in der Swagger UI unter /docs/public.

Management API

Die Management API richtet sich an Partner, die eine Installation betreuen. Sie bietet unter anderem:

Benutzer und Rollen: Benutzer und Rollen abfragen, Benutzer ändern, Rollen eines Benutzers setzen.
Stammdaten: bestehende Konten, Lieferanten und Währungen ändern.
Visumsstufen: Visumsstufen abfragen und deren Limiten ändern.
Einstellungen: einzelne Einstellungen des Mandanten lesen und schreiben.
Version: die installierte Version abfragen.

Jeder Endpunkt prüft die passende Berechtigung, zum Beispiel Stammdaten für die Stammdaten oder die Benutzerverwaltung für Benutzer und Rollen. Einige Endpunkte (Mandanten anlegen, System herunterfahren) sind nur für den Host-Betrieb gedacht.

Antworten

Endpunkte der Public API und der Management API geben das Ergebnis direkt als JSON zurück, ohne die Hülle { "result": …, "success": … }, die die interne API verwendet.

Fehlermeldungen

Kann der invoiceR eine Anfrage nicht ausführen, antwortet er mit einem HTTP-Fehlerstatus.

Fachliche Fehler des invoiceR erkennst du am Feld isInvoiceR. Die Antwort sieht so aus:

{
  "isInvoiceR": true,
  "code": 500,
  "message": "Kurze Beschreibung des Fehlers",
  "type": "TaskLockedException",
  "details": "{\"taskId\":4711,\"taskExternalId\":\"R-000123\",\"isCurrentUser\":false,\"lockedByDisplayName\":\"Muster Max\",\"lockedOn\":\"2026-10-29T08:15:00\",\"canUnlockTask\":false}",
  "eventNames": []
}

Feld	Bedeutung
`isInvoiceR`	Immer `true` bei fachlichen Fehlern des invoiceR.
`code`	Derselbe Wert wie der HTTP-Status. Bei den heutigen fachlichen Fehlern ist das in der Regel 500.
`type`	Art des Fehlers. Daran entscheidet deine Anwendung, wie sie reagiert.
`details`	Zusatzinformationen zum Fehler als JSON-Text. Der Aufbau hängt von `type` ab.
`eventNames`	Interne Ereignisse, die der Fehler ausgelöst hat. In der Regel leer.

Die Schemas der Fehlertypen und ihrer Details sind in den OpenAPI-Dokumenten enthalten. Häufige Typen:

TaskLockedException: Der Beleg ist gerade von einem anderen Benutzer geöffnet und gesperrt. details nennt die Aufgabe, wer sie sperrt, seit wann und ob der aktuelle Benutzer die Sperre aufheben darf. Versuche es später erneut.
ValidationException: Eine oder mehrere Validierungen sind fehlgeschlagen, zum Beispiel beim Fortsetzen des Workflows. details listet die fehlgeschlagenen Validierungen auf. Änderungen, die während der Validierung gemacht wurden, verwirft der invoiceR.

Alle anderen Fehler (zum Beispiel fehlende Berechtigung, ungültige Anfrage, Serverfehler) erkennst du am HTTP-Status: 401 ohne gültige Anmeldung, 403 ohne Berechtigung, 400 bei ungültigen Daten, 500 bei einem Fehler im Server.