Passer au contenu
/
Get virtual currency pack...

API Catalog (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.

Authentification

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.

Authentification à l'aide du JWT utilisateur

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.

Authentification HTTP basique

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.

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_key est la paire project_id:api_key encodée en Base64
  • pour basicMerchantAuth — Authorization: Basic <your_authorization_basic_key>, où your_authorization_basic_key est la paire merchant_id:api_key encodée en Base64

Vous trouverez les valeurs des paramètres dans le Compte éditeur :

  • merchant_id s'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_id s'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_key s'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 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.

Authentification avec prise en charge de l'accès invité

Le schéma d’authentification AuthForCart est utilisé pour les achats via le panier et prend en charge deux modes :

  1. Authentification par JWT utilisateur. Le jeton est passé 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.

  2. 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-id avec un identifiant de requête
    • x-user avec l'adresse e-mail de l'utilisateur encodée en Base64

Structure de l'entité principale

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.

Identification

  • merchant_id — ID de l'entreprise dans le Compte éditeur
  • project_id — ID de projet dans le Compte éditeur
  • sku — UGS de l'objet, unique au sein du projet

Affichage en magasin

  • name — nom de l'objet
  • description — description de l'objet
  • image_url — URL de l'image
  • is_enabled — disponibilité de l'objet
  • is_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 appartient
  • order — ordre d'affichage dans le catalogue

Conditions de vente

  • prices — prix en devise réelle ou monnaie virtuelle
  • limits — limites d'achat
  • periods — 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": []
}

Processus d'achat de base

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éation d'objets et de groupes (Administrateur)

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 :

Configuration de promotions, chaînes et limites (Administrateur)

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 :

Récupération d'informations sur un objet (Client)

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.

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 "show_inactive_time_limited_items": 1 dans la requête du catalogue.

Vente des objets

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.

Achat rapide

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.

Achat via le panier

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 :

  1. 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).
  2. Mettez à jour le contenu du panier en fonction des actions utilisateur :
Note

Pour obtenir le statut actuel du panier, utilisez l'appel API Lire le panier de l'utilisateur actuel.
  1. 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 new par 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 :

  1. 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).
  2. 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 new par défaut.

Ouverture de l'interface de paiement

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.

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

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éée
  • paid — paiement reçu
  • done — objet attribué
  • canceled — commande annulée
  • expired — commande expirée

Suivez le statut de la commande en utilisant l'une des méthodes suivantes :

Pagination

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 page
  • offset — indice du premier objet sur la page (la numérotation commence à 0)
  • has_more — indique si une autre page est disponible
  • total_items_count — nombre total d'objets

Exemple de requête :

GET /items?limit=20&offset=40

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

Format de date et d'heure

Les dates et les valeurs temporelles sont transmises au format ISO 8601.

Les valeurs suivantes sont prises en charge :

  • Décalage UTC
  • Valeur null lorsqu'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

Localisation

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 :

  • name
  • description
  • long_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"
  }
}

Format de réponse d'erreur

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 valide
  • 401 — erreur d'authentification
  • 403 — permissions insuffisantes
  • 404 — ressource non trouvée
  • 422 — erreur de validation
  • 429 — limite de taux dépassée

Recommandations

  • Gérez ensemble le statut HTTP et le corps de la réponse.
  • Utilisez errorCode pour traiter les erreurs liées à la logique de l'application.
  • Utilisez transactionId pour identifier plus rapidement les requêtes lors de l'analyse des erreurs.
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/

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.

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.

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 :

Exemple de processus d'achat avec de la monnaie virtuelle

Administrateur

Opérations

Catalogue

Opérations

Get virtual currency list by specified groupClient-side

Requête

Retrieves a list of virtual currencies from the specified group for building a catalog.

Attention

Tous les projets sont soumis à une limite de nombre d'objets pouvant être retourné dans une réponse. La valeur par défaut et maximale est de 50 objets par réponse. Pour récupérer davantage de données page par page, utilisez les champs limit et offset.

