Saltar para o conteúdo
/
Obter jogo para catálogo

Catalog API (2.0.0)

Visão geral

  • Versão: 2.0.0
  • Servidores: https://store.xsolla.com/api
  • Contate-nos por e-mail
  • URL de contato: https://xsolla.com/
  • Versão TLS necessária: 1.2

A Catalog API permite que você configure um catálogo de itens de jogo no lado da Xsolla e exibir o catálogo aos usuários na sua loja.

A API permite que você gerencie as seguintes entidades de catálogo:

  • Itens virtuais — itens de jogo tais como armas, visuais e reforços.
  • Moedas virtuais — dinheiro virtual utilizado para comprar bens virtuais.
  • Pacotes de moedas virtuais — conjuntos pré-definidos de moedas virtuais.
  • Conjuntos — pacotes combinados de itens virtuais, moedas ou chaves de jogo vendidas como um único SKU.
  • Chaves de jogo — chaves para jogos e DLCs distribuídos via plataformas como o Steam ou outros provedores de DRM.
  • Grupos — agrupamentos lógicos para organizar e filtrar itens dentro do catálogo.

Chamadas de API

A API divide-se nos seguintes grupos:

  • Admin — chamadas para criar, atualizar, excluir e configurar itens de catálogo e grupos. Autenticada via autenticação de acesso básica com seu comerciante ou credenciais do projeto. Não se destina a uso em vitrines.
  • Catalog — chamadas para recuperar itens e construir vitrines personalizadas para usuários finais. Desenvolvida para gerenciar cenários de carga alta. Suporta a autorização opcional de JWT de usuários para retornar dados personalizados, tais como limites específicos aos usuários e promoções ativas.
Transferir a descrição da OpenAPI
index.json
index.yaml
Idiomas
Servidores
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/pt/api/catalog/

Admin

Operações

Catálogo

Operações

Pagamento virtual

Operações

Catálogo

Operações

Obter chave de jogo para catálogoClient-side

Pedido

Obtém uma chave de jogo para o catálogo.

Observação

Esse ponto de extremidade, acessível sem autorização, retorna dados genéricos. No entanto, a autorização enriquece a resposta com detalhes específicos do usuário para um resultado personalizado, como limites de usuários disponíveis e promoções.
Segurança
XsollaLoginUserJWT
Caminho
project_idintegerobrigatório

ID do projeto. Você pode encontrar esse parâmetro em sua Conta de Distribuidor ao lado do nome do projeto.

Exemplo: 44056
item_skustringobrigatório

SKU do item.

Padrão "xsollus_basic_edition_steam"
Consulta
localestring

Linguagem de resposta. Código de idioma minúsculo de duas letras de acordo com o padrão ISO 639-1.

Padrão "en"
additional_fields[]Array of strings

A lista de campos adicionais. Esses campos estarão na resposta se você enviá-los em sua solicitação.

Itens Enum"media_list""order""long_description""custom_attributes""item_order_in_group"
countrystring

Código de país de duas letras maiúsculas de acordo com o padrão ISO 3166-1 alfa-2. Verifique a documentação para obter informações detalhadas sobre os países suportados pela Xsolla e o processo de determinação do país.

Exemplo: country=US
promo_codestring[ 1 .. 128 ] characters

Código exclusivo que diferencia maiúsculas de minúsculas. Contém letras e números.

Exemplo: promo_code=WINTER2021
show_inactive_time_limited_itemsinteger

Exibe itens de tempo limitado que não estão disponíveis para o usuário. O prazo de validade desses itens não começou ou já expirou.

Padrão 0
Exemplo: show_inactive_time_limited_items=1
curl -i -X GET \
  'https://store.xsolla.com/api/v2/project/44056/items/game/key/sku/{item_sku}?locale=en&additional_fields%5B%5D=media_list&country=US&promo_code=WINTER2021&show_inactive_time_limited_items=1' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Respostas

A chave de jogo foi recebida com sucesso.

Corpoapplication/json
attributesArray of objects(Game-Keys_schemas-client-attributes)

Lista de atributos e seus valores correspondentes ao item. Pode ser usado para a filtragem de catálogos.

