Passer au contenu
/
Lire une liste d'objets p...

Catalog API (2.0.0)

Aperçu

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

Appels API

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.
Télécharger la description d'OpenAPI
index.json
index.yaml
Langues
Serveurs
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/fr/api/catalog/

Administrateur

Opérations

Catalogue

Opérations

Lire la liste de tous les objets virtuelsClient-side

Requête

Récupère une liste de tous les objets virtuels à rechercher côté client.

Attention

Renvoie uniquement l'UGS, le nom, les groupes et la description.

Remarque

L'utilisation des appels API du catalogue des objets est disponible sans autorisation, mais pour obtenir un catalogue personnalisé, vous devez passer le JWT utilisateur dans l'en-tête d'autorisation.
Sécurité
XsollaLoginUserJWT
Chemin
project_idintegerobligatoire

ID de projet. Ce paramètre se trouve dans le Compte éditeur à côté du nom du projet.

Exemple: 44056
Requête
localestring

Langue de la réponse. Code de langue à deux lettres minuscules selon la norme ISO 639-1.

Par défaut "en"
promo_codestring[ 1 .. 128 ] characters

Code unique sensible à la casse. Comprend des lettres et des chiffres.

Exemple: promo_code=WINTER2021
curl -i -X GET \
  'https://store.xsolla.com/api/v2/project/44056/items/virtual_items/all?locale=en&promo_code=WINTER2021' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Réponses

La liste de tous les objets virtuels a été reçue avec succès.

Corpsapplication/json
itemsArray of objects
Exemple: [{"description":"Big Rocket - description","groups":[{"external_id":"accessory","name":{"en":"accessory"}}],"name":"Big Rocket","sku":"com.xsolla.big_rocket_1"},{"description":"description","groups":[{"external_id":"hair","name":{"en":"Hair"}}],"name":"SHOTGUN FOR TRUE RAIDERS","sku":"com.xsolla.shotgun_raider_1"},{"description":"description","groups":[],"name":"SHOTGUN FOR TRUE RAIDERS","sku":"com.xsolla.shotgun_raider_2"}]
Réponse
application/json
{
  "items": [
    { … },
    { … },
    { … }
  ]
}

Lire une liste d'objets par groupe spécifiqueClient-side

Requête

Récupère une liste d'objets au sein d'un groupe spécifique pour la constitution d'un catalogue.

Attention

Tous les projets sont soumis à une limite de nombre d'objets que vous pouvez obtenir dans la réponse. La valeur par défaut et la valeur maximale sont 50 éléments par réponse. Pour obtenir plus de données page par page, utilisez les champs limit et offset.

Note

Cet endpoint, accessible sans autorisation, renvoie des données génériques. Cependant, l'autorisation permet d'enrichir la réponse avec des détails spécifiques à l'utilisateur pour un résultat personnalisé, tels que les limites et les promotions disponibles pour l'utilisateur.
Sécurité
XsollaLoginUserJWT
Chemin
project_idintegerobligatoire

ID de projet. Ce paramètre se trouve dans le Compte éditeur à côté du nom du projet.

Exemple: 44056
external_idstringobligatoire

External ID du groupe.

Par défaut "all"
Requête
limitinteger>= 1

Nombre maximal d'éléments sur une page.

Exemple: limit=50
offsetinteger>= 0

Numéro de l'élément à partir duquel la liste est générée (le décompte commence à 0).

Exemple: offset=0
localestring

Langue de la réponse. Code de langue à deux lettres minuscules selon la norme ISO 639-1.

Par défaut "en"
additional_fields[]Array of strings

La liste des champs supplémentaires. Ces champs figureront dans la réponse si vous les envoyez dans votre requête.

Éléments Enum"media_list""order""long_description""custom_attributes""item_order_in_group"
countrystring

Code pays à deux lettres majuscules selon la norme ISO 3166-1 alpha-2. Consultez la documentation pour obtenir des informations détaillées sur les pays pris en charge par Xsolla et le processus de détermination du pays.

Exemple: country=US
promo_codestring[ 1 .. 128 ] characters

Code unique sensible à la casse. Comprend des lettres et des chiffres.

Exemple: promo_code=WINTER2021
show_inactive_time_limited_itemsinteger

Affiche les objets à durée limitée qui ne sont pas disponibles pour l'utilisateur. La période de validité de ces objets n'ayant pas commencé ou ayant déjà expiré.

Par défaut 0
Exemple: show_inactive_time_limited_items=1
curl -i -X GET \
  'https://store.xsolla.com/api/v2/project/44056/items/virtual_items/group/{external_id}?limit=50&offset=0&locale=en&additional_fields%5B%5D=media_list&country=US&promo_code=WINTER2021&show_inactive_time_limited_items=1' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Réponses

La liste d'objets du groupe spécifié a été reçue avec succès.

