Saltar al contenido
/
Actualizar juego por su I...

API de catálogo (2.0.0)

Descripción general

La API de catálogo le permite configurar un catálogo de artículos de juego en el lado de Xsolla y mostrar dicho catálogo a los usuarios de su tienda.

La API le permite gestionar las siguientes entidades de catálogo:

  • Artículos virtuales: artículos de juego, como armas, apariencias o potenciadores.
  • Moneda virtual: dinero virtual que se utiliza para comprar productos virtuales.
  • Paquetes de moneda virtual: lotes predefinidos de moneda virtual.
  • Lotes: paquetes combinados de artículos virtuales, moneda o claves de juego que se venden como un único SKU.
  • Claves de juego: claves para juegos y DLC distribuidos a través de plataformas como Steam u otros proveedores de DRM.
  • Grupos: agrupaciones lógicas para organizar y clasificar artículos dentro del catálogo.

Llamadas API

La API se divide en los siguientes grupos:

  • Admin: llamadas para crear, actualizar, eliminar y configurar artículos de catálogo y grupos. La autenticación se realiza mediante autenticación de acceso básica con sus credenciales de comerciante o de proyecto. No está diseñado para uso en escaparates.
  • Catalog: llamadas para buscar artículos y crear escaparates personalizados para los usuarios finales. Diseñado para gestionar situaciones de alta carga. Admite la autorización JWT opcional de usuarios para devolver datos personalizados, como límites específicos para determinados usuarios y promociones activas.
Descargar descripción de OpenAPI
index.json
index.yaml
Idiomas
Servidores
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/es/api/catalog/

Admin

Operaciones

Catálogo

Operaciones

Pago virtual

Operaciones

Catálogo

Operaciones

Derechos

Operaciones

Admin

Operaciones

Obtener juego por ID (admin)Server-sideAdmin

Solicitud

Obtiene un juego para administración. El juego se compone de claves del juego que podrían ser compradas por un usuario.

Nota

No utilice este punto final para crear un catálogo de tienda.
Seguridad
basicAuth
Ruta
project_idintegerrequerido

ID del proyecto. Encontrará este parámetro en su Cuenta del editor junto al nombre del proyecto.

Ejemplo: 44056
item_idstringrequerido

ID del artículo.

Ejemplo: 656
Consulta
promo_codestring[ 1 .. 128 ] characters

Código único que distingue entre mayúsculas y minúsculas. Contiene letras y números.

Ejemplo: promo_code=WINTER2021
curl -i -X GET \
  -u <username>:<password> \
  'https://store.xsolla.com/api/v2/project/44056/admin/items/game/id/656?promo_code=WINTER2021'

Respuestas

El juego se recibió correctamente.

Cuerpoapplication/json
attributesArray of objects(Game-Keys_admin-attributes)

Lista de atributos.

Ejemplo: [{"external_id":"attribute_external_id","name":{"de":"Attributname","en":"Attribute name"},"values":[{"external_id":"value_1","name":{"de":"wert 1","en":"value 1"}},{"external_id":"value_2","name":{"de":"wert 2","en":"value 2"}}]}]
description(two-letter (object or null)) or (cinco letras (object or null))(description-localization-object)

Objeto con traducciones para la descripción del artículo. Acepta valores en uno de dos formatos: códigos de idioma de dos letras en minúscula (p. ej., en) o códigos de configuración regional de cinco caracteres (p. ej., en-US). Aunque ambos formatos se aceptan como entradas, las respuestas devuelven códigos de idioma de dos letras en minúscula. Cuando se facilitan ambas opciones para el mismo idioma (p. ej. en y en-US), se almacena el último valor proporcionado. Puede consultar la lista completa de idiomas admitidos en la documentación.

One of:

Objeto con traducciones para la descripción del artículo. Acepta valores en uno de dos formatos: códigos de idioma de dos letras en minúscula (p. ej., en) o códigos de configuración regional de cinco caracteres (p. ej., en-US). Aunque ambos formatos se aceptan como entradas, las respuestas devuelven códigos de idioma de dos letras en minúscula. Cuando se facilitan ambas opciones para el mismo idioma (p. ej. en y en-US), se almacena el último valor proporcionado. Puede consultar la lista completa de idiomas admitidos en la documentación.

groupsArray of objects

Grupos a los que pertenece el artículo.

Ejemplo: [{"external_id":"horror","name":{"en":"Horror"}}]
image_urlstring

URL de la imagen.

Ejemplo: "https://image.example.com"
is_enabledboolean
is_freeboolean(value-is_free)

Si es true, el artículo es gratuito.