Padrão []
Exemplo: {"value":{"external_id":"genre","name":"Жанр","values":[{"external_id":"genre_e3364991f92e751689a68b96598a5a5a84010b85","value":"Casual"},{"external_id":"genre_eba07bfd0f982940773cba3744d97264dd58acd7","value":"Strategy"},{"external_id":"genre_b8d0c6d8f0524c2b2d79ebb93aa3cd0e8b5199a8","value":"Mobile"}]}}
can_be_boughtboolean(Can_be_bought)

Se true, o usuário pode comprar um item.

Exemplo: true
descriptionstring

Descrição do item.

Exemplo: "Game description"
drm_namestring

Nome do DRM.

Exemplo: "Steam"
drm_skustring

ID de DRM exclusivo. O SKU só pode conter caracteres alfanuméricos latinos minúsculos e maiúsculos, pontos, traços e sublinhados.

Exemplo: "steam_key_1"
groupsArray of objects(items_client_groups_response)

Grupo aos quais o item pertence.

Padrão []
Exemplo: [{"external_id":"exclusive","name":"Exclusive"}]
has_keysboolean

Se true, a chave de jogo tem chaves para venda.

Exemplo: true
image_urlstring

URL da imagem.

Exemplo: "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png"
is_freeboolean(value-is_free)

Se true, o item é gratuito.

Padrão false
Exemplo: false
is_pre_orderboolean

Se true, a chave do jogo é uma pré-venda e a data de lançamento não foi passada.

Exemplo: true
limitsobject or null(Catalog_item_limits)

Limites de itens.

namestring

Nome do item.

Exemplo: "Game name"
periodsArray of objects or null(item-periods)

Período de venda de itens.

priceobject

Preços dos itens.

Exemplo: {"amount":"30.5","amount_without_discount":"30.5","currency":"USD"}
promotionsArray of objects(Catalog_item_promotions)

Promoções aplicadas a itens específicos no carrinho. A matriz é retornada nos seguintes casos:

  • Uma promoção de desconto é configurada para um item específico.

  • Um código promocional com a configuração Desconto em itens selecionados é aplicado.

Se nenhuma promoção no nível do item for aplicada, é retornada uma matriz vazia.

release_datestring

Data de lançamento da chave de jogo no formato ISO 8601.

Exemplo: "2020-08-11T10:00:00+03:00"
skustring

ID de item exclusivo. O SKU só pode conter caracteres alfanuméricos latinos minúsculos e maiúsculos, pontos, traços e sublinhados.

Exemplo: "com.xsolla.game_1"
typestring

Tipo de item: game_key.

Exemplo: "game_key"
virtual_pricesArray of objects

Preços virtuais.

Exemplo: []
Resposta
application/json
{
  "attributes": [
    { … },
    { … }
  ],
  "can_be_bought": true,
  "description": "Game description",
  "drm_name": "Steam",
  "drm_sku": "steam_key_1",
  "groups": [
    { … },
    { … }
  ],
  "has_keys": true,
  "image_url": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png",
  "is_free": false,
  "is_pre_order": true,
  "limits": null,
  "name": "Game name",
  "periods": [
    { … }
  ],
  "price": {
    "amount": "30.5",
    "amount_without_discount": "30.5",
    "currency": "USD"
  },
  "promotions": [],
  "release_date": "2020-08-11T10:00:00+03:00",
  "sku": "com.xsolla.game_1",
  "type": "game_key",
  "virtual_prices": []
}

Obter jogo para catálogoClient-side

Pedido

Obtém um jogo para o catálogo.

Observação

Esse ponto de extremidade, acessível sem autorização, retorna dados genéricos. No entanto, a autorização enriquece a resposta com detalhes específicos do usuário para um resultado personalizado, como limites de usuários disponíveis e promoções.
Segurança
XsollaLoginUserJWT
Caminho
project_idintegerobrigatório

ID do projeto. Você pode encontrar esse parâmetro em sua Conta de Distribuidor ao lado do nome do projeto.

Exemplo: 44056
item_skustringobrigatório

SKU do item.

Padrão "full_game_1"
Consulta
localestring

