Importar catálogo

Criação e atualização do catálogo de itens usando importação JSON

Você pode criar, atualizar ou desativar itens usando através da importação de um arquivo JSON.

Observação
Você pode criar, atualizar ou desativar itens usando chamadas API ou manualmente na Conta de Distribuidor. Porém, para cada item, você precisa desempenhar uma solicitação ou ação separada. Com a importação, você pode realizar essas ações para múltiplos itens simultaneamente especificando-os em um único arquivo JSON.

Com essa ferramenta, você pode:

Recursos:

  • Suporte para os seguintes tipos de itens:
    • itens virtuais
    • moedas virtuais
    • pacotes de moedas virtuais
    • conjuntos
  • Validação de dados. Se a estrutura do arquivo ou formato de dados não cumprir os requisitos, você verá uma lista de erros ao importar.

Limitações:

Observação
Para itens pré-criados, você pode importar preços regionais de um arquivo CSV:

Importação do catálogo de itens

Para importar catálogo de itens de um arquivo:

  1. Abra o projeto na Conta de Distribuidor.
  2. No menu lateral, clique em Store e vá para a seção Virtual currency, Virtual items ou Bundles.
  3. Clique em Import items.

  1. Escolha uma ação:
    • Add new items — apenas itens com SKUs novos serão adicionados.
    • Add new items and update existing ones — itens com SKUs novos serão adicionados e os dados de itens existentes serão atualizados.
    • Add new, update existing, disable missing items — itens com SKUs do arquivo serão adicionados/atualizados. Se houver um item no catálogo, mas não houver tal SKU no arquivo, o status do item na Conta de Distribuidor será alterado para Partially available — o item não pode ser comprado separadamente, mas está disponível como parte de um conjunto ou bônus.

  1. Preencha o arquivo para importação:
    • Baixe o modelo de arquivo na janela de download e preencha-o de acordo com o exemplo abaixo.
    • Exporte os itens e use o arquivo exportado como modelo.
    • Crie seu próprio arquivo JSON e preencha-o de acordo com o exemplo abaixo.

Um exemplo de um arquivo 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. Envie o arquivo completo ao campo correspondente na janela de importação.
  2. Se houver erros durante a importação, uma lista desses erros e recomendações para a correção deles será exibida na janela de importação. Faça as alterações necessárias ao arquivo e envie-o novamente.

Após um envio bem-sucedido, os itens com os SKUs especificados serão criados, atualizados ou desativados.

Observação
Você pode importar itens usando a chamada de API Importação de itens por arquivo JSON.
Para evitar erros durante a importação, siga as recomendações acima para preencher o arquivo.

Exportação do catálogo de itens

Para exportar um item ou catálogo de itens a um arquivo JSON:

  1. Abra o projeto na Conta de Distribuidor.
  2. No menu lateral, clique em Store e vá para a seção Virtual currency, Virtual items ou Bundles.
  3. Clique em Export items.

  1. Escolha a ação:
    • Export all items — o catálogo inteiro de todos os tipos de itens deste projeto será exportado. Por exemplo, se você navegar para a seção Virtual Currency e exportar todos os itens, o arquivo JSON descarregará as moedas virtuais, pacotes de moedas virtuais, itens virtuais e pacotes de chaves de jogo do seu projeto.
    • Export only selected items — na janela aberta, selecione os itens que devem ser exportados.

  1. Clique em Export.

O download do arquivo JSON começará automaticamente.

Importação do catálogo de itens de plataformas externas

Você pode importar itens e assinaturas de plataformas externas e sincronizar o inventário do usuário.

Aviso
Após a importação, você pode sincronizar as alterações feitas no catálogo de itens e nas assinaturas na origem de importação e na Xsolla das seguintes maneiras:Se o catálogo não puder ser importado, configure o catálogo de itens e assinaturas na Conta de Distribuidor ou usando métodos de API.

Como importar o catálogo do Google Play

Aviso

Antes de iniciar a importação, verifique se a Google Play Android Developer API está ativada em seu projeto Google Play. Visite https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/overview?project={project_id}, onde project_id — seu ID do projeto na Google Play. Se essa API estiver desativada, ative-a. As configurações podem levar um tempo até serem aplicadas, então a importação pode falhar se você tentar imediatamente após a ativação das configurações. Espere alguns minutos e tente novamente.

  1. Abra seu projeto em Conta de Distribuidor.
  2. Clique em Store no menu lateral.
  3. No painel Catalog Management, clique em Configure.
  4. No painel Integration with external platforms, clique em Configure.
  5. No painel Google Play, clique em Configure.
  6. Especifique o Application ID — o ID do seu aplicativo no Google Play.