Predeterminado false
Ejemplo: false
is_show_in_storeboolean
item_idinteger

ID único interno del artículo que se proporciona al crearlo.

Ejemplo: 1
long_description(two-letter (object or null)) or (cinco letras (object or null))(long-description-localization-object)

Objeto con traducciones para la descripción larga del artículo. Acepta valores en uno de estos dos formatos: códigos de idioma de dos letras en minúscula (p. ej., en) o códigos de configuración regional de cinco caracteres (p. ej., en-US). Aunque ambos formatos se aceptan como entradas, las respuestas devuelven códigos de idioma de dos letras en minúscula. Cuando se facilitan ambas opciones para el mismo idioma (p. ej. en y en-US), se almacena el último valor proporcionado. Puede consultar la lista completa de idiomas admitidos en la documentación.

Any of:

Objeto con traducciones para la descripción larga del artículo. Acepta valores en uno de estos dos formatos: códigos de idioma de dos letras en minúscula (p. ej., en) o códigos de configuración regional de cinco caracteres (p. ej., en-US). Aunque ambos formatos se aceptan como entradas, las respuestas devuelven códigos de idioma de dos letras en minúscula. Cuando se facilitan ambas opciones para el mismo idioma (p. ej. en y en-US), se almacena el último valor proporcionado. Puede consultar la lista completa de idiomas admitidos en la documentación.

media_listArray of objects

Recursos adicionales del juego, como capturas de pantalla, vídeos de partidas del juego, etc.

Ejemplo: [{"type":"image","url":"https://cdn3.xsolla.com/img/misc/images/71ab1e12126f2103e1868076f0acb21a.jpg"}]
name(two-letter (object or null)) or (cinco letras (object or null))(name-localization-object)

Objeto con traducciones para la descripción del artículo. Acepta valores en uno de estos dos formatos: códigos de idioma de dos letras en minúscula (p. ej., en) o códigos de idioma de cinco caracteres (p. ej., en-US). Aunque ambos formatos se aceptan como entradas, las respuestas devuelven códigos de idioma de dos letras en minúscula. Cuando se facilitan ambas opciones para el mismo idioma (p. ej. en y en-US), se almacena el último valor proporcionado. Puede consultar la lista completa de idiomas admitidos en la documentación.

One of:

Objeto con traducciones para la descripción del artículo. Acepta valores en uno de estos dos formatos: códigos de idioma de dos letras en minúscula (p. ej., en) o códigos de idioma de cinco caracteres (p. ej., en-US). Aunque ambos formatos se aceptan como entradas, las respuestas devuelven códigos de idioma de dos letras en minúscula. Cuando se facilitan ambas opciones para el mismo idioma (p. ej. en y en-US), se almacena el último valor proporcionado. Puede consultar la lista completa de idiomas admitidos en la documentación.

orderinteger

Prioridad de orden del juego en la lista.

Ejemplo: 1
skustring

ID único del artículo. El SKU solo puede contener caracteres alfanuméricos latinos en minúsculas y mayúsculas, puntos, guiones y guiones bajos.

Ejemplo: "game_1"
typestring

Tipo de artículo. En este caso es siempre unit.

Ejemplo: "unit"
unit_itemsArray of objects

Claves del juego para diferentes DRM (gestión de derechos digitales).

Respuesta
application/json
{
  "attributes": [
    { … }
  ],
  "description": {
    "en": "Example game 1"
  },
  "groups": [
    { … }
  ],
  "image_url": "https://image.example.com",
  "is_enabled": true,
  "is_free": false,
  "is_show_in_store": false,
  "item_id": 1,
  "long_description": {
    "en": "Example game's long description"
  },
  "media_list": [
    { … }
  ],
  "name": {
    "en": "Game 1"
  },
  "order": 1,
  "sku": "com.xsolla.game_1",
  "type": "unit",
  "unit_items": [
    { … },
    { … }
  ]
}

Actualizar juego por su IDServer-sideAdmin

Solicitud

Actualiza un juego en el proyecto por su ID.

Seguridad
basicAuth
Ruta
project_idintegerrequerido

ID del proyecto. Encontrará este parámetro en su Cuenta del editor junto al nombre del proyecto.

Ejemplo: 44056
item_idstringrequerido

ID del artículo.

Ejemplo: 656
Cuerpoapplication/jsonrequerido

Objeto con datos del juego.

attributesArray of objects(Game-Keys_admin-post-put-attributes)<= 20 items

Lista de atributos.

Atención. No puede especificar más de 20 atributos para el artículo. Cualquier intento de superar el límite provocará un error.
description(two-letter (object or null)) or (cinco letras (object or null))(description-localization-object)