Linguagem de resposta. Código de idioma minúsculo de duas letras de acordo com o padrão ISO 639-1.

Padrão "en"
additional_fields[]Array of strings

A lista de campos adicionais. Esses campos estarão na resposta se você enviá-los em sua solicitação.

Itens Enum"media_list""order""long_description""custom_attributes""item_order_in_group"
countrystring

Código de país de duas letras maiúsculas de acordo com o padrão ISO 3166-1 alfa-2. Verifique a documentação para obter informações detalhadas sobre os países suportados pela Xsolla e o processo de determinação do país.

Exemplo: country=US
promo_codestring[ 1 .. 128 ] characters

Código exclusivo que diferencia maiúsculas de minúsculas. Contém letras e números.

Exemplo: promo_code=WINTER2021
show_inactive_time_limited_itemsinteger

Exibe itens de tempo limitado que não estão disponíveis para o usuário. O prazo de validade desses itens não começou ou já expirou.

Padrão 0
Exemplo: show_inactive_time_limited_items=1
curl -i -X GET \
  'https://store.xsolla.com/api/v2/project/44056/items/game/sku/{item_sku}?locale=en&additional_fields%5B%5D=media_list&country=US&promo_code=WINTER2021&show_inactive_time_limited_items=1' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Respostas

Jogo recebido com sucesso.

Corpoapplication/json
attributesArray of objects(Game-Keys_schemas-client-attributes)

Lista de atributos e seus valores correspondentes ao item. Pode ser usado para a filtragem de catálogos.

Padrão []
Exemplo: {"value":{"external_id":"genre","name":"Жанр","values":[{"external_id":"genre_e3364991f92e751689a68b96598a5a5a84010b85","value":"Casual"},{"external_id":"genre_eba07bfd0f982940773cba3744d97264dd58acd7","value":"Strategy"},{"external_id":"genre_b8d0c6d8f0524c2b2d79ebb93aa3cd0e8b5199a8","value":"Mobile"}]}}
descriptionstring

Descrição do item.

Exemplo: "Game description"
groupsArray of objects(items_client_groups_response)

Grupo aos quais o item pertence.

Padrão []
Exemplo: [{"external_id":"exclusive","name":"Exclusive"}]
image_urlstring

URL da imagem.

Exemplo: "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png"
namestring

Nome do item.

Exemplo: "Game name"
promotionsArray of objects(Catalog_item_promotions)

Promoções aplicadas a itens específicos no carrinho. A matriz é retornada nos seguintes casos:

  • Uma promoção de desconto é configurada para um item específico.

  • Um código promocional com a configuração Desconto em itens selecionados é aplicado.

Se nenhuma promoção no nível do item for aplicada, é retornada uma matriz vazia.

skustring

ID de item exclusivo. O SKU só pode conter caracteres alfanuméricos latinos minúsculos e maiúsculos, pontos, traços e sublinhados.

Exemplo: "game_01"
typestring

Tipo de item:virtual_good/virtual_currency/bundle/physical_good/unit.

Exemplo: "unit"
unit_itemsArray of objects
unit_typestring

Tipo de unidade: game.

Exemplo: "game"
Resposta
application/json
{
  "attributes": [
    { … },
    { … }
  ],
  "description": "Game description",
  "groups": [
    { … },
    { … }
  ],
  "image_url": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png",
  "name": "Game name",
  "promotions": [],
  "sku": "com.xsolla.game_1",
  "type": "unit",
  "unit_items": [
    { … },
    { … }
  ],
  "unit_type": "game"
}

Direito

Operações

Admin

Operações

Admin

Operações

Catálogo

Operações

Carrinho (lado do cliente)

Operações

Carrinho (lado do servidor)

Operações

Pagamento (lado do cliente)

Operações

Pagamento (lado do servidor)

Operações

Pedido

Operações

Itens gratuitos

Operações

Gestão

Operações

Admin

Operações

Webhooks

Operações

Reservas

Operações

Comerciante

Operações

Catálogo

Esta API permite obter qualquer tipo de itens vendáveis ou itens específicos.

Operações

Regiões comuns

Operações

Admin

Operações