REST API

DiKAS bietet eine umfangreiche REST API mit über 565 öffentlichen Endpoints in über 60 Bereichen. Damit können Sie DiKAS in Ihre bestehende Infrastruktur integrieren — vom Kassenplatz über Disco/Hotel/Booking/Ticketing bis zur DATEV-Automatisierung für die Kanzlei. (Interne und Legacy-/rest/-Endpoints sind in der öffentlichen Referenz bewusst ausgeblendet — Abschnitt weiter unten.)

Authentifizierung

Die API verwendet JWT-Bearer-Token zur Authentifizierung.

Token anfordern

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin"
}

Antwort:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "dGhpcyBpcyBhIH...",
    "expiresAt": "2026-07-13T22:00:00Z",
    "user": { "id": "usr_...", "name": "Admin", "roles": ["Admin"] }
  }
}

Token verwenden

Setzen Sie den Token im Authorization-Header:

GET /api/v1/articles
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Token erneuern

Nur der refreshToken wird benötigt — keine Zugangsdaten:

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refreshToken": "dGhpcyBpcyBh..."
}

Ein abgelaufener/ungültiger Refresh-Token liefert 401 — dann ist ein erneuter /login nötig.

API-Format

Alle Antworten folgen dem Schema:

{
  "success": true,
  "data": { ... }
}

Bei Fehlern:

{
  "success": false,
  "errorCode": "NOT_FOUND",
  "errorMessage": "Artikel mit ID 'art_123' existiert nicht"
}

Bei Validierungsfehlern zusätzlich validationErrors (Liste aus field/message). Immer zuerst success prüfen; Feldnamen sind durchgehend camelCase.

Anfragelimit (HTTP 429)

Das Limit zählt pro Client-IP in einem festen Ein-Minuten-Fenster. Wird es überschritten, antwortet der Server mit HTTP 429 — es gibt keine Warteschlange, die Anfrage wird sofort abgewiesen.

Bereich	Limit
Alle Endpunkte (Grundschutz)	1.200 Anfragen/Minute
Anmeldung, Einmalcodes und ausgewählte öffentliche Schreib-/Abfrage-Aktionen	10 Anfragen/Minute

Das strenge Limit ist ein Brute-Force-Schutz und gilt unabhängig vom Grundschutz — es betrifft unter anderem Login und OTP sowie öffentliche Endpunkte wie die Gast-Reservierung und die Gutschein-Abfrage im Online-Checkout.

Für Integrationen

Behandeln Sie 429 als vorübergehend: kurz warten und erneut versuchen (exponentiell steigende Wartezeit). Ein Massen-Import sollte in Blöcken laufen statt in einer engen Schleife.

Endpoint-Übersicht

Artikel

Methode	Endpoint	Beschreibung
GET	/api/v1/articles	Alle Artikel abrufen
GET	/api/v1/articles/{id}	Einzelnen Artikel abrufen
POST	/api/v1/articles	Artikel erstellen
PUT	/api/v1/articles/{id}	Artikel aktualisieren
DELETE	/api/v1/articles/{id}	Artikel löschen
GET	/api/v1/article-groups	Alle Gruppen abrufen
POST	/api/v1/article-groups	Gruppe erstellen

Beispiel: Artikel erstellen

POST /api/v1/articles
Authorization: Bearer eyJ...
Content-Type: application/json

{
  "name": "Cola 0,3l",
  "price": 3.50,
  "taxClass": 0,
  "groupId": "artgrp_abc123"
}

Antwort (201 Created):

{
  "success": true,
  "data": {
    "id": "art_def456",
    "name": "Cola 0,3l",
    "price": 3.50,
    "taxClass": 0,
    "groupId": "artgrp_abc123",
    "isActive": true,
    "createdDate": "2026-03-05T18:30:00Z",
    "changedDate": "2026-03-05T18:30:00Z"
  }
}

Kunden

Methode	Endpoint	Beschreibung
GET	/api/v1/customers	Alle Kunden
GET	/api/v1/customers/{id}	Einzelner Kunde
POST	/api/v1/customers	Kunde erstellen
PUT	/api/v1/customers/{id}	Kunde aktualisieren
DELETE	/api/v1/customers/{id}	Kunde löschen
GET	/api/v1/customers/{id}/account-transactions	Guthaben-/Kontobewegungen
GET	/api/v1/customers/{id}/point-transactions	Treuepunkte-Bewegungen
POST	/api/v1/customers/{id}/payout	Guthaben auszahlen
POST	/api/v1/customers/{id}/settle	Offenen Saldo (Schuldschein) ausgleichen
GET	/api/v1/customers/card/{cardId}	Kunde per Kundenkarte auflösen

