Einstieg

WorkOffice Pro hat nicht eine Schnittstelle, sondern mehrere – jede für einen anderen Zweck. Alle sind gewöhnliches REST über JSON und laufen unter derselben Adresse wie die Oberfläche: Die Oberfläche leitet /api/* an die API weiter, nach außen genügt ein Name (siehe HTTPS mit Caddy).

Die Übersicht

Pfad	Für wen	Anmeldung	Stabil?
`/api/v1/…`	die eigene Oberfläche, eigene Werkzeuge	Sitzung (JWT) oder API-Schlüssel	darf sich ändern
`/api/worktime/v1/…`	WorkTime Pro, direkte Verbindung	nur Schlüssel einer WorkTime-Verbindung	ja, Vertrag v1
`/api/lexware/v1/…`	Programme, die Lexware Office sprechen, ältere WorkTime-Fassungen	nur API-Schlüssel	ja, wie Lexware
Webhooks	wer Änderungen gemeldet bekommen will	–	ja
`/api/v1/kombi/status`	nur die beiden Cloud-Server des Herstellers untereinander	Signatur	–

Warum die Oberflächen-API sich ändern darf

Unter /api/v1 liegt alles, was die Oberfläche selbst benutzt: Kunden, Belege, Bank, Einstellungen. Mit einem API-Schlüssel ist sie auch für eigene Programme erreichbar. Sie folgt aber der Oberfläche – kommt dort ein Feld dazu oder ändert sich ein Ablauf, ändert sich der Endpunkt mit. Ein fremdes Programm, das jahrelang laufen soll, braucht etwas Stabiles.

Stabil sind deshalb die beiden Schnittstellen für andere Programme:

/api/worktime/v1 folgt einem schriftlichen Vertrag zwischen WorkOffice Pro und WorkTime Pro. Die Regel dort: Erweitern ja, umdeuten nein. Neue Felder dürfen dazukommen, und beide Seiten übergehen, was sie nicht kennen; Weglassen oder Umdeuten gibt es erst mit v2. Siehe WorkTime-Anbindung (v1).
/api/lexware/v1 bildet die Schnittstelle von Lexware Office nach, im Umfang, den WorkTime Pro und andere Programme nutzen. Ihr Maßstab ist Lexware selbst. Siehe Lexware-kompatible Schnittstelle.

Die Schnittstellenbeschreibung

Unter /api/docs liegt eine OpenAPI-Beschreibung der Endpunkte unter /api/v1 mit allen Feldern und Prüfregeln. Im Betrieb ist sie ausgeschaltet, weil sie die gesamte Schnittstelle offenlegt; mit ENABLE_API_DOCS=true in der .env und einem Neustart (up -d) geht sie an. Die WorkTime- und die Lexware-kompatible Schnittstelle stehen bewusst nicht darin – für sie gelten der Vertrag bzw. Lexware.

Was mit einer Anfrage geschieht

Anmeldung prüfen. Standardmäßig ist alles geschützt, außer den wenigen Endpunkten, die öffentlich sein müssen – unter anderem Anmeldung, Registrierung, Kundenportal, /api/health, /api/ready und der öffentliche Schlüssel der Webhooks.
Taktsperre. Siehe Taktsperre.
Rechte prüfen – die Rechte des Benutzers bzw. des Schlüssels.
Abo, Paket und Lizenz prüfen. Steht der Betrieb auf „nur lesen“, wird alles abgewiesen, was schreibt (402). Gehört eine Funktion nicht zum Paket, kommt 403.
Felder prüfen (nur /api/v1): Unbekannte Felder führen zu einem Fehler, statt stillschweigend verworfen zu werden – ein Tippfehler im Feldnamen wäre sonst eine Änderung, die nie stattfindet.

Ein JSON-Leib darf höchstens 2 MB groß sein.

Statuscodes unter `/api/v1`

Code	Bedeutung
200 / 201	in Ordnung
400	Anfrage fachlich nicht möglich – die Meldung sagt warum
401	nicht angemeldet, Sitzung abgelaufen oder Schlüssel ungültig
402	Betrieb steht auf „nur lesen“ (kein Abo bzw. keine gültige Lizenz)
403	Recht fehlt, oder die Funktion gehört nicht zum Paket
404	nicht gefunden – auch, wenn es zu einem anderen Betrieb gehört
409	Konflikt, z. B. ein festgeschriebener Beleg (GoBD)
429	Taktsperre

Fehler kommen einheitlich als { "statusCode", "message", "error" }; message ist ein deutscher Satz. Die WorkTime- und die Lexware-kompatible Schnittstelle haben jeweils ihr eigenes Fehlerformat.

Betriebe

Jeder Zugang gehört zu genau einem Betrieb – die Sitzung über den Benutzer, der Schlüssel über den Betrieb, in dem er erzeugt wurde. Einen Weg, über die Schnittstelle einen anderen Betrieb zu erreichen, gibt es nicht; fremde Kennungen ergeben 404.