Mise à jour automatique du catalogue via API

Utilisez les appels In-Game Store API pour automatiser la création et la mise à jour du catalogue. Grâce à l’automatisation, vous pouvez maintenir votre catalogue à jour sans y consacrer beaucoup de temps. L’automatisation du catalogue vous permet de créer et de mettre à jour des objets et des promotions et d’importer des données à partir de systèmes externes.

Cela permet de réduire le temps nécessaire à la maintenance et à la mise à jour :

• des catalogues contenant un grand nombre d’objets ;
• des promotions de tout type ;
• des prix par pays.

Une autorisation de base est requise pour utiliser les appels API de création et de mise à jour des objets et des promotions. Passez le code Authorization:Basic <your_authorization_basic_key>, où <your_authorization_basic_key> est la paire merchant ID:API key encodée conformément à la norme Base64. Accédez au Compte éditeur pour trouver les paramètres suivants :

• Merchant ID est affiché :
  • Dans la section Company settings > Company ;
  • Dans l'URL de la barre d'adresse du navigateur sur n'importe quelle page du Compte éditeur. L'URL est au format suivant : https:​//publisher.xsolla.com/<merchant ID>/<Publisher Account section>.

• L'API key ne s'affiche dans le Compte éditeur qu'une seule fois lors de sa création, vous devez donc la conserver de votre côté. Vous pouvez créer une nouvelle clé dans les sections suivantes :
  • Company settings > API keys ;
  • Project settings > API keys.

Créer et mettre à jour des biens

Pour créer de nombreux objets, créez un script qui appelle la méthode API du type d’objet requis le nombre de fois nécessaire.

Objets virtuels

Pour mettre à jour le catalogue :

1. Récupérez les données du catalogue avec la méthode API Lire une liste d’objets virtuels ou Lire la liste de tous les objets virtuels.
2. Passez de nouvelles valeurs de paramètres avec la méthode API Mettre à jour un objet virtuel.

Pour créer un objet virtuel, utilisez la méthode API Créer un objet virtuel.

Lots

Pour mettre à jour le catalogue :

1. Récupérez les données du catalogue avec la méthode API Lire une liste de lots.
2. Passez de nouvelles valeurs de paramètres avec la méthode API Mettre à jour un lot.

Pour créer un lot, utilisez la méthode API Créer un lot.
Si vous souhaitez ajouter des clés de jeu, des restrictions régionales ou des prix par pays aux lots, utilisez les instructions.

Créer et mettre à jour des promotions

Coupons

Pour mettre à jour la promotion :

1. Récupérez les données du catalogue avec la méthode API Get coupon promotion ou Lire la liste des promotions par coupon.
2. Passez les nouvelles valeurs des paramètres à l’aide de la méthode API Mettre à jour une promotion par coupon.
3. Activez la promotion à l’aide de la méthode API Activer une promotion par coupon.

Pour créer une promotion, utilisez les méthodes API Créer une promotion par coupon, puis Créer un code de coupon pour créer des codes de coupon personnalisés ou Générer des codes de coupon pour générer des codes de coupon aléatoires.
Pour désactiver une promotion, utilisez la méthode API Désactiver une promotion par coupon.

Codes promo

Pour mettre à jour la promotion :

1. Récupérez les données du catalogue avec la méthode API Lire une promotion par code promo ou Lire la liste des promotions par code promo.
2. Passez les nouvelles valeurs des paramètres à l’aide de la méthode API Mettre à jour une promotion par code promo.
3. Activez la promotion à l’aide de la méthode API Activer une promotion par code promo.

Pour créer une promotion, utilisez les méthodes API Créer une promotion par code promo, puis Créer un code pour une promotion par code promo pour créer des codes promotionnels personnalisés ou Générer des codes pour une promotion par code promo pour générer des codes promotionnels aléatoires.
Pour désactiver une promotion, utilisez la méthode API Désactiver une promotion par code promo.

Réductions

Pour mettre à jour la promotion :

1. Récupérez les données du catalogue avec la méthode API Lire une promotion sur les objets ou Lire la liste des promotions sur des objets.
2. Passez les nouvelles valeurs des paramètres à l’aide de la méthode API Mettre à jour une promotion sur les objets.
3. Activez la promotion à l’aide de la méthode API Activer une promotion.

