API-Zugänge und Rechte: Was brauche ich wofür?¶

DiKAS kennt mehrere Arten, sich an einer Schnittstelle anzumelden. Jede hat eigene Rechte und einen eigenen Zweck. Diese Seite hilft bei der Frage „Welchen Zugang brauche ich für meine Aufgabe?" – und beantwortet für Ketten-Gutscheine, welches Recht zu welchem Aufruf gehört.

Die Zugangsarten im Überblick¶

Zugang	Wer legt ihn an	Anmeldung	Rechte bestimmen	Typischer Einsatz
Benutzer-Anmeldung (REST API Version 1)	Administrator der Instanz (Benutzer)	`POST /api/v1/auth/login` → Bearer-Token	Die Rechte des angemeldeten Benutzers	Eigene Auswertungen, Artikel- und Kundenpflege, lokale Gutscheinabfrage
API-Key (Legacy-Schnittstelle `/rest/…`)	Administrator unter Admin → Einstellungen → API-Keys	Header `X-Api-Key` (Pfadsegment `{key}` dann `-`)	Der Zugriffstyp des Schlüssels	Online-Shop, Kunden-/Gutschein-Anbindung bestehender Software, Zahlautomaten, Drehkreuz
Integrationszugang einer Kette	Ketten-Eigentümer über das Kundenportal	Header `Authorization: Bearer <schlüssel>` oder `X-Api-Key`	Rechte (`voucher:…`) und Filialen des Zugangs	Fremdkassen, die Kettengutscheine prüfen, einlösen, erstatten, ausgeben
Portal-Anmeldung	Kunde mit seinem Kundenkonto (`konto.dikas.de`)	Portal-Login	Rolle in der Kette: Eigentümer oder Filiale	Kette verwalten, Integrationszugänge anlegen, Verrechnung, Berichte

Faustregel: Ein Zugang, der Geld bewegt, bekommt nur die Rechte, die seine Aufgabe braucht, und nur die Filialen, in denen er arbeitet. Vergeben Sie lieber einen eigenen Zugang je Kasse oder Dienstleister – so lässt sich ein einzelner sperren, ohne die anderen zu stören.

„Ich will …" – welcher Zugang?¶

Aufgabe	Zugang	Recht / Typ
Einen lokalen Gutschein abfragen	Benutzer-Anmeldung (`GET /api/v1/vouchers/…`) oder API-Key	Benutzerrechte bzw. Zugriffstyp Voucher
Einen lokalen Gutschein aus einer bestehenden Anwendung anlegen oder belasten	API-Key (`/rest/extern/voucher/-/…`)	Zugriffstyp Voucher
Einen Kettengutschein prüfen	Integrationszugang	`voucher:lookup`
Kettengutschein einlösen (reservieren, ankündigen, bestätigen, freigeben)	Integrationszugang	`voucher:redeem`
Kettengutschein erstatten	Integrationszugang	`voucher:refund`
Kettengutscheine ausgeben oder Karten aktivieren (samt Abschluss und Abbruch)	Integrationszugang	`voucher:issue`
Änderungen an Kettengutscheinen abholen	Integrationszugang	`voucher:export`
Einen Vorgang abfragen (`operations/…`) oder das Programm (`programs`) lesen	Integrationszugang	irgendein Recht
Einen Integrationszugang anlegen, erneuern oder sperren	Portal-Anmeldung	Ketten-Eigentümer
Bestellungen aus einem eigenen Online-Shop annehmen	API-Key	Zugriffstyp OnlineOrder
Einen Zahlautomaten (Disco) anbinden	API-Key	Zugriffstyp Disco
Kunden, Artikel, Buchungen oder Druckaufträge per Legacy-Schnittstelle bearbeiten	API-Key	passender Zugriffstyp (siehe unten)
Verrechnung, Abrechnung, DATEV-Konfiguration, Kartenbögen der Kette sehen	Portal-Anmeldung	Ketten-Eigentümer

API-Keys: Zugriffstypen¶

Beim Anlegen eines Schlüssels unter Admin → Einstellungen → API-Keys wählen Sie den Zugriffstyp. Er legt fest, was der Schlüssel darf. Technisch gibt es folgende Typen: OnlineOrder (Online-Bestellungen), LagerOrder, Datev, Bookings, Customer, Article, Print, CustomerBookings, Voucher, Disco und CustomerContacts.

Ein Schlüssel hat genau einen Zugriffstyp. Brauchen Sie zwei Aufgaben, legen Sie zwei Schlüssel an.
Bei Zahlautomaten bestimmt der Schlüssel zusätzlich den Arbeitsplatz (siehe REST API).
Vertrauliche Schlüssel gehören nicht in URLs. Neue Clients senden sie im Header X-Api-Key und lassen im Pfad - stehen.
Ein Schlüssel kann jederzeit gelöscht und ersetzt werden; die Anbindung muss dann umgestellt werden.

Integrationszugang: Welches Recht für welchen Aufruf?¶

Alle Aufrufe liegen unter /api/v1/integrations/vouchers. Ein Aufruf ohne das nötige Recht endet mit 403 INSUFFICIENT_SCOPE, bevor etwas gebucht wird.

