Authentifizierung

Alle Public-API-Anfragen benötigen ein Bearer-Token. Channel-Zugangsdaten und Warehouse-Codes werden im Developer Portal verwaltet - binden Sie sie niemals in Client-Apps ein.

API-Schlüssel {#api-keys}

Erstellen Sie Schlüssel unter Developer Portal → API Keys, nachdem Ihre App genehmigt wurde.

Element	Beschreibung
Format	`Authorization: Bearer hio_live_…` (Produktion) oder Testschlüssel, wie vom Portal ausgegeben
Scope	Ein Schlüssel pro App. Kontingente und Channel-Zugriff folgen dem Subscription-Plan der App.
Rotation	Widerrufen Sie kompromittierte Schlüssel sofort; erstellen Sie in Produktion zuerst einen Ersatz, bevor Sie widerrufen.
Speicherung	Nur serverseitig. Geben Sie Schlüssel nicht in mobilen Apps, Browser-JS oder öffentlichen Repos preis.

Beispielanfrage

curl https://api.hiobuy.com/v1/products/detail \
  -H "Authorization: Bearer hio_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "1688",
    "product_id": "554456348334",
    "language": "en"
  }'

Channel-Autorisierung (Voraussetzung) {#channel-authorization}

Ein API-Schlüssel allein reicht nicht aus. Jede App muss die Channel-Autorisierung abschließen, bevor sie Produkt- oder Bestell-APIs für diesen Marketplace aufruft.

Modus	Was Sie konfigurieren	Was Gateway verwendet
Self-Fulfillment	Pro-Channel-OAuth oder Token-JSON im Portal	Gespeicherte Tokens pro App + Channel
HIOBuy-Warehouse	Ein Warehouse-Developer-Code	Code + serverseitig verwaltete Tokens; Beschaffung/Fulfillment wird an HIOBuy weitergeleitet

Siehe Portal-Autorisierung. Wenn ein Channel nicht autorisiert ist, geben Aufrufe 401 CHANNEL_NOT_AUTHORIZED zurück (Fehler).

Was Sie niemals senden {#what-not-to-send}

Taobao-/1688-/Weidian-Access-Tokens oder Refresh-Tokens
Warehouse-Developer-Code (Gateway fügt ihn für Fulfillment-Routen an)
Portal-Session-JWT bei Public-API-Aufrufen

Request-Tracing {#tracing}

Jede Antwort enthält:

Header x-request-id - korreliert mit request_id im JSON-Body
Optionale Kontingent-Header auf abrechenbaren Routen - siehe Rate Limits

Geben Sie x-request-id an, wenn Sie den HIOBuy-Support kontaktieren.

Häufige Authentifizierungsfehler {#auth-errors}

HTTP	Code	Bedeutung
401	`INVALID_API_KEY`	Fehlendes, widerrufenes oder fehlerhaftes Bearer-Token
401	`CHANNEL_NOT_AUTHORIZED`	App hat den angefragten Channel im Portal nicht autorisiert
403	`INSUFFICIENT_SCOPE`	Schlüssel oder App hat keine Berechtigung für den Vorgang
403	`FULFILLMENT_MODE_NOT_SUPPORTED`	Fulfillment-API wurde aufgerufen, während die App im Self-Fulfillment-Modus ist