Scopes und Freischaltung

Berechtigungen heißen Scopes. Ob ein Aufruf klappt, entscheidet sich auf drei Ebenen.

Die drei Ebenen

1. Freischaltung deines Kontos. Shirtee legt fest, welche Scopes dein Konto überhaupt nutzen darf: ein Standard für alle Händler plus Zusatzrechte für einzelne Händler. Wirksam ist beides zusammen. Diese Menge kann sich ändern.
2. Scopes des Schlüssels. Beim Anlegen wählst du aus den freigeschalteten Scopes die aus, die der Schlüssel tragen soll. Der Schlüssel behält sie bis zum Ablauf.
3. Anforderung des Endpunkts. Jede Operation nennt in der Spec unter x-customer-scopes die Scopes, die sie akzeptiert. Dein Schlüssel braucht mindestens einen davon.

Beim Aufruf zählt der Schnitt aus Ebene 1 und 2, bei jeder Anfrage neu. Nimmt Shirtee einen Scope aus der Freischaltung, verliert ihn auch ein bereits ausgestellter Schlüssel ab der nächsten Anfrage.

Wo du siehst, was freigeschaltet ist

Im Portal unter KI-Assistent & API bietet das Anlegen eines Schlüssels nur freigeschaltete Berechtigungen an. Der Bereich Fähigkeiten erklärt sie. Fehlt dir eine Berechtigung, wende dich an den Support.

Die Scopes

Scope	Erlaubt
merchant_order:read	Eigene Bestellungen, Sendungsverfolgung und Verlauf lesen; Vorschauen für Storno, Adressänderung und Variantentausch
merchant_order:create	Bestellungen anlegen, nachbestellen und Lieferbelege hochladen
merchant_order:cancel	Bestellungen stornieren
merchant_order:address	Liefer- und Rechnungsadresse ändern
merchant_order:items	Varianten tauschen und Positionen hinzufügen, ändern oder löschen
merchant_order:write	Sammel-Scope: alle Schreibrechte für Bestellungen
merchant_catalog:read	Produktkatalog, Varianten und Bestand lesen
merchant_invoice:read	Eigene Rechnungen lesen
merchant_complaint:write	Reklamationsentwürfe anlegen
warehouse:read	Anlieferungen und Lagerartikel lesen
warehouse:shipment_write	Anlieferungen anlegen, ändern und Versandlisten einlesen
warehouse:shipment_cancel	Anlieferungen stornieren
warehouse:document_write	Dokumente an Anlieferungen hochladen und entfernen
warehouse:write	Sammel-Scope: alle Schreibrechte im Lager

Eine Operation akzeptiert den feinen Scope und den passenden Sammel-Scope. Fordere für neue Schlüssel die feinen Scopes an, dann gibst du nicht mehr frei, als die Software braucht.

Warum liefert mein Schlüssel 403?

Gehe in dieser Reihenfolge vor:

1. Meldung lesen. Scoped API key revoked heißt: Schlüssel widerrufen. Lege einen neuen an.
2. Operation prüfen. Steht der Endpunkt in der Referenz? Alles andere lehnt ein Händler-Schlüssel ab.
3. Scopes vergleichen. Nimm x-customer-scopes der Operation und vergleiche mit den Berechtigungen deines Schlüssels (Portal, API-Schlüssel). Trägt der Schlüssel keinen davon, braucht es einen neuen Schlüssel.
4. Freischaltung prüfen. Trägt der Schlüssel den Scope, ist er aber für dein Konto nicht (mehr) freigeschaltet, hilft nur der Support.