REST API

In der REST API verwaltest Du API-Zugriffe für externe Systeme, KI-Agenten und andere Integrationen. Du legst fest, welcher Client aktiv ist, welche Berechtigungen er erhält und wo Du die passenden Schnittstellen-Logs findest.

Wofür der Bereich gedacht ist

Die REST API ist die zentrale Schnittstelle für Systeme, die Daten aus dem Shop lesen oder im Shop schreiben sollen. Typische Beispiele sind Warenwirtschaft, ERP, PIM, externe Automationen, KI-Agenten oder individuell angebundene Tools.

• API Version 2: ist die aktuelle Schnittstelle für neue Integrationen. Die Dokumentation ist je Shop persönlich und interaktiv erreichbar.
• API Version 1: ist veraltet und bleibt nur für bestehende Altanbindungen relevant.
• Clients: Ein Client steht für eine konkrete externe Anwendung oder einen klar abgegrenzten Zugriff.
• Berechtigungen: Über die Scope-Auswahl legst Du fest, welche Daten ein Client lesen, anlegen, ändern oder löschen darf.
• Logs: Im Log-Reiter prüfst Du API-Aufrufe und andere Schnittstellen-Logdateien, ohne Secrets oder Tokens offen anzuzeigen.

Übersicht

Der Reiter Übersicht zeigt die eingerichteten API-Clients und die wichtigsten Zugangsinformationen.

• API Url - Version 2: zeigt die Basisadresse, die externe Systeme für die aktuelle API verwenden.
• Interaktive API-Dokumentation - Version 2: öffnet die persönliche API-Dokumentation des jeweiligen Shops. Dort werden die verfügbaren Endpunkte, Parameter und Tests direkt für diesen Shop dargestellt.
• API Url - Version 1: wird nur noch als veraltete Adresse angezeigt, falls alte Integrationen weiter bestehen.
• ApiKey erstellen: legt einen neuen API-Client an, sofern die REST-API-App aktiv ist.

Client-Tabelle

Die Übersicht nutzt eine konfigurierbare Tabelle. Die Suche kann für sichtbare Werte wie Bezeichnung oder Client ID genutzt werden.

• Id: eindeutige Nummer des API-Clients.
• Bezeichnung: frei gewählter Name, damit der Zweck des Clients schnell erkennbar ist, zum Beispiel Warenwirtschaft, PIM oder KI-Agent.
• API-Key (v1): Schlüssel für alte API-v1-Anbindungen. Die Spalte ist normalerweise ausgeblendet.
• Client ID (v2): Kennung des Clients für API Version 2.
• E-Mailadresse: Zieladresse für das einmalig erzeugte Client Secret. Die Spalte ist normalerweise ausgeblendet.
• Optionen: enthält die Aktionen zum Bearbeiten, Client Secret erstellen und zusenden sowie Löschen.

Client erstellen oder bearbeiten

Über ApiKey erstellen oder die Bearbeiten-Aktion öffnest Du den Client-Dialog. Die sichtbaren Felder beschreiben, wer zugreifen darf und welche Berechtigungen dieser Zugriff erhält.

• Bezeichnung: Pflichtfeld für einen sprechenden Namen. Verwende einen Namen, der später eindeutig erklärt, wofür der Zugriff genutzt wird.
• E-Mail-Adresse: Pflichtfeld. An diese Adresse wird das Client Secret für API Version 2 gesendet.
• Hat Zugriff auf die API: schaltet den Client aktiv oder inaktiv. Ein inaktiver Client kann nicht für den Zugriff genutzt werden.
• Client Id: eindeutige Kennung für API Version 2. Die Kennung sollte zusammenhängend und dauerhaft sein, zum Beispiel für ein angebundenes System.
• Client Type: unterscheidet normale API-Benutzer und KI-Agenten.
• Scope-Auswahl: legt fest, welche Bereiche und Aktionen der Client verwenden darf.

Scope-Auswahl verstehen

Die Scope-Tabelle zeigt pro Datenbereich, welche Aktionen verfügbar sind. Nicht jede Aktion existiert für jeden Bereich.

• Alle: Die Checkbox im Tabellenkopf wählt alle verfügbaren Berechtigungen aus oder ab.
• Alle in einer Zeile: Die Checkbox am Zeilenanfang wählt alle verfügbaren Aktionen dieses Datenbereichs aus oder ab.
• Read: erlaubt das Lesen von Daten.
• Create: erlaubt das Anlegen neuer Daten.
• Update: erlaubt das Ändern bestehender Daten.
• Delete: erlaubt das Löschen von Daten.
• Leere Felder: bedeuten, dass diese Aktion für den jeweiligen Datenbereich nicht angeboten wird.

Client Secret erstellen und zusenden

Die Aktion Client Secret erstellen & zusenden erzeugt ein neues Secret und sendet es an die im Client hinterlegte E-Mail-Adresse.

1. Prüfe zuerst, ob der Client aktiv ist und die Client ID korrekt gepflegt ist.
2. Öffne die Secret-Aktion in der Optionsspalte.
3. Bestätige Erstellen & versenden.
4. Teile die Client ID separat an die Person oder das System mit, das die Integration einrichtet.
5. Bewahre das Secret sicher auf. Wenn es verloren geht, muss ein neues Secret erzeugt werden.

API Version 1

Der Abschnitt Einstellungen für den Zugriff auf Version 1 (veraltet) ist nur für bestehende Altanbindungen relevant. Neue Integrationen sollten API Version 2 verwenden.

• API-Key: Schlüssel für alte API-v1-Zugriffe.
• Hash-Token: Token für die alte Signaturprüfung.
• Ressourcenrechte: Für alte Bereiche können die Methoden GET, POST, PUT und DELETE einzeln erlaubt werden.

Für die alte Version wurde früher eine externe Dokumentation verwendet. Für neue Anbindungen ist stattdessen die persönliche API-v2-Dokumentation im jeweiligen Shop maßgeblich.

Logs

Der Reiter Logs zeigt tagesbasierte Schnittstellen-Logdateien. Tokens und Secrets werden für die Anzeige maskiert.

• Logbereich: wählt den Schnittstellenbereich aus, zum Beispiel API V2, Versanddienste, Zahlungsdienste oder Marktplatz-APIs.
• Logdatei: wählt eine konkrete Tagesdatei des gewählten Bereichs.
• Abrufen: lädt die gewählte Logdatei neu.
• Übersichtstabelle: zeigt die vorhandenen Logbereiche, Dateianzahl, letzte Datei und Aufbewahrungsdauer.
• Dateiansicht: zeigt den maskierten Inhalt der ausgewählten Logdatei.
• Alte API Logdatei: erscheint nur, wenn noch eine alte API-v1-Logdatei vorhanden ist.

Sicher arbeiten

• Lege für jedes externe System einen eigenen Client an.
• Verwende sprechende Bezeichnungen, damit Zugriffe später eindeutig zugeordnet werden können.
• Deaktiviere Clients, die nicht mehr genutzt werden.
• Erzeuge ein neues Secret, wenn ein Secret versehentlich weitergegeben wurde oder nicht mehr auffindbar ist.
• Prüfe bei Fehlern zuerst die Logs und danach die vergebenen Scopes.