Objeto con traducciones para la descripción del artículo. Acepta valores en uno de dos formatos: códigos de idioma de dos letras en minúscula (p. ej., en) o códigos de configuración regional de cinco caracteres (p. ej., en-US). Aunque ambos formatos se aceptan como entradas, las respuestas devuelven códigos de idioma de dos letras en minúscula. Cuando se facilitan ambas opciones para el mismo idioma (p. ej. en y en-US), se almacena el último valor proporcionado. Puede consultar la lista completa de idiomas admitidos en la documentación.

One of:

Objeto con traducciones para la descripción del artículo. Acepta valores en uno de dos formatos: códigos de idioma de dos letras en minúscula (p. ej., en) o códigos de configuración regional de cinco caracteres (p. ej., en-US). Aunque ambos formatos se aceptan como entradas, las respuestas devuelven códigos de idioma de dos letras en minúscula. Cuando se facilitan ambas opciones para el mismo idioma (p. ej. en y en-US), se almacena el último valor proporcionado. Puede consultar la lista completa de idiomas admitidos en la documentación.

groupsArray of objects

Grupos a los que pertenece el artículo.

Ejemplo: ["new_games"]
image_urlstring

URL de la imagen.

Ejemplo: "http://image.png"
is_enabledboolean

Si se deshabilita, el artículo no se puede comprar ni se puede acceder a este a través del inventario.

Ejemplo: true
is_show_in_storeboolean

El artículo está disponible para la compra.

Ejemplo: true
long_description(two-letter (object or null)) or (cinco letras (object or null))(long-description-localization-object)

Objeto con traducciones para la descripción larga del artículo. Acepta valores en uno de estos dos formatos: códigos de idioma de dos letras en minúscula (p. ej., en) o códigos de configuración regional de cinco caracteres (p. ej., en-US). Aunque ambos formatos se aceptan como entradas, las respuestas devuelven códigos de idioma de dos letras en minúscula. Cuando se facilitan ambas opciones para el mismo idioma (p. ej. en y en-US), se almacena el último valor proporcionado. Puede consultar la lista completa de idiomas admitidos en la documentación.

Any of:

Objeto con traducciones para la descripción larga del artículo. Acepta valores en uno de estos dos formatos: códigos de idioma de dos letras en minúscula (p. ej., en) o códigos de configuración regional de cinco caracteres (p. ej., en-US). Aunque ambos formatos se aceptan como entradas, las respuestas devuelven códigos de idioma de dos letras en minúscula. Cuando se facilitan ambas opciones para el mismo idioma (p. ej. en y en-US), se almacena el último valor proporcionado. Puede consultar la lista completa de idiomas admitidos en la documentación.

media_listArray of objects

Recursos adicionales del juego, como capturas de pantalla, vídeos de partidas del juego, etc.

Ejemplo: [{"type":"image","url":"http://image.png"},{"type":"video","url":"http://video.png"}]
name(two-letter (object or null)) or (cinco letras (object or null))(name-localization-object)requerido

Objeto con traducciones para la descripción del artículo. Acepta valores en uno de estos dos formatos: códigos de idioma de dos letras en minúscula (p. ej., en) o códigos de idioma de cinco caracteres (p. ej., en-US). Aunque ambos formatos se aceptan como entradas, las respuestas devuelven códigos de idioma de dos letras en minúscula. Cuando se facilitan ambas opciones para el mismo idioma (p. ej. en y en-US), se almacena el último valor proporcionado. Puede consultar la lista completa de idiomas admitidos en la documentación.

One of:

Objeto con traducciones para la descripción del artículo. Acepta valores en uno de estos dos formatos: códigos de idioma de dos letras en minúscula (p. ej., en) o códigos de idioma de cinco caracteres (p. ej., en-US). Aunque ambos formatos se aceptan como entradas, las respuestas devuelven códigos de idioma de dos letras en minúscula. Cuando se facilitan ambas opciones para el mismo idioma (p. ej. en y en-US), se almacena el último valor proporcionado. Puede consultar la lista completa de idiomas admitidos en la documentación.

name.​arstring or null

Árabe

name.​bgstring or null

Búlgaro

name.​cnstring or null

Chino (simplificado)

name.​csstring or null

Checo

name.​destring or null

Alemán

name.​enstring or null

Inglés

name.​esstring or null

Español (España)

name.​frstring or null

Francés

name.​hestring or null

Hebreo

name.​idstring or null

Indonesio

name.​itstring or null

Italiano

name.​jastring or null

Japonés

name.​kmstring or null

Jemer

name.​kostring or null