Observação
Você pode encontrar o ID do aplicativo no Google Play Console. No menu lateral, clique em All apps. Encontre o aplicativo necessário na tabela. Seu ID será especificado na coluna App, ao lado do nome e do logotipo.
  1. Envie o JSON com uma chave privada.
Observação
Uma chave privada é gerada quando você cria sua conta de serviço.

  1. Vá para o Google Play Console. No menu lateral, clique em Users and permissions e adicione a conta de serviço como um novo usuário com a função de Android Management User. Isso exige que você tenha a função Project IAM admin.

  1. Clique em Save.
  2. Clique em Start import. A importação do catálogo começará imediatamente.
Observação
O SKU corresponde à ID do produto na origem da importação.
  1. Para vender itens virtuais na loja virtual criada pelo Site Builder, configure grupos de itens na Conta de Distribuidor e atribua um ou mais deles a cada item.
  2. Para exibir imagens de itens, envie-as para sua Conta de Distribuidor.
Observação
Para usuários de Bangladesh, os preços de catálogo serão exibidos na moeda padrão (USD), em vez de em BDT.

Importação de catálogo da App Store

Observação
Apenas produtos com o status Aprovado no App Store Connect serão importados. Na seção Store da sua Conta de Distribuidor, os itens importados serão exibidos com o status Parcialmente Disponível. Para tornar os itens visíveis, você precisa alterar o status para Disponível.
Antes de importar um catálogo da App Store, você precisa obter os seguintes dados:

Obtenção do ID do aplicativo

Para obter seu Id do Aplicativo no App Store Connect:
  1. Faça login no App Store Connect.
  2. Vá para a seção Apps.

  3. Abra a página do seu aplicativo.
  4. Navegue para General Information > App Information.
  5. Em General Information, copie o ID do Aplicativo no campo Apple ID.

Obter Chave API e ID de Emissor

O ID de Emissor no App Store Connect é usado para a interação com a Apple API, incluindo a App Store Connect API. Ele é necessário para configurar as chaves de API para automatizar tarefas tais como o gerenciamento do aplicativo, a recuperação de dados analíticos e outras operações no App Store Connect.

A Chave API é um identificador único para autenticar solicitações de API na App Store Connect API e garantir o acesso seguro aos dados e funcionalidades da Apple Developer Account.

Para obter o ID de Emissor e Chave API no App Store Connect:

  1. Faça login no App Store Connect e vá para a seção Users and Access.
  2. Abra a aba Integrations.
  3. No menu lateral Keys, clique em App Store Connect API.
  4. Vá para a aba Team Keys. Clique no ícone + para criar uma nova chave API.

  5. Na janela Generate API Key, atribua um nome à chave e defina o nível de acesso a esta chave.
  6. Clique em Generate.

  7. A chave recém-criada aparecerá na lista de chaves API ativas. Baixe-a como um arquivo P8 e copie o ID da Chave.

  8. Na aba Team Keys, copie o ID de Emissor.

Importação de catálogos da App Store

  1. Abra sua Conta de Distribuidor e acesse Store > Catalog management > Integration with external platforms > App Store.
  2. Forneça os dados obtidos no App Store Connect:
    • ID de Aplicativo;
    • Arquivo de chaves privadas (P8);
    • ID de Emissor;
    • ID da Chave.
  3. Clique em Iniciar importação. A importação do catálogo começará automaticamente.

Para vender itens virtuais na loja virtual criada usando o Site Builder, crie grupos de itens na sua Conta de Distribuidor e atribua um ou mais grupos para cada item virtual.

Para exibir imagens de itens, você precisa enviá-los editando o item importado em Store > Virtual Items.

Observação
O SKU de um produto corresponde ao ID de Produto na fonte de importação.

Como importar o catálogo do PlayFab

Aviso
Suportado pela PlayFab API versão: Economy v1.

O PlayFab oferece aos desenvolvedores de jogos soluções de servidor prontas para uso no gerenciamento de catálogos e monetização. Após a integração com o PlayFab, você poderá importar catálogos do PlayFab direto à Store para usar junto as soluções Xsolla.

Observação
Você precisará de um ID de projeto e uma chave secreta de projeto no PlayFab. Além disso, o catálogo que você quiser importar à Xsolla deve ser configurado no PlayFab como básico (Base).

  1. Abra seu projeto na Conta de Distribuidor.
  2. Clique em Store no menu lateral.
  3. No painel Catalog Management, clique em Configure.
  4. No painel Integration with external platforms, clique em Configurar.
  5. No painel PlayFab, clique em Configurar.
  6. Na guia Importação de itens especifique:
  7. Clique em Salvar.
  8. Sincronize o inventário do usuário com o PlayFab (opcional):
    1. Vá para Sincronização do inventário e especifique:
    2. Defina a configuração Synchronize user inventory with PlayFab como On.
    3. Clique em Save.
  9. Vá para a guia Item import e clique em Start import. A importação do catálogo será iniciada automaticamente.
  10. Para vender itens virtuais na loja virtual criada pelo Construtor de Sites, configure grupos de itens na Conta de Distribuidor e atribua um ou mais deles a cada item.
  11. Para exibir imagens de itens, envie-as à sua Conta de Distribuidor.

