REST API

Die REST API verwaltet API-Clients, Client-IDs, Secrets, Scopes, alte API-Key-Berechtigungen, Dokumentation und Schnittstellen-Logs fuer externe Integrationen.

Navigation und Voraussetzungen

Der Bereich besteht aus zwei Reitern: Uebersicht fuer Clients und Dokumentation sowie Logs fuer Schnittstellen-Logdateien.

• Rechtepruefung: Ohne das Recht fuer das API-Setup wird die Seite nicht ausgegeben.
• App-Pruefung: Ist die REST-API-App nicht aktiv, zeigt die Uebersicht einen Setup-Hinweis. Die Client-Tabelle wird zwar ausgegeben, neue Clients und Optionen werden aber nur bei aktiver App sinnvoll angeboten.
• Version 2: Die Uebersicht zeigt die Basisadresse der aktuellen API-Generation und einen Link zur interaktiven Dokumentation.
• Version 1: Die alte API-Generation wird nur noch als veralteter Bereich angezeigt und ueber API-Key, Hash-Token und Methodenrechte gepflegt.
• Developer-Aktion: Wenn der Developer-Modus aktiv ist, erscheint die Aktion DOC JSON erstellen. Die Aktion erzeugt die OpenAPI-Datei neu.

Client-Tabelle

Die Uebersicht verwendet eine konfigurierbare BsTable. Nutze die Tabellensuche fuer sichtbare Werte wie Bezeichnung oder Client-ID. Ein separates Filterformular gibt es nicht.

• ID: interne Client-ID des API-Setups; auf kleinen Ansichten ausgeblendet.
• Bezeichnung: zeigt name und ist die Hauptspalte der Tabelle.
• API-Key v1: zeigt apikey, ist standardmaessig ausgeblendet und auf kleinen Ansichten verborgen.
• Client ID v2: zeigt client_id; auf kleinen Ansichten ausgeblendet.
• E-Mailadresse: zeigt email, ist standardmaessig ausgeblendet und dient als Zieladresse fuer das Client Secret.
• Optionen: enthaelt Bearbeiten, Client Secret erstellen und zusenden sowie Loeschen. Die Secret-Aktion erscheint nur, wenn client_id gesetzt ist und is_active aktiv ist. Die Spalte ist zentriert und nicht sortierbar.

Client erstellen und bearbeiten

Ueber ApiKey erstellen oder die Bearbeiten-Aktion oeffnet sich ein grosser Dialog. Das Formular kombiniert aktuelle API-v2-Einstellungen mit dem veralteten v1-Bereich.

• name: Pflichtfeld fuer die interne Bezeichnung des Clients und Hauptwert in der Tabelle.
• email: Pflichtfeld fuer die E-Mail-Adresse, an die ein neu erzeugtes Client Secret gesendet wird.
• is_active: Ja/Nein-Feld fuer den Zugriff auf die API. Die Secret-Aktion in der Tabelle wird nur fuer aktive Clients angeboten.
• client_id: frei vergebene zusammenhaengende Zeichenkette fuer OAuth-Client-Zugriffe. Die Client-ID wird nicht automatisch per Secret-Mail mitgeteilt und muss separat kommuniziert werden.
• type: Client-Typ mit den Optionen api_user fuer API-Benutzer und trust_agent fuer KI-Agenten. Neue Objekte starten intern als api_user.
• scopes[]: Scope-Auswahl fuer API Version 2. Beim Speichern werden die gewaehlten Scopes als Leerzeichen-getrennte Liste gespeichert.
• apikey: API-Key fuer Version 1. Wenn noch kein Key vorhanden ist, erzeugt das Formular einen neuen Wert und zeigt ihn schreibgeschuetzt an.
• hashToken: Token fuer Signaturpruefungen der alten API-Version.
• v1-Ressourcenrechte: Fuer Baskets, Bills, Content, Customers, NewsletterRecipients, Orders, Products, ProductsStock und Webhooks koennen die Methoden GET, POST, PUT und DELETE einzeln aktiviert werden.

Scope-Matrix fuer API Version 2