Note

Cet appel API renvoie des données génériques du catalogue des objets lorsqu'il est utilisé sans autorisation. Utilisez l'autorisation pour récupérer des données utilisateur personnalisées, telles que les limites et les promotions associées à l'objet. Pour ce faire, passez le JWT utilisateur dans l'en-tête Authorization. Pour plus d'informations sur le JWT utilisateur, consultez le bloc Security pour cet appel.
Sécurité
XsollaLoginUserJWT
Chemin
project_idintegerobligatoire

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
external_idstringobligatoire

External item group ID specified during creation.

Exemple: weapons
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 ISO 639-1 à deux lettres en minuscules (par exemple, en). Les codes régionaux à cinq caractères (par exemple, en-US) sont pris en charge dans les champs localisables tels que name et description, mais sont normalisés en codes à deux lettres dans les réponses. La liste complète des langues prises en charge est disponible dans la documentation.

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

Champs supplémentaires à inclure dans la réponse. Par défaut, ces champs ne sont pas renvoyés. Passez les valeurs requises pour les inclure.

É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_currency/group/weapons?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

The list of virtual currency from the specified group was successfully received.

Corpsapplication/json
has_moreboolean

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

itemsArray of objects
items[].​item_idinteger

Unique item ID assigned by Xsolla.

items[].​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: "crystal"
items[].​namestring

Nom de l'objet.

Exemple: "Crystals"
items[].​groupsArray of objects

Groupes auxquels l'objet appartient.

items[].​groups[].​external_idstring

External item group ID specified during creation.

Exemple: "exclusive"
items[].​groups[].​namestring

Nom du groupe.

Exemple: "Exclusive"
items[].​groups[].​item_order_in_groupinteger

The item's position within the group that determines its display order. Returned only if requested via the additional_fields[] query parameter.

Exemple: 1
items[].​attributesArray of objects

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

items[].​attributes[].​external_idstring[ 1 .. 255 ] characters^[a-zA-Z0-9-_]+$

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.

items[].​attributes[].​nameobject

Nom de l'attribut.

Exemple: "Genre"
items[].​attributes[].​name.​property name*string or nullpropriété supplémentaire
items[].​attributes[].​valuesArray of objects
items[].​attributes[].​values[].​external_idstring[ 1 .. 255 ] characters^[-_.\d\w]+$

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.

items[].​attributes[].​values[].​valuestring

Valeur de l'attribut.

Exemple: "Strategy"
items[].​typestring

Type d'objet : virtual_good/virtual_currency/bundle.

Exemple: "virtual_currency"
items[].​descriptionstring

Description de l'objet.

Exemple: "Crystals - description"
items[].​image_urlstring

URL de l'image.

Exemple: "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png"
items[].​is_freeboolean

Détermine la gratuité de l'objet.

items[].​priceobject or null

Prix de l'objet.

items[].​price.​amountstring

Prix de l'objet avec remise.

Exemple: "100.99"
items[].​price.​amount_without_discountstring

Prix de l'objet.

Exemple: "100.99"
items[].​price.​currencystring

Devise du prix de l'objet. Code à trois lettres selon ISO 4217. Consultez la documentation pour obtenir des informations détaillées sur les devises prises en charge par Xsolla.

Exemple: "USD"
items[].​virtual_pricesArray of objects

Prix virtuels.

Exemple: [{"amount":100,"sku":"com.xsolla.crystals_1","is_default":true,"amount_without_discount":100,"image_url":"http://image.png"}]
items[].​virtual_prices[].​amountinteger

Prix de l'objet en monnaie virtuelle.

Exemple: 100
items[].​virtual_prices[].​amount_without_discountinteger

Prix de l'objet en monnaie virtuelle, hors remise. Il correspond toujours à amount, car les remises ne s'appliquent pas aux prix en monnaie virtuelle.

Exemple: 200
items[].​virtual_prices[].​skustring

UGS de la monnaie virtuelle.

