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.

Nota
Puede crear, actualizar o desactivar artículos mediante llamadas API o manualmente en Cuenta del editor. No obstante, para cada artículo debe realizar una solicitud o acción independiente. Con la importación, puede ejecutar estas acciones para varios artículos simultáneamente, especificándolos en un único 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:

Nota
Para los artículos previamente creados, puede importar precios regionales desde un archivo CSV.

Importación del catálogo de artículos

Para importar un artículo o catálogo de artículos de un archivo JSON:

  1. Abra el proyecto en Cuenta del editor.
  2. En el menú lateral, haga clic en Store y vaya a la sección Virtual currency, Virtual items o Bundles.
  3. Haga clic en Import items.

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

  1. 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:

Copy
Full screen
Small screen

{
    "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
                }
            ]
        }
    ]
}

  1. Cargue el archivo completo en el campo correspondiente de la ventana de importación.
  2. 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.

Nota
Puede importar artículos utilizando la llamada API Importar artículos mediante un archivo JSON.
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:

  1. Abra el proyecto en Cuenta del editor.
  2. En el menú lateral, haga clic en Store y vaya a la sección Virtual currency, Virtual items o Bundles.
  3. Haga clic en Export items.

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

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

Aviso
Después de la importación, puede sincronizar los cambios realizados en el catálogo de artículos y suscripciones en el origen de importación y en Xsolla de las siguientes maneras:Si no se puede importar el catálogo, configure el catálogo de artículos y suscripciones en Cuenta del editor o mediante métodos API.

Importar catálogo desde Google Play

Aviso

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.

  1. Abra su proyecto en Cuenta del editor.
  2. Haga clic en Store en el menú lateral.
  3. En el panel Catalog Management, haga clic en Configure.
  4. En el panel Integration with external platforms, haga clic en Configure.
  5. En el panel Google Play, haga clic en Configure.
  6. Especifique el Application ID: el ID de su aplicación de Google Play.
Nota
Puede encontrar el ID de aplicación en Google Play Console. En el menú lateral, haga clic en All apps. Busque la aplicación que necesite en la tabla. Su ID se especificará en la columna App, junto al nombre y el logotipo.
  1. Cargar JSON con una clave privada.
Nota
Se genera una clave privada cuando crea su cuenta de servicio.

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

  1. Haga clic en Save.
  2. Haga clic en Start import. La importación del catálogo comenzará inmediatamente.
Nota
El código de artículo (SKU) corresponde al ID del producto en la fuente de importación.
  1. 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.
  2. Para mostrar imágenes de artículos, súbalas a su Cuenta del Editor.
Nota
Para los usuarios de Bangladesh, los precios del catálogo se mostrarán en la moneda por defecto (USD), en lugar de en BDT.

Importar catálogo desde App Store

Nota
Solo se importarán los productos con el estado Aprobado en App Store Connect. En la sección Store de su Cuenta del editor, los artículos importados se mostrarán con el estado Parcialmente disponible. Para que los artículos se muestren, debe cambiar el estado a Disponible.
Antes de importar un catálogo de la App Store, debe obtener los siguientes datos:

Obtener ID de aplicación

Para obtener el ID de aplicación en App Store Connect:
  1. Inicie sesión en App Store Connect.
  2. Vaya a la sección Apps.

  3. Abra la página de su aplicación.
  4. Acceda a General Information > App Information.
  5. 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:

  1. Inicie sesión en App Store Connect y vaya a la sección Users and Access.
  2. Abra la pestaña Integrations.
  3. En el menú lateral Keys haga clic en App Store Connect API.
  4. Acceda a la pestaña Team Keys. Haga clic en el icono + para crear una nueva clave API.

  5. En la ventana Generate API Key, asigne un nombre a la clave y establezca el nivel de acceso para esta clave.
  6. Haga clic en Generate.

  7. La clave creada aparecerá en la lista de claves API activas. Descárguela como archivo P8 y copie el Key ID.

  8. En la pestaña Team Keys, copie el Issuer ID.

