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.

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.

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