Exemple: "vc_gold"
items[].​virtual_prices[].​is_defaultboolean

Détermine s'il s'agit du prix par défaut en monnaie virtuelle.

Exemple: true
items[].​virtual_prices[].​image_urlstring or null

URL de l'image de la monnaie virtuelle.

Exemple: "http://image.png"
items[].​virtual_prices[].​namestring

Nom de la monnaie virtuelle.

Exemple: "Gold"
items[].​virtual_prices[].​typestring

Type d'objet. Pour la monnaie virtuelle, il s'agit de virtual_currency.

Exemple: "virtual_currency"
items[].​virtual_prices[].​descriptionstring or null

Virtual currency description.

Exemple: "In-game currency used to purchase weapons and upgrades"
items[].​can_be_boughtboolean

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

items[].​promotionsArray of objects

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

items[].​promotions[].​namestring
items[].​promotions[].​date_startstring or null(date-time)
items[].​promotions[].​date_endstring or null(date-time)
items[].​promotions[].​discountobject or null
items[].​promotions[].​discount.​percentstring or null
items[].​promotions[].​discount.​valuestring or null
items[].​promotions[].​bonusArray of objects
items[].​promotions[].​bonus[].​skustring
items[].​promotions[].​bonus[].​quantityinteger
items[].​promotions[].​bonus[].​typestring

Type d'objet bonus.

Enum"virtual_good""virtual_currency""bundle""physical_good""game_key""nft"
items[].​promotions[].​bonus[].​namestring

Nom de l'objet bonus. Non disponible pour le type d'objet bonus physical_good.

items[].​promotions[].​bonus[].​image_urlstring

URL de l'image de l'objet bonus. Non disponible pour le type d'objet bonus physical_good.

items[].​promotions[].​bonus[].​bundle_typestring

Type de lot bonus. Disponible uniquement pour le type d'objet bundle.

Enum"standard""virtual_currency_package"
items[].​promotions[].​limitsobject
items[].​promotions[].​limits.​per_userobject
items[].​promotions[].​limits.​per_user.​availableinteger
items[].​promotions[].​limits.​per_user.​totalinteger
items[].​limitsobject or null

Limites d'objets.

items[].​limits.​per_userobject or null

Limites d'objets pour un utilisateur.

items[].​limits.​per_user.​totalinteger

Nombre maximal d'objets qu'un utilisateur unique peut acheter.

Exemple: 5
items[].​limits.​per_user.​availableinteger

Nombre d'objets restants que l'utilisateur actuel peut acheter.

Exemple: 3
items[].​limits.​per_user.​recurrent_schedule(object or null)
One of:

Délai d'actualisation récurrent des limites d'un objet pour un utilisateur.

object or null
items[].​limits.​per_user.​limit_exceeded_visibilitystring

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'indicateur can_be_bought: false. La prochaine date de réinitialisation est renvoyée dans reset_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"
items[].​limits.​per_itemobject or null

Informations sur les limites pour un objet.

items[].​limits.​per_item.​totalinteger

Nombre maximal d'objets que tous les utilisateurs peuvent acheter.

Exemple: 5
items[].​limits.​per_item.​availableinteger

Nombre d'objets restants que tous les utilisateurs peuvent acheter.

Exemple: 3
items[].​periodsArray of objects

Période de vente d'objets.

items[].​periods[].​date_fromstring or null(date-time)

Date de mise en vente de l'objet spécifié.

Exemple: "2020-08-11T10:00:00+03:00"
items[].​periods[].​date_untilstring or null(date-time)

Date de retrait de la vente de l'objet spécifié. Peut prendre la valeur null.

Exemple: "2020-08-11T20:00:00+03:00"
items[].​custom_attributesobject(json)

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

items[].​vp_rewardsArray of objects

List of value point rewards for the item.

items[].​vp_rewards[].​item_idinteger

Internal ID unique de l'objet.

items[].​vp_rewards[].​skustring

ID unique du point de valeur.

