Saltar para o conteúdo
/
Obter lista de chaves de...

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 lista de jogos por grupo especificadoClient-side

Pedido

Recebe uma lista de jogos do grupo especificado para montar um catálogo.

Atenção

Todos os projetos têm uma limitação na quantidade de itens que você pode receber na resposta. O valor padrão e máximo é de 50 itens por resposta. Para obter mais dados página por página, use os campos limit e offset.

Observação

O use das chamadas API de catálogo de itens está disponível sem autorização, mas para obter um catálogo personalizado, você deve passar o JWT do usuário no cabeçalho da Autorização.
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
external_idstringobrigatório

ID externo de grupo.

Padrão "all"
Consulta
limitinteger>= 1

Limite da quantidade de elementos na página.

Exemplo: limit=50
offsetinteger>= 0

Número do elemento a partir do qual a lista é gerada (a quantidade começa a partir de 0).

Exemplo: offset=0
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/group/{external_id}?limit=50&offset=0&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 lista de jogos foi recebida com sucesso.

Corpoapplication/json
has_moreboolean(Pagination_has-more)

Usado como um indicador de que há mais páginas.

Exemplo: true
itemsArray of objects
Exemplo: [{"attributes":[{"external_id":"genre","name":"Genre","values":[{"external_id":"23fda05111c125608af8f1fa0e99db45a10ea1cc","value":"Horror"}]}],"description":"Game description","groups":[{"external_id":"all","name":"All games"},{"external_id":"Xsolla","name":"Xsolla games"}],"image_url":"https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png","name":"Game name","promotions":[],"sku":"com.xsolla.game_1","type":"unit","unit_items":[{"can_be_bought":true,"drm_name":"Steam","drm_sku":"steam_key_1","has_keys":true,"is_free":false,"is_pre_order":true,"periods":[{"date_from":"2020-08-11T10:00:00+03:00","date_until":"2020-08-11T20:00:00+03:00"}],"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_key_01","type":"game_key","virtual_prices":[]},{"can_be_bought":true,"drm_name":"Origin","drm_sku":"origin_key_1","has_keys":false,"is_free":false,"is_pre_order":false,"periods":[],"price":{"amount":"30.5","amount_without_discount":"30.5","currency":"USD"},"promotions":[],"release_date":null,"sku":"com.xsolla.game_key_02","type":"game_key","virtual_prices":[]}],"unit_type":"game"},{"attributes":[{"external_id":"OS","name":"OS","values":[{"external_id":"9d5c5efb7c0f00a00fe4e3583f1215b0050bc723","value":"Windows"}]}],"description":"Game description","groups":[{"external_id":"all","name":"All games"}],"image_url":"https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png","name":"Game name","promotions":[],"sku":"com.xsolla.game_2","type":"unit","unit_items":[{"can_be_bought":true,"drm_name":"Steam","drm_sku":"steam_key_2","has_keys":false,"is_free":false,"is_pre_order":false,"periods":[{"date_from":null,"date_until":"2020-08-11T20:00:00+03:00"}],"price":{"amount":"30.5","amount_without_discount":"30.5","currency":"USD"},"promotions":[],"release_date":null,"sku":"com.xsolla.game_key_01","type":"game_key","virtual_prices":[]}],"unit_type":"game"}]
Resposta
application/json
{
  "has_more": false,
  "items": [
    { … },
    { … }
  ]
}

Obter lista de chaves de jogo por grupo especificadoClient-side

Pedido

Recebe uma lista de chaves de jogo do grupo especificado para montar um catálogo.

Atenção

Todos os projetos têm uma limitação na quantidade de itens que você pode receber na resposta. O valor padrão e máximo é de 50 itens por resposta. Para obter mais dados página por página, use os campos limit e offset.

Observação

O use das chamadas API de catálogo de itens está disponível sem autorização, mas para obter um catálogo personalizado, você deve passar o JWT do usuário no cabeçalho da Autorização.
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
external_idstringobrigatório

ID externo de grupo.

Padrão "all"
Consulta
limitinteger>= 1

Limite da quantidade de elementos na página.

Exemplo: limit=50
offsetinteger>= 0

Número do elemento a partir do qual a lista é gerada (a quantidade começa a partir de 0).

Exemplo: offset=0
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/group/{external_id}?limit=50&offset=0&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 lista de chaves de jogo foi recebida com sucesso.

Corpoapplication/json
has_moreboolean(Pagination_has-more)

Usado como um indicador de que há mais páginas.

Exemplo: true
itemsArray of objects
Exemplo: [{"attributes":[{"external_id":"OS","name":"OS","values":[{"external_id":"9d5c5efb7c0f00a00fe4e3583f1215b0050bc723","value":"Windows"}]},{"external_id":"genre","name":"Genre","values":[{"external_id":"23fda05111c125608af8f1fa0e99db45a10ea1cc","value":"Horror"}]}],"description":"Game description","drm_name":"Steam","drm_sku":"steam_key_1","groups":[{"external_id":"all","name":"All games"},{"external_id":"Xsolla","name":"Xsolla games"}],"has_keys":true,"image_url":"https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png","is_free":false,"is_pre_order":true,"name":"Game name","periods":[{"date_from":"2020-08-11T10:00:00+03:00","date_until":"2020-08-11T20:00:00+03:00"}],"price":{"amount":"30.5","amount_without_discount":"30.5","currency":"USD"},"release_date":"2020-08-11T10:00:00+03:00","sku":"com.xsolla.game_1","type":"game_key","virtual_prices":[]},{"attributes":[{"external_id":"OS","name":"OS","values":[{"external_id":"9d5c5efb7c0f00a00fe4e3583f1215b0050bc723","value":"Windows"}]},{"external_id":"genre","name":"Genre","values":[{"external_id":"23fda05111c125608af8f1fa0e99db45a10ea1cc","value":"Horror"}]}],"description":"Game description","drm_name":"Steam","drm_sku":"steam_key_2","groups":[{"external_id":"all","name":"All games"}],"has_keys":true,"image_url":"https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png","is_free":false,"is_pre_order":false,"name":"Game name","periods":[],"price":{"amount":"30.5","amount_without_discount":"30.5","currency":"USD"},"release_date":null,"sku":"com.xsolla.game_2","type":"game_key","virtual_prices":[]}]
Resposta
application/json
{
  "has_more": true,
  "items": [
    { … },
    { … }
  ]
}

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": []
}

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