Gérer les clients OAuth2

curl -X POST https://shop.de/xpanel/xoport/oauth/token 
  -H "Content-Type: application/x-www-form-urlencoded" 
  -d "grant_type=client_credentials" 
  -d "client_id=xoc_abc123..." 
  -d "client_secret=xos_def456..."

Réponse

{
  "access_token": "xoat_eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "products:read products:write categories:read"
}

Erreur au niveau du point de terminaison des jetons

Le point de terminaison du jeton répond au format OAuth2 avec error et error_description, vérifiés dans cet ordre :

Sans scope, tous les champs d’application du client s’appliquent.

curl -X GET https://shop.de/xpanel/xoPort/me 
  -H "Authorization: Bearer xoat_eyJhbGciOi..."

Réponse

{
  "success": true,
  "api_version": "2.122.11",
  "type": "client_info",
  "data": {
    "client_id": "xoc_abc123...",
    "client_name": "Mein API Client",
    "scopes": ["products:read", "products:write", "categories:read"],
    "rate_limit": 5000,
    "rate_limit_window": 3600,
    "rate_limit_remaining": 4987,
    "rate_limit_reset": 1792327500,
    "token_expires_at": "2026-10-18 15:00:00",
    "token_created_at": "2026-10-18 14:00:00",
    "client_created_at": "2026-01-15 10:30:00",
    "client_last_used_at": "2026-10-18 14:22:15"
  },
  "timestamp": "2026-10-18 14:22:16"
}

Depuis la version v2.122.11 rate_limit_window, la durée de la fenêtre de comptage est exprimée en secondes (toujours 3 600). rate_limit_remaining et rate_limit_reset ont les mêmes valeurs que les en-têtes X-RateLimit-Remaining et X-RateLimit-Reset de la même réponse ; la requête envoyée à /me est prise en compte dans ce calcul. Pour les clients sans limite de requêtes, les deux valeurs sont null.

La limite de requêtes s'applique par client, et non par jeton : tous les jetons et processus d'un même client partagent un compteur. Le comptage s’effectue dans une fenêtre glissante de 3 600 secondes ; une place se libère dès que la requête la plus ancienne comptabilisée date de plus d’une heure. Vous définissez la valeur (rate_limit, nombre de requêtes par fenêtre) dans le backend au niveau du client ; GET /me l’affiche (null signifie « illimité », 0 a le même effet).

Paramètres par défaut (depuis la version 4.9.17 de la boutique ; auparavant, un champ vide signifiait « illimité ») : pour l’exploitant, le champ est prérempli à 5 000 lors de la création ; une valeur supérieure n’est pas possible, et s’il est enregistré vide, la valeur par défaut est 5 000. Une valeur supérieure à 5 000 définie par XONIC est conservée tant que le champ reste inchangé. À partir de la version 4.9.174 de Shop, la fonction « Modifier le client » affiche, pour un client illimité, un champ vide accompagné de la mention « Illimité (défini par XONIC) » ; s’il est enregistré vide, il reste illimité ; un nombre inférieur ou égal à 5 000 le limite ; seul XONIC peut alors le rétablir à « illimité ». ⚠️ Jusqu’à la version 4.9.173 de Shop, un client « illimité » se voyait attribuer la valeur 5 000 dès que l’administrateur l’enregistrait, même si seuls le nom ou la note avaient été modifiés. Dans l’administrateur XONIC, le champ est vide, et « vide » signifie ici « illimité ». ⚠️ Jusqu’à la version Shop 4.9.173, lors de la création avec un champ vide, un client avec une limite de 5 000 était tout de même généré si la colonne dans la base de données avait la valeur par défaut de 5 000 (par exemple après une réinstallation à partir de la version Shop 4.9.17). Vérifiez ces valeurs après la création dans « GET /me » → « rate_limit ». Sur les boutiques de la version 4.9.17 à 4.9.167, chaque vérification HealthCheck et chaque mise à jour réinitialisent un client « illimité » à 5 000 ; à partir de la version 4.9.168 de la boutique, la valeur « illimitée » est conservée. Une limite modifiée prend effet immédiatement, y compris pour les jetons en cours.

Quota dans chaque réponse Depuis la v2.122.11

Chaque réponse à une requête comportant un jeton valide provenant d’un client soumis à une limite de requêtes comporte trois en-têtes :

• Avec en-têtes : données, réponses d'erreur telles que 400, 403 ou 404, téléchargements de fichiers, requêtes XML avec jeton et la réponse 429 elle-même.
• Sans en-têtes : clients sans limite de requêtes, requêtes sans jeton valide (401), requêtes XML sans jeton ou provenant d’une adresse dont l’IP est autorisée par l’interface XML et le point de terminaison des jetons.
• Le reste s'applique à l'ensemble des processus du client : ce qu'une réponse mentionne peut déjà avoir été utilisé par un processus parallèle.
• Les boutiques jusqu’à la version 4.9.170 n’envoient pas ces en-têtes. Leur absence ne signifie pas « illimité » : dans ce cas, consultez GET /me.

Si la limite est dépassée, l’API répond avec un code HTTP 429 et Retry-After, voir l’exemple dans la section « Gestion des erreurs ».

Limite propre au point de terminaison du jeton

POST /oauth/token a sa propre limite : 30 requêtes en 300 secondes par client_id, également calculée de manière glissante ; les requêtes avec un secret incorrect sont également comptabilisées. Au-delà, un code d'erreur HTTP 429 est renvoyé avec rate_limit_exceeded. Depuis la version v2.122.11, Retry-After indique le nombre de secondes jusqu'à la prochaine acceptation (de 1 à 300) ; auparavant, cette valeur était fixe à 300. Le point de terminaison des jetons n'envoie pas de X-RateLimit-*. Un jeton est valable une heure : récupérez-le une seule fois et transmettez-le à tous les processus.

Journal d'utilisation

Dans le backend, le journal d'utilisation affiche, pour chaque client, les 1 000 dernières requêtes avec la requête et la réponse correspondantes. Ne figurent pas dans ce journal les interruptions de l'exportation avec un code HTTP 400 avant le début d'une requête (erreurs de filtrage, de défilement et de chemin d'accès), les justificatifs et les pièces jointes individuelles aux tickets, la réponse 429 et les requêtes XML. Ces requêtes sont néanmoins comptabilisées dans la limite de requêtes, à l'exception des codes 429 et des requêtes XML sans jeton.

Depuis la version v2.119.0, l’API REST exige systématiquement un jeton OAuth2, et ses champs d’application s’appliquent. L’autorisation IP de l’interface XML (XML_PORT_IP_FILTER) ne donne pas accès à l’API REST.

De plus, vous pouvez limiter l’accès à des adresses fixes. Si le paramètre XOPORT_REST_IP_LIST est renseigné, toute requête doit provenir d’une adresse figurant dans la liste et comporter un jeton valide ; la liste ne remplace en aucun cas le jeton. Les requêtes provenant d’autres adresses reçoivent la réponse « 403 » avec le message « reason: deny_ip_not_listed ».