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 Get virtual item ou Get all virtual items list.
2. Passez de nouvelles valeurs de paramètres avec la méthode API Update virtual item.

Pour créer un objet virtuel, utilisez la méthode API Create virtual item.

Lots

Pour mettre à jour le catalogue :

1. Récupérez les données du catalogue avec la méthode API Get list of bundles.
2. Passez de nouvelles valeurs de paramètres avec la méthode API Update bundle.

Pour créer un lot, utilisez la méthode API Create bundle.
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 Get list of coupon promotions.
2. Passez les nouvelles valeurs des paramètres à l’aide de la méthode API Update coupon promotion.
3. Activez la promotion à l’aide de la méthode API Activate coupon promotion.

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

Codes promo

Pour mettre à jour la promotion :

1. Récupérez les données du catalogue avec la méthode API Get promo codes promotion ou Get list of promo codes promotions.
2. Passez les nouvelles valeurs des paramètres à l’aide de la méthode API Update promo codes promotion.
3. Activez la promotion à l’aide de la méthode API Activate promo codes promotion.

Pour créer une promotion, utilisez les méthodes API Create promo code promotion, puis Create code for promo code promotion pour créer des codes promotionnels personnalisés ou Generate codes for promo code promotion pour générer des codes promotionnels aléatoires.
Pour désactiver une promotion, utilisez la méthode API Deactivate promo code promotion.

Réductions

Pour mettre à jour la promotion :

1. Récupérez les données du catalogue avec la méthode API Get item promotion ou Get list of item promotions.
2. Passez les nouvelles valeurs des paramètres à l’aide de la méthode API Update item promotion.
3. Activez la promotion à l’aide de la méthode API Activate promotion.

Pour créer une promotion, utilisez la méthode API Create discount promotion for item.
Pour désactiver une promotion, utilisez la méthode API Deactivate promotion.

Bonus

Pour mettre à jour la promotion :

1. Récupérez les données du catalogue avec la méthode API Get bonus promotion ou Get list of bonus promotions.
2. Passez les nouvelles valeurs des paramètres à l’aide de la méthode API Update bonus promotion.
3. Activez la promotion à l’aide de la méthode API Activate promotion.

Pour créer une promotion, utilisez la méthode API Create bonus promotion.
Pour désactiver une promotion, utilisez la méthode API Deactivate 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é :
  • Create virtual item ;
  • Create virtual currency ;
  • Create virtual currency package ;
  • Create bundle.

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 Create virtual item 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 Create virtual item.

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