Es gibt kein POST /customers/{id}/credit — Guthaben wird über die normalen Zahlungs-Endpoints aufgeladen. Details, Beispiele und der genaue Aufladeweg: → Kundenkonto: Guthaben & Punkte

Tische

Methode	Endpoint	Beschreibung
GET	/api/v1/tables	Alle Tische
GET	/api/v1/tables/{id}	Einzelner Tisch
POST	/api/v1/tables	Tisch erstellen
POST	/api/v1/tables/{id}/gang	Gang wechseln
POST	/api/v1/tables/{id}/cleaned	Als gereinigt markieren

Bestellungen & Zahlungen

Methode	Endpoint	Beschreibung
POST	/api/v1/open-bons	Bestellung aufgeben
POST	/api/v1/open-bons/batch	Mehrere Bestellungen
POST	/api/v1/payments/direct-sale	Direktverkauf
POST	/api/v1/payments/table	Tischzahlung
GET	/api/v1/receipts	Bons abrufen
POST	/api/v1/receipts/{id}/void	Bon stornieren

Personal

Methode	Endpoint	Beschreibung
GET	/api/v1/staff	Alle Mitarbeiter
POST	/api/v1/staff	Mitarbeiter erstellen
POST	/api/v1/staff/switch	Kellnerwechsel

Tagesabschluss

Methode	Endpoint	Beschreibung
POST	/api/v1/day-close	Tagesabschluss durchführen
GET	/api/v1/day-close	Alle Tagesabschlüsse
GET	/api/v1/day-close/{id}	Einzelner Tagesabschluss

Berichte

Methode	Endpoint	Beschreibung
GET	/api/v1/reports/revenue	Umsatzbericht
GET	/api/v1/reports/top-articles	Renner & Penner
GET	/api/v1/reports/wgr	Warengruppen
GET	/api/v1/reports/weekly	Wochenauswertung

Weitere Endpoints