Corpsapplication/json
has_moreboolean(Pagination_has-more)

Utilisé pour indiquer qu'il y a plus de pages.

Exemple: true
itemsArray of objects
Exemple: [{"attributes":[{"external_id":"stack_size","name":"Stack size","values":[{"value":"5"}]}],"can_be_bought":true,"description":"Big Rocket - description","groups":[{"external_id":"weapons","name":"weapons"}],"image_url":"https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png","is_free":false,"limits":{"per_item":null,"per_user":{"available":3,"limit_exceeded_visibility":"show","recurrent_schedule":{"interval_type":"weekly","reset_next_date":1746057600},"total":5}},"name":"Big Rocket","periods":[{"date_from":"2020-08-11T10:00:00+03:00","date_until":"2020-08-11T20:00:00+03:00"}],"price":{"amount":"100.99","amount_without_discount":"100.99","currency":"USD"},"promotions":[{"bonus":[{"image_url":"https://cdn.xsolla.net/img/misc/images/2fc5c491a47413a8e8000447889093c2.png","name":"Xsolla Minigun","quantity":1,"sku":"com.xsolla.minigun_1","type":"virtual_good"}],"date_end":"2026-04-15T16:16:00+03:00","date_start":"2020-04-15T16:16:00+03:00","discount":{"percent":"50.00"},"name":"Bonus promotion"}],"sku":"com.xsolla.big_rocket_1","type":"virtual_good","virtual_item_type":"non_renewing_subscription","virtual_prices":[{"amount":100,"amount_without_discount":100,"description":"description","image_url":"http://image.png","is_default":true,"name":"SHOTGUN FOR TRUE RAIDERS","sku":"com.xsolla.vc_1","type":"virtual_currency"}]},{"attributes":[{"external_id":"stack_size","name":"Stack size","values":[{"value":"5"}]},{"external_id":"rating","name":"Rating","values":[{"value":"3.9"}]},{"external_id":"genre","name":"Genre","values":[{"value":"Strategy"},{"value":"Tactical"},"Turn-based"]}],"can_be_bought":true,"description":"description","groups":[{"external_id":"weapons","name":{"en":"weapons"}}],"image_url":"http://image.png","is_free":false,"limits":null,"name":"SHOTGUN FOR TRUE RAIDERS","periods":[],"price":{"amount":"101.0","amount_without_discount":"101.0","currency":"USD"},"promotions":[],"sku":"com.xsolla.shotgun_raider","type":"virtual_good","virtual_item_type":"non_renewing_subscription","virtual_prices":[{"amount":100,"amount_without_discount":100,"description":"description","image_url":"http://image.png","is_default":true,"name":"SHOTGUN FOR TRUE RAIDERS","sku":"com.xsolla.vc_1","type":"virtual_currency"},{"amount":200,"amount_without_discount":200,"description":"description","image_url":"http://image.png","is_default":false,"name":"SHOTGUN FOR TRUE RAIDERS","sku":"com.xsolla.vc_2","type":"virtual_currency"}]}]
Réponse
application/json
{
  "has_more": false,
  "items": [
    { … },
    { … }
  ]
}

Lire un objet virtuel par UGSClient-side

Requête

Récupère des informations sur un objet virtuel par son UGS pour la constitution d'un catalogue.

Note

Cet endpoint, accessible sans autorisation, renvoie des données génériques. Cependant, l'autorisation enrichit la réponse avec des détails spécifiques à l'utilisateur pour un résultat personnalisé, tels que les limites et les promotions disponibles pour l'utilisateur.
Sécurité
XsollaLoginUserJWT
Chemin
project_idintegerobligatoire

ID de projet. Ce paramètre se trouve dans le Compte éditeur à côté du nom du projet.

Exemple: 44056
item_skustringobligatoire

UGS de l'objet.

Exemple: booster_mega_1
Requête
localestring

Langue de la réponse. Code de langue à deux lettres minuscules selon la norme ISO 639-1.

Par défaut "en"
countrystring

Code pays à deux lettres majuscules selon la norme ISO 3166-1 alpha-2. Consultez la documentation pour obtenir des informations détaillées sur les pays pris en charge par Xsolla et le processus de détermination du pays.

Exemple: country=US
show_inactive_time_limited_itemsinteger

Affiche les objets à durée limitée qui ne sont pas disponibles pour l'utilisateur. La période de validité de ces objets n'ayant pas commencé ou ayant déjà expiré.

Par défaut 0
Exemple: show_inactive_time_limited_items=1
additional_fields[]Array of strings

La liste des champs supplémentaires. Ces champs figureront dans la réponse si vous les envoyez dans votre requête.

Éléments Enum"media_list""order""long_description""custom_attributes""item_order_in_group"
curl -i -X GET \
  'https://store.xsolla.com/api/v2/project/44056/items/virtual_items/sku/booster_mega_1?locale=en&country=US&show_inactive_time_limited_items=1&additional_fields%5B%5D=media_list' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Réponses

