Importar catálogo
Crear y actualizar un catálogo de artículos mediante la importación de JSON
Puede crear, actualizar o desactivar artículos utilizando la importación desde un archivo JSON.
Con esta herramienta, puede hacer lo siguiente:
Características:
- Compatibilidad con los siguientes tipos de artículos:
- artículos virtuales
- moneda virtual
- paquetes de moneda virtual
- lotes
- Validación de datos. Si la estructura del archivo o el formato de datos no cumple los requisitos, podrá ver una lista de errores al hacer la importación.
Limitaciones:
- La importación no está disponible para claves del juego, promociones y sistemas de recompensas.
- El tamaño del archivo JSON cargado no debe superar los 7 MB.
- El formato de los parámetros presentes en el archivo JSON debe coincidir con el formato especificado en el correspondiente método de creación de productos:
Importación del catálogo de artículos
Para importar un artículo o catálogo de artículos de un archivo JSON:
- Abra el proyecto en Cuenta del editor.
- En el menú lateral, haga clic en Store y vaya a la sección Virtual currency, Virtual items o Bundles.
- Haga clic en Import items.
- Escoja la acción:
- Agregar nuevos artículos - solamente se agregarán artículos con nuevos códigos de artículo (SKU).
- Agregar nuevos artículos y actualizar los existentes - se agregarán artículos con nuevos SKU y se actualizarán los datos de los artículos existentes.
- Agregar los nuevos, actualizar los existentes, deshabilitar los artículos que faltan - se agregarán/actualizarán los artículos con SKU del archivo. Si hay un artículo en el catálogo, pero no existe el correspondiente SKU en el archivo, el estado del artículo en Cuenta del editor cambiará a Partially available - el artículo no puede comprarse por separado, pero está disponible como parte de un lote o bonificación.
- Rellene el archivo para la importación:
- Descargue la plantilla del archivo en la ventana de descargas y rellénela siguiendo el ejemplo que aparece a continuación.
- Exporte los elementos y utilice el archivo exportado como plantilla.
- Cree su propio archivo JSON y rellénelo según el ejemplo que aparece abajo.
Un ejemplo de archivo JSON completo:
- json
{
"virtual_currency": [
{
"sku": "Gem_test_import",
"name": {
"en": "Gem_test_import"
},
"type": "virtual_currency",
"description": {
"en": "my test imported currency"
},
"image_url": "https://cdn3.xsolla.com/img/misc/merchant/default-dc-image.png",
"description": {
"en": "my test imported currency",
"de": "meine importierte Testwährung"
},
"attributes": [],
"is_free": false,
"order": 1,
"groups": [],
"regional_prices": [],
"prices": [
{
"amount": 2,
"currency": "USD",
"is_default": true,
"is_enabled": true
}
],
"media_list": [],
"vc_prices": [],
"is_enabled": true,
"is_show_in_store": true,
"regions": [],
"limits": {
"per_user": null,
"per_item": null,
"recurrent_schedule": null
},
"periods": [],
"inventory_options": {
"consumable": true,
"expiration_period": null
},
"is_hard": false
}
],
"virtual_items": [
{
"sku": "event_access_test_import",
"name": {
"en": "Special Event Access_test_import"
},
"type": "virtual_good",
"description": {
"en": "Get special event access as a bonus only on your first purchase. Find the right doggy at the Robo-Dog Exhibition!"
},
"image_url": "https://cdn3.xsolla.com/img/misc/images/1e3ef1a96cc9dd8d98bc124d5d6fad79.png",
"long_description": null,
"attributes": [],
"is_free": false,
"order": 1,
"groups": [
"my_test_group"
],
"regional_prices": [],
"prices": [
{
"amount": 35,
"currency": "USD",
"is_default": true,
"is_enabled": true
}
],
"media_list": [],
"vc_prices": [],
"is_enabled": true,
"is_show_in_store": true,
"regions": [],
"limits": {
"per_user": null,
"per_item": null,
"recurrent_schedule": null
},
"periods": [],
"inventory_options": {
"consumable": true,
"expiration_period": null
}
}
],
"virtual_currency_packages": [
{
"item_id": 441982,
"sku": "small_gold_pack_test_import",
"type": "bundle",
"name": {
"en": "Small gold pack"
},
"bundle_type": "virtual_currency_package",
"description": {
"en": "Gold x100"
},
"image_url": "https://cdn3.xsolla.com/img/misc/images/ba43c46ea75fd5713c210f5736993a92.png",
"vc_prices": [],
"regional_prices": [],
"prices": [
{
"amount": 5,
"currency": "USD",
"is_default": true,
"is_enabled": true
}
],
"is_enabled": true,
"is_show_in_store": true,
"regions": [],
"limits": {
"per_user": null,
"per_item": null,
"recurrent_schedule": null
},
"periods": [],
"attributes": [],
"long_description": null,
"media_list": [],
"order": 100000000,
"is_free": false,
"groups": [],
"content": [
{
"sku": "Gem_test_import",
"quantity": 100
}
]
}
],
"bundles": [
{
"item_id": 684024,
"sku": "start_pack_test_import_test_import",
"type": "bundle",
"name": {
"en": "Legendary Start Pack"
},
"bundle_type": "standard",
"description": {
"en": "Crystal x 1\nGem x 1"
},
"image_url": "https://cdn3.xsolla.com/img/misc/merchant/default-dc-image.png",
"regional_prices": [],
"prices": [
{
"amount": 20,
"currency": "USD",
"is_default": true,
"is_enabled": true
}
],
"virtual_prices": [],
"is_enabled": true,
"is_show_in_store": true,
"regions": [],
"limits": {
"per_user": null,
"per_item": null,
"recurrent_schedule": null
},
"periods": [],
"attributes": [],
"long_description": null,
"media_list": [],
"order": 5,
"is_free": false,
"groups": [
"my_test_group"
],
"content": [
{
"sku": "Gem_test_import",
"quantity": 1
},
{
"sku": "event_access_test_import",
"quantity": 1
}
]
}
]
}
- Cargue el archivo completo en el campo correspondiente de la ventana de importación.
- Si ocurre algún error durante la importación, en la ventana de importación aparecerá una lista con estos errores y recomendaciones para su corrección. Haga los cambios necesarios en el archivo y cárguelo de nuevo.
Tras cargarlo correctamente, se crearán, actualizarán o desactivarán los artículos con los códigos de artículo (SKU) especificados.
Para evitar errores durante la importación, siga las recomendaciones anteriores para rellenar el archivo.
Exportación del catálogo de artículos
Para exportar un artículo o catálogo de artículos a un archivo JSON:
- Abra el proyecto en Cuenta del editor.
- En el menú lateral, haga clic en Store y vaya a la sección Virtual currency, Virtual items o Bundles.
- Haga clic en Export items.
- Elija la acción:
- Export all items: se exportará todo el catálogo de todos los tipos de artículos de este proyecto. Por ejemplo, si navega a la sección Virtual Currency y exporte todos los artículos, el archivo JSON descargará monedas virtuales, paquetes de moneda virtual, artículos virtuales, paquetes de claves del juego de su proyecto.
- Export only selected items: en la ventana abierta, seleccione los artículos que deben exportarse.
- Haga clic en Export.
La descarga del archivo JSON se iniciará de forma automática.
Importar catálogo desde plataformas externas
Puede importar artículos y suscripciones de plataformas externas y sincronizar el inventario del usuario.
- volver a importar el catálogo (excepto las suscripciones)
- realizar cambios en el catálogo en su Cuenta del editor manualmente
- realizar cambios en el catálogo utilizando grupos de métodos API para la gestión de lotes, artículos virtuales y monedas, planes de suscripción y productos de suscripción.
Importar catálogo desde Google Play
Antes de comenzar a importar, compruebe que la API Google Play Android Developer está activado en su proyecto de Google Play. Vaya https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/overview?project={project_id}
, en la que project_id
es el ID de su proyecto en Google Play. Si esta API está deshabilitada, habilítela. La configuración tardará en aplicarse, por lo que la importación puede fallar si lo intenta inmediatamente después de habilitar la configuración. Espere unos minutos y vuelva a intentarlo.
- Abra su proyecto en Cuenta del editor.
- Haga clic en Store en el menú lateral.
- En el panel Catalog Management, haga clic en Configure.
- En el panel Integration with external platforms, haga clic en Configure.
- En el panel Google Play, haga clic en Configure.
- Especifique el Application ID: el ID de su aplicación de Google Play.
- Cargar JSON con una clave privada.
- Vaya a Google Play Console, en el menú lateral haga clic en Users and permissions y añada la cuenta del servicio como un nuevo usuario con el rol de Android Management User. Para ello es necesario tener el rol de Project IAM admin.
- Haga clic en Save.
- Haga clic en Start import. La importación del catálogo comenzará inmediatamente.
- Para vender artículos virtuales en la tienda web creada por Site Builder, configure grupos de artículos en la Cuenta del editor y asigne uno o más de ellos a cada artículo.
- Para mostrar imágenes de artículos, súbalas a su Cuenta del Editor.
Importar catálogo desde App Store
- ID de aplicación de la sección App Information en App Store Connect.
- API Key e Issuer ID de la sección Users and Access en App Store Connect.
Obtener ID de aplicación
Para obtener el ID de aplicación en App Store Connect:- Inicie sesión en App Store Connect.
- Vaya a la sección Apps.
- Abra la página de su aplicación.
- Acceda a General Information > App Information.
- En General Information copie el ID de aplicación en el campo Apple ID.
Obtener API Key e Issuer ID
El Issuer ID en App Store Connect se utiliza para interactuar con la Apple API, incluida la App Store Connect API. Se requiere para configurar claves API que permiten automatizar tareas como la gestión de aplicaciones, la obtención de datos analíticos y otras operaciones en App Store Connect.
La API Key es un identificador único que se utiliza para autenticar las solicitudes API en App Store Connect API y garantizar el acceso seguro a los datos y las funciones de la cuenta de Apple Developer.
Para obtener el Issuer ID y la API Key en App Store Connect:
- Inicie sesión en App Store Connect y vaya a la sección Users and Access.
- Abra la pestaña Integrations.
- En el menú lateral Keys haga clic en App Store Connect API.
- Acceda a la pestaña Team Keys. Haga clic en el icono + para crear una nueva clave API.
- En la ventana Generate API Key, asigne un nombre a la clave y establezca el nivel de acceso para esta clave.
- Haga clic en Generate.
- La clave creada aparecerá en la lista de claves API activas. Descárguela como archivo P8 y copie el Key ID.
- En la pestaña Team Keys, copie el Issuer ID.
Importar un catálogo de la App Store
- Abra su Cuenta del editor y vaya a Store > Catalog management > Integration with external platforms > App Store.
- Proporcione los datos obtenidos en App Store Connect:
- ID de aplicación;
- Archivo de clave privada (P8);
- Issuer ID;
- Key ID.
- Haga clic en Iniciar importación. La importación del catálogo comenzará automáticamente.
Para vender artículos virtuales en la tienda web creada con Site Builder, cree grupos de artículos en su Cuenta del editor y asigne uno o varios grupos a cada artículo virtual.
Para mostrar imágenes de artículos, debe subirlas editando el artículo importado en Store > Virtual Items.
Importar catálogo desde PlayFab
PlayFab brinda a los desarrolladores de juegos soluciones de servidor listas para usar para gestionar catálogos y monetización. Tras la integración con PlayFab, puede importar un catálogo de PlayFab a Store para usar las soluciones de Xsolla.
- Abra su proyecto en Cuenta del editor.
- Haga clic en Store en el menú lateral.
- En el panel Catalog Management, haga clic en Configure.
- En el panel Integration with external platforms, haga clic en Configure.
- En el panel PlayFab, haga clic en Configure.
- En la pestaña Item import especifique:
- Title ID - el ID del proyecto en PlayFab.
- Secret key - la clave del proyecto en PlayFab.
- Haga clic en Save.
- Sincronice el inventario del usuario con PlayFab (opcional):
- Vaya a Inventory synchronization y especifique:
- Title ID - el ID del proyecto en PlayFab.
- Secret key - la clave del proyecto en PlayFab.
- Establezca el conmutador Synchronize user inventory with PlayFab en la posición On.
- Haga clic en Save.
- Vaya a Inventory synchronization y especifique:
- Vaya a la pestaña Item import y haga clic en Start import. La importación del catálogo se iniciará automáticamente.
- Para vender artículos virtuales en la tienda web creada por Site Builder, configure grupos de artículos en Cuenta del editor y asigne uno o más de ellos a cada artículo.
- Para mostrar imágenes de artículos, súbalas a su Cuenta del editor.
Para comprobar si la importación se ha realizado correctamente, vaya a la sección Store del menú lateral y asegúrese de que los artículos, la moneda y los paquetes están habilitados en las pestañas Virtual currency, Virtual items y Bundles.
Reimportar el catálogo
Al volver a importar el catálogo, debe tener en cuenta que:
- Se actualizarán los artículos que ya están en la Store.
- Se añadirán los artículos que no estén disponibles en la Store.
- Los artículos que ya se hayan eliminado de la fuente de importación permanecerán en la Store. Puede eliminarlos en su Cuenta del editor o a través de la API.
Creación automática de artículos mediante API
Si tiene que crear numerosos artículos a partir de los datos de su sistema, puede automatizar este proceso mediante la API.
Tendrá que:
- Exportar los datos del artículo desde su sistema.
- Transformar los datos exportados a un formato que coincida con el formato de datos del método API del tipo de artículo requerido.
- Para cada artículo de la exportación, cree un script que invoque el método API requerido:
Si quiere utilizar grupos de artículo, créelos antes en la interfaz de la Cuenta del editor.
Si pretende usar varios tipos de artículos, deben crearse en el siguiente orden:
- Grupos de artículos en Cuenta del editor.
- Monedas virtuales.
- Artículos virtuales.
- Paquetes de moneda virtual.
- Lotes.
A continuación, presentamos un ejemplo de script que invoca repetidamente el método Crear artículo virtual para crear artículos virtuales.
El script se desarrolla utilizando JavaScript y el tiempo de ejecución de JavaScript: Node.js.
- Importe la función
fetch
del módulo“node-fetch”
para enviar solicitudes HTTP al servidor de Xsolla.
- javascript
import fetch from "node-fetch";
- Establezca las constantes necesarias para la autorización de la solicitud. En lugar de
<your project_id from PA>
y<your api key from PA>
, ingrese sus valores para el ID del proyecto y la clave de API, que se codificarán usando Base64 para su posterior uso en las solicitudes a la 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')
- Implemente la función de ayuda
sleep
, la cual se usa para crear un retardo al enviar solicitudes. Esto es imprescindible para no exceder los límites de frecuencia de la solicitud a la API.
- javascript
function sleep(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
- Implemente la función
getItems
, específica de su sistema, para recuperar los datos de los artículos desde su sistema.
- javascript
async function getItems() {
// receive items from the original system or read from a pre-prepared file
return items;
}
- Implemente la función
prepareData
, específica de su sistema, para dar formato a los datos del artículo según el formato de datos definido en la llamada API Crear artículo virtual.
- javascript
function prepareData(items) {
// format items in accordance with API requirements
return formattedItems;
}
- Agregue la función
createItem
, la cual envía una solicitudPOST
a la API de Xsolla para crear un artículo virtual.
- 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),
});
}
- Agregue la función
checkItemExist
, la cual comprueba si existe un artículo virtual con un código de artículo (SKU) especificado. La función envía una solicitudGET
a la API de Xsolla:- Si se recibe una respuesta con un código HTTP
404
, el artículo con el SKU especificado no se localiza y hay que crearlo. - Si se recibe una respuesta con un código HTTP
200
, el artículo con el SKU especificado se localiza y no hay que crearlo.
- Si se recibe una respuesta con un código 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;
}
- Agregue la función
createItems
, la cual analiza la lista de artículos y comprueba si existe un artículo con un código de artículo (SKU) de su sistema en el lado de Xsolla. Si no hay ningún artículo con ese SKU, la función lo crea. La información del progreso se visualiza en la consola.
- 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`);
}
- Agregue la función
run
que invoca todas las funciones anteriores en el orden correcto.
- javascript
async function run() {
const items = await getItems();
const formattedItems = prepareData(items);
await createItems(formattedItems);
}
El código completo
- 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();
¿Has encontrado una errata u otro error de texto? Selecciona el texto y pulsa Ctrl+Intro.