Présentation

L’API Xsolla comprend :

• Pay Station API — interface de paiement et méthodes de tokénisation.
• IGS & BB API — méthodes pour travailler avec les modules In-Game Store et Buy Button.
• Subscriptions API — méthodes pour Subscriptions.
• Publisher Account API — méthodes pour travailler avec les projets et les utilisateurs du Compte éditeur, les rapports et les tickets de support.
• Login API — méthodes pour l’authentification utilisateur à l’aide de votre propre interface (voir le guide d’intégration).

L’API utilise des fonctions HTTP intégrées telles que l’authentification HTTP et les verbes HTTP, qui peuvent être interprétées par des clients HTTP standard. Elle prend également en charge le partage de ressources inter-origines, ce qui vous permet d’y accéder en toute sécurité à partir d’une application Web cliente.

• https://api.xsolla.com — Pay Station API, Publisher Account API, Subscriptions API ;
• https://login.xsolla.com/api — Login API ;
• https://store.xsolla.com/api — IGS&BB API.

Requêtes et réponses

• être envoyées via HTTPS ;
• utiliser TLS 1.2 ou ou versions ultérieures ;
• contenir les paramètres d’authentification ;
• contenir un en-tête supplémentaire : Content-Type: application/json pour les requêtes PUT et POST.

Authorization: Basic <your_authorization_basic_key>
Content-Type: application/json

Par défaut, toutes les requêtes renvoient une réponse contenant des données JSON dans le corps et Content-Type: application/json dans l’en-tête.

Modifications de l'API

• Ajouter de nouvelles ressources API ;
• Ajouter des paramètres de requête facultatifs ;
• Ajouter de nouvelles propriétés aux réponses API existantes ;
• Ajouter de nouvelles valeurs pour les paramètres existants avec des valeurs énumérables ;
• Ajouter de nouveaux types de webhook et de paramètres JSON ;
• Ajouter des en-têtes de requête HTTP facultatifs ;
• Rejeter toute requête dans laquelle des paramètres valides contiennent des valeurs non valides ;
• Rejeter les requêtes mal formées qui ont été acceptées précédemment en raison d’une analyse laxiste, si la logique d’analyse est modifiée ;
• Ajouter, modifier ou supprimer des fonctionnalités non documentées à tout moment.

Versionnage

Authentification

• Merchant ID est affiché :
  • Dans la section Company settings > Company ;
  • Dans l'URL de la barre d'adresse du navigateur sur n'importe quelle page du Compte éditeur. L'URL est au format suivant : https:​//publisher.xsolla.com/<merchant ID>/<Publisher Account section>.

• L'API key ne s'affiche dans le Compte éditeur qu'une seule fois lors de sa création, vous devez donc la conserver de votre côté. Vous pouvez créer une nouvelle clé dans les sections suivantes :
  • Company settings > API keys ;
  • Project settings > API keys.

Types d'endpoints

Format de la date

Pagination

Gestion des erreurs

• 200, 201, 204 — Pas d’erreur ;
• 400 Bad Request — Cela indique souvent l’absence d’un paramètre requis. Reportez-vous au corps de la réponse pour plus de détails ;
• 401 Unauthorized — Clé API valide non fournie ;
• 402 Request Failed — La requête a échoué malgré des paramètres valides ;
• 403 Forbidden — Aucuns droits d’accès. Reportez-vous au corps de la réponse pour plus de détails ;
• 404 Not Found — L’élément demandé n’existe pas ;
• 409, 422 — Paramètres de requête non valides ;
• 412 Precondition Failed — Le projet n’a pas encore été activé (utilisé dans la méthode Créer un jeton) ;
• 415 Unsupported Media Type — Content-Type: application/json manquant dans l’en-tête HTTP ;
• 500, 502, 503, 504 Server Errors — Un problème est durvenu.

{
    "http_status_code": 500,
    "message": "Internal Server Error",
    "extended_message": null,
    "request_id": "6445b85"
}

Limites de fréquence

Informations générales

Causes courantes de dépassement des limites de fréquence

