UGS du lot.
API Catalog (2.0.0)
- Version : 2.0.0
- Serveurs :
https://store.xsolla.com/api - Contactez-nous par e-mail
- URL de contact : https://xsolla.com/
- Version TLS requise : 1.2
L’API Catalog permet de configurer un catalogue des objets en jeu côté Xsolla et de l’afficher aux utilisateurs dans votre magasin.
L’API permet de gérer les entités de catalogue suivantes :
- Objets virtuels — objets en jeu tels que armes, skins, boosters.
- Monnaie virtuelle — monnaie utilisée pour acheter des objets virtuels.
- Packages de monnaie virtuelle — lots prédéfinis de monnaie virtuelle.
- Lots — packages combinant objets virtuels, monnaie virtuelle ou clés de jeu vendus sous un seul UGS.
- Clés de jeu — clés pour jeux et DLC distribuées via Steam ou d’autres fournisseurs DRM.
- Groupes — regroupements logiques pour organiser et trier les éléments du catalogue.
L’API est divisée en groupes suivants :
Admin — appels pour créer, mettre à jour, supprimer et configurer les objets et groupes du catalogue. Authentification via l’authentification d’accès de base avec vos identifiants marchand ou projet. Non destinés à un usage côté magasin.Catalog — appels pour récupérer des objets et construire des vitrines personnalisées pour les utilisateurs finaux. Conçue pour gérer des charges importantes. Supporte l’autorisation optionnelle par JWT utilisateur pour retourner des données personnalisées telles que des limites spécifiques à l’utilisateur et des promotions actives.
Les appels API nécessitent une authentification au nom d'un utilisateur ou d'un projet. Le schéma d'authentification à utiliser figure dans la section Security de la description de chaque appel.
L'authentification par JWT utilisateur est utilisée lorsqu'une requête provient d'un navigateur, d'une application mobile ou d'un jeu. Par défaut, le schéma XsollaLoginUserJWT s'applique. Pour savoir comment créer un jeton, consultez la documentation de l'API Xsolla Login.
Transmettez le jeton dans l'en-tête Authorization au format suivant : Authorization: Bearer <user_JWT>, où <user_JWT> représente le jeton utilisateur. Ce jeton identifie l'utilisateur et donne accès à ses données personnalisées.
Vous pouvez également utiliser un jeton pour ouvrir l’interface de paiement.
L'authentification HTTP basique est utilisée pour les interactions serveur à serveur, lorsqu'un appel API est envoyé directement depuis votre serveur plutôt que depuis le navigateur ou l'application mobile d'un utilisateur. Elle repose généralement sur une clé API.
Note
La clé API est confidentielle et ne doit jamais être stockée ni utilisée dans une application cliente.
La clé API est confidentielle et ne doit jamais être stockée ni utilisée dans une application cliente.
Avec l'authentification basique côté serveur, toutes les requêtes API doivent inclure l'en-tête suivant :
- pour
basicAuth—Authorization: Basic <your_authorization_basic_key>, oùyour_authorization_basic_keyest la paireproject_id:api_keyencodée en Base64 - pour
basicMerchantAuth—Authorization: Basic <your_authorization_basic_key>, oùyour_authorization_basic_keyest la pairemerchant_id:api_keyencodée en Base64
Vous trouverez les valeurs des paramètres dans le Compte éditeur :
merchant_ids'affiche :- Dans Company settings > Company*.
- Dans l'URL dans la barre d'adresse du navigateur sur n'importe quelle page du Compte éditeur. L'URL a le format suivant :
https://publisher.xsolla.com/<merchant_id>.
project_ids'affiche :- À côté du nom du projet dans le Compte éditeur.
- Dans l'URL dans la barre d'adresse du navigateur lors de l'utilisation d'un projet dans le Compte éditeur. L'URL a le format suivant :
https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.
api_keys'affiche dans le Compte éditeur uniquement au moment de la création et doit être stockée en toute sécurité de votre côté. Vous pouvez créer une clé API dans les sections suivantes :
Remarque
Si un appel API requis n'inclut pas le paramètre de chemin
Si un appel API requis n'inclut pas le paramètre de chemin
project_id, utilisez une clé API valide pour l'ensemble des projets de l'entreprise pour l'autorisation.Pour plus d'informations sur l'utilisation des clés API, consultez les références API.
Le schéma d’authentification AuthForCart est utilisé pour les achats via le panier et prend en charge deux modes :
Authentification par JWT utilisateur. Le jeton est passé dans l'en-tête
Authorizationau format suivant :Authorization: Bearer <user_JWT>, où<user_JWT>représente le jeton utilisateur. Ce jeton identifie l'utilisateur et donne accès à ses données personnalisées. Vous pouvez également utiliser un jeton pour ouvrir l'interface de paiement.Mode simplifié sans en-tête Authorization. Ce mode est réservé aux utilisateurs non authentifiés et peut être utilisé uniquement pour la vente de clés de jeu. Au lieu d'un jeton, la requête doit inclure les en-têtes suivants :
x-unauthorized-idavec un identifiant de requêtex-useravec l'adresse e-mail de l'utilisateur encodée en Base64
Les objets de tous types (objets virtuels, lots, monnaie virtuelle et clés) partagent une structure de données similaire. Comprendre cette structure de base facilite l’utilisation de l'API et la navigation dans la documentation.
Note
Certains appels peuvent inclure des champs supplémentaires, mais ils ne modifient pas la structure de base.
Certains appels peuvent inclure des champs supplémentaires, mais ils ne modifient pas la structure de base.
Identification
merchant_id— ID de l'entreprise dans le Compte éditeurproject_id— ID de projet dans le Compte éditeursku— UGS de l'objet, unique au sein du projet
Affichage en magasin
name— nom de l'objetdescription— description de l'objetimage_url— URL de l'imageis_enabled— disponibilité de l'objetis_show_in_store— affichage de l'objet dans le catalogue
Pour plus d'informations sur la gestion de la disponibilité des objets dans le catalogue, consultez la documentation.
Organisation
type— type d'objet, par exemple, un objet virtuel (virtual_item) ou un lot (bundle)groups— groupes auxquels l'objet appartientorder— ordre d'affichage dans le catalogue
Conditions de vente
prices— prix en devise réelle ou monnaie virtuellelimits— limites d'achatperiods— périodes de disponibilitéregions— restrictions régionales
Exemple de structure d'entité principale :
{
"attributes": [],
"bundle_type": "virtual_currency_package",
"content": [
{
"description": {
"en": "Main in-game currency"
},
"image_url": "https://.../image.png",
"name": {
"en": "Crystals",
"de": "Kristalle"
},
"quantity": 500,
"sku": "com.xsolla.crystal_2",
"type": "virtual_currency"
}
],
"description": {
"en": "Crystals x500"
},
"groups": [],
"image_url": "https://.../image.png",
"is_enabled": true,
"is_free": false,
"is_show_in_store": true,
"limits": {
"per_item": null,
"per_user": null,
"recurrent_schedule": null
},
"long_description": null,
"media_list": [],
"name": {
"en": "Medium crystal pack"
},
"order": 1,
"periods": [
{
"date_from": null,
"date_until": "2020-08-11T20:00:00+03:00"
}
],
"prices": [
{
"amount": 20,
"country_iso": "US",
"currency": "USD",
"is_default": true,
"is_enabled": true
}
],
"regions": [],
"sku": "com.xsolla.crystal_pack_2",
"type": "bundle",
"vc_prices": []
}L'API Xsolla vous permet d'implémenter la logique de magasin en jeu, notamment la récupération du catalogue des objets, la gestion du panier, la création de commandes et le suivi de leur statut. Selon le scénario d'intégration, les appels API sont répartis en sections Administrateur et Catalogue, qui utilisent différents schémas d'authentification.
L'exemple suivant montre un processus de base pour configurer et exploiter un magasin, de la création d'objets à l'achat.
Créez un catalogue des objets pour votre magasin, tels que des objets virtuels, des lots ou de la monnaie virtuelle.
Exemples d'appels API :
Configurez des outils d'acquisition d'utilisateurs et de monétisation, tels que des remises, des bonus, des récompenses quotidiennes ou des chaînes d'offres.
Exemples d'appels API :
Configurez l'affichage des objets dans l'application.
Remarque
N'utilisez pas les appels API de la sous-section Administrateur pour créer un catalogue utilisateur. Ces appels API présentent des limites de taux et ne sont pas destinés au trafic utilisateur.
N'utilisez pas les appels API de la sous-section Administrateur pour créer un catalogue utilisateur. Ces appels API présentent des limites de taux et ne sont pas destinés au trafic utilisateur.
Exemples d'appels API :
Note
Par défaut, les appels API du catalogue renvoient les objets disponibles dans la boutique au moment de la requête. Pour récupérer les objets inactifs ou à durée limitée, ajoutez le paramètre
Par défaut, les appels API du catalogue renvoient les objets disponibles dans la boutique au moment de la requête. Pour récupérer les objets inactifs ou à durée limitée, ajoutez le paramètre
"show_inactive_time_limited_items": 1 dans la requête du catalogue.
Vous pouvez vendre des objets en utilisant les méthodes suivantes :
- Achat rapide — vendre une UGS plusieurs fois.
- Achat via le panier — l'utilisateur ajoute des objets au panier, supprime des objets et modifie les quantités dans une seule commande.
Si un objet est acheté en utilisant de la monnaie virtuelle au lieu des devises réelles, utilisez l'appel API Créer une commande à partir d'un objet spécifique en monnaie virtuelle. L'interface de paiement n'est pas requise, car le coût est traité lors de l'exécution de l'appel API.
Pour l'achat d'un objet gratuit, utilisez l'appel API Créer une commande avec un bien gratuit spécifique ou l'appel API Créer une commande à partir d'un panier gratuit. L'interface de paiement n'est pas requise, la commande est immédiatement définie sur le statut done.
Utilisez l'appel API côté client pour créer une commande à partir d'un objet spécifique. L'appel renvoie un jeton utilisé pour ouvrir l'interface de paiement.
Note
Les informations sur les remises sont disponibles pour l'utilisateur uniquement dans l'interface de paiement. Les codes promo ne sont pas pris en charge.
Les informations sur les remises sont disponibles pour l'utilisateur uniquement dans l'interface de paiement. Les codes promo ne sont pas pris en charge.
La configuration et les achats du panier peuvent être gérés côté client ou côté serveur.
Configuration et achat du panier côté client
Implémentez vous-même la logique d'ajout et de suppression des objets. Avant d'appeler l'API pour configurer un panier, vous ne disposerez pas d'informations sur les promotions qui s'appliqueront à l'achat. Le coût total ainsi que les informations des objets bonus ajoutés ne seront donc pas encore connus.
Implémentez la logique suivante pour le panier :
- Après que le joueur a rempli un panier, utilisez l'appel API Remplir le panier d'objets. L'appel renvoie les informations actuelles sur les objets sélectionnés (prix avant et après remises, objets bonus).
- Mettez à jour le contenu du panier en fonction des actions utilisateur :
- Pour ajouter un objet ou modifier la quantité de l'objet, utilisez l'appel API Mettre à jour un objet du panier par ID de panier.
- Pour supprimer un objet, utilisez l'appel API Supprimer un objet du panier par ID de panier.
Note
Pour obtenir le statut actuel du panier, utilisez l'appel API Lire le panier de l'utilisateur actuel.
Pour obtenir le statut actuel du panier, utilisez l'appel API Lire le panier de l'utilisateur actuel.
- Utilisez l'appel API Créer une commande à partir de tous les objets du panier actuel. L'appel renvoie l'ID de commande et le jeton de paiement. La commande nouvellement créée est définie sur le statut
newpar défaut.
Configuration et achat du panier côté serveur
Cette approche peut nécessiter davantage de temps pour configurer le panier, car chaque modification doit être effectuée via des appels API.
Implémentez la logique suivante pour le panier :
- Après que le joueur a rempli un panier, utilisez l'appel API Remplir le panier d'objets. L'appel renvoie les informations à jour sur les objets sélectionnés (prix avant et après remises, objets bonus).
- Utilisez l'appel API Créer une commande à partir de tous les objets du panier actuel. L'appel renvoie l'ID de commande et le jeton de paiement. La commande nouvellement créée est définie sur le statut
newpar défaut.
Utilisez le jeton renvoyé pour ouvrir l'interface de paiement dans une nouvelle fenêtre. D'autres méthodes d'ouverture de l'interface de paiement sont décrites dans la documentation.
| Action | Endpoint |
|---|---|
| Ouverture dans l'environnement de production. | https://secure.xsolla.com/paystation4/?token={token} |
| Ouverture en mode bac à sable. | https://sandbox-secure.xsolla.com/paystation4/?token={token} |
Note
Utilisez le mode bac à sable pendant le développement et les tests. Les achats de test n'entraînent aucun débit sur des comptes réels. Vous pouvez utiliser des cartes bancaires de test.
Utilisez le mode bac à sable pendant le développement et les tests. Les achats de test n'entraînent aucun débit sur des comptes réels. Vous pouvez utiliser des cartes bancaires de test.
Après le premier paiement réel, une politique stricte du mode bac à sable s'applique. Les paiements en mode bac à sable sont disponibles uniquement pour les utilisateurs spécifiés dans la section Company settings > Users du Compte éditeur.
L'achat de monnaie virtuelle et d'objets en devise réelle n'est possible qu'après la signature d'un contrat de licence avec Xsolla. Pour cela, dans le Compte éditeur, accédez à Agreements & Taxes > Agreements, complétez le formulaire et attendez la validation. Le traitement du contrat peut prendre jusqu'à 3 jours ouvrés.
Pour activer ou désactiver le mode bac à sable, modifiez la valeur du paramètre sandbox dans la requête pour l'achat rapide et l'achat via le panier. Le mode bac à sable est désactivé par défaut.
Statuts de commande possibles :
new— commande crééepaid— paiement reçudone— objet attribuécanceled— commande annuléeexpired— commande expirée
Suivez le statut de la commande en utilisant l'une des méthodes suivantes :
Les appels API qui renvoient de grands ensembles d'enregistrements (par exemple lors de la création d'un catalogue) utilisent la pagination. La pagination est un mécanisme qui limite le nombre d'objets renvoyés dans une seule réponse et permet de récupérer les pages suivantes de manière séquentielle.
Utilisez les paramètres suivants pour contrôler le nombre d'objets renvoyés :
limit— nombre d'objets par pageoffset— indice du premier objet sur la page (la numérotation commence à 0)has_more— indique si une autre page est disponibletotal_items_count— nombre total d'objets
Exemple de requête :
GET /items?limit=20&offset=40Exemple de réponse :
{
"items": [...],
"has_more": true,
"total_items_count": 135
}Il est recommandé d'envoyer des requêtes successives jusqu'à ce que la réponse renvoie has_more = false.
Les dates et les valeurs temporelles sont transmises au format ISO 8601.
Les valeurs suivantes sont prises en charge :
- Décalage UTC
- Valeur
nulllorsqu'il n'y a pas de restriction temporelle pour l'affichage d'un objet - Horodatage Unix (en secondes) utilisé dans certains champs
Format : YYYY-MM-DDTHH:MM:SS±HH:MM
Exemple : 2026-03-16T10:00:00+03:00
Xsolla prend en charge la localisation des champs destinés aux utilisateurs, tels que le nom et la description de l'objet. Les valeurs localisées sont transmises sous forme d'objet, où le code de langue est utilisé comme clé. La liste complète des langues prises en charge est disponible dans la documentation.
Champs pris en charge
Les paramètres suivants peuvent être localisés :
namedescriptionlong_description
Format de langue
La clé de la langue peut être spécifiée dans l'un des formats suivants :
- Code de langue à deux lettres :
en,ru - Code de langue à cinq lettres :
en-US,ru-RU,de-DE
Exemples
Exemple avec un code de langue à deux lettres :
{
"name": {
"en": "Starter Pack",
"ru": "Стартовый набор"
}
}Exemple avec un code de langue à cinq lettres :
{
"description": {
"en-US": "Premium bundle",
"de-DE": "Premium-Paket"
}
}En cas d'erreur, l'API renvoie un statut HTTP ainsi qu'un corps de réponse au format JSON. La liste complète des erreurs liées au magasin est disponible dans la documentation.
Exemple de réponse :
{
"errorCode": 1102,
"errorMessage": "Validation error",
"statusCode": 422,
"transactionId": "c9e1a..."
}errorCode— code d'erreur.errorMessage— courte description de l'erreur.statusCode— statut de la réponse HTTP.transactionId— ID de la requête. Retourné uniquement dans certains cas.errorMessageExtended— informations supplémentaires sur l'erreur, telles que les paramètres de la requête. Retournées uniquement dans certains cas.
Exemple de réponse détaillée :
{
"errorCode": 7001,
"errorMessage": "Chain not found",
"errorMessageExtended": {
"chain_id": "test_chain_id",
"project_id": "test_project_id",
"step_number": 2
},
"statusCode": 404
}Codes de statut HTTP courants
400— requête non valide401— erreur d'authentification403— permissions insuffisantes404— ressource non trouvée422— erreur de validation429— limite de taux dépassée
Recommandations
- Gérez ensemble le statut HTTP et le corps de la réponse.
- Utilisez
errorCodepour traiter les erreurs liées à la logique de l'application. - Utilisez
transactionIdpour identifier plus rapidement les requêtes lors de l'analyse des erreurs.
Télécharger la description d'OpenAPI
Langues
Serveurs
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/fr/api/catalog/
Aperçu
Vous pouvez utiliser des objets virtuels et de la monnaie virtuelle pour créer un magasin en jeu et configurer son affichage pour les utilisateurs. Les types d'objets suivants sont disponibles :
- Objets virtuels — biens en jeu tels que des armes, des skins ou des boosters. Peuvent être vendus contre des devises réelles ou de la monnaie virtuelle.
- Monnaie virtuelle — monnaie en jeu utilisée pour acheter des objets virtuels. Peut être vendue contre des devises réelles ou de la monnaie virtuelle.
- Packages de monnaie virtuelle — quantité fixe de monnaie virtuelle. Peuvent être vendus contre des devises réelles ou de la monnaie virtuelle.
Les groupes sont utilisés pour organiser les objets dans le catalogue. Ils vous permettent de regrouper logiquement les objets et de gérer leur affichage.
Utilisez les appels API de la sous-section Administrateur pour créer, modifier et supprimer des objets.
Utilisez les appels API de la sous-section Catalogue pour récupérer des listes d'objets et les afficher aux utilisateurs.
Note
N'utilisez pas les appels API de la sous-section Administrateur pour créer un catalogue de magasin.
N'utilisez pas les appels API de la sous-section Administrateur pour créer un catalogue de magasin.
Note
L'appel API Lire la liste des objets virtuels renvoie des données détaillées sur les objets, y compris les prix et les attributs, et prend en charge la pagination. Utilisez-le pour afficher les pages du catalogue dans la vitrine.
L'appel API Lire la liste de tous les objets virtuels renvoie l'UGS, le nom, la description des objets, ainsi que l'ID et le nom du groupe sans pagination. Utilisez-le pour la recherche côté client ou l'indexation.
L'appel API Lire la liste des objets virtuels renvoie des données détaillées sur les objets, y compris les prix et les attributs, et prend en charge la pagination. Utilisez-le pour afficher les pages du catalogue dans la vitrine.
L'appel API Lire la liste de tous les objets virtuels renvoie l'UGS, le nom, la description des objets, ainsi que l'ID et le nom du groupe sans pagination. Utilisez-le pour la recherche côté client ou l'indexation.
Pour les achats avec de la monnaie virtuelle, utilisez l'appel API Créer une commande à partir d'un objet spécifique en monnaie virtuelle. L'interface de paiement n'est pas requise, le coût est traité lors de l'exécution de l'appel API.
Exemple de processus d'achat avec de la monnaie virtuelle :
Aperçu
Game keys are single-use unique alphanumeric codes that grant users access to a game or DLC on gaming platforms. You can sell game keys via a direct link, through the store UI, or via a widget. You can also configure regional restrictions to sell game keys in specific countries. For detailed information, refer to the Game keys packages section.
User authentication is not required to sell game keys — the keys are sent to the email the user specified at checkout. You can configure authentication to enable additional scenarios: personalization, purchase limits, or an entitlement system. For detailed information, refer to the How to set up authentication when selling game keys section.
Game key sales flow:
- Create a game using the Create game API call.
- Configure regional restrictions.
- Upload keys to a game key package using the Upload codes API call to make them available for purchase.
- Display the game catalog with prices for the user's region using the Get games list API call.
- Create an order. For a fast purchase, you can use the Create order with all items from current cart API call, passing the game key SKU. The response returns a token for opening the payment UI.
- Implement the opening of the payment UI to pay for the order.
To receive timely notifications about successful payments and deliver items to the user, set up order status tracking, for example, using webhooks. The keys are sent to the email the user specified at checkout, and the order moves to the done status.
Aperçu
Bundles are sets of items sold as a single unit. A bundle can include virtual items, virtual currency, virtual currency packages, game keys, and other bundles. Use bundles to create starter packs, seasonal offers, and special deals.
Use the following API call groups to work with bundles:
- Use API calls from the Admin subsection to create, update, delete bundles, and manage their visibility.
- Use API calls from the Catalog subsection to retrieve bundles.
Purchase limits are configured via the limits object when creating or updating a bundle. For more information, refer to the Limits overview. You can also configure regional restrictions to sell items in specific countries.
Bundle management scenario:
- Create a bundle using the Create bundle API call. To verify the created bundle, use the Get bundle API call. To retrieve all bundles in the project, use the Get list of bundles API call.
- If needed, use the Update bundle API call to modify the bundle content or settings.
- Implement bundle display logic in your storefront using the Get list of bundles, Get specified bundle, or Get list of bundles by specified group API call.
- Create an order using the Cart and payment section. For example, for a fast purchase you can use the Create order with specified item API call, passing the bundle SKU. The response contains a token for opening the payment UI.
- Implement opening the payment UI to pay for the order.
- Set up order status tracking, for example using webhooks, to promptly receive data on successfully paid items and grant them to the user.
Requête
Updates a bundle. This call fully replaces the bundle — pass all required fields in the request body, not only the fields you want to change. For more information, refer to the Bundles section.
Notice
All items in the
All items in the
content array must be created in your project in advance. The system returns an error if the specified SKU doesn't exist.Sécurité
basicAuth
Chemin
Corpsapplication/jsonobligatoireID du projet. Vous trouverez ce paramètre dans le Compte éditeur, à côté du nom du projet, ainsi que dans l'URL affichée dans la barre d'adresse du navigateur lorsque vous utilisez ce projet. L'URL présente le format suivant : https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.
Exemple: 44056
Objet contenant des données du lot
ID unique de l'objet. L'UGS ne peut comprendre que des caractères alphanumériques latins minuscules et majuscules, des points, des tirets et des traits bas.
Conteneur objet contenant les localisations du nom de l'objet (item). Il accepte deux formats de codes de langue : les codes à deux lettres minuscules (comme en) et les codes régionaux à cinq caractères (comme en-US). Les deux formats sont valides en entrée, mais les réponses utilisent toujours le format à deux lettres. Si les deux variantes sont fournies pour une même langue (par exemple, en et en-US), seule la dernière est conservée. Consultez la documentation pour la liste complète des langues prises en charge.
Any of:
Codes de langue à deux lettres minuscules.
Groupes auxquels l'objet appartient.
Note. La valeur de la chaîne correspond à l'`external_id` du groupe.
Liste des attributs.
Attention. La création de plus de 20 attributs pour un objet n'est pas autorisée. Toute tentative de dépassement entraîne une erreur.
ID unique de l'attribut. Le external_id ne peut comprendre que des caractères alphanumériques latins minuscules et majuscules, des tirets et des traits bas.
Objet contenant des versions localisées du nom de l'attribut. Les clés sont spécifiées selon la norme ISO 3166-1.
Attention. La création de plus de 6 valeurs pour un attribut n'est pas autorisée. Toute tentative de dépassement entraînera une erreur.
Exemple: [{"external_id":"strategy","value":{"en":"Strategy","de":"Strategie"}},{"external_id":"action","value":{"en":"Action","de":"Aktion"}}]
ID unique de la valeur d'un attribut. Le external_id ne peut comprendre que des caractères alphanumériques latins minuscules, des tirets et des tirets bas.
Exemple: "value_external_id"
Conteneur objet contenant les localisations de la description de l'objet (item). Il accepte deux formats de codes de langue : les codes à deux lettres minuscules (comme en) et les codes régionaux à cinq caractères (comme en-US). Les deux formats sont valides en entrée, mais les réponses utilisent toujours le format à deux lettres. Si les deux variantes sont fournies pour une même langue (par exemple, en et en-US), seule la dernière est conservée. Consultez la documentation pour la liste complète des langues prises en charge.
Any of:
Codes de langue à deux lettres minuscules.
Conteneur objet contenant les localisations de la description complète de l'objet (item). Il accepte deux formats de codes de langue : les codes à deux lettres minuscules (comme en) et les codes régionaux à cinq caractères (comme en-US). Les deux formats sont valides en entrée, mais les réponses utilisent toujours le format à deux lettres. Si les deux variantes sont fournies pour une même langue (par exemple, en et en-US), seule la dernière est conservée. Consultez la documentation pour la liste complète des langues prises en charge.
Any of:
Codes de langue à deux lettres minuscules.
URL de l'image. Pour garantir un affichage correct et un chargement rapide dans l'interface de paiement, consultez les recommandations suivantes pour les images et les URL :
- Formats pris en charge : WebP (recommandé), PNG, JPG.
- Taille du fichier : ≤ 50 Kb (WebP) ou ≤ 150 Kb (PNG et JPG).
- Dimensions : 280 x 280 px.
- Espace colorimétrique : sRGB.
- Protocole : HTTPS avec mise en cache longue durée pour les URL versionnées.
Prix en devises réelles.
Devise du prix de l'objet. Code à trois lettres selon ISO 4217.
Le prix par défaut est utilisé pour constituer le catalogue si aucun prix n'est spécifié dans la devise de l'utilisateur.
Pays où ce prix est disponible. Code à deux lettres selon la norme ISO 3166-1 alpha 2.
Exemple: "US"
Any of:
ID unique de l'objet. L'UGS ne peut comprendre que des caractères alphanumériques latins minuscules et majuscules, des points, des tirets et des traits bas.
Exemple: "gold"
Type de lot. Utilisez standard pour créer un lot contenant des objets et spécifiez les UGS des objet inclus. Utilisez partner_side_content pour créer un lot vide auquel vous ajouterez des objets de votre côté via un webhook. Ce type est réservé à la Personnalisation du catalogue côté partenaire.
Enum"standard""partner_side_content"
Array of items included in the bundle. Each entry specifies the item SKU and quantity. All items must be created in your project in advance. The system returns an error if the specified SKU doesn't exist.
Exemple: [{"sku":"com.xsolla.kg_1","quantity":1}]
SKU of an item to include in the bundle. The item must be created in your project in advance. The system returns an error if the specified SKU doesn't exist. Allowed characters: a–z, A–Z, 0–9, period (.), hyphen (-), underscore (_).
Exemple: "com.xsolla.kg_1"
Si l’objet est une récompense payante aléatoire (par exemple, une boîte à butin).
Limites d'objets.
Limites d'objets pour un utilisateur spécifique.
Any of:
Limites d'objets pour un utilisateur spécifique.
null
Délai d'actualisation des limites.
Réinitialisation des limites d'achat effectuée selon l'intervalle de temps spécifié, en heures.
One of:
Réinitialisation des limites d'achat effectuée selon l'intervalle de temps spécifié, en heures.
Délai d'actualisation récurrent.
Valeur"daily"
Période de vente d'objets.
Un JSON contenant les attributs de l'objet et leurs valeurs. Les attributs permettent d'ajouter des informations supplémentaires aux objets, telles que le niveau requis du joueur pour utiliser l'objet. Les attributs enrichissent la logique interne de votre jeu et sont accessibles via des méthodes GET et des webhooks spécifiques.
- https://store.xsolla.com/api/v2/project/{project_id}/admin/items/bundle/sku/{sku}
- Mock serverhttps://xsolla.redocly.app/_mock/fr/api/catalog/v2/project/{project_id}/admin/items/bundle/sku/{sku}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PUT \
-u <username>:<password> \
https://store.xsolla.com/api/v2/project/44056/admin/items/bundle/sku/kg_1 \
-H 'Content-Type: application/json' \
-d '{
"sku": "com.xsolla.armour_chest_1",
"name": {
"en": "Chest of armour",
"de": "Brustpanzer"
},
"is_enabled": true,
"is_free": true,
"is_paid_randomized_reward": true,
"order": 1,
"long_description": {
"en": "Chest of armour for soldiers",
"de": "Brustpanzer für Soldaten"
},
"description": {
"en": "Chest of armour for soldiers",
"de": "Brustpanzer für Soldaten"
},
"image_url": "https://picture.bundle-with-many-stuff.png",
"media_list": [
{
"type": "image",
"url": "https://test.com/image0"
},
{
"type": "image",
"url": "https://test.com/image1"
}
],
"groups": [
"chests"
],
"attributes": [
{
"external_id": "class",
"name": {
"en": "Class"
},
"values": [
{
"external_id": "soldier",
"value": {
"en": "Soldier"
}
},
{
"external_id": "officer",
"value": {
"en": "Officer"
}
}
]
}
],
"prices": [
{
"currency": "USD",
"amount": "9.99",
"is_default": true,
"is_enabled": true
},
{
"currency": "EUR",
"amount": "9.99",
"is_default": false,
"is_enabled": true
}
],
"vc_prices": [],
"content": [
{
"sku": "com.xsolla.iron_gloves_1",
"quantity": 1
},
{
"sku": "com.xsolla.iron_boots_1",
"quantity": 1
},
{
"sku": "com.xsolla.iron_shield_1",
"quantity": 1
},
{
"sku": "com.xsolla.iron_armour_1",
"quantity": 1
},
{
"sku": "com.xsolla.iron_helmet_1",
"quantity": 1
}
],
"limits": {
"per_user": null,
"per_item": null
},
"periods": [
{
"date_from": "2020-08-11T10:00:00+03:00",
"date_until": "2020-08-11T20:00:00+03:00"
}
],
"custom_attributes": {
"type": "lootbox",
"purchased": 0
}
}'Chemin
ID du projet. Vous trouverez ce paramètre dans le Compte éditeur, à côté du nom du projet, ainsi que dans l'URL affichée dans la barre d'adresse du navigateur lorsque vous utilisez ce projet. L'URL présente le format suivant : https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.
Exemple: 44056
- https://store.xsolla.com/api/v2/project/{project_id}/admin/items/bundle/sku/{sku}
- Mock serverhttps://xsolla.redocly.app/_mock/fr/api/catalog/v2/project/{project_id}/admin/items/bundle/sku/{sku}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X DELETE \
-u <username>:<password> \
https://store.xsolla.com/api/v2/project/44056/admin/items/bundle/sku/kg_1Chemin
ID du projet. Vous trouverez ce paramètre dans le Compte éditeur, à côté du nom du projet, ainsi que dans l'URL affichée dans la barre d'adresse du navigateur lorsque vous utilisez ce projet. L'URL présente le format suivant : https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.
Exemple: 44056
- https://store.xsolla.com/api/v2/project/{project_id}/admin/items/bundle/sku/{sku}
- Mock serverhttps://xsolla.redocly.app/_mock/fr/api/catalog/v2/project/{project_id}/admin/items/bundle/sku/{sku}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
https://store.xsolla.com/api/v2/project/44056/admin/items/bundle/sku/kg_1Le lot spécifié a été reçu avec succès.
ID unique de l'objet. L'UGS ne peut comprendre que des caractères alphanumériques latins minuscules et majuscules, des points, des tirets et des traits bas.
Conteneur objet contenant les localisations du nom de l'objet (item). Il accepte deux formats de codes de langue : les codes à deux lettres minuscules (comme en) et les codes régionaux à cinq caractères (comme en-US). Les deux formats sont valides en entrée, mais les réponses utilisent toujours le format à deux lettres. Si les deux variantes sont fournies pour une même langue (par exemple, en et en-US), seule la dernière est conservée. Consultez la documentation pour la liste complète des langues prises en charge.
Any of:
Codes de langue à deux lettres minuscules.
Liste des attributs.
Exemple: [{"external_id":"attribute_external_id","name":{"en":"Attribute name","de":"Attributname"},"values":[{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]}]
ID unique de l'attribut. Le external_id ne peut comprendre que des caractères alphanumériques latins minuscules et majuscules, des tirets et des traits bas.
Exemple: "attribute_external_id"
Objet contenant des versions localisées du nom de l'attribut. Les clés sont spécifiées selon la norme ISO 3166-1.
Exemple: {"en":"Attribute name","de":"Attributname"}
Exemple: [{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]
ID unique de la valeur d'un attribut. Le external_id ne peut comprendre que des caractères alphanumériques latins minuscules, des tirets et des tirets bas.
Exemple: "value_external_id"
Type de lot. Renvoyé si le type d'objet est un lot.
Enum"standard""virtual_currency_package""partner_side_content"
Conteneur objet contenant les localisations de la description de l'objet (item). Il accepte deux formats de codes de langue : les codes à deux lettres minuscules (comme en) et les codes régionaux à cinq caractères (comme en-US). Les deux formats sont valides en entrée, mais les réponses utilisent toujours le format à deux lettres. Si les deux variantes sont fournies pour une même langue (par exemple, en et en-US), seule la dernière est conservée. Consultez la documentation pour la liste complète des langues prises en charge.
Any of:
Codes de langue à deux lettres minuscules.
Conteneur objet contenant les localisations de la description complète de l'objet (item). Il accepte deux formats de codes de langue : les codes à deux lettres minuscules (comme en) et les codes régionaux à cinq caractères (comme en-US). Les deux formats sont valides en entrée, mais les réponses utilisent toujours le format à deux lettres. Si les deux variantes sont fournies pour une même langue (par exemple, en et en-US), seule la dernière est conservée. Consultez la documentation pour la liste complète des langues prises en charge.
Any of:
Codes de langue à deux lettres minuscules.
URL de l'image. Pour garantir un affichage correct et un chargement rapide dans l'interface de paiement, consultez les recommandations suivantes pour les images et les URL :
- Formats pris en charge : WebP (recommandé), PNG, JPG.
- Taille du fichier : ≤ 50 Kb (WebP) ou ≤ 150 Kb (PNG et JPG).
- Dimensions : 280 x 280 px.
- Espace colorimétrique : sRGB.
- Protocole : HTTPS avec mise en cache longue durée pour les URL versionnées.
Si l’objet est une récompense payante aléatoire (par exemple, une boîte à butin).
Groupes auxquels l'objet appartient.
Prix en devises réelles.
Devise du prix de l'objet. Code à trois lettres selon ISO 4217.
Le prix par défaut est utilisé pour constituer le catalogue si aucun prix n'est spécifié dans la devise de l'utilisateur.
Pays où ce prix est disponible. Code à deux lettres selon la norme ISO 3166-1 alpha 2.
Exemple: "US"
ID unique de l'objet. L'UGS ne peut comprendre que des caractères alphanumériques latins minuscules et majuscules, des points, des tirets et des traits bas.
Conteneur objet contenant les localisations du nom de l'objet (item). Il accepte deux formats de codes de langue : les codes à deux lettres minuscules (comme en) et les codes régionaux à cinq caractères (comme en-US). Les deux formats sont valides en entrée, mais les réponses utilisent toujours le format à deux lettres. Si les deux variantes sont fournies pour une même langue (par exemple, en et en-US), seule la dernière est conservée. Consultez la documentation pour la liste complète des langues prises en charge.
Any of:
Codes de langue à deux lettres minuscules.
Conteneur objet contenant les localisations de la description de l'objet (item). Il accepte deux formats de codes de langue : les codes à deux lettres minuscules (comme en) et les codes régionaux à cinq caractères (comme en-US). Les deux formats sont valides en entrée, mais les réponses utilisent toujours le format à deux lettres. Si les deux variantes sont fournies pour une même langue (par exemple, en et en-US), seule la dernière est conservée. Consultez la documentation pour la liste complète des langues prises en charge.
Any of:
Codes de langue à deux lettres minuscules.
URL de l'image. Pour garantir un affichage correct et un chargement rapide dans l'interface de paiement, consultez les recommandations suivantes pour les images et les URL :
- Formats pris en charge : WebP (recommandé), PNG, JPG.
- Taille du fichier : ≤ 50 Kb (WebP) ou ≤ 150 Kb (PNG et JPG).
- Dimensions : 280 x 280 px.
- Espace colorimétrique : sRGB.
- Protocole : HTTPS avec mise en cache longue durée pour les URL versionnées.
ID unique de l'objet. L'UGS ne peut comprendre que des caractères alphanumériques latins minuscules et majuscules, des points, des tirets et des traits bas.
Conteneur objet contenant les localisations du nom de l'objet (item). Il accepte deux formats de codes de langue : les codes à deux lettres minuscules (comme en) et les codes régionaux à cinq caractères (comme en-US). Les deux formats sont valides en entrée, mais les réponses utilisent toujours le format à deux lettres. Si les deux variantes sont fournies pour une même langue (par exemple, en et en-US), seule la dernière est conservée. Consultez la documentation pour la liste complète des langues prises en charge.
Any of:
Codes de langue à deux lettres minuscules.
Conteneur objet contenant les localisations de la description de l'objet (item). Il accepte deux formats de codes de langue : les codes à deux lettres minuscules (comme en) et les codes régionaux à cinq caractères (comme en-US). Les deux formats sont valides en entrée, mais les réponses utilisent toujours le format à deux lettres. Si les deux variantes sont fournies pour une même langue (par exemple, en et en-US), seule la dernière est conservée. Consultez la documentation pour la liste complète des langues prises en charge.
Any of:
Codes de langue à deux lettres minuscules.
URL de l'image. Pour garantir un affichage correct et un chargement rapide dans l'interface de paiement, consultez les recommandations suivantes pour les images et les URL :
- Formats pris en charge : WebP (recommandé), PNG, JPG.
- Taille du fichier : ≤ 50 Kb (WebP) ou ≤ 150 Kb (PNG et JPG).
- Dimensions : 280 x 280 px.
- Espace colorimétrique : sRGB.
- Protocole : HTTPS avec mise en cache longue durée pour les URL versionnées.
Limites d'objets.
Limites d'objets pour un utilisateur spécifique.
Détermine la visibilité de l'objet dans le catalogue une fois la limite d'achat atteinte, jusqu'à la prochaine réinitialisation de la limite.
S'applique aux objets pour lesquels des réinitialisations de limite récurrentes sont configurées dans le tableau recurrent_schedule.
Si aucune réinitialisation de limite n'est configurée, l'objet n'apparaît plus dans le catalogue une fois la limite d'achat atteinte, quelle que soit la valeur de limit_exceeded_visibility.
Valeurs possibles :
show— L'objet est renvoyé dans les appels API de récupération du catalogue après avoir atteint la limite d'achat. Dans les appels côté client, une fois la limite atteinte, l'objet est renvoyé avec l'indicateurcan_be_bought: false. La prochaine date de réinitialisation est renvoyée dansreset_next_date.hide— L'objet n'est pas renvoyé dans les appels API de récupération du catalogue après avoir atteint la limite d'achat, jusqu'à la réinitialisation de la limite.
Enum"show""hide"
Limites globales d'objets.
Délai d'actualisation des limites.
Délai d'actualisation des limites pour un utilisateur.
One of:
Type quotidien d'actualisation des limites pour l'utilisateur.
Type de délai d'actualisation récurrent.
Valeur"daily"
Heure d'actualisation des limites dans le fuseau horaire souhaité (arrondie en heures).
Exemple: "11:00:00+03:00"
Date et heure de réinitialisation des limites (horodatage Unix).
Exemple: 1677553200
Date et heure de la première réinitialisation des limites (ISO 8601).
Exemple: "2023-02-28T11:00:00+08:00"
Période de vente d'objets.
Somme des prix du contenu du lot.
Somme des prix du contenu du lot.
Exemple: "100.99"
Devise du prix de l'objet. Code à trois lettres selon ISO 4217.
Réponse
application/json
{ "item_id": 610316, "sku": "com.xsolla.EmpireBundle_1", "name": { "en": "Empire bundle" }, "type": "bundle", "description": { "en": "Empire bundle with items" }, "image_url": "https://cdn.xsolla.net/img/misc/images/685b21f9d9dca4aa0c953e8816b4eb4b.png", "long_description": { "en": "Empire bundle with some goods" }, "attributes": [], "is_free": false, "is_paid_randomized_reward": true, "groups": [ { … } ], "prices": [], "virtual_prices": [ { … } ], "media_list": [], "order": 1, "is_enabled": true, "is_show_in_store": true, "regions": [], "bundle_type": "standard", "content": [ { … }, { … }, { … } ], "limits": { "per_user": { … }, "per_item": null, "recurrent_schedule": null }, "periods": [ { … } ], "custom_attributes": { "type": "lootbox", "purchased": 0 } }
Aperçu
The cart is a purchasing mechanism that enables combining multiple items into a single order. A user can buy items of any type in any quantity for real currency, as well as use promo codes.
The cart is stored on the Xsolla side. Saving the cart across sessions depends on whether the user is authorized:
For authorized users, the cart is linked to a specific user and is saved across sessions as long as requests are sent on behalf of the same user.
For unauthorized users, saving the cart depends on passing the
x-unauthorized-idheader. To save the cart of an unauthorized user across sessions, pass the samex-unauthorized-idin every request. This option is available only for game key sales.
You can identify the cart in two ways: automatically by user's JWT or by cart ID (cart_id).
Cart management is available both on the client side and on the server side.
On the server side, you can fill the cart with items, e.g., when restoring a user session. The following actions are available on the client side:
- retrieve the current user's cart or a cart by ID
- fill the cart
- update items in the cart
- delete items from the cart
To purchase items from the cart, the client and server calls for order creation are used.
The cart’s time to live (TTL) is 72 hours by default. If its content changes, e.g., when a new item is added, the TTL is extended.
After successful payment, the cart isn’t cleared automatically. To clear the cart, use the following client-side API calls:
Delete cart item by cart ID and Delete cart item from current cart — the cart is cleared when you delete the last item from it.
Cart usage scenario:
Implement a store UI where the user will select items.
When the user selects items in the store, add them to the cart, e.g., using the Fill cart with items call. In the items array, you need to pass the SKUs and the required quantity of items.
Implement the cart viewing UI. When the user navigates to the cart, display its contents using the Get current user's cart call. The response will return information about the final price of the items, including discounts and applied promotions.
Implement the opening of the payment UI to pay for the order. For example, you can use the Create order with all items from particular cart call. The response returns a token to open the payment UI.
Configure order status tracking, e.g., using webhooks, to promptly receive data about successfully paid items and grant them to the user.
Note
To implement selling items in-game and online, refer to the integration guide.
Cycle de vie d'une commande
Comprendre le cycle de vie d'une commande vous aide à suivre les commandes et à implémenter correctement la logique post-achat, par exemple l'attribution des objets.
La commande passe par les statuts suivants :
| Statut | Description | Notes |
new | Commande créée. Le système attend la confirmation du paiement.. | Les descriptions des statuts de transaction se trouvent dans la documentation Pay Station API. |
paid | Commande payée (la transaction est passée au statut done), et l'objet peut être attribué à l'utilisateur. | La commande reste en statut new jusqu'à ce que le paiement soit confirmé. |
done | Objet attribué à l'utilisateur. | — |
canceled | Paiement remboursé. | La commande passe à ce statut lorsque le statut de la transaction devient refunded. |
expired | La création d'une nouvelle commande pour un objet en édition limitée, un code promo ou une promotion fait passer toute commande antérieure non réglée contenant cet objet au statut expired. Seule la commande la plus récente peut être réglée. | Si un utilisateur tente de régler une commande expirée, l'interface de paiement affichera une erreur 2002 et le paiement échouera. |
Note
Lorsque la commande passe au statut expired pendant que l'utilisateur finalise un paiement, mais que le paiement aboutit, la commande passe du statut expired au statut paid. Cela s'applique uniquement si la limite d'achat de l'objet associé à la commande n'est pas dépassée lors du paiement.
Biens gratuits
Use calls from this section to grant free items to users.
Opérations
Aperçu
Les limites d'achat vous permettent de restreindre la quantité d'objets disponibles à l'achat par un utilisateur unique ou par l'ensemble des utilisateurs. Vous pouvez également configurer des réinitialisations programmées des limites.
Les limites sont stockées côté Xsolla et sont configurées au niveau de l'objet individuel dans le Compte éditeur ou via l'objet limits dans les appels API suivants :
- Créer un objet virtuel
- Créer un jeu
- Créer une monnaie virtuelle
- Créer un package de monnaie virtuelle
- Créer un lot
Les informations sur les limites sont renvoyées dans l'objet items.limits dans les appels API suivants pour récupérer le catalogue des objets :
- Lire la liste des objets virtuels
- Lire la liste des monnaies virtuelles
- Lire la liste des packages de monnaie virtuelle
- Lire la liste des lots
- Lire la liste des jeux
Les appels API de la sous-section Gestion du groupe Limites vous permettent de récupérer l'état actuel des limites et de les mettre à jour pour un utilisateur spécifique, par exemple, réinitialiser le compteur après la fin d'une quête ou ajuster manuellement la quantité restante.
Note
Pour des informations détaillées sur la configuration des limites dans le catalogue, consultez la section Item purchase limits.
Pour des informations détaillées sur la configuration des limites dans le catalogue, consultez la section Item purchase limits.