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¶
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:
Token erneuern¶
Nur der refreshToken wird benötigt — keine Zugangsdaten:
Ein abgelaufener/ungültiger Refresh-Token liefert 401 — dann ist ein erneuter /login nötig.
API-Format¶
Alle Antworten folgen dem Schema:
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.
Eindeutige Nummer Ihres Systems (Wiederholsicherheit)¶
Wenn Ihre Anwendung Belege, Barausgaben oder Überweisungen anlegt (z. B. ein Ankauf mit Ankaufnummer), kann
eine Anfrage durch Zeitüberschreitung oder Verbindungsabbruch ungewiss enden. Damit eine Wiederholung nie
doppelt bucht, geben Sie im Feld externalReference die eindeutige Nummer Ihres Vorgangs mit (höchstens
100 Zeichen, z. B. A-2026-000123). Das gilt für:
| Endpunkt | Wofür |
|---|---|
POST /api/v1/incoming-documents |
Beleg (z. B. Ankaufsbeleg), PDF danach per POST /api/v1/incoming-documents/{id}/attachments |
POST /api/v1/spendings |
Barausgabe, wird sofort gebucht und TSE-signiert |
POST /api/v1/saved-transfers |
vorgemerkte Banküberweisung |
Der Server antwortet bei Wiederholung so:
| Anfrage | Ergebnis |
|---|---|
| gleiche Nummer, gleicher Inhalt | der bereits angelegte Vorgang, ohne zweite Buchung und ohne zweite Signatur |
| gleiche Nummer, anderer Inhalt | 409 mit errorCode EXTERNAL_REFERENCE_CONFLICT; der erste Vorgang bleibt unverändert |
| Nummer eines gelöschten Vorgangs | 409 mit EXTERNAL_REFERENCE_DELETED; Nummern werden nie wiederverwendet |
Groß-/Kleinschreibung und Leerzeichen am Rand der Nummer spielen keine Rolle. Alternativ oder zusätzlich
wirkt der Kopf Idempotency-Key; bei einem Konflikt lautet der Code dann IDEMPOTENCY_KEY_REUSED. Bei einem
Timeout senden Sie dieselbe Anfrage mit derselben Nummer erneut — nie mit einer neuen Nummer.
Beispiel (Barausgabe für einen Ankauf, steuerfrei, 120,00 €):
POST /api/v1/spendings
Authorization: Bearer <token>
Content-Type: application/json
{
"comment": "Ankauf A-2026-000123",
"accountMode": 1,
"accountType": 1,
"receiptDate": "2026-10-16",
"amountTaxFree": 120.00,
"externalReference": "A-2026-000123"
}
Die Antwort enthält id, externalReference, total sowie die Signaturdaten der TSE
(tseTransactionNumber, tseSignature, tseSignatureCounter, tseSerialNumber).
Hinweis zur Barausgabe
Eine Ausgabe wird mit dem Anlegen sofort gebucht. Legen Sie sie erst an, wenn die Geldübergabe bestätigt ist. Eine Ausgabe lässt sich nur löschen, solange der Tag nicht abgeschlossen und der Zeitraum nicht an die Buchhaltung übergeben ist.
Sammelüberweisung als SEPA-Datei¶
Mehrere vorgemerkte Überweisungen können Sie als eine SEPA-Datei (pain.001) für Ihr Bankprogramm abrufen:
POST /api/v1/saved-transfers/sepa-file
Authorization: Bearer <token>
Content-Type: application/json
{ "ids": ["<id-1>", "<id-2>"], "bankAccountId": null, "executionDate": "2026-10-16" }
- Zugriff nur mit Administratorrechten (Rolle
Admin). - Aufgenommen werden nur offene Überweisungen. Bereits ausgeführte oder gerade laufende werden abgelehnt.
- Alle Überweisungen einer Datei werden von einem Konto belastet. Ohne
bankAccountIdgilt das gemeinsame Konto der Aufträge, sonst das Standardkonto. - IBANs werden geprüft, die Datei enthält höchstens 500 Posten. Namen und Verwendungszweck werden auf den
SEPA-Zeichensatz gekürzt (Umlaute werden zu
ae,oe,ue,ss). - Die Nachrichten-Id der Datei ergibt sich aus den Überweisungen und dem Datum. Dieselbe Datei am selben Tag
trägt dieselbe Id, damit ein zweiter Upload bei der Bank als Dublette auffällt. Sie steht auch im Antwortkopf
X-Sepa-Message-Id(dazuX-Sepa-CountundX-Sepa-Sum). - Wer die Überweisungen direkt bei der Bank einreichen möchte, nutzt
POST /api/v1/saved-transfers/execute-batchmit demselben Rumpf (ids). Die Antwort entspricht der Einzelausführung (success,tan_requiredodervop_confirmation); nach der TAN schließen Sie jede Überweisung mitcomplete(Erfolg) bzw.resetab. - Der Abruf ändert keinen Status. Nach der Ausführung bei der Bank markieren Sie jede Überweisung mit
POST /api/v1/saved-transfers/{id}/completeals bezahlt.
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 |
Kundenliste, höchstens 100 Kunden (limit bis 500), optional search, groupId, activeOnly |
GET |
/api/v1/customers/seite |
Alle Kunden seitenweise (page, pageSize bis 500, search, groupId, sort, dir) |
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 |
Kundenliste ist begrenzt
GET /api/v1/customers liefert höchstens 100 Kunden — mit und ohne search. Mit limit sind bis zu 500
möglich. Ohne Suche stehen die zuletzt geänderten Kunden vorn, mit Suche die genauen Treffer (Kundennummer, Karte,
E-Mail).
Ob die Liste vollständig ist, steht im Antwortkopf X-Has-More: false = alle passenden Kunden sind dabei,
true = es gibt mehr. Dann zeigt der Kopf Link auf /api/v1/customers/seite mit denselben Filtern.
Sie brauchen alle Kunden (Abgleich, Export): Blättern Sie über GET /api/v1/customers/seite?page=1&pageSize=500,
dann page=2 usw., bis hasMore in der Antwort false ist. Die Antwort trägt außerdem totalCount.
Ausnahme: openBalanceOnly=true ohne limit liefert weiter alle Kunden mit offenem Saldo.
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 Endpunkte der einzelnen Module — im Benutzerhandbuch steht je Modul nur ein Verweis hierher.
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 |
Neue Webshop-Anbindung
Für neue Anbindungen verwenden Sie die aktuelle Schnittstelle unter /api/v1/…, siehe Eigenen Webshop anbinden. Das Online-Bestellportal unten bleibt für bestehende Anbindungen erhalten.
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) |
Buchen ohne Preis: es gilt der Preis der Kasse
Schickt ein Fremdsystem bei /rest/cp/add oder /rest/cp/addcard keinen Preis, bucht DiKAS denselben Preis, den die Kasse an diesem Arbeitsplatz zeigen würde: Mengenstaffel, sonst die Preisregeln (Happy Hour, Wochentage, Bereich des Tisches) mit dem Arbeitsplatz des API-Keys und der Uhrzeit und Tagesgrenze des Betriebs. /rest/cp/getprice/{key}/{plu} meldet genau diesen Preis. Ein mitgeschickter Preis gilt immer unverändert.
- Happy-Hour-Preis fehlt auf dem Bon? Prüfen Sie, ob das Fremdsystem einen Preis mitschickt (der gewinnt) und ob die Regel eine Arbeitsplatz-Bedingung hat: Dann muss am API-Key (Admin → Einstellungen → API-Keys) genau dieser Arbeitsplatz eingetragen sein. Ohne Arbeitsplatz am Key greift eine Arbeitsplatz-Regel nicht.
- Kartenterminal mit Kundenguthaben (
/rest/cp/addcard/{key}/{Karte}): Guthaben-Prüfung, Abbuchung und Bon tragen genau diesen Preis; zusätzlich gilt eine Preisregel für die Kundengruppe der Karte (z. B. Stammgast-Preis)./rest/cp/card/{key}/{Karte}zeigt dem Terminal denselben Stückpreis. Rabattartikel mit Prozentsatz lassen sich dort nicht buchen (die Meldung nennt die PLU) — sie gehören an die bediente Kasse. - Kauf am Kartenterminal scheitert mit „unbare Überzahlung nicht zulässig“? Das betraf Artikel mit Mengenstaffel ab der Staffelmenge in Versionen vor dem 17.11.2026 — ein Update genügt.
- Versionen vor dem 17.11.2026 buchten ohne Preis immer den normalen Artikelpreis — ein Update genügt.
- Online-Bestellungen (
/rest/online/…) ohne Preis werden zum normalen Artikelpreis gebucht — dem Preis, den/rest/online/{key}/articelsdem Shop meldet.
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.
Nach der Umstellung von DiKAS Classic auf DiKAS next: Adresse des Fremdsystems umstellen
Ein Fremdsystem, das die Legacy-Endpoints bisher über https://<name>.portal.dikas.de/rest/... aufgerufen hat, ruft nach der Umstellung https://<name>.next.dikas.de/rest/... auf — gleicher Pfad, gleicher API-Key. Bitte die Adresse im Fremdsystem umstellen.
- Das alte Portal leitet nicht mit Pfad weiter: Aufrufe unter
.../portal.dikas.de/rest/...landen nach der Umstellung auf der Startseite von DiKAS next und erreichen die Schnittstelle nicht. Die Adresse im Fremdsystem muss deshalb umgestellt werden. - Fremdsystem bekommt nach der Umstellung keine Daten mehr oder landet auf einer Anmeldeseite? Dann ruft es noch die alte Portal-Adresse auf. Adresse wie oben umstellen.
- Ruft das Fremdsystem die Kasse im eigenen Netz direkt an (eigener Hostname statt
portal.dikas.de), betrifft es die Umleitung nicht — dort zählt, unter welchem Namen und Zertifikat die Kasse nach der Umstellung erreichbar ist (Support fragen).
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.jsonist 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
successprüfen, bevordatagelesen wird. BeifalsestehenerrorCode(stabil, zum Programmieren gegen) underrorMessage(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. Für Belege, Barausgaben und Überweisungen zusätzlichexternalReferencemit der eindeutigen Nummer Ihres Vorgangs setzen — das gilt dauerhaft, nicht nur eine Stunde (siehe Eindeutige Nummer Ihres Systems).- 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/refreshmit demrefreshToken→ einmal wiederholen. Kein Re-Login mit Zugangsdaten nötig, solange der Refresh-Token gültig ist.
Swagger / OpenAPI¶
Die API-Referenz nach Bereichen:
→ API-Referenz (Swagger) — Übersicht der Bereiche und Endpunkte
→ API-Referenz Webshop — Referenz zur Anbindung eines eigenen Webshops (Karte, Bestellung, Artikel, Ereignisse, Webhooks, Partner-Schlüssel) mit OpenAPI-Datei zum Herunterladen
Auf Instanzen, auf denen die Referenz freigeschaltet ist, ist Swagger direkt erreichbar unter https://<server>/swagger.
Nächster Schritt¶
→ Backup & Restore — Datensicherung