• Une augmentation soudaine du trafic du côté du partenaire à la suite de :
  • ventes saisonnières ;
  • début des essais en milieu fermé et en milieu ouvert.
• Augmentation soudaine du trafic à la suite d’attaques DDoS du côté du partenaire.
• Une intégration mal configurée, par exemple :
  • l’utilisation des méthodes de la sous-section Administrateur qui ne sont pas destinées à un usage fréquent au lieu des méthodes de la sous-section Catalogue ;
  • appel fréquent à la méthode Lire une commande pour obtenir l’état d’une commande et la liste des objets qu’elle contient. Par exemple : 1 fois par seconde alors que le délai recommandé entre les requêtes devrait être de 3 secondes.
• Lancement d’un nombre excessivement élevé de requêtes dans une période donnée. Par exemple : plus de 200 appels par seconde à la méthode Lire la liste des objets virtuels pour afficher un catalogue des objets.

Traitement des limites de fréquence

• Suivre les codes d’état 429 et créer un mécanisme de relance. Pour ce faire, utilisez le modèle Retry avec un backoff exponentiel ou fixe entre les tentatives au lieu de tentatives continues.
• Optimiser le code pour n’obtenir que les données nécessaires. Veillez à n’effectuer que les requêtes dont votre application a besoin et évitez tout appel inutile à l’API. Si vous utilisez IGS & BB API, recourez à WebSocket API pour réduire le nombre d’appels.
• Mettre en cache les données fréquemment utilisées par votre application. Par exemple, conservez les données statiques de votre côté afin de réduire le nombre de requêtes à l’API externe.
• Prévenir les attaques DDoS susceptibles d’interrompre votre API.
• Ajuster la fréquence de vos requêtes pour une distribution plus régulière. Si l’erreur 429 se produit régulièrement, envisagez d’inclure dans votre code un processus qui régule la fréquence de vos requêtes et permet de les répartir plus uniformément.

Clés API

Une clé API est une clé unique utilisée pour le cryptage des données utilisateur et l’authentification des requêtes API. Dans le Compte éditeur, vous pouvez créer des clés API pour tous les projets de l’entreprise ainsi que pour des projets individuels.

Créer une clé API

1. Ouvrez le Compte éditeur.
2. Accédez à la section Company settings > API keys ou Project settings > API keys.
3. Cliquez sur Create API key.
4. Remplissez les champs :
   • Key name — nom de la clé qui sera affiché dans la liste des clés. Définissez un nom qui vous permettra d’identifier facilement la clé ;
   • Key type — type de clé, permanente ou temporaire ;
   • Expiration date — date d’expiration, uniquement pour une clé temporaire. Après la date d’expiration, la clé n’est plus valide et vous devez en créer une nouvelle ;
   • Project — projet où la clé est valide (le champ n’est pas affiché lorsque vous créez une clé API sur la page du projet). Tous les projets sont sélectionnés par défaut.
5. Cliquez sur Create.
6. Dans la fenêtre qui s’affiche, cliquez sur Copy API key et enregistrez la clé API créée de votre côté.

Supprimer une clé API

1. Ouvrez le Compte éditeur.
2. Accédez à la section Company settings > API keys ou Project settings > API keys.
3. Dans la ligne Clé API, cliquez sur l’icône de la poubelle et confirmez l’action.

• à la réception de paiements dans les projets pour lesquels cette clé API a été utilisée ;
• à l’appel des méthodes API qui ont utilisé cette clé API.

1. Créez une nouvelle clé API.
2. Modifiez votre application pour utiliser la nouvelle clé API.
3. Supprimez la clé API initiale.

Webhooks

Les webhooks vous permettent de recevoir des notifications instantanées d’événements configurés côté Xsolla. Configurez leur traitement pour automatiser votre application. Pour obtenir la liste des webhooks disponibles et des descriptions détaillées de leur fonctionnement, consultez notre documentation.

Évaluer cette page

Que pouvons-nous améliorer ? Envoyer

Préfère ne pas répondre

Merci pour votre commentaire !