Importar un catálogo de la App Store

  1. Abra su Cuenta del editor y vaya a Store > Catalog management > Integration with external platforms > App Store.
  2. Proporcione los datos obtenidos en App Store Connect:
    • ID de aplicación;
    • Archivo de clave privada (P8);
    • Issuer ID;
    • Key ID.
  3. 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.

Nota
El SKU de un producto corresponde al ID de producto en la fuente de importación.

Importar catálogo desde PlayFab

Aviso
Versión de PlayFab API compatible: Economy v1.

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.

Nota
Necesitará un ID de proyecto y una clave secreta de proyecto en PlayFab. Además, el catálogo que quiere importar a Xsolla debe establecerse en PlayFab como básico (Base).

  1. Abra su proyecto en Cuenta del editor.
  2. Haga clic en Store en el menú lateral.
  3. En el panel Catalog Management, haga clic en Configure.
  4. En el panel Integration with external platforms, haga clic en Configure.
  5. En el panel PlayFab, haga clic en Configure.
  6. En la pestaña Item import especifique:
  7. Haga clic en Save.
  8. Sincronice el inventario del usuario con PlayFab (opcional):
    1. Vaya a Inventory synchronization y especifique:
    2. Establezca el conmutador Synchronize user inventory with PlayFab en la posición On.
    3. Haga clic en Save.
  9. Vaya a la pestaña Item import y haga clic en Start import. La importación del catálogo se iniciará automáticamente.
  10. 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.
  11. 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.

Aviso
Cuando compruebe los resultados de la importación, tenga en cuenta que un paquete de moneda virtual es un paquete que contiene solo una moneda. PlayFab utiliza la moneda virtual RM (Real money) que es equivalente a la moneda real: 1 centavo (100 RM = 1 USD). Por ejemplo, si importa 400 RM desde PlayFab, verá 4 USD en su Cuenta del editor.

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:

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:

  1. Grupos de artículos en Cuenta del editor.
  2. Monedas virtuales.
  3. Artículos virtuales.
  4. Paquetes de moneda virtual.
  5. 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.

  1. Importe la función fetch del módulo “node-fetch” para enviar solicitudes HTTP al servidor de Xsolla.
Copy
Full screen
Small screen
import fetch from "node-fetch";
  1. 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.
Copy
Full screen
Small screen
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')
  1. 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.
Copy
Full screen
Small screen
function sleep(ms) {

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

}
  1. Implemente la función getItems, específica de su sistema, para recuperar los datos de los artículos desde su sistema.
Copy
Full screen
Small screen
async function getItems() {

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

   return items;

}
  1. 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.
Copy
Full screen
Small screen
function prepareData(items) {

   // format items in accordance with API requirements

   return formattedItems;

}
  1. Agregue la función createItem, la cual envía una solicitud POST a la API de Xsolla para crear un artículo virtual.
Copy
Full screen
Small screen
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),

   });

}
  1. 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 solicitud GET 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.
Copy
Full screen
Small screen
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;

}
  1. 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.
Copy
Full screen
Small screen
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`);

}
  1. Agregue la función run que invoca todas las funciones anteriores en el orden correcto.
Copy
Full screen
Small screen
async function run() {

 const items = await getItems();

 const formattedItems = prepareData(items);

 await createItems(formattedItems);

}

El código completo

Copy
Full screen
Small screen
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(); 
¿Te ha resultado útil este artículo?
¡Gracias!
¿Hay algo en lo que podamos mejorar? Mensaje
Lo sentimos
Por favor, cuéntanos por qué no te ha resultado útil este artículo. Mensaje
¡Gracias por tu mensaje!
Nos ayudará a mejorar tu experiencia.
Última actualización: 8 de Noviembre de 2024

¿Has encontrado una errata u otro error de texto? Selecciona el texto y pulsa Ctrl+Intro.

Informar de un problema
Nos esforzamos por ofrecer contenido de calidad. Tus comentarios nos ayudan a mejorar.
Déjanos tu correo electrónico para que te podamos responder
¡Gracias por tu mensaje!