items[].​vp_rewards[].​amountinteger

Montant des points de valeur.

items[].​vp_rewards[].​namestring

Nom du point de valeur.

items[].​vp_rewards[].​image_urlstring

URL de l'image.

items[].​vp_rewards[].​is_clanboolean

Détermine l'utilisation du point de valeur dans les chaînes de récompense de clan.

Réponse
application/json
{
  "has_more": false,
  "items": [
    { … },
    { … }
  ]
}

Get virtual currency package list by specified groupClient-side

Requête

Retrieves a list of virtual currency packages from the specified group for building a catalog.

Attention

Tous les projets sont soumis à une limite de nombre d'objets pouvant être retourné dans une réponse. La valeur par défaut et maximale est de 50 objets par réponse. Pour récupérer davantage de données page par page, utilisez les champs limit et offset.

Note

Cet appel API renvoie des données génériques du catalogue des objets lorsqu'il est utilisé sans autorisation. Utilisez l'autorisation pour récupérer des données utilisateur personnalisées, telles que les limites et les promotions associées à l'objet. Pour ce faire, passez le JWT utilisateur dans l'en-tête Authorization. Pour plus d'informations sur le JWT utilisateur, consultez le bloc Security pour cet appel.
Sécurité
XsollaLoginUserJWT
Chemin
project_idintegerobligatoire

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
external_idstringobligatoire

External item group ID specified during creation.

Exemple: weapons
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 ISO 639-1 à deux lettres en minuscules (par exemple, en). Les codes régionaux à cinq caractères (par exemple, en-US) sont pris en charge dans les champs localisables tels que name et description, mais sont normalisés en codes à deux lettres dans les réponses. La liste complète des langues prises en charge est disponible dans la documentation.

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

Champs supplémentaires à inclure dans la réponse. Par défaut, ces champs ne sont pas renvoyés. Passez les valeurs requises pour les inclure.

É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_currency/package/group/weapons?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

The list of virtual currency packages from the specified group was successfully received.

Corpsapplication/json
has_moreboolean

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

itemsArray of objects
items[].​item_idinteger

Unique item ID assigned by Xsolla.

items[].​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: "crystal-pack"
items[].​namestring

Nom de l'objet.

Exemple: "Crystal Pack"
items[].​groupsArray of objects

Groupes auxquels l'objet appartient.

items[].​groups[].​external_idstring

External item group ID specified during creation.

Exemple: "exclusive"
items[].​groups[].​namestring

Nom du groupe.

Exemple: "Exclusive"
items[].​groups[].​item_order_in_groupinteger

The item's position within the group that determines its display order. Returned only if requested via the additional_fields[] query parameter.

Exemple: 1
items[].​attributesArray of objects

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

items[].​attributes[].​external_idstring[ 1 .. 255 ] characters^[a-zA-Z0-9-_]+$

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.

items[].​attributes[].​nameobject

Nom de l'attribut.

Exemple: "Genre"
items[].​attributes[].​name.​property name*string or nullpropriété supplémentaire
items[].​attributes[].​valuesArray of objects
items[].​attributes[].​values[].​external_idstring[ 1 .. 255 ] characters^[-_.\d\w]+$

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.

items[].​attributes[].​values[].​valuestring

Valeur de l'attribut.

Exemple: "Strategy"
items[].​typestring

Type d'objet : virtual_good/virtual_currency/bundle.

Exemple: "bundle"
items[].​bundle_typestring

Bundle type. Always virtual_currency_package for virtual currency packages.

Exemple: "virtual_currency_package"
items[].​descriptionstring

Description de l'objet.

Exemple: "Crystal Pack Description"
items[].​image_urlstring

URL de l'image.

Exemple: "https://cdn.xsolla.net/items/crystal-pack.png"
items[].​is_freeboolean

Détermine la gratuité de l'objet.

items[].​priceobject

Prix de l'objet.

items[].​price.​amountstring

Prix de l'objet avec remise.

Exemple: "100.99"
items[].​price.​amount_without_discountstring