Para verificar se a importação foi concluída com sucesso, vá para a seção Store no menu lateral e verifique se os itens, a moeda e os pacotes estão habilitados nas abas Virtual currency, Virtual items e Bundles.

Aviso
Ao verificar os resultados da importação, considere que um pacote de moeda virtual é um pacote contendo apenas um tipo de moeda. PlayFab usa a moeda virtual RM (Real Money, dinheiro real em inglês) que é equivalente à moeda real - 1 centavo (100 RM = 1 USD). Por exemplo, se você importar 400 RM do PlayFab, você verá 4 USD em sua Conta de Distribuidor.

Reimportação de catálogo

Ao reimportar o catálogo, você precisa considerar que:

  • Os itens que já estão na Store serão atualizados.
  • Os itens que não estão disponíveis na Store serão adicionados.
  • Os itens que já foram removidos da fonte de importação permanecerão na Store. Você pode excluí-los em sua Conta de Distribuidor ou via API.

Criação automática de itens via API

Se você precisa criar diversos itens com base nos dados do seu sistema, você pode automatizar esse processo usando a API.

Você precisa:

Se você quiser usar grupos de itens, crie-os antecipadamente pela interface da Conta de Distribuidor.

Se quiser usar múltiplos tipos de itens, eles devem ser criados na seguinte ordem:

  1. grupos de itens na Conta de Distribuidor.
  2. Moedas virtuais.
  3. Itens virtuais.
  4. Pacotes de moedas virtuais.
  5. Conjuntos.

A seguir está um exemplo de um script que chama repetidamente o método Obter pedido para criar itens virtuais.

O script é desenvolvido usando JavaScript e o tempo de execução do JavaScript — Node.js.

  1. Importe a função fetch do módulo “node-fetch” para enviar solicitações ao servidor Xsolla.
Copy
Full screen
Small screen
import fetch from "node-fetch";
  1. Defina as constantes necessárias para solicitar a autorização. Em vez de <your project_id from PA> e <your api key from PA>, insira seus valores no ID de projeto e chave API, que será codificado usando Base64 para o uso subsequente nas solicitações 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 a função do ajudante sleep, que é usada para criar um atraso ao enviar solicitações. isso é necessário para não exceder os limites de taxa de solicitações API.
Copy
Full screen
Small screen
function sleep(ms) {

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

}
  1. Implemente a função getItems, que é específica ao seu sistema, para receber dados de itens do seu 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 a função prepareData, que é específica ao seu sistema, para formatar os dados do item de acordo com o formato de dados na chamada de API Obter pedido.
Copy
Full screen
Small screen
function prepareData(items) {

   // format items in accordance with API requirements

   return formattedItems;

}
  1. Adicione a função createItem, que envia uma solicitação POST à API Xsolla para criar um item 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. Adicione a função checkItemExist, que verifica se um item virtual com um SKU especificado existe. A função envia uma solicitação GET à API Xsolla:
    • Se uma resposta com um código HTTP 404 for recebida, o item com o SKU especificado não foi encontrado, e precisa ser criado.
    • Se uma resposta com um código HTTP 200 for recebido, o item com o SKU especificado foi encontrado e não precisa ser criado.
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. Adicione a função createItems, que passa pela lista de itens e verifica se há um item com um SKU do seu sistema no lado Xsolla. Se não houver um item com esse SKU, a função o cria. A informação de progresso é exibida no console.
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. Adicione a função run que chama todas as funções na ordem correta.
Copy
Full screen
Small screen
async function run() {

 const items = await getItems();

 const formattedItems = prepareData(items);

 await createItems(formattedItems);

}

O 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(); 
Este artigo foi útil?
Obrigado!
Podemos melhorar alguma coisa? Mensagem
Que pena ouvir isso
Explique porque este artigo não foi útil para você. Mensagem
Obrigado pelo seu feedback!
Avaliaremos sua mensagem e a usaremos para melhorar sua experiência.
Última atualização: 8 de Novembro de 2024

Encontrou um erro de texto ou digitação? Selecione o texto e pressione Ctrl+Enter.

Relatar um problema
Nós sempre avaliamos nossos conteúdos. Seu feedback nos ajuda a melhorá-los.
Forneça um e-mail para que possamos responder
Obrigado pelo seu feedback!