Aufruf	Benötigtes Recht
`GET /programs`	irgendein Recht
`POST /lookup`	`voucher:lookup`
`POST /reservations`	`voucher:redeem`
`POST /reservations/{id}/prepare`	`voucher:redeem`
`POST /reservations/{id}/commit`	`voucher:redeem`
`POST /reservations/{id}/release`	`voucher:redeem`
`POST /refunds`	`voucher:refund`
`POST /issues`	`voucher:issue`
`POST /activations`	`voucher:issue`
`POST /operations/{id}/complete`	`voucher:issue`
`POST /operations/{id}/cancel`	`voucher:issue`
`GET /changes`, `GET /transactions`	`voucher:export`
`GET /operations/{id}`, `GET /operations/by-reference/{referenz}`	irgendein Recht

Typische Rechte-Pakete¶

Einsatz	Rechte
Fremdkasse, die nur einlöst	`voucher:lookup`, `voucher:redeem`
Fremdkasse mit Storno/Retoure	zusätzlich `voucher:refund`
Kasse, die auch Gutscheine verkauft	zusätzlich `voucher:issue`
Buchhaltung oder BI-Werkzeug, das nur mitliest	`voucher:export`

Ein Zugang, der nur mitliest, braucht weder redeem noch refund noch issue. Umgekehrt braucht eine Kasse, die einlöst, kein export, solange sie keinen Feed abholt.

Filialen¶

Zusätzlich zu den Rechten bekommt jeder Integrationszugang eine Liste von Filialen. Er sieht und bucht nur dort:

Eine Filiale außerhalb der Liste antwortet wie „unbekannt" (BRANCH_UNKNOWN, 404) – nicht „verboten". Das verrät nicht, welche Filialen es gibt.
Erstattet wird nur in der Filiale, die eingelöst hat.
Tritt eine Filiale aus der Kette aus, wirkt das bei der nächsten Anfrage.

Zugang verwalten¶

Nur der Ketten-Eigentümer darf Zugänge anlegen, erneuern und sperren (mit Portal-Anmeldung, siehe Externe Gutscheinsysteme anbinden). Eine Filiale der Kette kann das nicht, auch nicht mit Teilnahme „Voll".

Aktion	Folge
Anlegen	Schlüssel wird einmal angezeigt; DiKAS speichert nur einen Hash
Schlüssel erneuern	Der alte Schlüssel gilt sofort nicht mehr
Sperren	Aufrufe antworten mit `CLIENT_BLOCKED`
Rechte oder Filialen ändern	Wirkt ab der nächsten Anfrage

Rollen in der Kette (Portal)¶

Im Kundenportal unterscheidet DiKAS drei Sichten. Was sie sehen, steht ausführlich in Filialen & Ketten – Wer sieht was?:

Rolle	Kann
Ketten-Eigentümer	Alles der Kette: Mitglieder, Einstellungen, Artikelstamm, Verrechnung, Abrechnung, DATEV-Konfiguration, Kartenbögen, Integrationszugänge; sieht Gutscheine und Kunden vollständig
Filiale mit Teilnahme „Voll"	Gutscheine und Kunden der eigenen Filiale sehen (Nummern maskiert), eigene Einlösungen und Erstattungen durchführen; keine Verwaltung der Kette
Filiale mit „Nur Reporting"	Berichte und Kennzahlen; kein Zugriff auf Kundenverlauf

Die Teilnahme „Voll" ist Voraussetzung dafür, dass eine Filiale überhaupt Gutscheine einlöst oder ausgibt. Eine Filiale mit „Nur Reporting" löst nicht ein – auch nicht über einen Integrationszugang.

Fehlerbilder: Wo liegt es am Recht?¶

Meldung	Wahrscheinliche Ursache	Was tun
`401` / `INVALID_CREDENTIALS`	Schlüssel falsch, abgelaufen oder erneuert	Aktuellen Schlüssel prüfen; beim Eigentümer neu erzeugen lassen
`403 INSUFFICIENT_SCOPE`	Dem Zugang fehlt das Recht für diesen Aufruf	Tabelle oben; Recht beim Eigentümer ergänzen lassen
`404 BRANCH_UNKNOWN`	Filiale nicht für den Zugang freigegeben, oder ausgetreten	Filialenliste des Zugangs prüfen
`CLIENT_BLOCKED`	Zugang gesperrt	Beim Eigentümer klären
`429 RATE_LIMITED`	Mehr als 600 Aufrufe pro Minute	`Retry-After` abwarten, mit demselben Key wiederholen
Legacy: Antwort ohne Daten trotz `200`	Falscher Zugriffstyp des API-Keys	`IsOk` und `ErrorId` prüfen; Typ des Schlüssels kontrollieren

Prinzip der geringsten Rechte

Beginnen Sie mit voucher:lookup und fügen Sie Rechte erst hinzu, wenn die Anbindung sie braucht. Ein Fehler in einer Anbindung kann dann höchstens das auslösen, wofür sein Zugang gedacht war.