Item price without discount.

Exemple: "100.99"
items[].​price.​currencystring

Devise du prix de l'objet. Code à trois lettres selon ISO 4217. Consultez la documentation pour obtenir des informations détaillées sur les devises prises en charge par Xsolla.

Exemple: "USD"
items[].​virtual_pricesArray of objects

Prix virtuels.

items[].​virtual_prices[].​amountinteger

Prix de l'objet en monnaie virtuelle.

Exemple: 100
items[].​virtual_prices[].​amount_without_discountinteger

Prix de l'objet en monnaie virtuelle, hors remise. Il correspond toujours à amount, car les remises ne s'appliquent pas aux prix en monnaie virtuelle.

Exemple: 200
items[].​virtual_prices[].​skustring

UGS de la monnaie virtuelle.

Exemple: "vc_gold"
items[].​virtual_prices[].​is_defaultboolean

Détermine s'il s'agit du prix par défaut en monnaie virtuelle.

Exemple: true
items[].​virtual_prices[].​image_urlstring or null

URL de l'image de la monnaie virtuelle.

Exemple: "http://image.png"
items[].​virtual_prices[].​namestring

Nom de la monnaie virtuelle.

Exemple: "Gold"
items[].​virtual_prices[].​typestring

Type d'objet. Pour la monnaie virtuelle, il s'agit de virtual_currency.

Exemple: "virtual_currency"
items[].​virtual_prices[].​descriptionstring or null

Virtual currency description.

Exemple: "In-game currency used to purchase weapons and upgrades"
items[].​can_be_boughtboolean

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

items[].​contentArray of objects

Contenu du package de monnaie virtuelle.

Exemple: [{"description":"Crystal - short description","image_url":"https://cdn.xsolla.net/items/crystal-pack.png","sku":"com.xsolla.crystal_1","name":"Crystals","type":"virtual_currency","quantity":100}]
items[].​content[].​item_idinteger

Unique item ID assigned by Xsolla.

items[].​content[].​skustring

ID unique de l'objet. L'UGS ne peut comprendre que des caractères alphanumériques latins minuscules et majuscules, des tirets et des traits bas.

Exemple: "com.xsolla.crystal_1"
items[].​content[].​namestring

Nom de l'objet.

Exemple: "Crystals"
items[].​content[].​typestring

Type d'objet. Pour la monnaie virtuelle, il s'agit de virtual_currency.

Exemple: "virtual_currency"
items[].​content[].​descriptionstring

Description de l'objet.

Exemple: "Crystals - description"
items[].​content[].​image_urlstring

URL de l'image.

Exemple: "https://cdn.xsolla.net/items/crystal-pack.png"
items[].​content[].​quantityinteger

Quantité de la monnaie virtuelle dans le package.

Exemple: 250
items[].​content[].​limitsobject or null

Limites d'objets.

items[].​content[].​limits.​per_userobject or null

Limites d'objets pour un utilisateur.

items[].​content[].​limits.​per_user.​totalinteger

Nombre maximal d'objets qu'un utilisateur unique peut acheter.

Exemple: 5
items[].​content[].​limits.​per_user.​availableinteger

Nombre d'objets restants que l'utilisateur actuel peut acheter.

Exemple: 3
items[].​content[].​limits.​per_user.​recurrent_schedule(object or null)
One of:

Délai d'actualisation récurrent des limites d'un objet pour un utilisateur.

object or null
items[].​content[].​limits.​per_user.​limit_exceeded_visibilitystring

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'indicateur can_be_bought: false. La prochaine date de réinitialisation est renvoyée dans reset_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"
items[].​content[].​limits.​per_itemobject or null

Informations sur les limites pour un objet.

items[].​content[].​limits.​per_item.​totalinteger

Nombre maximal d'objets que tous les utilisateurs peuvent acheter.

Exemple: 5
items[].​content[].​limits.​per_item.​availableinteger

Nombre d'objets restants que tous les utilisateurs peuvent acheter.

