Passer au contenu
/
Lire une liste de lots pa...

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

Paiement virtuel

Opérations

Catalogue

Opérations

Droit

Opérations

Administrateur

Opérations

Administrateur

Opérations

Catalogue

Opérations

Lire une liste de lotsClient-side

Requête

Récupère une liste de lots 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 maximale est de 50 objets par réponse.

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
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/bundle?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 de lots 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(Bundles_client_bundle)
Réponse
application/json
{
  "has_more": true,
  "items": [
    { … }
  ]
}

Lire une liste de lots par groupe spécifiqueClient-side

Requête

Récupère une liste de lots dans un groupe 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 maximale est de 50 objets par réponse.

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
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/bundle/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 de lots 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(Bundles_client_bundle)
Réponse
application/json
{
  "has_more": true,
  "items": [
    { … }
  ]
}

Lire un lot spécifiqueClient-side

Requête

Récupère des informations sur un lot spécifique.

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
skustringobligatoire

UGS du lot.

Exemple: kg_1
Requête
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
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/bundle/sku/kg_1?promo_code=WINTER2021&show_inactive_time_limited_items=1&additional_fields%5B%5D=media_list' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Réponses

Le lot spécifié a été reçu avec succès.

Corpsapplication/json
attributesArray of objects(Bundles_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"}]}}
bundle_typestring(Bundles_bundle_type)

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.

Par défaut "standard"
Enum"standard""partner_side_content"
Exemple: "standard"
can_be_boughtboolean(Can_be_bought)

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

Exemple: true
contentArray of objects(Bundles_client_content)

Contenu du lot.

Exemple: [{"attributes":[],"description":"Big Rocket - short description.","groups":[],"image_url":"https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png","is_free":false,"name":"Big Rocket","price":{"amount":"10.99","amount_without_discount":"10.99","currency":"USD"},"quantity":100,"sku":"com.xsolla.big_rocket_1","type":"virtual_currency"}]
custom_attributesobject(json)(item-custom-attributes-response)

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

descriptionstring or null(Bundles_client_description)

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 or null(Bundles_image_url)

URL de l'image.

Exemple: "https://image.example.com"
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_idinteger(Bundles_item_id)[ 1 .. 255 ] characters

Internal ID unique de l'objet.

Exemple: 1
limitsobject or null(Catalog_item_limits_with_hourly)

Limites d'objets.

long_description(two-letter (object or null)) or (five-letter (object or null))(long-description-localization-object)

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:

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.

media_listArray of objects(Bundles_media_list)

Ressources supplémentaires du lot.

Exemple: [{"type":"image","url":"https://cdn3.xsolla.com/img/misc/images/71ab1e12126f2103e1868076f0acb21a.jpg"}]
namestring(Bundles_client_name)

Nom de l'objet.

Exemple: "Big Rocket"
orderinteger(Bundles_order)

Ordre de priorité des lots dans la liste.

Par défaut 1
Exemple: 1
periodsArray of objects or null(item-periods)

Période de vente d'objets.

priceobject or null(Bundles_price)

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(Bundles_sku)[ 1 .. 255 ] characters^[a-zA-Z0-9_\-–.]*$

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: "bundle_1"
total_content_priceobject or null(Bundles_total_content_price)

Somme des prix du contenu du lot.

typestring(Bundles_type)

Type d'objet.

Exemple: "bundle"
virtual_pricesArray of objects(Bundles_virtual_prices)

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": [],
  "bundle_type": "standard",
  "can_be_bought": true,
  "content": [
    { … }
  ],
  "custom_attributes": {
    "attr": "value",
    "purchased": 0
  },
  "description": "pricePoint_44056_1.",
  "groups": [],
  "image_url": null,
  "is_free": false,
  "item_id": 610316,
  "limits": {
    "per_user": { … }
  },
  "long_description": null,
  "media_list": [],
  "name": "kg_10.00_bundle",
  "order": 999,
  "periods": [
    { … }
  ],
  "price": {
    "amount": "9.99",
    "amount_without_discount": "9.99",
    "currency": "USD"
  },
  "promotions": [],
  "sku": "com.xsolla.kg_1",
  "total_content_price": {
    "amount": "10.99",
    "amount_without_discount": "10.99",
    "currency": "USD"
  },
  "type": "bundle",
  "virtual_prices": [],
  "vp_rewards": [
    { … },
    { … }
  ]
}

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