Bereich	Prefix	Endpoints
Disco	/api/v1/disco	Cashless-Club, Karten, Buchen, Statistik — siehe Disco-API
Gutscheine	/api/v1/vouchers	CRUD, Einlösen
Banking	/api/v1/bank-transfers	CRUD, Import, FinTS-Kontoabruf (/{id}/submit-fints)
DATEV	/api/v1/datev	Konfiguration, Export, Status, Download, Senden — vollständig automatisierbar, siehe DATEV-Automatisierung
Rechnungen	/api/v1/invoices	CRUD, PDF
Mahnungen	/api/v1/dunning	Erstellen, Senden
Ausgaben	/api/v1/spendings	CRUD, Anhänge
Zeiterfassung	/api/v1/time-tracking	Stempeln, Berichte
Werkstatt	/api/v1/workshop/orders	CRUD, Status
Hotel	/api/v1/hotel/*	Zimmer, Zimmertypen, Reservierungen, Folio, Housekeeping — siehe Swagger
Booking-Engine	/api/v1/booking/*	Buchbare Pakete/Termine (z. B. Kurse, Events) — siehe Swagger
Ticketing	/api/v1/tickets	Online-Ticketverkauf — siehe Swagger
Dienstplan	/api/v1/shifts, /shift-templates, /shift-positions, /shift-swaps, /absences	Schichtplanung, Tausch, Abwesenheiten — siehe Swagger
Online-Shop	/api/v1/online-menu, /online-shop, /online-checkout, /table-order	Online-Speisekarte, Checkout, Tisch-Selbstbestellung — siehe Swagger
Lager/ERP	/api/v1/stocks, /stock-*, /distributors, /haccp	Bestand, Wareneingang/-ausgang, Inventur, Lieferanten, HACCP — siehe Swagger

Modulare Zusatzbereiche (Hotel, Booking-Engine, Ticketing)

Hotel, Booking-Engine und Ticketing werden pro Lizenz geladen und erscheinen in der live /swagger-Referenz einer Instanz, die das jeweilige Modul aktiviert hat — im statischen Referenz-Snapshot oben sind sie nicht enthalten.

Modul-Endpunkte

Die folgenden Tabellen standen bis 28.08.2026 in den Kapiteln des Benutzerhandbuchs und sind hierher umgezogen — im Handbuch steht je Modul nur noch der Verweis.

HACCP (/api/v1/haccp)

Methode	Endpoint	Beschreibung
GET	/api/v1/haccp/templates	Alle Vorlagen
POST	/api/v1/haccp/templates	Neue Vorlage erstellen
PUT	/api/v1/haccp/templates/{id}	Vorlage aktualisieren
DELETE	/api/v1/haccp/templates/{id}	Vorlage löschen
GET	/api/v1/haccp/logs	Protokolle abfragen (mit Filtern)
GET	/api/v1/haccp/logs/{id}	Einzelnes Protokoll
POST	/api/v1/haccp/logs	Neues Protokoll starten
PUT	/api/v1/haccp/logs/{id}/complete	Protokoll abschließen
POST	/api/v1/haccp/logs/{id}/photos/{index}	Foto hochladen
GET	/api/v1/haccp/logs/{id}/photos/{name}	Foto abrufen

Lieferservice (/api/v1/delivery)

Methode	Endpoint	Beschreibung
GET	/api/v1/delivery	Bestellungen abfragen (mit Filtern)
GET	/api/v1/delivery/{id}	Einzelne Bestellung
GET	/api/v1/delivery/by-number/{nr}	Bestellung nach Nummer
GET	/api/v1/delivery/stats	Statistiken (Anzahl pro Status)
POST	/api/v1/delivery	Neue Bestellung erstellen
PUT	/api/v1/delivery/{id}/status	Status aktualisieren
PUT	/api/v1/delivery/assign	Fahrer zuweisen
POST	/api/v1/delivery/{id}/pay	Bestellung bezahlen
POST	/api/v1/delivery/dispatch	Sammelversand (Dispatch)
POST	/api/v1/delivery/place	Bestellung mit Küchenbons
POST	/api/v1/delivery/optimize-route	Route optimieren
POST	/api/v1/delivery/send-route	Route als Nachrichtentext + Maps-Link liefern (verschickt nichts)
POST	/api/v1/delivery/{id}/load-for-edit	Zum Bearbeiten laden
POST	/api/v1/delivery/{id}/void-item	Position stornieren
PUT	/api/v1/delivery/{id}/reassign-driver	Fahrer umzuweisen
DELETE	/api/v1/delivery/{id}	Bestellung stornieren

Online-Bestellportal für eigene Webshops (/rest/online/{key}) — erfordert einen API-Key aus Admin → Einstellungen → API-Keys:

Methode	Endpoint	Beschreibung
GET	/rest/online/{key}/articels	Verfügbare Artikel mit Gruppen
GET	/rest/online/{key}/tables	Tischgruppen und Tische
POST	/rest/online/{key}/order	Bestellung aufgeben

Zeiterfassung (/api/v1/time-tracking)

Methode	Endpoint	Beschreibung
POST	/api/v1/time-tracking/stamp	Stempeln
GET	/api/v1/time-tracking/status/{userId}	Status abfragen
GET	/api/v1/time-tracking/active-workers	Aktive Mitarbeiter
GET	/api/v1/time-tracking/sheets/{userId}/{year}/{month}	Monats-Daten
GET	/api/v1/time-tracking/report	Zeitbericht
GET	/api/v1/time-tracking/report/excel	Excel-Export
PUT	/api/v1/time-tracking/sheets/{id}/stamps/{index}	Stempel bearbeiten
DELETE	/api/v1/time-tracking/sheets/{id}/stamps/{index}	Stempel löschen

DATEV (/api/v1/datev) — Details: DATEV-Automatisierung

Methode	Endpoint	Beschreibung
GET	/api/v1/datev/config	Konfiguration laden
PUT	/api/v1/datev/config	Konfiguration speichern
POST	/api/v1/datev/export	Export starten (asynchron)
GET	/api/v1/datev/export/{sessionId}/status	Export-Status abfragen
GET	/api/v1/datev/export/{sessionId}/download	ZIP herunterladen
POST	/api/v1/datev/send	Export + E-Mail an Steuerberater

Legacy-API

Für Kompatibilität mit bestehenden Integrationen gibt es Legacy-Endpoints unter /rest/:

Endpoint	Beschreibung
/rest/cp/add/{key}/{plu}	Artikel buchen
/rest/extern/customer/{key}/...	Kunden-CRUD
/rest/extern/voucher/{key}/...	Gutschein-CRUD
/rest/online/{key}/...	Online-Bestellungen

Legacy-Endpoints verwenden API-Keys statt JWT-Token.

SignalR (Echtzeit)

Für Echtzeit-Updates (Küchemonitor, Werkstatt, Tischstatus):

const connection = new signalR.HubConnectionBuilder()
  .withUrl("/hubs/dikas", {
    accessTokenFactory: () => jwtToken
  })
  .build();

connection.on("OrderCreated", (data) => {
  console.log("Neue Bestellung:", data);
});

connection.on("TableStatusChanged", (data) => {
  console.log("Tisch-Status:", data);
});

await connection.start();

Was ist nicht in der öffentlichen API — und warum

Ein Fremd-Entwickler soll alle fachlichen Funktionen von DiKAS über die API steuern können — Kasse, Disco, Hotel, Booking, Ticketing, Dienstplan, Lager, DATEV eingeschlossen. Bewusst nicht Teil der öffentlichen Referenz ist alles, was reiner Betrieb/Infrastruktur der DiKAS-Instanz selbst ist, kein Fremd-System legitim anspricht, oder Hardware voraussetzt, die nur am jeweiligen Gerät sitzt:

Kategorie	Beispiele	Warum nicht öffentlich
Ops/Infra/Status	Health, Sync, Restore, Reset, Relay, SystemSetup, Status-Poller, Logs	Interner Cluster-/Instanz-Betrieb, kein fachlicher Integrationspunkt
Self-Service-Portal-Backend	Portal-Account/-Auth/-Invoices/-SEPA/-Subscriptions/-Support	Eigenes Backend des Kunden-Self-Service-Portals, nicht die POS-Integrations-API
Geräte/Hardware/Terminals	Kartenterminals (ZVT/SumUp/Stripe), Kassendrucker, Barzahlung, Schankanlage, Caller-ID, Kundendisplay, Geräte-Scan/-Provisionierung	Spricht physische Geräte direkt an einer Kasse an — kein Fremdsystem klinkt sich hier ein
Fiskal-Signatur/Meldung	TSE-Signierung, Kassenmeldung (ERiC)	Gesetzlich vorgeschriebene Signier-/Meldeinfrastruktur, kein frei nutzbarer Business-Endpoint
Migration/Import	Altsystem-Migration, DSFinV-K-Import, CouchDB→SQL-Migration	Einmalige Umzugswerkzeuge, nicht für den laufenden Betrieb gedacht
Billing/Lizenz	Abonnements/Lizenzverwaltung des DiKAS-Geschäftsmodells selbst	Internes Vertragsverhältnis DiKAS↔Kunde, keine Integration durch den Kunden
Eingehende Webhooks	Lieferando, Uber Eats, Wolt	Werden von den Plattformen selbst aufgerufen, nicht von Ihrer Integration
Interne Konfiguration/Helfer	Config (Backend/Frontend-Einstellungen), E-Mail/IMAP-Versand, Geocoding, Problemberichte, Well-Known	Technische Hilfsdienste ohne eigenständigen fachlichen Nutzen von außen

Ob ein Endpoint öffentlich ist oder nicht, wird serverseitig über eine zentrale Liste (InternalApiConvention) entschieden — die Tabelle oben ist die kuratierte Erklärung dazu.

Für AI-Integratoren / Coding-Agents

Diese API ist bewusst so gestaltet, dass auch ein Coding-Agent sie ohne menschliche Rückfragen integrieren kann:

• swagger.json ist die maschinenlesbare Single Source of Truth — https://<server>/swagger/v1/swagger.json. Enthält jede öffentliche Route, jedes Request-/Response-Schema, alle <summary>-Beschreibungen. Bei Zweifel: gegen dieses Dokument verifizieren, nicht gegen diese Handbuch-Seite (die ist kuratiert, nicht vollständig).
• Immer zuerst success prüfen, bevor data gelesen wird. Bei false stehen errorCode (stabil, zum Programmieren gegen) und errorMessage (für Menschen) im Response.
• Idempotency-Key-Header bei jeder Zahlung/Buchung (POST/PUT/PATCH/DELETE) mitschicken — eine wiederholte Anfrage mit demselben Key innerhalb einer Stunde wird nicht doppelt verarbeitet.
• IDs sind opak (art_a1b2c3, cus_..., rec_...) — nicht parsen, nicht auf ein Format verlassen, nur als Ganzes weiterreichen.
• Feldnamen sind durchgehend camelCase, Beträge sind Dezimalzahlen in Venue-Währung, Datumswerte ISO-8601.
• Token-Refresh-Loop einplanen: Access-Token läuft ab (401) → POST /api/v1/auth/refresh mit dem refreshToken → einmal wiederholen. Kein Re-Login mit Zugangsdaten nötig, solange der Refresh-Token gültig ist.

Swagger / OpenAPI

Die vollständige API-Referenz mit allen 565 öffentlichen Endpoints (über 60 Bereiche) und Schemas:

→ API-Referenz (Swagger) — Interaktive Dokumentation mit Suchfunktion

Auf einer laufenden DiKAS-Instanz ist Swagger auch direkt erreichbar unter https://<server>/swagger.

---

Nächster Schritt

→ Backup & Restore — Datensicherung