Coreano

name.​lostring or null

Lao

name.​mystring or null

Birmano

name.​nestring or null

Nepalí

name.​phstring or null

Filipino

name.​plstring or null

Polaco

name.​ptstring or null

Portugués

name.​rostring or null

Rumano

name.​rustring or null

Ruso

name.​thstring or null

Tailandés

name.​trstring or null

Turco

name.​twstring or null

Chino (tradicional)

name.​vistring or null

Vietnamita

orderinteger

Prioridad de orden del juego en la lista.

Ejemplo: 1
skustring[ 1 .. 255 ] characters^[a-zA-Z0-9_\-–.]*$requerido

ID único del artículo. El SKU solo puede contener caracteres alfanuméricos latinos en minúsculas y mayúsculas, puntos, guiones y guiones bajos.

Ejemplo: "com.xsolla.game_1"
unit_itemsArray of objectsrequerido

Claves del juego para diferentes DRM (gestión de derechos digitales).

Ejemplo: [{"drm_sku":"steam_key_1","is_enabled":true,"is_free":false,"is_show_in_store":true,"limits":{"per_item":{"available":5000,"reserved":500,"sold":4500,"total":10000},"per_user":{"total":5}},"name":{"en-US":"Game key name","ru-RU":"Название игрового ключа"},"periods":[{"date_from":"2020-08-11T10:00:00+03:00","date_until":"2020-08-11T20:00:00+03:00"}],"pre_order":{"description":"Some description","is_enabled":true,"release_date":"2020-08-11T10:00:00+03:00"},"prices":[{"amount":35.5,"currency":"USD","is_default":true,"is_enabled":true}],"regions":[{"id":12},{"id":64}],"sku":"com.xsolla.game_key_1","vc_prices":[{"amount":35.5,"is_default":true,"is_enabled":true,"sku":"com.xsolla.gold_1"}]}]
unit_items[].​attributesArray of objects(Game-Keys_admin-attributes)

Lista de atributos.

Ejemplo: [{"external_id":"attribute_external_id","name":{"de":"Attributname","en":"Attribute name"},"values":[{"external_id":"value_1","name":{"de":"wert 1","en":"value 1"}},{"external_id":"value_2","name":{"de":"wert 2","en":"value 2"}}]}]
unit_items[].​drm_skustringrequerido

ID único del DRM.

Ejemplo: "steam"
unit_items[].​groupsArray of objects

Grupos a los que pertenece el artículo.

unit_items[].​is_enabledboolean

Si se deshabilita, el artículo no se puede comprar ni se puede acceder a este a través del inventario.

unit_items[].​is_freeboolean(value-is_free)

Si es true, el artículo es gratuito.

Predeterminado false
Ejemplo: false
unit_items[].​is_show_in_storeboolean

El artículo está disponible para la compra.

unit_items[].​limitsobject(Game-key-item-limit)

Límites del artículo.

unit_items[].​name(two-letter (object or null)) or (cinco letras (object or null))(name-localization-object)

Objeto con traducciones para la descripción del artículo. Acepta valores en uno de estos dos formatos: códigos de idioma de dos letras en minúscula (p. ej., en) o códigos de idioma de cinco caracteres (p. ej., en-US). Aunque ambos formatos se aceptan como entradas, las respuestas devuelven códigos de idioma de dos letras en minúscula. Cuando se facilitan ambas opciones para el mismo idioma (p. ej. en y en-US), se almacena el último valor proporcionado. Puede consultar la lista completa de idiomas admitidos en la documentación.

One of:

Objeto con traducciones para la descripción del artículo. Acepta valores en uno de estos dos formatos: códigos de idioma de dos letras en minúscula (p. ej., en) o códigos de idioma de cinco caracteres (p. ej., en-US). Aunque ambos formatos se aceptan como entradas, las respuestas devuelven códigos de idioma de dos letras en minúscula. Cuando se facilitan ambas opciones para el mismo idioma (p. ej. en y en-US), se almacena el último valor proporcionado. Puede consultar la lista completa de idiomas admitidos en la documentación.

unit_items[].​orderinteger

Prioridad de orden del juego en la lista.

Ejemplo: 1
unit_items[].​periodsArray of objects or null(item-periods)

Periodo de venta del artículo.

unit_items[].​pre_orderobject

Configuración del pedido por anticipado.

unit_items[].​pricesArray of objectsrequerido

Precios en monedas reales.

unit_items[].​prices[].​amountnumberrequerido
Ejemplo: 1299.99
unit_items[].​prices[].​currencystringrequerido

