Présentation

L’API Xsolla comprend :

• Pay Station API — interface de paiement et méthodes de tokénisation.
• IGS API — méthodes pour travailler avec le module In-Game Store.
• Subscriptions API — méthodes pour Subscriptions.
• 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, Subscriptions API ;
• https://login.xsolla.com/api — Login API ;
• https://store.xsolla.com/api — IGS 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

• Authentification d’accès de base. Ces requêtes à l’API doivent contenir l’en-tête Authorization: Basic <your_authorization_basic_key<, où <your_authorization_basic_key> est la paire merchant ID:API key, encodée selon la norme Base64. Accédez au Compte éditeur pour trouver ces paramètres :
  • Le 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.
• Authentification par JWT utilisateur. Ces requêtes à l’API doivent contenir l’ en-tête Authorization: Bearer <user_JWT>, où <user_JWT> est le jeton de l’utilisateur.
• Authentification par JWT serveur. Ces méthodes API doivent contenir l’en-tête X-SERVER-AUTHORIZATION: <server_JWT>, où <server_JWT> est le jeton du serveur.
• Sans authentification.

Appels API par modèle d'interaction

• Appels API côté client — Ces appels API servent à l’interaction entre la partie client de l’application du partenaire et le serveur Xsolla. Les actions de l’utilisateur sur le client initient la requête de ces appels API. Exemples d’appels API côté client : récupération d’une liste d’objets, authentification utilisateur, obtention d’un jeton de paiement sur le client.
• Appels API côté serveur — Ces appels API servent à l’interaction entre le serveur du partenaire et le serveur Xsolla. Ils sont destinés aux tâches suivantes :
  • Implémentation du flux utilisateur
    Les actions de l’utilisateur sur le client déclenchent l’invocation d’un appel API côté client du partenaire, puis un appel API côté serveur Xsolla est invoqué sur le serveur du partenaire. Exemples d’appels API côté serveur pour l’implémentation du flux utilisateur : mise à jour des attributs utilisateur sur le serveur, obtention d’un jeton de paiement sur le serveur.
  • Tâches administratives ou configuration des produits Xsolla par le partenaire
    Les actions de l’utilisateur sur le client ne peuvent pas initier un appel à ces méthodes. Exemples d’appels API côté serveur pour les tâches administratives : création et modification d’un objet ou d’une promotion.

• Dépassement des limites de fréquence :
  • Les limites de fréquence pour les appels API côté serveur sont plus strictes que pour les appels API côté client ;
  • Les limites de fréquence pour les appels API côté serveur pour les tâches administratives sont plus strictes que pour les appels API pour l’implémentation du flux utilisateur.
• Réception d’informations non pertinentes en réponse. Par exemple, lors de l’utilisation d’appels API côté serveur pour obtenir une liste d’objets à des fins administratives au lieu d’appels API côté client pour l’obtention d’une liste d’objets afin de constituer un catalogue.
• Modifications non autorisées des données par l’utilisateur. Par exemple, lors de l’utilisation d’appels API côté client pour mettre à jour les attributs au lieu d’appels API côté serveur.
• Détermination incorrecte du pays et de la devise dans l’interface de paiement.

Le schéma d’authentification permet de déterminer si un appel API est effectué côté client ou côté serveur :

• Les appels API côté client s’utilisent sans authentification ou avec l’en-tête Authorization header: Bearer <user_JWT>, où <user_JWT> est le jeton utilisateur.
• Les appels API côté serveur pour l’implémentation du flux utilisateur s’utilisent avec l’en-tête :
  • X-SERVER-AUTHORIZATION: <server_JWT>, où <server_JWT> est le jeton de serveur ;
  • Authorization: Basic <your_authorization_basic_key>, où <your_authorization_basic_key> est la paire project_id:api_key encodée selon la norme Base64.
• Les appels API côté serveur pour les tâches administratives s’utilisent avec l’en-tête Authorization: Basic <your_authorization_basic_key>, où <your_authorization_basic_key> est la paire project_id:api_key encodée selon la norme Base64.

Exemple d’appel API côté serveur avec authentification côté serveur :

Exemple d’appel API côté client avec authentification côté client :

En fonction de vos besoins, vous pouvez choisir de configurer l’intégration lors de l’implémentation du flux utilisateur avec des appels API côté serveur ou côté client. Les appels API côté serveur pour les tâches administratives ne doivent pas être utilisés pour implémenter le flux utilisateur.

Exemple d’implémentation du flux utilisateur à l’aide d’appels API côté client :

1. L’utilisateur effectue des actions sur le client. Par exemple : remplir le panier, acheter un objet.
2. Le client du jeu envoie une requête avec des données au serveur Xsolla.
3. Le serveur Xsolla envoie une réponse au client du jeu.
4. Le client du jeu affiche le résultat à l’utilisateur.

Dans ce flux, l’authentification par JWT est utilisée.

Exemple d’implémentation d’un flux utilisateur à l’aide d’appels API côté serveur :

1. L’utilisateur effectue des actions sur le client. Par exemple : remplir le panier, acheter un objet.
2. Le client du jeu envoie une requête au serveur du jeu.
3. Si nécessaire, le partenaire implémente un traitement supplémentaire des données sur le serveur du jeu.
4. Le serveur du jeu envoie une requête au serveur Xsolla.
5. Le serveur Xsolla envoie une réponse au serveur du jeu.
6. Le serveur du jeu traite les données et envoie une réponse au client du jeu.
7. Le client du jeu affiche le résultat à l’utilisateur.

Dans ce flux, l’authentification d’accès de base ou un jeton de serveur est utilisé.

Flux d’interaction lors de l’utilisation des appels API côté serveur pour les tâches administratives :

1. Le partenaire envoie une requête au serveur Xsolla à partir du client ou du serveur de son application.
2. Le serveur Xsolla renvoie une réponse contenant le résultat du traitement de la requête.

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 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.