Chino (simplificado)
- Obtener juego (admin)
Crear juego
Obtener lista de juegos (admin)
Actualizar juego por SKU
Eliminar juego por SKU
Obtener juego por ID (admin)
Actualizar juego por su ID
Eliminar un juego por su ID
Cargar códigos
Cargar códigos por ID
Obtener información de la sesión de carga de códigos
Obtener códigos
Obtener códigos por ID
Eliminar códigos
Borrar códigos por ID
Obtener juego (admin)
API de catálogo (2.0.0)
- Versión: 2.0.0
- Servidores:
https://store.xsolla.com/api - Contacte con nosotros por correo electrónico
- URL de contacto: https://xsolla.com/
- Versión TLS requerida: 1.2
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.
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.
Las llamadas API requieren autenticación ya sea en nombre de un usuario o en nombre de un proyecto. El esquema de autenticación utilizado se especifica en la sección Seguridad en la descripción de cada llamada.
La autenticación mediante el JWT del usuario se utiliza cuando se envía una solicitud desde un navegador, aplicación móvil o juego. Por defecto, se aplica el esquema XsollaLoginUserJWT. Para obtener más detalles sobre cómo crear un token, consulte la documentación del API de Xsolla Login.
El token se transmite en el encabezado Authorization con el siguiente formato: Authorization: Bearer <user_JWT>, en el que <user_JWT> es el token de usuario. El token identifica al usuario y proporciona acceso a datos personalizados.
También puede utilizar un token para abrir la interfaz de pago.
La autenticación HTTP básica se utiliza para interacciones de servidor a servidor, cuando una llamada API se envía directamente desde tu servidor en lugar de desde el navegador de un usuario o aplicación móvil. Normalmente, se usa la autenticación HTTP básica con una clave de API.
Nota:
La clave de API es confidencial y no debe almacenarse ni usarse en aplicaciones cliente.
La clave de API es confidencial y no debe almacenarse ni usarse en aplicaciones cliente.
Con la autenticación básica del lado del servidor, todas las solicitudes de API deben incluir el siguiente encabezado:
- para
basicAuth—Authorization: Basic <your_authorization_basic_key>, en las queyour_authorization_basic_keyes el parproject_id:api_keycodificado en Base64 - para
basicMerchantAuth—Authorization: Basic <your_authorization_basic_key>, en las queyour_authorization_basic_keyes el parmerchant_id:api_keycodificado en Base64
Puede encontrar los valores de parámetro en Cuenta del editor:
- Se muestra
merchant_id:- En Configuración de la empresa > Empresa.
- En la URL en la barra de direcciones del navegador en cualquier página de Cuenta del editor. La URL tiene el siguiente formato:
https://publisher.xsolla.com/<merchant_id>.
- Se muestra
project_id:- Junto al nombre del proyecto en Cuenta del editor.
- En la URL en la barra de direcciones del navegador al trabajar en un proyecto en la Cuenta del editor. La URL tiene el siguiente formato:
https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.
api_keyse muestra en Cuenta del editor solo en el momento de la creación y debe almacenarse de forma segura en su servidor. Puede crear una clave de API en las siguientes secciones:
Aviso:
Si una llamada API requerida no incluye el parámetro de ruta
Si una llamada API requerida no incluye el parámetro de ruta
project_id, utilice una clave de API que sea válida para todos los proyectos de la empresa para la autorización.Para obtener más información sobre cómo trabajar con claves de API, consulte las referencias de la API.
El esquema de autenticación AuthForCart se utiliza para las compras con cesta y admite dos modos:
Autenticación mediante el JWT del usuario. El token se transmite en el encabezado
Authorizationcon el siguiente formato:Authorization: Bearer <user_JWT>, en el cual<user_JWT>es el token del usuario. El token identifica al usuario y proporciona acceso a datos personalizados. Como alternativa, puede utilizar un token para abrir la interfaz de pago.Modo simplificado sin encabezado "Authorization". Este modo se utiliza solo para usuarios no autorizados y puede aplicarse solo para ventas de claves de juego. En lugar de un token, la solicitud debe incluir los siguientes encabezados:
x-unauthorized-idcon un ID de solicitudx-usercon la dirección de correo electrónico del usuario codificada en Base64
Los artículos de todos los tipos (artículos virtuales, lotes, moneda virtual y claves) emplean una estructura de datos similar. Comprender la estructura básica simplifica el trabajo con la API y le ayuda a orientarse más fácilmente en la documentación.
Nota:
Algunas llamadas pueden incluir campos adicionales, pero no cambian la estructura básica.
Algunas llamadas pueden incluir campos adicionales, pero no cambian la estructura básica.
Identificación
merchant_id— ID de la empresa en Cuenta del editorproject_id— ID del proyecto en Cuenta del editorsku— SKU del artículo, único dentro del proyecto
Visualización en la tienda
name— nombre del artículodescription— descripción del artículoimage_url— URL de la imagenis_enabled— disponibilidad del artículois_show_in_store— si el artículo se muestra o no en el catálogo
Para obtener más información sobre la gestión de la disponibilidad de artículos en el catálogo, consulte la documentación.
Organización
type— tipo de artículo, p. ej., un artículo virtual (virtual_item) o lote (bundle)groups— grupos a los que pertenece el artículoorder— orden de visualización en el catálogo
Condiciones de venta
prices— precios en moneda real o virtuallimits— límites de compraperiods— periodos de disponibilidadregions— restricciones regionales
Ejemplo de estructura de entidad principal:
{
"attributes": [],
"bundle_type": "virtual_currency_package",
"content": [
{
"description": {
"en": "Main in-game currency"
},
"image_url": "https://.../image.png",
"name": {
"en": "Crystals",
"de": "Kristalle"
},
"quantity": 500,
"sku": "com.xsolla.crystal_2",
"type": "virtual_currency"
}
],
"description": {
"en": "Crystals x500"
},
"groups": [],
"image_url": "https://.../image.png",
"is_enabled": true,
"is_free": false,
"is_show_in_store": true,
"limits": {
"per_item": null,
"per_user": null,
"recurrent_schedule": null
},
"long_description": null,
"media_list": [],
"name": {
"en": "Medium crystal pack"
},
"order": 1,
"periods": [
{
"date_from": null,
"date_until": "2020-08-11T20:00:00+03:00"
}
],
"prices": [
{
"amount": 20,
"country_iso": "US",
"currency": "USD",
"is_default": true,
"is_enabled": true
}
],
"regions": [],
"sku": "com.xsolla.crystal_pack_2",
"type": "bundle",
"vc_prices": []
}La API de Xsolla le permite implementar la lógica de una tienda en el juego, incluyendo la recuperación del catálogo de artículos, la gestión de la cesta, la creación de pedidos y el seguimiento de su estado. Dependiendo del escenario de integración, las llamadas API se dividen en subsecciones de Admin y Catálogo, que usan diferentes esquemas de autenticación.
El siguiente ejemplo muestra un flujo básico para establecer y operar una tienda, desde la creación de artículos hasta la compra.
Cree un catálogo de artículos para su tienda, como artículos virtuales, lotes o moneda virtual.
Ejemplos de llamadas API:
Configure herramientas de adquisición de usuarios y monetización, como descuentos, bonificaciones, recompensas diarias o cadenas de ofertas.
Ejemplos de llamadas API:
Configure la visualización de artículos en su aplicación.
Aviso:
No utilice llamadas API de la subsección Admin para crear un catálogo de usuarios. Estas llamadas API tienen límites de frecuencia y no están destinadas para el tráfico de usuarios.
No utilice llamadas API de la subsección Admin para crear un catálogo de usuarios. Estas llamadas API tienen límites de frecuencia y no están destinadas para el tráfico de usuarios.
Ejemplos de llamadas a la API:
Nota:
Por defecto, las llamadas API del catálogo devuelven artículos que están actualmente disponibles en la tienda en el momento de la solicitud. Para recuperar artículos que aún no están disponibles o que ya no lo están, incluya el parámetro
Por defecto, las llamadas API del catálogo devuelven artículos que están actualmente disponibles en la tienda en el momento de la solicitud. Para recuperar artículos que aún no están disponibles o que ya no lo están, incluya el parámetro
"show_inactive_time_limited_items": 1 en la solicitud del catálogo.
Puede vender artículos utilizando los siguientes métodos:
- Compra rápida: venda un código de artículo (SKU) varias veces.
- Compra con cesta: el usuario añade artículos a la cesta, elimina artículos y actualiza cantidades dentro de un solo pedido.
Si un artículo se compra utilizando moneda virtual en lugar de dinero real, utilice la llamada API Crear pedido con artículo especificado comprado con moneda virtual. La interfaz de pago no es necesaria, ya que el cargo se procesa cuando se ejecuta la llamada API.
Para la compra de artículos gratuitos, utilice la llamada API Crear pedido con artículo gratuito especificado o la llamada API Crear pedido con cesta gratuita. La interfaz de pago no es necesaria: el pedido se establece inmediatamente con el estado done.
Utilice la llamada API del lado del cliente para crear un pedido con un artículo especificado. La llamada devuelve un token utilizado para abrir la interfaz de pago.
Nota:
La información de descuento está disponible para el usuario únicamente en la interfaz de pago. Los códigos promocionales no son compatibles.
La información de descuento está disponible para el usuario únicamente en la interfaz de pago. Los códigos promocionales no son compatibles.
La configuración y compra de la cesta se puede realizar en el cliente o en el lado del servidor.
Configurar y comprar una cesta en el cliente
Implemente la lógica de añadir y eliminar artículos por usted mismo. Antes de llamar a la API para establecer una cesta, no tendrá información sobre qué promociones se aplicarán a la compra. Esto implica que el coste total y los detalles de los artículos de bonificación añadidos no se conocerán.
Implemente la siguiente lógica de cesta:
- Después de que el jugador haya llenado una cesta, utilice la llamada API Llenar la cesta con artículos. La llamada devuelve la información actual sobre los artículos seleccionados (precios antes y después de descuentos y artículos de bonificación).
- Actualice el contenido de la cesta basándose en las acciones de los usuarios:
- Para añadir un artículo o cambiar la cantidad del artículo, utilice la llamada API Actualizar artículo de la cesta por ID de la cesta.
- Para eliminar un artículo, utilice la llamada API Eliminar artículo de la cesta por ID de la cesta.
Nota:
Para obtener el estado actual de la cesta, utilice la llamada API Obtener la cesta del usuario actual.
Para obtener el estado actual de la cesta, utilice la llamada API Obtener la cesta del usuario actual.
- Utilice la llamada API Crear pedido con todos los artículos de la cesta actual. La llamada devuelve el ID del pedido y el token de pago. El pedido recién creado se establece por defecto con el estado
new.
Configurar y comprar una cesta en el servidor
Esta opción de configuración puede requerir más tiempo para configurar la cesta, ya que cada modificación que se realice en ella debe ir acompañada de llamadas API.
Implemente la siguiente lógica de cesta:
- Después de que el jugador haya llenado una cesta, utilice la llamada API Llenar la cesta con artículos. La llamada devuelve la información actual sobre los artículos seleccionados (precios antes y después de descuentos, y artículos de bonificación).
- Utilice la llamada API Crear pedido con todos los artículos de la cesta actual. La llamada devuelve el ID del pedido y el token de pago. El pedido recién creado se establece por defecto con el estado
new.
Utilice el token devuelto para abrir la interfaz de pago en una nueva ventana. Otras formas de abrir la interfaz de pago se describen en la documentación.
| Acción | Punto final |
|---|---|
| Abrir en entorno de producción. | https://secure.xsolla.com/paystation4/?token={token} |
| Abrir en modo sandbox. | https://sandbox-secure.xsolla.com/paystation4/?token={token} |
Nota:
Utilice el modo sandbox durante el desarrollo y las pruebas. Las compras de prueba no hacen cargos en cuentas reales. Puede usar tarjetas bancarias de prueba.
Utilice el modo sandbox durante el desarrollo y las pruebas. Las compras de prueba no hacen cargos en cuentas reales. Puede usar tarjetas bancarias de prueba.
Tras realizar el primer pago real, se aplica una política estricta de pagos en aislador de proceso (sandbox). Un pago en modo sandbox está disponible solo para los usuarios especificados en Cuenta del Editor > Configuración de la empresa > Usuarios.
Comprar moneda virtual y artículos con moneda real es posible solamente después de firmar un acuerdo de licencia con Xsolla. Para hacerlo, en Cuenta del editor, vaya a Acuerdos e impuestos > Acuerdos, rellene el formulario de acuerdo y espere la confirmación. La revisión del acuerdo puede tardar hasta tres días laborables.
Para habilitar o deshabilitar el modo sandbox, cambie el valor del parámetro sandbox en la solicitud para compra rápida y compra con cesta. El modo sandbox está desactivado por defecto.
Posibles estados del pedido:
new: pedido creadopaid: pago recibidodone: artículo entregadocanceled: pedido canceladoexpired: pedido expirado
Haga un seguimiento del estado del pedido usando uno de los siguientes métodos:
Las llamadas API que devuelven grandes conjuntos de registros (p. ej., al crear un catálogo) devuelven datos en páginas. La paginación es un mecanismo que limita el número de artículos devueltos en una sola respuesta de API y le permite recuperar páginas posteriores de manera secuencial.
Utilice los siguientes artículos para controlar el número de artículos devueltos:
limit— número de artículos por páginaoffset— índice del primer artículo de la página (la numeración comienza desde 0)has_more— indica si hay otra página disponibletotal_items_count— número total de artículos
Ejemplo de solicitud:
GET /items?limit=20&offset=40Ejemplo de respuesta:
{
"items": [...],
"has_more": true,
"total_items_count": 135
}Se recomienda enviar solicitudes posteriores hasta que la respuesta devuelva has_more = false.
Las fechas y valores de tiempo se transmiten en el formato ISO 8601.
Se admiten los siguientes:
- Desfase UTC (tiempo universal coordinado)
- Valor
nullcuando no hay restricción de tiempo para mostrar un artículo - Marca de tiempo Unix (en segundos) utilizada en algunos campos
Formato: AAAA-MM-DDTHH:MM:SS±HH:MM
Ejemplo: 2026-03-16T10:00:00+03:00
Xsolla admite la localización de campos visibles por el usuario, como el nombre y la descripción del artículo. Los valores localizados se transmiten como un objeto en el que el código de idioma se utiliza como la clave. La lista completa de idiomas admitidos está disponible en la documentación.
Campos admitidos
La localización puede especificarse para los siguientes parámetros:
namedescriptionlong_description
Formato de configuración regional
La clave de configuración regional puede especificarse en uno de los siguientes formatos:
- Código de idioma de dos letras:
en,ru - Código de idioma de cinco letras:
en-US,ru-RU,de-DE
Ejemplos
Ejemplo con un código de idioma de dos letras:
{
"name": {
"en": "Starter Pack",
"ru": "Стартовый набор"
}
}Ejemplo con un código de idioma de cinco letras:
{
"description": {
"en-US": "Premium bundle",
"de-DE": "Premium-Paket"
}
}Si ocurre un error, la API devuelve un estado HTTP y un cuerpo de respuesta JSON. La lista completa de errores relacionados con la tienda está disponible en la documentación.
Ejemplo de respuesta:
{
"errorCode": 1102,
"errorMessage": "Validation error",
"statusCode": 422,
"transactionId": "c9e1a..."
}errorCode— código de error.errorMessage— descripción breve del error.statusCode— estado de la respuesta HTTP.transactionId— ID de la solicitud. Se devuelve solo en algunos casos.errorMessageExtended— detalles adicionales del error, como los parámetros de la solicitud. Se devuelve solo en algunos casos.
Ejemplo de respuesta ampliada:
{
"errorCode": 7001,
"errorMessage": "Chain not found",
"errorMessageExtended": {
"chain_id": "test_chain_id",
"project_id": "test_project_id",
"step_number": 2
},
"statusCode": 404
}Códigos de estado HTTP habituales
400— solicitud no válida401— error de autenticación403— permisos insuficientes404— recurso no encontrado422— error de validación429— límite de frecuencia excedido
Recomendaciones
- Gestione el estado HTTP y el cuerpo de la respuesta juntos.
- Utilice
errorCodepara procesar errores relacionados con la lógica de la aplicación. - Utilice
transactionIdpara identificar solicitudes más rápidamente al analizar errores.
Descargar descripción de OpenAPI
Idiomas
Servidores
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/es/api/catalog/
Descripción general
Puede usar artículos virtuales y moneda virtual para crear una tienda dentro del juego y configurar cómo se muestra a los usuarios. Los siguientes tipos de artículos están disponibles:
- Artículos virtuales: productos dentro del juego como armas, apariencias o potenciadores. Pueden venderse por dinero real o moneda virtual.
- Moneda virtual: moneda del juego utilizada para comprar artículos virtuales. Puede venderse por dinero real o moneda virtual.
- Paquetes de moneda virtual: una cantidad fija de moneda virtual. Puede venderse por dinero real o moneda virtual.
Los grupos sirven para organizar los artículos en el catálogo. Permiten agrupar de forma lógica los artículos y gestionar cómo se muestran.
Utilice las llamadas API de la subsección Admin para crear, actualizar y eliminar artículos.
Utilice las llamadas API de la subsección Catálogo para recuperar listas de artículos y mostrarlas a los usuarios.
Aviso
No utilice las llamadas API de la subsección Admin para crear un catálogo de tienda.
No utilice las llamadas API de la subsección Admin para crear un catálogo de tienda.
Nota:
La llamada API Obtener lista de artículos virtuales devuelve datos detallados de los artículos, incluidos precios y atributos, y admite paginación. Utilícela para mostrar páginas de catálogo en la tienda.
La llamada API Obtener lista de todos los artículos virtuales devuelve SKU, nombre y descripción del artículo, así como ID de grupo y nombre sin paginación. Úsela para la búsqueda o indexación en el lado del cliente.
La llamada API Obtener lista de artículos virtuales devuelve datos detallados de los artículos, incluidos precios y atributos, y admite paginación. Utilícela para mostrar páginas de catálogo en la tienda.
La llamada API Obtener lista de todos los artículos virtuales devuelve SKU, nombre y descripción del artículo, así como ID de grupo y nombre sin paginación. Úsela para la búsqueda o indexación en el lado del cliente.
Para hacer compras con moneda virtual, utilice la llamada API Crear pedido con artículo especificado comprado mediante moneda virtual. La interfaz de pago no es necesaria: el cargo se procesa cuando se ejecuta la llamada API.
Ejemplo de un flujo de compra con moneda virtual:
Descripción general
Game keys are single-use unique alphanumeric codes that grant users access to a game or DLC on gaming platforms. You can sell game keys via a direct link, through the store UI, or via a widget. You can also configure regional restrictions to sell game keys in specific countries. For detailed information, refer to the Game keys packages section.
User authentication is not required to sell game keys — the keys are sent to the email the user specified at checkout. You can configure authentication to enable additional scenarios: personalization, purchase limits, or an entitlement system. For detailed information, refer to the How to set up authentication when selling game keys section.
Game key sales flow:
- Create a game using the Create game API call.
- Configure regional restrictions.
- Upload keys to a game key package using the Upload codes API call to make them available for purchase.
- Display the game catalog with prices for the user's region using the Get games list API call.
- Create an order. For a fast purchase, you can use the Create order with all items from current cart API call, passing the game key SKU. The response returns a token for opening the payment UI.
- Implement the opening of the payment UI to pay for the order.
To receive timely notifications about successful payments and deliver items to the user, set up order status tracking, for example, using webhooks. The keys are sent to the email the user specified at checkout, and the order moves to the done status.
Ruta
ID del proyecto. Encontrará este parámetro en su Cuenta del editor junto al nombre del proyecto y en la barra de direcciones del navegador cuando se trabaja en un proyecto. La URL tiene el siguiente formato: https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.
Ejemplo: 44056
- https://store.xsolla.com/api/v2/project/{project_id}/admin/items/game
- Mock serverhttps://xsolla.redocly.app/_mock/es/api/catalog/v2/project/{project_id}/admin/items/game
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
'https://store.xsolla.com/api/v2/project/44056/admin/items/game?limit=50&offset=0&promo_code=WINTER2021'La lista de juegos se recibió correctamente.
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"
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.
Any of:
Códigos lingüísticos de dos letras minúsculas.
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.
Any of:
Códigos lingüísticos de dos letras minúsculas.
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:
Códigos lingüísticos de dos letras minúsculas.
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"}]
Si se deshabilita, el artículo no se puede comprar ni se puede acceder a este a través del inventario.
Grupos a los que pertenece el artículo.
Ejemplo: [{"external_id":"horror","name":{"en":"Horror"}}]
Lista de atributos.
Ejemplo: [{"external_id":"attribute_external_id","name":{"en":"Attribute name","de":"Attributname"},"values":[{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]}]
ID único del atributo. external_id solo puede contener caracteres alfanuméricos latinos en minúsculas y mayúsculas, guiones y guiones bajos.
Ejemplo: "attribute_external_id"
Objeto con traducciones para el nombre del atributo. Las claves se especifican en la norma ISO 3166-1.
Ejemplo: {"en":"Attribute name","de":"Attributname"}
Ejemplo: [{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]
ID del valor único para un atributo. external_id solo puede contener caracteres alfanuméricos latinos en minúsculas, guiones y guiones bajos.
Ejemplo: "value_external_id"
Claves del juego para diferentes DRM (gestión de derechos digitales).
ID único interno del artículo que se proporciona al crearlo.
Ejemplo: 1
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"
Tipo de artículo. En este caso es siempre game_key.
Ejemplo: "game_key"
Precios en monedas reales.
Ejemplo: [{"amount":1299.99,"currency":"RUB","is_default":true,"is_enabled":true}]
Divisa del precio del artículo. Código de tres letras según ISO 4217.
Ejemplo: "RUB"
El precio por defecto se utiliza para generar el catálogo si no se especifica el precio en la moneda del usuario.
País en el que está disponible este precio. Código de dos letras según la norma ISO 3166-1 alfa 2.
Ejemplo: "US"
Ejemplo: [{"sku":"com.xsolla.gold_1","name":{"en":"Gold"},"type":"virtual_currency","description":null,"image_url":"https://i.pinimg.com/originals/91/ae/56/91ae5683045f6dbef16b1482bade938f.png","amount":1000,"is_default":true}]
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: "gold"
Objeto con traducciones para el nombre de la moneda virtual. Las claves se especifican en la norma ISO 3166-1.
Ejemplo: {"en":"Gold"}
Tipo de artículo. En este caso es siempre virtual_currency.
Ejemplo: "virtual_currency"
Object with localizations for game description. Keys are specified in ISO 3166-1.
Ejemplo: {"en":"Game 1 Example"}
URL de la imagen.
Ejemplo: "https://image.example.com"
Si se deshabilita, el artículo no se puede comprar ni se puede acceder a este a través del inventario.
Icono del DRM de clave del juego.
Ejemplo: "https://upload.wikimedia.org/wikipedia/en/4/48/Steam_Icon_2014.png"
Si es true, la clave del juego fue comprada por los usuarios.
Configuración del pedido por anticipado.
Fecha de lanzamiento de la clave del juego en formato ISO 8601.
Si está deshabilitada, el artículo no es un pedido por anticipado.
Límites del artículo.
Limitación de artículos para un usuario independiente.
Número máximo de artículos que un mismo usuario puede comprar.
Determina la visibilidad del artículo en el catálogo tras alcanzar el límite de compra, hasta el siguiente restablecimiento del límite.
Se aplica a los artículos para los que se han configurado restablecimientos periódicos del límite en la matriz recurrent_schedule.
Si no están configurados los restablecimientos del límite, el artículo no aparecerá en el catálogo cuando se haya alcanzado el límite de compra, independientemente del valor de limit_exceeded_visibility.
Valores posibles:
show— El artículo se devuelve en las llamadas API de recuperación del catálogo tras alcanzar el límite de compra. En las llamadas API de recuperación del catálogo en el lado del cliente, tras alcanzar el límite, el artículo se devuelve con el indicadorcan_be_bought: false. La La próxima fecha de restablecimiento se devuelve el díareset_next_date.hide— El artículo no se devuelve en las llamadas API de recuperación del catálogo tras alcanzar el límite de compra, hasta que se restablezca ese límite.
Enumeración"show""hide"
Limitación global de artículos.
Número máximo de artículos que pueden comprar todos los usuarios.
Número restante de artículos que todos los usuarios pueden comprar.
Periodo de actualización del límite.
Periodo de actualización del límite del usuario.
One of:
Tipo diario de actualización del límite del usuario.
Tipo de periodo de actualización recurrente.
Valor"daily"
Hora de actualización del límite en la zona horaria deseada (redondeo a horas).
Ejemplo: "11:00:00+03:00"
Fecha y hora de actualización de los límites (Marca de tiempo Unix).
Ejemplo: 1677553200
Periodo de venta del artículo.
Fecha en la que el artículo especificado estará disponible para la venta.
Ejemplo: "2020-08-11T10:00:00+03:00"
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.
Any of:
Códigos lingüísticos de dos letras minúsculas.
Lista de atributos.
Ejemplo: [{"external_id":"attribute_external_id","name":{"en":"Attribute name","de":"Attributname"},"values":[{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]}]
items[].unit_items[].attributes[].external_idstring[ 1 .. 255 ] characters^[a-zA-Z0-9-_]+$requerido
ID único del atributo. external_id solo puede contener caracteres alfanuméricos latinos en minúsculas y mayúsculas, guiones y guiones bajos.
Ejemplo: "attribute_external_id"
Objeto con traducciones para el nombre del atributo. Las claves se especifican en la norma ISO 3166-1.
Ejemplo: {"en":"Attribute name","de":"Attributname"}
Ejemplo: [{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]
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:
Códigos lingüísticos de dos letras minúsculas.
Respuesta
application/json
{ "items": [ { … }, { … } ] }
Ruta
ID del proyecto. Encontrará este parámetro en su Cuenta del editor junto al nombre del proyecto y en la barra de direcciones del navegador cuando se trabaja en un proyecto. La URL tiene el siguiente formato: https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.
Ejemplo: 44056
- https://store.xsolla.com/api/v2/project/{project_id}/admin/items/game/sku/{item_sku}
- Mock serverhttps://xsolla.redocly.app/_mock/es/api/catalog/v2/project/{project_id}/admin/items/game/sku/{item_sku}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
'https://store.xsolla.com/api/v2/project/44056/admin/items/game/sku/booster_mega_1?promo_code=WINTER2021'El juego se recibió correctamente.
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"
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.
Any of:
Códigos lingüísticos de dos letras minúsculas.
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.
Any of:
Códigos lingüísticos de dos letras minúsculas.
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:
Códigos lingüísticos de dos letras minúsculas.
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"}]
Grupos a los que pertenece el artículo.
Ejemplo: [{"external_id":"horror","name":{"en":"Horror"}}]
Lista de atributos.
Ejemplo: [{"external_id":"attribute_external_id","name":{"en":"Attribute name","de":"Attributname"},"values":[{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]}]
ID único del atributo. external_id solo puede contener caracteres alfanuméricos latinos en minúsculas y mayúsculas, guiones y guiones bajos.
Ejemplo: "attribute_external_id"
Objeto con traducciones para el nombre del atributo. Las claves se especifican en la norma ISO 3166-1.
Ejemplo: {"en":"Attribute name","de":"Attributname"}
Ejemplo: [{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]
ID del valor único para un atributo. external_id solo puede contener caracteres alfanuméricos latinos en minúsculas, guiones y guiones bajos.
Ejemplo: "value_external_id"
Claves del juego para diferentes DRM (gestión de derechos digitales).
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"
Precios en monedas reales.
Ejemplo: [{"amount":1299.99,"currency":"RUB","is_default":true,"is_enabled":true,"country_is":"RU"}]
Divisa del precio del artículo. Código de tres letras según ISO 4217.
Ejemplo: "RUB"
El precio por defecto se utiliza para generar el catálogo si no se especifica el precio en la moneda del usuario.
País en el que está disponible este precio. Código de dos letras según la norma ISO 3166-1 alfa 2.
Ejemplo: "US"
Ejemplo: [{"sku":"com.xsolla.gold_1","name":{"en":"Gold"},"type":"virtual_currency","description":null,"image_url":"https://i.pinimg.com/originals/91/ae/56/91ae5683045f6dbef16b1482bade938f.png","amount":1000,"is_default":true}]
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: "gold"
Objeto con traducciones para el nombre de la moneda virtual. Las claves se especifican en la norma ISO 3166-1.
Ejemplo: {"en":"Gold"}
Tipo de artículo. En este caso es siempre virtual_currency.
Ejemplo: "virtual_currency"
Object with localizations for game description. Keys are specified in ISO 3166-1.
Ejemplo: {"en":"Game 1 Example"}
URL de la imagen.
Ejemplo: "https://image.example.com"
Si se deshabilita, el artículo no se puede comprar ni se puede acceder a este a través del inventario.
Icono del DRM de clave del juego.
Ejemplo: "https://upload.wikimedia.org/wikipedia/en/4/48/Steam_Icon_2014.png"
Configuración del pedido por anticipado.
Fecha de lanzamiento de la clave del juego en formato ISO 8601.
Si está deshabilitada, el artículo no es un pedido por anticipado.
Límites del artículo.
Limitación de artículos para un usuario independiente.
Número máximo de artículos que un mismo usuario puede comprar.
Determina la visibilidad del artículo en el catálogo tras alcanzar el límite de compra, hasta el siguiente restablecimiento del límite.
Se aplica a los artículos para los que se han configurado restablecimientos periódicos del límite en la matriz recurrent_schedule.
Si no están configurados los restablecimientos del límite, el artículo no aparecerá en el catálogo cuando se haya alcanzado el límite de compra, independientemente del valor de limit_exceeded_visibility.
Valores posibles:
show— El artículo se devuelve en las llamadas API de recuperación del catálogo tras alcanzar el límite de compra. En las llamadas API de recuperación del catálogo en el lado del cliente, tras alcanzar el límite, el artículo se devuelve con el indicadorcan_be_bought: false. La La próxima fecha de restablecimiento se devuelve el díareset_next_date.hide— El artículo no se devuelve en las llamadas API de recuperación del catálogo tras alcanzar el límite de compra, hasta que se restablezca ese límite.
Enumeración"show""hide"
Limitación global de artículos.
Número máximo de artículos que pueden comprar todos los usuarios.
Número restante de artículos que todos los usuarios pueden comprar.
Periodo de actualización del límite.
Periodo de actualización del límite del usuario.
One of:
Tipo diario de actualización del límite del usuario.
Tipo de periodo de actualización recurrente.
Valor"daily"
Hora de actualización del límite en la zona horaria deseada (redondeo a horas).
Ejemplo: "11:00:00+03:00"
Fecha y hora de actualización de los límites (Marca de tiempo Unix).
Ejemplo: 1677553200
Fecha y hora de la primera actualización del límite (ISO 8601).
Ejemplo: "2023-02-28T11:00:00+08:00"
Periodo de venta del artículo.
Fecha en la que el artículo especificado estará disponible para la venta.
Ejemplo: "2020-08-11T10:00:00+03:00"
Respuesta
application/json
{ "item_id": 1, "sku": "com.xsolla.game_1", "type": "unit", "name": { "en": "Game 1" }, "description": { "en": "Example game 1" }, "long_description": { "en": "Example game's long description" }, "image_url": "https://image.example.com", "media_list": [ { … } ], "order": 1, "groups": [ { … } ], "attributes": [ { … } ], "is_free": false, "is_enabled": true, "is_show_in_store": false, "unit_items": [ { … }, { … } ] }
Ruta
Cuerpoapplication/jsonrequeridoID del proyecto. Encontrará este parámetro en su Cuenta del editor junto al nombre del proyecto y en la barra de direcciones del navegador cuando se trabaja en un proyecto. La URL tiene el siguiente formato: https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.
Ejemplo: 44056
Objeto con datos del juego.
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"
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.
Ejemplo: {"en-US":"Game name","ru-RU":"Название игры"}
Any of:
Códigos lingüísticos de dos letras minúsculas.
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.
Ejemplo: {"en-US":"Game description","ru-RU":"Краткое описание игры"}
Any of:
Códigos lingüísticos de dos letras minúsculas.
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.
Ejemplo: {"en-US":"Game long description","ru-RU":"Полное описание игры"}
Any of:
Códigos lingüísticos de dos letras minúsculas.
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"}]
Grupos a los que pertenece el artículo.
Ejemplo: ["new_games"]
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.
ID único del atributo. external_id solo puede contener caracteres alfanuméricos latinos en minúsculas y mayúsculas, guiones y guiones bajos.
Objeto con traducciones para el nombre del atributo. Las claves se especifican en la norma ISO 3166-1.
Atención. No puede crear más de 6 valores para cada atributo. Cualquier intento de exceder el límite resultará en un error.
Ejemplo: [{"external_id":"strategy","value":{"en":"Strategy","de":"Strategie"}},{"external_id":"action","value":{"en":"Action","de":"Aktion"}}]
ID del valor único para un atributo. external_id solo puede contener caracteres alfanuméricos latinos en minúsculas, guiones y guiones bajos.
Ejemplo: "value_external_id"
Si se deshabilita, el artículo no se puede comprar ni se puede acceder a este a través del inventario.
Ejemplo: true
Claves del juego para diferentes DRM (gestión de derechos digitales).
Ejemplo: [{"sku":"com.xsolla.game_key_1","name":{"en-US":"Game key name","ru-RU":"Название игрового ключа"},"drm_sku":"steam_key_1","prices":[{"amount":35.5,"currency":"USD","is_enabled":true,"is_default":true}],"vc_prices":[{"amount":35.5,"sku":"com.xsolla.gold_1","is_enabled":true,"is_default":true}],"is_enabled":true,"is_free":false,"is_show_in_store":true,"pre_order":{"release_date":"2020-08-11T10:00:00+03:00","is_enabled":true,"description":"Some description"},"regions":[{"id":12},{"id":64}],"limits":{"per_user":{"total":5},"per_item":{"total":10000,"available":5000,"reserved":500,"sold":4500}},"periods":[{"date_from":"2020-08-11T10:00:00+03:00","date_until":"2020-08-11T20:00:00+03:00"}]}]
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"
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.
Any of:
Códigos lingüísticos de dos letras minúsculas.
Grupos a los que pertenece el artículo.
Lista de atributos.
Ejemplo: [{"external_id":"attribute_external_id","name":{"en":"Attribute name","de":"Attributname"},"values":[{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]}]
ID único del atributo. external_id solo puede contener caracteres alfanuméricos latinos en minúsculas y mayúsculas, guiones y guiones bajos.
Ejemplo: "attribute_external_id"
Objeto con traducciones para el nombre del atributo. Las claves se especifican en la norma ISO 3166-1.
Ejemplo: {"en":"Attribute name","de":"Attributname"}
Ejemplo: [{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]
ID del valor único para un atributo. external_id solo puede contener caracteres alfanuméricos latinos en minúsculas, guiones y guiones bajos.
Ejemplo: "value_external_id"
Precios en monedas reales.
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"
El precio por defecto se utiliza para generar el catálogo si no se especifica el precio en la moneda del usuario.
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: "gold"
Si se deshabilita, el artículo no se puede comprar ni se puede acceder a este a través del inventario.
Configuración del pedido por anticipado.
Fecha de lanzamiento de la clave del juego en formato ISO 8601.
Si está deshabilitada, el artículo no es un pedido por anticipado.
Límites del artículo.
Limitación de artículos para un usuario independiente.
Any of:
Limitación de artículos para un usuario independiente.
null
Periodo de actualización del límite.
One of:
Tipo diario de actualización del límite del usuario.
Periodo de actualización recurrente.
Valor"daily"
Periodo de venta del artículo.
Fecha en la que el artículo especificado estará disponible para la venta.
Ejemplo: "2020-08-11T10:00:00+03:00"
- https://store.xsolla.com/api/v2/project/{project_id}/admin/items/game/sku/{item_sku}
- Mock serverhttps://xsolla.redocly.app/_mock/es/api/catalog/v2/project/{project_id}/admin/items/game/sku/{item_sku}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PUT \
-u <username>:<password> \
https://store.xsolla.com/api/v2/project/44056/admin/items/game/sku/booster_mega_1 \
-H 'Content-Type: application/json' \
-d '{
"sku": "com.xsolla.game_1",
"name": {
"en-US": "Game name",
"ru-RU": "Название игры"
},
"description": {
"en-US": "Game description",
"ru-RU": "Краткое описание игры"
},
"long_description": {
"en-US": "Game long description",
"ru-RU": "Полное описание игры"
},
"image_url": "http://image.png",
"media_list": [
{
"type": "image",
"url": "http://image.png"
},
{
"type": "video",
"url": "http://video.png"
}
],
"groups": [
"new_games"
],
"is_enabled": true,
"is_show_in_store": true,
"unit_items": [
{
"sku": "com.xsolla.game_key_1",
"name": {
"en-US": "Game key name",
"ru-RU": "Название игрового ключа"
},
"drm_sku": "steam_key_1",
"prices": [
{
"amount": 35.5,
"currency": "USD",
"is_enabled": true,
"is_default": true
}
],
"vc_prices": [
{
"amount": 35.5,
"sku": "com.xsolla.gold_1",
"is_enabled": true,
"is_default": true
}
],
"is_enabled": true,
"is_free": false,
"is_show_in_store": true,
"pre_order": {
"release_date": "2020-08-11T10:00:00+03:00",
"is_enabled": true,
"description": "Some description"
},
"regions": [
{
"id": 12
},
{
"id": 64
}
],
"limits": {
"per_user": {
"total": 5
},
"per_item": {
"total": 10000,
"available": 5000,
"reserved": 500,
"sold": 4500
}
},
"periods": [
{
"date_from": "2020-08-11T10:00:00+03:00",
"date_until": "2020-08-11T20:00:00+03:00"
}
]
}
]
}'Descripción general
Bundles are sets of items sold as a single unit. A bundle can include virtual items, virtual currency, virtual currency packages, game keys, and other bundles. Use bundles to create starter packs, seasonal offers, and special deals.
Use the following API call groups to work with bundles:
- Use API calls from the Admin subsection to create, update, delete bundles, and manage their visibility.
- Use API calls from the Catalog subsection to retrieve bundles.
Purchase limits are configured via the limits object when creating or updating a bundle. For more information, refer to the Limits overview. You can also configure regional restrictions to sell items in specific countries.
Bundle management scenario:
- Create a bundle using the Create bundle API call. To verify the created bundle, use the Get bundle API call. To retrieve all bundles in the project, use the Get list of bundles API call.
- If needed, use the Update bundle API call to modify the bundle content or settings.
- Implement bundle display logic in your storefront using the Get list of bundles, Get specified bundle, or Get list of bundles by specified group API call.
- Create an order using the Cart and payment section. For example, for a fast purchase you can use the Create order with specified item API call, passing the bundle SKU. The response contains a token for opening the payment UI.
- Implement opening the payment UI to pay for the order.
- Set up order status tracking, for example using webhooks, to promptly receive data on successfully paid items and grant them to the user.
Descripción general
The cart is a purchasing mechanism that enables combining multiple items into a single order. A user can buy items of any type in any quantity for real currency, as well as use promo codes.
The cart is stored on the Xsolla side. Saving the cart across sessions depends on whether the user is authorized:
For authorized users, the cart is linked to a specific user and is saved across sessions as long as requests are sent on behalf of the same user.
For unauthorized users, saving the cart depends on passing the
x-unauthorized-idheader. To save the cart of an unauthorized user across sessions, pass the samex-unauthorized-idin every request. This option is available only for game key sales.
You can identify the cart in two ways: automatically by user's JWT or by cart ID (cart_id).
Cart management is available both on the client side and on the server side.
On the server side, you can fill the cart with items, e.g., when restoring a user session. The following actions are available on the client side:
- retrieve the current user's cart or a cart by ID
- fill the cart
- update items in the cart
- delete items from the cart
To purchase items from the cart, the client and server calls for order creation are used.
The cart’s time to live (TTL) is 72 hours by default. If its content changes, e.g., when a new item is added, the TTL is extended.
After successful payment, the cart isn’t cleared automatically. To clear the cart, use the following client-side API calls:
Delete cart item by cart ID and Delete cart item from current cart — the cart is cleared when you delete the last item from it.
Cart usage scenario:
Implement a store UI where the user will select items.
When the user selects items in the store, add them to the cart, e.g., using the Fill cart with items call. In the items array, you need to pass the SKUs and the required quantity of items.
Implement the cart viewing UI. When the user navigates to the cart, display its contents using the Get current user's cart call. The response will return information about the final price of the items, including discounts and applied promotions.
Implement the opening of the payment UI to pay for the order. For example, you can use the Create order with all items from particular cart call. The response returns a token to open the payment UI.
Configure order status tracking, e.g., using webhooks, to promptly receive data about successfully paid items and grant them to the user.
Note
To implement selling items in-game and online, refer to the integration guide.
Ciclo de vida del pedido
Comprender el ciclo de vida de un pedido le ayuda a hacer un seguimiento de los pedidos y a aplicar correctamente la lógica posterior a la compra, como, p. ej., la entrega de los artículos.
El pedido atraviesa los siguientes estados:
| Estado | Descripción | Notas |
new | Se creó el pedido. El sistema está a la espera de la confirmación del pago. | Las descripciones del estado de las transacciones pueden encontrarse en la documentación de la API de Pay Station. |
paid | El pedido se ha pagado (la transacción ha pasado al estado done), y ya se puede entregar el artículo al usuario. | El pedido seguirá en el estado new hasta que se confirme el pago. |
done | El artículo se concede al usuario. | — |
canceled | TSe reembolsó el pago. | El pedido pasa a este estado cuando el estado de la transacción cambia a refunded. |
expired | Al crear un nuevo pedido que incluya un artículo limitado, un código promocional o una promoción, cualquier pedido anterior pendiente de pago que contenga dicho artículo pasará al estado expired status. Solo se podrá pagar el pedido más reciente. | Si un usuario intenta pagar un pedido expirado, la interfaz de pago mostrará un error 2002, y el pago será rechazado. |
Nota:
Cuando el pedido pasa al estado expired mientras el usuario está realizando el pago, pero el pago se realiza correctamente, el pedido pasa de expired al estado paid. Esto solamente se aplica si, al realizar el pago, no se supera el límite de compra del artículo del pedido.
Artículos gratuitos
Use calls from this section to grant free items to users.
Operaciones
Descripción general
Los límites de compra permiten restringir la cantidad de artículos disponibles para la compra por un solo usuario o por todos los usuarios. También puede configurar restablecimientos programados de límites.
Los límites se almacenan en el lado de Xsolla y se configuran a nivel de artículo individual en la Cuenta del editor o a través del objeto limits en las siguientes llamadas API:
La información de los límites se devuelve en el objeto items.limits en las siguientes llamadas API para recuperar el catálogo de artículos:
- Obtener lista de artículos virtuales
- Obtener lista de monedas virtuales
- Obtener lista de paquetes de moneda virtual
- Obtener lista de lotes
- Obtener lista de juegos
Las llamadas de API en la subsección Gestión del grupo Límites le permiten recuperar el estado actual de los límites y actualizarlos para un usuario específico; por ejemplo, reiniciar el contador después de realizar una misión o ajustar manualmente la cantidad restante.
Nota:
Para obtener información detallada sobre cómo configurar límites en el catálogo, consulte la sección Límites de compra de artículos.
Para obtener información detallada sobre cómo configurar límites en el catálogo, consulte la sección Límites de compra de artículos.