L'objet virtuel a été reçu avec succès.

Corpsapplication/json
attributesArray of objects(Virtual-Items-Currency_client-attributes)

Liste des attributs et de leurs valeurs correspondantes pour l'objet. Peut être utilisée pour le filtrage du catalogue.

Par défaut []
Exemple: {"value":{"external_id":"genre","name":"Жанр","values":[{"external_id":"genre_e3364991f92e751689a68b96598a5a5a84010b85","value":"Casual"},{"external_id":"genre_eba07bfd0f982940773cba3744d97264dd58acd7","value":"Strategy"},{"external_id":"genre_b8d0c6d8f0524c2b2d79ebb93aa3cd0e8b5199a8","value":"Mobile"}]}}
can_be_boughtboolean(Can_be_bought)

Si true, l'utilisateur peut acheter l'objet.

Exemple: true
custom_attributesobject(json)(item-custom-attributes-response)

Un JSON contenant les attributs de l'objet et leurs valeurs.

descriptionobject

Description de l'objet.

Exemple: "Big Rocket - description"
groupsArray of objects(items_client_groups_response)

Groupes auxquels l'objet appartient.

Par défaut []
Exemple: [{"external_id":"exclusive","name":"Exclusive"}]
image_urlstring

URL de l'image.

Exemple: "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png"
is_freeboolean(value-is_free)

Si ce paramètre est défini sur true, l'objet est gratuit.

Par défaut false
Exemple: false
item_idnumber

ID de l'objet

limitsobject or null(client-item-limit-response)

Limites d'objets.

nameobject

Nom de l'objet.

Exemple: "Big Rocket"
periodsArray of objects(item-periods-response)

Période de vente d'objets.

priceobject or null

Prix de l'objet.

promotionsArray of objects(Catalog_item_promotions)

Promotions appliquées à des objets spécifiques du panier. Le tableau est renvoyé dans les cas suivants :

  • Une promotion par réduction est configurée pour un objet spécifique.

  • Un code promo avec le paramètre Discount on selected items est appliqué.

Si aucune promotion de ce type n'est appliquée, un tableau vide est renvoyé.

skustring

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: "big_rocket"
typestring

Type d'objet : virtual_good/virtual_currency/bundle.

Exemple: "virtual_good"
virtual_item_typestring

Type d'objet virtuel.

Enum ValeurDescription
consumable

Un objet qui disparaît de l'inventaire après utilisation (par exemple, des munitions).

non_consumable

Un objet qui reste dans l'inventaire pour une durée illimitée.

non_renewing_subscription

Objet à durée limitée qui peut représenter l'accès à des services ou à du contenu pour une période de temps limitée.

Exemple: "non-consumable"
virtual_pricesArray of objects

Prix virtuels.

vp_rewardsArray of objects(client-item-value-point-reward)

Récompense en points de valeur pour l'objet.

Réponse
application/json
{
  "attributes": [
    { … }
  ],
  "can_be_bought": true,
  "custom_attributes": {
    "attr": "value",
    "purchased": 0
  },
  "description": {
    "en": "Honshu Boshin Wakizashi - Modern Tactical Samurai / Ninja Sword - Hand Forged 1060 Carbon Steel - Full Tang, Fully Functional, Battle Ready - Black TPR, Steel Guard and Pommel"
  },
  "groups": [
    { … }
  ],
  "image_url": "https://cdn.xsolla.net/img/misc/images/8ab44fe99038a56de01950ba4a971b77.png",
  "is_free": false,
  "item_id": 488833,
  "limits": {
    "per_item": null,
    "per_user": { … }
  },
  "name": {
    "en": "Sword Xsolla Skin"
  },
  "periods": [
    { … }
  ],
  "price": {
    "amount": "4.99",
    "amount_without_discount": "4.99",
    "currency": "USD"
  },
  "promotions": [],
  "sku": "com.xsolla.swords_1",
  "type": "virtual_good",
  "virtual_item_type": "non_consumable",
  "virtual_prices": [],
  "vp_rewards": []
}

Paiement virtuel

Opérations

Catalogue

Opérations

Droit

Opérations

Administrateur

Opérations

Administrateur

Opérations

Catalogue

Opérations

Panier (côté client)

Opérations

Panier (côté serveur)

Opérations

Paiement (côté client)

Opérations

Paiement (côté serveur)

Opérations

Commande

Opérations

Biens gratuits

Opérations

Gestion

Opérations

Administrateur

Opérations

Webhooks

Opérations

Pré-commandes

Opérations

Commerçant

Opérations

Catalogue

Cette API permet de récupérer tout type d'objet vendable ou tout objet spécifique.

Opérations

Régions communes

Opérations

Administrateur

Opérations