Автоматическое обновление каталога через API
Вы можете автоматизировать создание и обновление каталога, используя методы In-Game Store API. Благодаря автоматизации вы сможете поддерживать каталог в актуальном состоянии, не тратя на это много времени. Автоматизация каталога позволяет создавать и обновлять товары и акции и импортировать данные из внешних систем.
Это упростит и ускорит работу:
- с каталогом, в котором содержится большое количество товаров;
- большим количеством акций любого типа;
- страноцентричными ценами.
Чтобы поддерживать активность пользователей, важно обеспечивать актуальность каталога товаров на стороне Xsolla после его создания. Мы рекомендуем обновлять каталог на стороне Xsolla при обновлениях на вашей стороне, например при добавлении товаров или изменении цен.
Вы можете:
Методы API создания и обновления товаров и акций требуют базовой аутентификации. Передайте в запросе параметр Authorization:Basic <your_authorization_basic_key>
, где <your_authorization_basic_key>
— пара ID продавца:ключ API, закодированная по стандарту Base64. Значения параметров вы можете найти в Личном кабинете:
- ID продавца указан:
- В разделе Настройки компании > Компания.
- Aдресной строке браузера на любой странице Личного кабинета. URL-адрес имеет вид
https://publisher.xsolla.com/<merchant ID>/<Publisher Account section>
.
- Ключ API отображается в Личном кабинете только при создании и должен храниться на вашей стороне. Создать ключ можно в разделах:
- Настройки компании > Ключи API;
- Настройки проекта > Ключи API.
Создание и обновление товаров
Если вам нужно создать большое количество товаров, вы можете создать скрипт, который вызовет метод API нужного типа товаров необходимое количество раз.
Список параметров, который возвращается в ответе на запрос товаров, отличается от списка параметров, который вам требуется передать при обновлении каталога. Кроме обязательных и обновленных параметров, передайте в методе обновления товаров те параметры, которые вернулись в ответе на запрос товаров.
Пример:
В методе Get virtual items вернулся объект
Виртуальные предметы
Чтобы обновить каталог:
- Получите данные из каталога с помощью методов API Get virtual item или Get all virtual items list.
- Передайте новые значения параметров с помощью метода API Update virtual item.
Чтобы создать виртуальные предметы, воспользуйтесь методом API Create virtual item.
Бандлы
Чтобы обновить каталог:
- Получите данные из каталога с помощью метода API Get list of bundles.
- Передайте новые значения параметров с помощью метода API Update bundle.
Чтобы создать бандл, воспользуйтесь методом API Create bundle.
Если вы хотите добавить в бандлы игровые ключи, региональные ограничения или цены, воспользуйтесь инструкцией.
Создание и обновление акций
Купоны
Чтобы обновить акцию:
- Получите данные из каталога с помощью методов API Get coupon promotion или Get list of coupon promotions.
- Отправьте обновленные значения с помощью метода API Update coupon promotion.
- Активируйте акцию с помощью метода API Activate coupon promotion.
Чтобы создать акцию, воспользуйтесь методами API Create coupon promotion для создания акции, затем Create coupon code для создания собственных кодов купонов или Generate coupon codes для генерации случайных кодов купонов.
Чтобы деактивировать акцию, воспользуйтесь методом API Deactivate coupon promotion.
Промокоды
Чтобы обновить акцию:
- Получите данные из каталога с помощью методов API Get promo codes promotion, или Get list of promo codes promotions.
- Отправьте обновленные значения с помощью метода API Update promo codes promotion.
- Активируйте акцию с помощью метода API Activate coupon promotion.
Чтобы создать акцию, воспользуйтесь методами API Create promo code promotion для создания акции, затем Create code for promo code promotion для создания собственных промокодов или Generate codes for promo code promotion генерации случайных промокодов.
Чтобы деактивировать акцию, воспользуйтесь методом API Deactivate promo code promotion.
Скидки
Чтобы обновить акцию:
- Получите данные из каталога с помощью методов API Get item promotion или Get list of item promotions.
- Отправьте обновленные значения с помощью метода API Update item promotion.
- Активируйте акцию с помощью метода API Activate promotion.
Чтобы создать акцию, воспользуйтесь методом API Create discount promotion for item.
Чтобы деактивировать акцию, воспользуйтесь методом API Deactivate promotion.
Бонусы
Чтобы обновить акцию:
- Получите данные из каталога с помощью методов API Get bonus promotion или Get list of bonus promotions.
- Отправьте обновленные значения с помощью метода API Update bonus promotion.
- Активируйте акцию с помощью метода API Activate promotion.
Чтобы создать акцию, воспользуйтесь методом API Create bonus promotion.
Чтобы деактивировать акцию, воспользуйтесь методом API Deactivate promotion.
Автоматическое создание товаров через API
Если вам нужно создать большое количество товаров на основе данных из вашей системы, вы можете автоматизировать этот процесс с помощью API.
Вам потребуется:
- Выгрузить данные о товарах из вашей системы.
- Преобразовать выгруженные данные в формат, который соответствует формату данных в методе API нужного типа товара.
- Создать скрипт, который для каждого товара в выгрузке вызовет нужный метод API:
- Create virtual item — для виртуальных предметов.
- Create virtual currency — для виртуальной валюты.
- Create virtual currency package — для пакетов виртуальной валюты.
- Create bundle — для бандлов.
Если вы хотите использовать группы товаров, предварительно создайте их через интерфейс Личного кабинета.
Если вы хотите использовать несколько типов товаров, они должны быть созданы в следующем порядке:
- Группы товаров в Личном кабинете.
- Виртуальные валюты.
- Виртуальные предметы.
- Пакеты виртуальной валюты.
- Бандлы.
Далее рассмотрен пример скрипта, который многократно вызывает метод API Create virtual item для создания виртуальных предметов.
Скрипт разработан с применением JavaScript и среды выполнения JavaScript — Node.js.
- Импортируйте функцию
fetch
модуля“node-fetch”
для отправки HTTP-запросов к серверу Xsolla.
- javascript
import fetch from "node-fetch";
- Задайте константы, необходимые для авторизации запросов. Вместо
<your project_id from PA>
и<your api key from PA>
подставьте ваши значения ID проекта и ключа API, которые будут закодированы по стандарту Base64 для последующего использования в API запросах.
- javascript
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')
- Реализуйте вспомогательную функцию
sleep
, которая используется для создания задержки при отправке запросов. Это необходимо для того, чтобы не превышать ограничения частоты запросов к API.
- javascript
function sleep(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
- Реализуйте функцию
getItems
, специфичную для вашей системы, которая позволит получать данные о товарах из вашей системы.
- javascript
async function getItems() {
// receive items from the original system or read from a pre-prepared file
return items;
}
- Реализуйте функцию
prepareData
, специфичную для вашей системы, которая форматирует данные о товарах в соответствии с форматом данных в методе API Create virtual item.
- javascript
function prepareData(items) {
// format items in accordance with API requirements
return formattedItems;
}
- Добавьте функцию
createItem
, которая отправляетPOST
-запрос к Xsolla API для создания виртуального предмета.
- javascript
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),
});
}
- Добавьте функцию
checkItemExist
, которая проверяет, существует ли виртуальный товар с заданным артикулом (SKU). Для этого функция отправляетGET
-запрос к Xsolla API:- Если получен ответ с
404
HTTP-кодом, товар с заданным артикулом не найден, его требуется создать. - Если получен ответ с
200
HTTP-кодом, товар с заданным артикулом найден и его не требуется создавать.
- Если получен ответ с
- javascript
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;
}
- Добавьте функцию
createItems
, которая проходит по списку товаров, и проверяет, есть ли товар с артикулом из вашей системы на стороне Xsolla. Если товара с таким артикулом нет, функция создает его. Информация о прогрессе выводится в консоль.
- javascript
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`);
}
- Добавьте функцию
run
, которая вызывает все вышеперечисленные функции в правильном порядке.
- javascript
async function run() {
const items = await getItems();
const formattedItems = prepareData(items);
await createItems(formattedItems);
}
Полный код:
- javascript
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();
Обновление с помощью импорта из внешних систем
Если вы используете внешние системы PlayFab или Google Play, вы можете импортировать данные из них. Для этого воспользуйтесь инструкцией.Нашли опечатку или ошибку в тексте? Выделите ее и нажмите Ctrl+Enter.