Zum Inhalt
v26.3

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.

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 bankAccountId gilt 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 (dazu X-Sepa-Count und X-Sepa-Sum).
  • Wer die Überweisungen direkt bei der Bank einreichen möchte, nutzt POST /api/v1/saved-transfers/execute-batch mit demselben Rumpf (ids). Die Antwort entspricht der Einzelausführung (success, tan_required oder vop_confirmation); nach der TAN schließen Sie jede Überweisung mit complete (Erfolg) bzw. reset ab.
  • Der Abruf ändert keinen Status. Nach der Ausführung bei der Bank markieren Sie jede Überweisung mit POST /api/v1/saved-transfers/{id}/complete als 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}/articels dem 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.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. Für Belege, Barausgaben und Überweisungen zusätzlich externalReference mit 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/refresh mit dem refreshToken → 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