Divisa del precio del artículo. Código de tres letras según ISO 4217. Consulte la documentación para obtener información detallada sobre monedas soportadas por Xsolla.

Ejemplo: "RUB"
unit_items[].​prices[].​is_defaultbooleanrequerido

El precio por defecto se utiliza para generar el catálogo si no se especifica el precio en la moneda del usuario.

unit_items[].​prices[].​is_enabledbooleanrequerido
unit_items[].​regionsArray of objects(Game-Keys_regions)
unit_items[].​skustring[ 1 .. 255 ] charactersrequerido

ID único del artículo. El SKU solo puede contener caracteres alfanuméricos latinos en minúsculas y mayúsculas, puntos, guiones y guiones bajos.

Ejemplo: "game_1"
unit_items[].​vc_pricesArray of objects
curl -i -X PUT \
  -u <username>:<password> \
  https://store.xsolla.com/api/v2/project/44056/admin/items/game/id/656 \
  -H 'Content-Type: application/json' \
  -d '{
    "description": {
      "en-US": "Game description",
      "ru-RU": "Краткое описание игры"
    },
    "groups": [
      "new_games"
    ],
    "image_url": "http://image.png",
    "is_enabled": true,
    "is_show_in_store": true,
    "long_description": {
      "en-US": "Game long description",
      "ru-RU": "Полное описание игры"
    },
    "media_list": [
      {
        "type": "image",
        "url": "http://image.png"
      },
      {
        "type": "video",
        "url": "http://video.png"
      }
    ],
    "name": {
      "en-US": "Game name",
      "ru-RU": "Название игры"
    },
    "sku": "com.xsolla.game_1",
    "unit_items": [
      {
        "drm_sku": "steam_key_1",
        "is_enabled": true,
        "is_free": false,
        "is_show_in_store": true,
        "limits": {
          "per_item": {
            "available": 5000,
            "reserved": 500,
            "sold": 4500,
            "total": 10000
          },
          "per_user": {
            "total": 5
          }
        },
        "name": {
          "en-US": "Game key name",
          "ru-RU": "Название игрового ключа"
        },
        "periods": [
          {
            "date_from": "2020-08-11T10:00:00+03:00",
            "date_until": "2020-08-11T20:00:00+03:00"
          }
        ],
        "pre_order": {
          "description": "Some description",
          "is_enabled": true,
          "release_date": "2020-08-11T10:00:00+03:00"
        },
        "prices": [
          {
            "amount": 35.5,
            "currency": "USD",
            "is_default": true,
            "is_enabled": true
          }
        ],
        "regions": [
          {
            "id": 12
          },
          {
            "id": 64
          }
        ],
        "sku": "com.xsolla.game_key_1",
        "vc_prices": [
          {
            "amount": 35.5,
            "is_default": true,
            "is_enabled": true,
            "sku": "com.xsolla.gold_1"
          }
        ]
      }
    ]
  }'

Respuestas

El juego se actualizó correctamente.

Respuesta
Sin contenido

Borrar códigos por IDServer-sideAdmin

Solicitud

Elimina todos los códigos por ID de la clave del juego.

Seguridad
basicAuth
Ruta
project_idintegerrequerido

ID del proyecto. Encontrará este parámetro en su Cuenta del editor junto al nombre del proyecto.

Ejemplo: 44056
item_idstringrequerido

ID del artículo.

Ejemplo: 656
Consulta
user_emailstringrequerido

Correo del usuario.

Ejemplo: user_email=email@email.com
reasonstringrequerido

Motivo de recepción de códigos.

Ejemplo: reason=Very important
region_idinteger

ID de la región.

Predeterminado 1
curl -i -X DELETE \
  -u <username>:<password> \
  'https://store.xsolla.com/api/v2/project/44056/admin/items/game/key/delete/id/656?user_email=email%40email.com&reason=Very+important&region_id=1'

Respuestas

Los códigos se recibieron correctamente.

Cuerpotext/plain
string
Respuesta
text/plain
PIN-CODE-ALL PIN-CODE-ALL-3

Admin

Operaciones

Catálogo

Operaciones

Cesta (cliente)

Operaciones

Cesta (lado del servidor)

Operaciones

Pago (lado del cliente)

Operaciones

Pago (lado del servidor)

Operaciones

Pedido

Operaciones

Artículos gratuitos

Operaciones

Gestión

Operaciones

Admin

Operaciones

Webhooks

Operaciones

Pedidos anticipados

Operaciones

Comerciante

Operaciones

Catálogo

Esta API permite obtener cualquier tipo de artículo vendible o artículo específico.

Operaciones

Regiones comunes

Operaciones

Admin

Operaciones