WorkTime-Anbindung (v1)
WorkTime Pro erfasst die Stunden auf der Baustelle, WorkOffice Pro macht daraus die Rechnung. Dafür gibt es eine eigene Schnittstelle unter /api/worktime/v1, je Betrieb, mit schriftlichem Vertrag. Verbindlich ist der Vertrag selbst (docs/abstimmung/vertrag-worktime-v1.md im Repositorium); dieser Artikel fasst ihn zusammen.
Verbinden
- In WorkOffice unter Verwaltung → WorkTime Pro auf Mit WorkTime verbinden klicken (Recht
apikey:manage). Es entsteht ein Schlüssel der Art „WorkTime-Verbindung“, angezeigt genau einmal, zusammen mit der Adresse von WorkOffice. - In WorkTime Pro unter Einstellungen → WorkOffice Pro Adresse und Schlüssel eintragen.
Ein Schlüssel ist genau eine Verbindung. Webhook-Adresse und -Geheimnis hängen an ihr; Trennen widerruft den Schlüssel, meldet den Webhook ab und verwirft noch wartende Zustellungen. Der Schlüssel gilt nur hier – ein allgemeiner API-Schlüssel kommt an dieser Schnittstelle nicht durch, und eine angemeldete Browsersitzung auch nicht. So hängt jede Anfrage an einer Verbindung, die der Betrieb sieht und trennen kann.
WorkTime legt nur Entwürfe an. Festschreiben (Nummer, GoBD-Sperre), Versand und Zahlungen geschehen in WorkOffice.
Grundsätze
- JSON, UTF-8. Anmeldung mit
Authorization: Bearer wo_…(oderX-API-Key). - Geld als Zahl in Euro mit höchstens vier Nachkommastellen, Mengen mit höchstens drei; Steuersatz
19,7oder0. - Zeit nach ISO 8601 mit Versatz, Tage als
JJJJ-MM-TT. Kennungen sind UUIDs und ändern sich nie. - Erweitern ja, umdeuten nein: Unbekannte Felder werden auf beiden Seiten übergangen.
Endpunkte
| Methode | Pfad | Recht | Wofür |
|---|---|---|---|
| GET | /verbindung | – | Schlüssel prüfen; Betrieb, Version, Funktionen, kleinunternehmer, nurLesen |
| PUT | /webhook | – | { "url": "https://…" } → Geheimnis (nur in dieser Antwort) |
| DELETE | /webhook | – | Webhook abmelden (204) |
| GET | /kunden | customer:read | blättern: seite, groesse (≤ 250), geaendertSeit, suche |
| GET | /kunden/:id | customer:read | ein Kunde |
| POST | /kunden | customer:write | Kunde anlegen (201); mit bekannter worktimeId 200 und der vorhandene |
| GET | /artikel | article:read | wie Kunden; ohne Lagerbestand |
| GET | /artikel/:id | article:read | ein Artikel |
| POST | /belege | document:write | Rechnungs- oder Angebotsentwurf, höchstens 500 Positionen |
| GET | /belege/:id | document:read | Nummer, Status, Netto, Brutto, offen, bezahlt am |
| DELETE | /belege/:id | document:write | einen von WorkTime angelegten Entwurf zurückziehen (204) |
Positionen haben die Arten arbeit, fahrt, material, leistung und text. Eine artikelId muss zu einem Artikel dieses Betriebs gehören, sonst kommt 422 – hier soll ein Fehler sichtbar werden, statt eine fremde Kennung still zu verwerfen. Hat der Betrieb die Warenwirtschaft, bucht das Festschreiben Material mit Artikel aus dem Lager; /verbindung meldet dann die Funktion lager.
Idempotenz: POST /belege nimmt den Kopf Idempotency-Key an. Eine Wiederholung mit demselben Wert liefert 200 und denselben Beleg statt eines zweiten – wichtig, wenn nach einem Netzfehler unklar ist, ob die erste Anfrage angekommen war.
Fehler
Jeder Fehler kommt mit HTTP-Status und { "fehler": "…", "meldung": "…" }, bei Prüffehlern zusätzlich felder mit dem Feld und dem Grund. meldung ist ein deutscher Satz, den WorkTime dem Betrieb zeigen darf.
| Status | fehler | wann |
|---|---|---|
| 401 | schluessel | Schlüssel fehlt, ist ungültig, widerrufen oder von der falschen Art |
| 403 | gesperrt | Abo abgelaufen bzw. keine gültige Lizenz („nur lesen“) oder Betrieb gesperrt |
| 403 | paket | die Anbindung gehört nicht zum Paket des Betriebs |
| 404 | unbekannt | Kennung gibt es in diesem Betrieb nicht – auch fremde |
| 409 | konflikt | z. B. Beleg ist kein Entwurf mehr |
| 422 | pruefung | Prüfung fehlgeschlagen |
| 429 | zu_viele | Taktsperre, mit Retry-After |
| 5xx | server | später wiederholen |
Paket
Der Datenaustausch – Kunden, Artikel, Belege und die Webhooks an WorkTime – gehört zum Paket Komplett. Ohne es antworten diese Endpunkte mit 403 paket, auch beim Lesen:
Die Verbindung zu WorkTime Pro gehört in WorkOffice zum Paket „Komplett“. Der Betrieb kann sein Paket unter Einstellungen → Abo wechseln.
Die Verbindung selbst (/verbindung, /webhook) geht in jedem Paket; /verbindung liefert dann "funktionen": []. Wer schon vor dem 22.10.2026 verbunden war, behält die Anbindung, solange sein Abo läuft. In der Probezeit und auf einem eigenen Server mit Lizenz ist sie immer dabei. Siehe Abo, Pakete, Funktionen.
Grenzen
- 300 Anfragen je Minute und Schlüssel (siehe Taktsperre).
- Seitengröße höchstens 250, Positionen je Beleg höchstens 500.
Die Webhooks dieser Verbindung beschreibt Webhooks.