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	Lokale Gutscheinverwaltung — Abgrenzung zur Kette und Beispiele: Gutscheine und Fremdsysteme
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
POST	/rest/online/{key}/open	Bestellung ohne Zahlung aufgeben
POST	/rest/online/{key}/pay	Bereits bezahlte Bestellung als Kassenbeleg buchen

Unbekannte Artikel

Kennt die Kasse einen Artikel der Bestellung nicht (weder Id noch Artikelnummer noch Name), legt DiKAS ihn bei order, open und pay selbst an – mit dem Namen und Preis des Shops und dem normalen Steuersatz des Betriebs, ohne Artikelgruppe. Ohne Namen wird nichts angelegt, ein deaktivierter Artikel bleibt eine Ablehnung (Article not found), und je Bestellung entstehen höchstens 20 neue Artikel.

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}/...	Lokale Gutscheine abrufen, anlegen und einlösen; keine Kettenverwaltung
/rest/online/{key}/...	Online-Bestellungen
/rest/disco/guest/pay/{key}[/{Karte}]	Disco-Karte bezahlen und auschecken (z. B. Zahlautomat)

Zahlautomaten: Arbeitsplatz und Drucker

Bei /rest/disco/guest/pay genügt ein API-Key für mehrere Zahlautomaten. Der Arbeitsplatz kommt vom Key (Admin → Einstellungen → API-Keys), im Aufruf ist keiner nötig (WorkplaceId darf null sein). Den Bon-Drucker nennt jeder Automat im Feld Printer des Zahlauftrags – als Drucker-Id oder als IP, auch mit Port (192.168.1.52:9100), Groß-/Kleinschreibung egal. Ist er unbekannt oder leer, druckt der Bon auf dem Zieldrucker des Arbeitsplatzes bzw. dem Standarddrucker; die Zahlung scheitert daran nicht.

Legacy-Endpoints verwenden API-Keys statt JWT-Token. Neue Clients übermitteln den Schlüssel mit X-Api-Key oder Authorization: ApiKey …; im weiterhin erforderlichen Pfadsegment {key} steht dann -. Vertrauliche Schlüssel gehören nicht in URLs. Für die abweichenden Antwortfelder und Gutscheinabläufe siehe Gutscheine und Fremdsysteme.

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	Lieferdienst-Anbindung, 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