Exemple: 3
items[].​promotionsArray of objects

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

items[].​promotions[].​namestring
items[].​promotions[].​date_startstring or null(date-time)
items[].​promotions[].​date_endstring or null(date-time)
items[].​promotions[].​discountobject or null
items[].​promotions[].​discount.​percentstring or null
items[].​promotions[].​discount.​valuestring or null
items[].​promotions[].​bonusArray of objects
items[].​promotions[].​bonus[].​skustring
items[].​promotions[].​bonus[].​quantityinteger
items[].​promotions[].​bonus[].​typestring

Type d'objet bonus.

Enum"virtual_good""virtual_currency""bundle""physical_good""game_key""nft"
items[].​promotions[].​bonus[].​namestring

Nom de l'objet bonus. Non disponible pour le type d'objet bonus physical_good.

items[].​promotions[].​bonus[].​image_urlstring

URL de l'image de l'objet bonus. Non disponible pour le type d'objet bonus physical_good.

items[].​promotions[].​bonus[].​bundle_typestring

Type de lot bonus. Disponible uniquement pour le type d'objet bundle.

Enum"standard""virtual_currency_package"
items[].​promotions[].​limitsobject
items[].​promotions[].​limits.​per_userobject
items[].​promotions[].​limits.​per_user.​availableinteger
items[].​promotions[].​limits.​per_user.​totalinteger
items[].​limitsobject or null

Limites d'objets.

items[].​limits.​per_userobject or null

Limites d'objets pour un utilisateur.

items[].​limits.​per_user.​totalinteger

Nombre maximal d'objets qu'un utilisateur unique peut acheter.

Exemple: 5
items[].​limits.​per_user.​availableinteger

Nombre d'objets restants que l'utilisateur actuel peut acheter.

Exemple: 3
items[].​limits.​per_user.​recurrent_schedule(object or null)
One of:

Délai d'actualisation récurrent des limites d'un objet pour un utilisateur.

object or null
items[].​limits.​per_user.​limit_exceeded_visibilitystring

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'indicateur can_be_bought: false. La prochaine date de réinitialisation est renvoyée dans reset_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"
items[].​limits.​per_itemobject or null

Informations sur les limites pour un objet.

items[].​limits.​per_item.​totalinteger

Nombre maximal d'objets que tous les utilisateurs peuvent acheter.

Exemple: 5
items[].​limits.​per_item.​availableinteger

Nombre d'objets restants que tous les utilisateurs peuvent acheter.

Exemple: 3
items[].​periodsArray of objects

Période de vente d'objets.

items[].​periods[].​date_fromstring or null(date-time)

Date de mise en vente de l'objet spécifié.

Exemple: "2020-08-11T10:00:00+03:00"
items[].​periods[].​date_untilstring or null(date-time)

Date de retrait de la vente de l'objet spécifié. Peut prendre la valeur null.

Exemple: "2020-08-11T20:00:00+03:00"
items[].​custom_attributesobject(json)

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

items[].​vp_rewardsArray of objects

List of value point rewards for the item.

items[].​vp_rewards[].​item_idinteger

Internal ID unique de l'objet.

items[].​vp_rewards[].​skustring

ID unique du point de valeur.

items[].​vp_rewards[].​amountinteger

Montant des points de valeur.

items[].​vp_rewards[].​namestring

Nom du point de valeur.

items[].​vp_rewards[].​image_urlstring

URL de l'image.

items[].​vp_rewards[].​is_clanboolean

Détermine l'utilisation du point de valeur dans les chaînes de récompense de clan.

Réponse
application/json
{
  "has_more": false,
  "items": [
    { … },
    { … }
  ]
}

Paiement virtuel

Opérations

Aperçu

