API-Authentifizierung

Um mit der StoreLinkr REST API zu arbeiten, müssen Sie Ihre Anfragen mit zwei benutzerdefinierten HTTP-Headern authentifizieren. Diese Header identifizieren Ihre Anwendung und stellen sicher, dass Sie die Berechtigung für den Zugriff auf die angeforderten Daten haben.

Erforderliche Header

Jede Anfrage an die StoreLinkr API muss die folgenden Header enthalten:

Header	Beschreibung
X-StoreLinkr-Api-Key	Ihr eindeutiges API-Token.
X-StoreLinkr-Api-Secret	Ihr privates API-Secret.

Zugangsdaten abrufen

Ihre API-Zugangsdaten verwalten Sie im StoreLinkr-Dashboard.

1. Gehen Sie zu Einstellungen > API-Schlüssel.
2. Erstellen Sie ein neues Schlüsselpaar oder verwenden Sie ein vorhandenes.
3. Ihr API-Token entspricht X-StoreLinkr-Api-Key.
4. Ihr API-Secret entspricht X-StoreLinkr-Api-Secret.

warnung

Schützen Sie Ihr API-Secret! Das Secret darf niemals öffentlich geteilt, in die Versionsverwaltung eingecheckt oder in clientseitigem Code (z. B. JavaScript im Browser) offengelegt werden. Wenn Sie vermuten, dass Ihr Secret kompromittiert wurde, widerrufen Sie den Schlüssel sofort im Dashboard.

Bereiche (Scopes) von API-Schlüsseln

Jeder API-Schlüssel kann auf eine Reihe von Scopes beschränkt werden, also auf die Aktionen, die er ausführen darf. So können Sie zum Beispiel einen Schlüssel weitergeben, der nur den Bestand lesen darf, ohne ihm die Berechtigung zu geben, Ihren Katalog zu ändern oder Bestellungen zu lesen.

• Standardmäßig kann ein neuer Schlüssel alles. Wenn Sie die Scopes leer lassen ("Alle Aktionen"), hat der Schlüssel vollen Zugriff auf die API.
• Sobald Sie einen oder mehrere Scopes auswählen, ist der Schlüssel auf genau diese Aktionen beschränkt. Jede Anfrage außerhalb seiner Scopes wird mit 403 Forbidden abgelehnt.

Die Scopes verwalten Sie pro Schlüssel unter Einstellungen > API-Schlüssel: Klicken Sie auf einen Schlüssel und haken Sie die Aktionen an, die er ausführen darf.

Verfügbare Scopes

Scope	Erlaubt
catalog:read	Produkte, Kategorien, Varianten und Feeds lesen.
catalog:write	Produkte und Kategorien erstellen, aktualisieren und archivieren.
ecommerce:read	Produkte von Verkaufskanälen und Produktregeln lesen.
ecommerce:write	Produktregeln erstellen, aktualisieren und löschen.
orders:read	Bestellungen lesen.
orders:write	Bestellungen erstellen.
stock:read	Bestandsinformationen und Bestandsbewegungen lesen.

tipp

Erteilen Sie einem Schlüssel nur die geringsten Berechtigungen, die er benötigt. Ein Schlüssel, der nur Lagerbestände liest, sollte lediglich stock:read haben.

Basic-Authentifizierung

Statt der beiden Header können Sie auch die HTTP-Basic-Authentifizierung verwenden, mit dem API-Token als Benutzernamen und dem API-Secret als Passwort.

Paginierung, Ratenlimits und Fehler

• Paginierung: Listen-Endpunkte akzeptieren limit und page und liefern ein pagination-Objekt mit pages, page, limit, offset und totalRecords. Fordern Sie so lange weitere Seiten an, bis Sie pages erreicht haben.
• Ratenlimits: Anfragen werden pro Projekt begrenzt. Sie können einen Schub von bis zu 120 Anfragen senden, danach füllt sich das Kontingent mit 10 Anfragen pro Minute wieder auf. Ist es aufgebraucht, antwortet die API mit 429 Too Many Requests und einem Retry-After-Header, der die Anzahl der Sekunden bis zum nächsten Versuch enthält. Verwenden Sie lieber größere limit-Werte und Filter statt vieler kleiner Aufrufe.
• Fehler: Ein Fehler hat dieselbe Struktur wie eine erfolgreiche Antwort, mit "status": "failed", einer message und einem passenden HTTP-Status: 400 ungültige Anfrage, 401 fehlender oder ungültiger Schlüssel, 403 dem Schlüssel fehlt der Scope, 404 in Ihrem Projekt nicht gefunden, 409 Konflikt mit dem aktuellen Status, 429 Ratenlimit erreicht.

Die interaktive API-Dokumentation enthält eine Schnellstartanleitung, alle Endpunkte nach Bereichen gruppiert (Katalog, eCommerce, Bestand, Bestellungen und Produkt-Feeds) und eine Schaltfläche Download für die OpenAPI-Datei, mit der Sie einen Client in Ihrer eigenen Sprache generieren können. Sie folgt derselben Tag-/Nacht-Einstellung wie das Portal.

Beispielanfragen

Mit cURL

curl -X GET "https://api.storelinkr.com/api/public/v2/catalog/products" \
     -H "X-StoreLinkr-Api-Key: your_api_token_here" \
     -H "X-StoreLinkr-Api-Secret: your_api_secret_here" \
     -H "Accept: application/json"

Mit PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client();
$response = $client->request('GET', 'https://api.storelinkr.com/api/public/v2/catalog/products', [
    'headers' => [
        'X-StoreLinkr-Api-Key' => 'your_api_token_here',
        'X-StoreLinkr-Api-Secret' => 'your_api_secret_here',
        'Accept' => 'application/json',
    ]
]);

$body = json_decode($response->getBody(), true);

Fehlerbehebung bei der Authentifizierung

Wenn Sie eine Antwort 401 Unauthorized erhalten:

• Prüfen Sie noch einmal, dass beide Header X-StoreLinkr-Api-Key und X-StoreLinkr-Api-Secret vorhanden und korrekt geschrieben sind.
• Stellen Sie sicher, dass die Werte exakt mit den im StoreLinkr-Dashboard angezeigten übereinstimmen.
• Vergewissern Sie sich, dass der API-Schlüssel nicht widerrufen wurde.
• Prüfen Sie, dass Sie die Header in der korrekten Schreibweise senden (HTTP-Header sind zwar im Allgemeinen nicht von Groß- und Kleinschreibung abhängig, die Standardschreibweise wird aber empfohlen).