Authentification

Toutes les requêtes de l’API publique nécessitent un jeton Bearer. Les identifiants de canal et les codes entrepôt sont gérés dans le portail développeur — ne les intégrez jamais dans vos applications clientes.

Clés API {#api-keys}

Créez des clés dans Developer Portal → API Keys après l’approbation de votre app.

Élément	Description
Format	`Authorization: Bearer hio_live_…` (production) ou clés de test émises par le portail
Portée	Une clé par app. Les quotas et l’accès aux canaux suivent l’abonnement de l’app.
Rotation	Révoquez immédiatement les clés compromises ; créez un remplacement avant de révoquer en production.
Stockage	Côté serveur uniquement. N’exposez pas les clés dans les apps mobiles, le JS navigateur ou les dépôts publics.

Exemple de requête

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"
  }'

Autorisation des canaux (prérequis) {#channel-authorization}

Une clé API seule ne suffit pas. Chaque app doit terminer l’autorisation des canaux avant d’appeler les API produit ou commande pour cette marketplace.

Mode	Ce que vous configurez	Ce qu’utilise la passerelle
Fulfillment autonome	OAuth par canal ou JSON de jeton dans le portail	Jetons stockés par app + canal
Entrepôt HIOBuy	Un code développeur entrepôt	Code + jetons gérés côté serveur ; approvisionnement/fulfillment transmis à HIOBuy

Voir Autorisation portail. Si un canal n’est pas autorisé, les appels retournent 401 CHANNEL_NOT_AUTHORIZED (Erreurs).

Ce que vous n’envoyez jamais {#what-not-to-send}

Jetons d’accès ou de rafraîchissement Taobao / 1688 / Weidian
Code développeur entrepôt (la passerelle l’ajoute pour les routes de fulfillment)
JWT de session du portail dans les appels à l’API publique

Traçage des requêtes {#tracing}

Chaque réponse inclut :

En-tête x-request-id — à corréler avec request_id dans le corps JSON
En-têtes de quota optionnels sur les routes facturables — voir Limites de débit

Incluez x-request-id lorsque vous contactez le support HIOBuy.

Erreurs d’authentification courantes {#auth-errors}

HTTP	Code	Signification
401	`INVALID_API_KEY`	Jeton Bearer manquant, révoqué ou mal formé
401	`CHANNEL_NOT_AUTHORIZED`	L’app n’a pas autorisé le canal demandé dans le portail
403	`INSUFFICIENT_SCOPE`	La clé ou l’app n’a pas l’autorisation pour l’opération
403	`FULFILLMENT_MODE_NOT_SUPPORTED`	API fulfillment appelée alors que l’app est en mode fulfillment autonome