Les clés de jeu sont des codes alphanumériques uniques à usage unique permettant d’accéder à un jeu ou à un contenu téléchargeable (DLC) sur les plateformes de jeux vidéo. Vous pouvez vendre des clés de jeu via un lien direct, via l'interface du magasin, ou via un widget. Vous pouvez également configurer des restrictions régionales afin de vendre les clés de jeu dans des pays spécifiques. Pour plus d'informations, consultez la section Packs de clés de jeux.

L'authentification utilisateur n'est pas requise pour vendre des clés de jeu : elles sont envoyées à l'adresse e-mail fournie lors du paiement. Vous pouvez toutefois la configurer pour accéder à des fonctionnalités comme la personnalisation, les limites d'achat ou le système des droits. Pour en savoir plus, consultez la section Comment configurer l'authentification pour la vente de clés de jeu.

Flux de vente de clés de jeux :

  1. Créez un jeu en utilisant l'appel API Créer un jeu.
  2. Configurez les restrictions régionales.
  3. Téléchargez des clés dans un package de clés de jeu en utilisant l'appel API Télécharger des codes afin de les proposer à la vente.
  4. Affichez le catalogue des jeux avec les prix correspondant à la région de l'utilisateur à l'aide de l'appel API Lire la liste des jeux.
  5. Créez une commande. Pour un achat rapide, utilisez l'appel API Créer une commande à partir de tous les objets du panier actuel, en passant l'UGS de la clé de jeu. La réponse renvoie un jeton permettant d'ouvrir l'interface de paiement.
  6. Implémentez l'ouverture de l'interface de paiement afin de régler la commande.

Pour recevoir des notifications en temps réel sur les paiements réussis et l'attribution des objets à l'utilisateur, configurez le suivi du statut des commandes, par exemple via les webhooks. Les clés sont envoyées à l'adresse e-mail indiquée lors du paiement, et la commande passe au statut done.

Clés de jeu

Catalogue

Opérations

Droit

Opérations

Administrateur

Opérations

Aperçu

Les lots sont des ensembles d'objets vendus comme une seule unité. Un lot peut inclure des objets virtuels, de la monnaie virtuelle, des packages de monnaie virtuelle, des clés de jeu et d'autres lots. Utilisez les lots pour créer des kits de démarrage, des offres saisonnières et des offres spéciales.

Utilisez les groupes d'appels API suivants pour interagir avec les lots :

  • Utilisez des appels API de la sous-section Administrateur pour créer, mettre à jour, supprimer des lots, et gérer leur visibilité.
  • Utilisez des appels API de la sous-section Catalogue pour récupérer des lots.

Les limites d'achat sont configurées via l'objet limits lors de la création ou de la mise à jour d'un lot. Pour en savoir plus, consultez l'aperçu des Limites. Vous pouvez également configurer des restrictions régionales afin de vendre des objets dans des pays spécifiques.

Note

Pour en savoir plus sur la configuration des lots, consultez la section Lots.

Scénario de gestion de lot :

  1. Créez un lot en utilisant l'appel API Créer un lot. Pour vérifier le lot créé, utilisez l'appel API Lire un lot. Pour récupérer tous les lots du projet, utilisez l'appel API Lire la liste des lots.
  2. Si nécessaire, utilisez l'appel API Mettre à jour un lot pour modifier le contenu ou les paramètres du lot.
  3. Implémentez la logique d'affichage des lots dans votre vitrine en utilisant l'appel API Lire la liste des lots, Lire un lot spécifique, ou Lire la liste des lots par groupe spécifique.
  4. Créez une commande en utilisant la section Panier et paiement. Par exemple, pour un achat rapide, vous pouvez utiliser l'appel API Créer une commande à partir d'un objet spécifique, en passant l'UGS du lot. La réponse contient un jeton pour ouvrir l'interface de paiement.
  5. Implémentez l'ouverture de l'interface de paiement pour payer la commande.
  6. Configurez le suivi du statut de la commande, par exemple en utilisant des webhooks, pour recevoir rapidement des données sur les objets payés avec succès et les attribuer à l'utilisateur.

Scénario de gestion de lot

Administrateur

Opérations

Catalogue

Opérations