Pour créer une promotion, utilisez la méthode API Créer une promotion par réduction pour un objet.
Pour désactiver une promotion, utilisez la méthode API Désactiver une promotion.

Bonus

Pour mettre à jour la promotion :

1. Récupérez les données du catalogue avec la méthode API Lire une promotion par bonus ou Lire la liste des promotions par bonus.
2. Passez les nouvelles valeurs des paramètres à l’aide de la méthode API Mettre à jour une promotion par bonus.
3. Activez la promotion à l’aide de la méthode API Activer une promotion.

Pour créer une promotion, utilisez la méthode API Créer une promotion par bonus.
Pour désactiver une promotion, utilisez la méthode API Désactiver une promotion.

Création automatique des biens via API

Pour créer de nombreux objets sur la base de données de votre système, vous pouvez utiliser l’automatisation à l’aide de l’API.

Vous devez :

• Exporter les données sur les objets depuis votre système.
• Convertir les données exportées dans un format correspondant à celui des données de la méthode API pour le type d’objet requis.
• Créer un script qui appelle la méthode API requise pour chaque objet exporté :
  • Créer un objet virtuel ;
  • Créer une monnaie virtuelle ;
  • Créer un package de monnaie virtuelle ;
  • Créer un lot.

Si vous souhaitez utiliser des groupes d’objets, créez-les à l’avance via l’interface du Compte éditeur.

Si vous souhaitez utiliser plusieurs types d’objets, créez-les dans l’ordre suivant :

1. Groupes d’objets dans le Compte éditeur.
2. Monnaies virtuelles.
3. Objets virtuels.
4. Packages de monnaie virtuelle.
5. Lots.

Voici un exemple de script qui appelle de manière répétée la méthode Créer un objet virtuel pour créer des objets virtuels.

Le script est développé en utilisant JavaScript et le moteur d’exécution JavaScript — Node.js.

1. Importez la fonction fetch du module “node-fetch” pour envoyer des requêtes HTTP au serveur Xsolla.

import fetch from "node-fetch";

2. Définissez les constantes nécessaires à l’autorisation de la requête. Au lieu de <your project_id from PA> et <your api key from PA>, insérez vos valeurs pour l’ID de projet et la clé API, qui seront encodées en Base64 pour une utilisation ultérieure dans les requêtes API.

const projectId = <your project_id from PA>;

const apiKey = <your api key from PA>;

const buff = new Buffer(`${projectId}:${apiKey}`);

const basicAuth = buff.toString('base64')

3. Implémentez la fonction d’aide sleep, qui est utilisée pour créer un délai lors de l’envoi de requêtes. Cela est nécessaire afin de ne pas dépasser les limites de taux des requêtes API.

function sleep(ms) {

   return new Promise(resolve => setTimeout(resolve, ms));

}

4. Implémentez la fonction getItems, spécifique à votre système, pour récupérer les données des objets depuis votre système.

async function getItems() {

   // receive items from the original system or read from a pre-prepared file

   return items;

}

5. Implémentez la fonction prepareData, spécifique à votre système, pour formater les données des objets conformément au format de données dans l’appel API Créer un objet virtuel.

function prepareData(items) {

   // format items in accordance with API requirements

   return formattedItems;

}

6. Ajoutez la fonction createItem, qui envoie une requête POST à l’API Xsolla pour créer un objet virtuel.

async function createItem(item) {

   const url = `https://store.xsolla.com/api/v2/project/${projectId}/admin/items/virtual_items`;



   return await fetch(url, {

       method: "POST",

       headers: {

           Authorization: "Basic " + basicAuth,

           "Content-Type": "application/json"

       },

       body: JSON.stringify(item),

   });

}

7. Ajoutez la fonction checkItemExist, qui vérifie l’existence d’un objet virtuel avec une UGS spécifique. Cette fonction envoie une requête GET à l’API Xsolla :
   • Si la réponse retourne un code HTTP 404, l’objet avec l’UGS spécifiée n’est pas trouvé et doit être créé ;
   • Si la réponse retourne un code HTTP 200, l’objet avec l’UGS spécifiée est trouvé et n’a pas besoin d’être créé.