Die Scope-Matrix wird dynamisch aus den erkannten API-v2-Scopes aufgebaut. Zeilen stehen fuer Entitaeten, Spalten fuer Aktionen.

• Aktionen: Die Matrix unterscheidet read, create, update und delete.
• Verfuegbarkeit: Wenn eine Aktion fuer eine Entitaet nicht existiert, zeigt die Zelle nur einen Platzhalter und keine Checkbox.
• Alle-Checkbox: Die Kopf-Checkbox waehlt alle vorhandenen Scope-Checkboxen der Tabelle aus oder ab.
• Zeilen-Checkbox: Die Checkbox in einer Zeile waehlt alle verfuegbaren Aktionen dieser Entitaet aus oder ab. Zeilen ohne Scopes werden deaktiviert dargestellt.
• Teilstatus: Tabelle und Zeilen zeigen einen Zwischenstatus, wenn nur ein Teil der enthaltenen Scopes aktiv ist.
• Speicherung: Beim Speichern ersetzt die neue Auswahl den bisherigen Scope-String des Clients.

Client Secret erstellen und senden

Die Secret-Aktion oeffnet einen separaten Dialog. Der Dialog erzeugt ein neues Secret, speichert nur den Hash am Client und sendet das Klartext-Secret einmalig an die hinterlegte E-Mail-Adresse.

1. Die Aktion ist nur fuer aktive Clients mit gesetzter client_id sichtbar.
2. Beim Ausfuehren wird ein zufaelliges Secret erzeugt.
3. Das Secret wird mit Bcrypt gehasht und als client_secret gespeichert.
4. Die E-Mail enthaelt Client Secret, Hinweis zur separat mitzuteilenden Client-ID, die zugeteilten Scopes und den Hinweis auf die interaktive Dokumentation.
5. Nach erfolgreichem Versand wird der Dialog geschlossen und eine Erfolgsmeldung ausgegeben.
6. Der Vorgang wird im Backend-Log mit Client-ID und Bezeichnung protokolliert.

Speichern, Loeschen und Dokumentation

• Speichern: Formularwerte werden uebernommen, Scopes zusammengefuehrt und die zugehoerigen v1-Ressourcenrechte neu aufgebaut.
• Ressourcenrechte: Beim Speichern eines bestehenden Clients werden alte v1-Ressourcenrechte entfernt und aus den aktuellen Checkboxen neu gespeichert.
• Loeschen: Die Loeschen-Aktion entfernt den Client inklusive zugehoeriger Ressourcenrechte und laedt die Uebersicht neu.
• OpenAPI-Dokumentation: Die Developer-Aktion scannt die Controller der aktuellen API-Generation und schreibt die OpenAPI-Beschreibung neu.
• API-Key v1: Der alte API-Key wird bei Bedarf automatisch erzeugt, bleibt aber im Formular schreibgeschuetzt.

Logs

Der Reiter Logs nutzt den zentralen Tageslog-Viewer. Tokens und Secrets werden fuer die Anzeige maskiert.

• Logbereich: Auswahl zwischen mehreren Schnittstellenbereichen wie API V2, Versanddiensten, Zahlungsdiensten und Marktplatz-APIs.
• Logdatei: Auswahl einer konkreten Logdatei des gewaehlten Bereichs. Wenn keine Datei vorhanden ist, zeigt der Viewer einen entsprechenden Hinweis.
• Abrufen: laedt die gewaehlte Kombination aus Bereich und Datei neu.
• Uebersichtstabelle: zeigt Bereich, Prefix, Anzahl der Dateien, letzte Datei mit Groesse und Zeitpunkt sowie die Aufbewahrungsdauer.
• Dateiansicht: zeigt den maskierten Inhalt der gewaehlten Logdatei in einer scrollbaren Vorschau.
• API-V2-Logs: werden als eigener Bereich mit laengerer Aufbewahrung gefuehrt.
• Alte API-Logdatei: Wenn noch eine alte Logdatei vorhanden ist, erscheint darunter ein Legacy-Bereich mit Download- und Loeschaktion.