Aperçu

Le panier est un mécanisme d'achat qui permet de regrouper plusieurs objets dans une seule commande. Un utilisateur peut acheter des objets de tout type et en toute quantité avec de la devise réelle, ainsi qu'utiliser des codes promo.

Le panier est stocké côté Xsolla. Sa sauvegarde d'une session à une autre dépend de l'authentification :

  • pour les utilisateurs authentifiés, le panier est lié à un utilisateur et conservé entre les sessions tant que les requêtes sont effectuées au nom de ce même utilisateur.

  • Pour les utilisateurs non authentifiés, la sauvegarde du panier dépend de la transmission de l'en-tête x-unauthorized-id. Pour conserver le panier d'un utilisateur non authentifié d'une session à l'autre, passez le même x-unauthorized-id dans chaque requête. Cette option est disponible uniquement pour la vente de clés de jeu.

Vous pouvez identifier le panier de deux façons : automatiquement via le JWT utilisateur ou via l'ID du panier (cart_id).

La gestion du panier est disponible à la fois côté client et côté serveur.

Côté serveur, vous pouvez remplir le panier avec des objets, par exemple lors de la restauration d'une session utilisateur. Les actions suivantes sont disponibles côté client :

  • récupérer le panier de l'utilisateur actuel ou un panier par ID
  • remplir le panier
  • mettre à jour les objets dans le panier
  • supprimer des objets du panier

Pour acheter des objets du panier, les appels client et serveur servent à créer une commande.

La durée de vie (TTL) du panier est de 72 heures par défaut. Si son contenu change, par exemple lorsqu'un nouvel objet est ajouté, la TTL est prolongée.

Après un paiement réussi, le panier n'est pas vidé automatiquement. Pour le vider, utilisez les appels API côté client suivants :

Scénario d'utilisation du panier :

  1. Implémentez une interface de magasin permettant à l'utilisateur de sélectionner des objets.

  2. Lorsque l'utilisateur sélectionne des objets dans le magasin, ajoutez-les au panier, par exemple via l'appel Remplir le panier d'objets. Dans le tableau des objets, indiquez les UGS et les quantités requises pour chaque objet.

  3. Implémentez l'interface du panier. Lors de l'accès au panier, affichez son contenu via l'appel Lire le panier de l'utilisateur actuel. La réponse inclut des informations sur le prix final de l'objet, avec remises et promotions appliquées.

  4. Implémentez l'ouverture de l'interface de paiement pour régler la commande. Vous pouvez, par exemple, utiliser l'appel Créer une commande à partir de tous les objets d'un panier spécifique. La réponse renvoie un jeton permettant d'ouvrir l'interface de paiement.

  5. Configurez le suivi du statut des commandes, par exemple à l'aide des webhooks, afin de recevoir rapidement les informations sur les objets payés avec succès et de les attribuer à l'utilisateur.

Note

Pour implémenter la vente d'objets en jeu et en ligne, consultez le guide d'intégration.

Flux de panier et de paiement

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 :

StatutDescriptionNotes
newCommande créée. Le système attend la confirmation du paiement..Les descriptions des statuts de transaction se trouvent dans la documentation Pay Station API.
paidCommande 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é.
doneObjet attribué à l'utilisateur. —
canceledPaiement 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.

Cycle de vie d'une commande

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.

Panier (côté client)

Utilisez les appels de cette section pour gérer le panier côté client.

Opérations

Panier (côté serveur)

Utilisez les appels de cette section pour gérer le panier côté serveur.

Opérations

Paiement (côté client)

Utilisez les appels de cette section pour créer un jeton de paiement côté client.

Opérations

Paiement (côté serveur)

Utilisez les appels de cette section pour créer un jeton de paiement côté serveur.

Opérations

Commande

Utilisez les appels de cette section pour obtenir des informations sur les commandes.

Opérations

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 :

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 :

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.

Gestion

Opérations

Administrateur

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

Administrateur

Opérations

Catalogue

Opérations