async function checkItemExist(sku) {

   const url = `https://store.xsolla.com/api/v2/project/${projectId}/admin/items/virtual_items/sku/${sku}`;

   const response = await fetch(url, {

       method: "GET",

       headers: {

           Authorization: "Basic " + basicAuth

       }

   });

   return response.status !== 404;

}

8. Ajoutez la fonction createItems, qui parcourt la liste des objets et vérifie l’existence du côté de Xsolla d’un objet avec une UGS de votre système. Si aucun objet avec une telle UGS n’est trouvé, la fonction le crée. Les informations de progression s’affichent dans la console.

async function createItems(items) {

   let success = 0;

   let alreadyCreated = 0;

   for (let i = 0; i < items.length; i++) {

       const item = items[i];

       if (item['sku'] === undefined) {

           console.log(`${i} Field "sku" not specified`);

           continue;

       }

       const sku = item['sku'];

       if (await checkItemExist(sku)) {

           console.log(`${i} Item with sku "${sku}" already created`);

           alreadyCreated++;

           continue;

       }

       const response = await createItem(item);

       if (response.status === 201) {

           console.log(`${i} Item with sku "${sku}" successfully created`)

           success++;

       } else {

           const jsonData = await response.json();

           console.log(`${i} An error occurred while creating the items with sku "${sku}"`);

           console.log(jsonData);

       }

       // add a delay so as not to run into rate limits

       await sleep(500);

   }

   console.log(`${success} items out of ${items.length} created. ${alreadyCreated} items already existed`);

}

9. Ajouter la fonction run qui appelle toutes les fonctions ci-dessus dans le bon ordre.

async function run() {

 const items = await getItems();

 const formattedItems = prepareData(items);

 await createItems(formattedItems);

}

Le code complet :

import fetch from "node-fetch";

const projectId = <your project_id from PA>;
const apiKey = <your api key from PA>;
const buff = new Buffer(`${projectId}:${apiKey}`);
const basicAuth = buff.toString('base64')

function sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
}

async function getItems() {
    // receive items from the original system or read from a pre-prepared file
    return items;
}

function prepareData(items) {
    // format items in accordance with API requirements
    return formatedItems;
}

async function createItem(item) {
    const url = `https://store.xsolla.com/api/v2/project/${projectId}/admin/items/virtual_items`;

    return await fetch(url, {
        method: "POST",
        headers: {
            Authorization: "Basic " + basicAuth,
            "Content-Type": "application/json"
        },
        body: JSON.stringify(item),
    });
}

async function isItemExisted(sku) {
    const url = `https://store.xsolla.com/api/v2/project/${projectId}/admin/items/virtual_items/sku/${sku}`;
    const response = await fetch(url, {
        method: "GET",
        headers: {
            Authorization: "Basic " + basicAuth
        }
    });
    return response.status !== 404;
}

async function createItems(items) {
    let success = 0;
    let alreadyCreated = 0;
    for (let i = 0; i < items.length; i++) {
        const item = items[i];
        if (item['sku'] === undefined) {
            console.log(`${i} Field "sku" not specified`);
            continue;
        }
        const sku = item['sku'];
        if (await isItemExisted(sku)) {
            console.log(`${i} Item with sku "${sku}" already created`);
            alreadyCreated++;
            continue;
        }
        const response = await createItem(item);
        if (response.status === 201) {
            console.log(`${i} Item with sku "${sku}" successfully created`)
            success++;
        } else {
            const jsonData = await response.json();
            console.log(`${i} An error occurred while creating the items with sku "${sku}"`);
            console.log(jsonData);
        }
        // add a delay so as not to run into rate limits
        await sleep(500);
    }
    console.log(`${success} items out of ${items.length} created. ${alreadyCreated} items already existed`);
}

async function run() {
  const items = await getItems();
  const formattedItems = prepareData(items);
  await createItems(formattedItems);
}

run(); 

Mise à jour par importation à partir de systèmes externes