Chino (simplificado)
API de catálogo (2.0.0)
- Version: 2.0.0
- Servers:
https://store.xsolla.com/api - Contact Us by Email
- Contact URL: https://xsolla.com/
- Required TLS version: 1.2
The Catalog API allows you to configure a catalog of in-game items on the Xsolla side and display the catalog to users in your store.
The API allows you to manage the following catalog entities:
- Virtual items — in-game items such as weapons, skins, boosters.
- Virtual currency — virtual money used to purchase virtual goods.
- Virtual currency packages — predefined bundles of virtual currency.
- Bundles — combined packages of virtual items, currency, or game keys sold as a single SKU.
- Game keys — keys for games and DLCs distributed via platforms like Steam or other DRM providers.
- Groups — logical groupings for organizing and sorting items within the catalog.
The API is divided into the following groups:
Admin — calls for creating, updating, deleting, and configuring catalog items and groups. Authenticated via basic access authentication with your merchant or project credentials. Not intended for storefront use.Catalog — calls for retrieving items and building custom storefronts for end users. Designed to handle high-load scenarios. Support optional user JWT authorization to return personalized data such as user-specific limits and active promotions.
API calls require authentication either on behalf of a user or on behalf of a project. The authentication scheme used is specified in the Security section in the description of each call.
User's JWT authentication is used when a request is sent from a browser, mobile application, or game. By default, the XsollaLoginUserJWT scheme is applied. For details on how to create a token, see the Xsolla Login API documentation.
The token is passed in the Authorization header in the following format: Authorization: Bearer <user_JWT>, where <user_JWT> is the user token. The token identifies the user and provides access to personalized data.
También puede utilizar un token para abrir la interfaz de pago.
Basic HTTP authentication is used for server-to-server interactions, when an API call is sent directly from your server rather than from a user's browser or mobile application. HTTP Basic authentication with an API key is typically used.
Note
The API key is confidential and must not be stored or used in client applications.
The API key is confidential and must not be stored or used in client applications.
With basic server-side authentication, all API requests must include the following header:
- for
basicAuth—Authorization: Basic <your_authorization_basic_key>, whereyour_authorization_basic_keyis theproject_id:api_keypair encoded in Base64 - for
basicMerchantAuth—Authorization: Basic <your_authorization_basic_key>, whereyour_authorization_basic_keyis themerchant_id:api_keypair encoded in Base64
You can find the parameter values in Publisher Account:
merchant_idis displayed:- In Company settings > Company.
- In the URL in the browser address bar on any Publisher Account page. The URL has the following format:
https://publisher.xsolla.com/<merchant_id>.
project_idis displayed:- Next to the project name in Publisher Account.
- In the URL in the browser address bar when working on a project in Publisher Account. The URL has the following format:
https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.
api_keyis shown in Publisher Account only at the time of creation and must be stored securely on your side. You can create an API key in the following sections:
Notice
If a required API call doesn't include the
If a required API call doesn't include the
project_id path parameter, use an API key that is valid across all company projects for authorization.For more information about working with API keys, see the API references.
El esquema de autenticación AuthForCart se utiliza para las compras con cesta y admite dos modos:
Authentication with a user's JWT. The token is passed in the
Authorizationheader in the following format:Authorization: Bearer <user_JWT>, where<user_JWT>is the user token. The token identifies the user and provides access to personalized data. Alternatively, you can use a token for opening the payment UI.Simplified mode without Authorization header. This mode is used only for unauthorized users and can be applied only for game key sales. Instead of a token, the request must include the following headers:
x-unauthorized-idwith a request IDx-userwith the user's email address encoded in Base64
Items of all types (virtual items, bundles, virtual currency, and keys) use a similar data structure. Understanding the basic structure simplifies working with the API and helps you navigate the documentation more easily.
Note
Some calls may include additional fields but they don't change the basic structure.
Some calls may include additional fields but they don't change the basic structure.
Identification
merchant_id— company ID in Publisher Accountproject_id— project ID in Publisher Accountsku— item SKU, unique within the project
Store display
name— item namedescription— item descriptionimage_url— image URLis_enabled— item availabilityis_show_in_store— whether the item is displayed in the catalog
For more information about managing item availability in the catalog, see the documentation.
Organization
type— item type, for example, a virtual item (virtual_item) or bundle (bundle)groups— groups the item belongs toorder— display order in the catalog
Sale conditions
prices— prices in real or virtual currencylimits— purchase limitsperiods— availability periodsregions— regional restrictions
Example of core entity structure:
{
"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": []
}The Xsolla API allows you to implement in-game store logic, including retrieving the item catalog, managing the cart, creating orders, and tracking their status. Depending on the integration scenario, API calls are divided into Admin and Catalog subsections, which use different authentication schemes.
The following example shows a basic flow for setting up and operating a store, from item creation to purchase.
Create an item catalog for your store, such as virtual items, bundles, or virtual currency.
Example API calls:
Configure user acquisition and monetization tools, such as discounts, bonuses, daily rewards, or offer chains.
Example API calls:
Configure item display in your application.
Notice
Do not use API calls from the Admin subsection to build a user catalog. These API calls have rate limits and aren't intended for user traffic.
Do not use API calls from the Admin subsection to build a user catalog. These API calls have rate limits and aren't intended for user traffic.
Example API calls:
Note
By default, catalog API calls return items that are currently available in the store at the time of the request. To retrieve items that are not yet available or are no longer available, include the parameter
By default, catalog API calls return items that are currently available in the store at the time of the request. To retrieve items that are not yet available or are no longer available, include the parameter
"show_inactive_time_limited_items": 1 in the catalog request.
You can sell items using the following methods:
- Fast purchase — sell one SKU multiple times.
- Cart purchase — the user adds items to the cart, removes items, and updates quantities within a single order.
If an item is purchased using virtual currency instead of real money, use the Create order with specified item purchased by virtual currency API call. The payment UI is not required, as the charge is processed when the API call is executed.
For free item purchase, use the Create order with specified free item API call or the Create order with free cart API call. The payment UI is not required — the order is immediately set to the done status.
Use the client-side API call to create an order with a specified item. The call returns a token used to open the payment UI.
Note
Discount information is available to the user only in the payment UI. Promo codes are not supported.
Discount information is available to the user only in the payment UI. Promo codes are not supported.
Cart setup and purchase can be performed on the client or on the server side.
Set up and purchase a cart on the client
Implement the logic of adding and removing items by yourself. Before calling the API for setting up a cart, you will not have information about which promotions will be applied to the purchase. This means that the total cost and details of the added bonus items will not be known.
Implement the following cart logic:
- After the player has filled a cart, use the Fill cart with items API call. The call returns the current information about the selected items (prices before and after discounts, bonus items).
- Update the cart contents based on user actions:
- To add an item or change item quantity, use the Update cart item by cart ID API call.
- To remove an item, use the Delete cart item by cart ID API call.
Note
To get the current status of the cart, use the Get current user's cart API call.
To get the current status of the cart, use the Get current user's cart API call.
- Use the Create order with all items from current cart API call. The call returns the order ID and payment token. The newly created order is set to
newstatus by default.
Set up and purchase a cart on the server
This setup option may take longer for setting the cart up, since each change to the cart must be accompanied by API calls.
Implement the following cart logic:
- After the player has filled a cart, use the Fill cart with items API call. The call returns current information about the selected items (prices before and after discounts, bonus items).
- Use the Create order with all items from current cart API call. The call returns the order ID and payment token. The newly created order is set to
newstatus by default.
Use the returned token to open the payment UI in a new window. Other ways to open the payment UI are described in the documentation.
| Action | Endpoint |
|---|---|
| Open in production environment. | https://secure.xsolla.com/paystation4/?token={token} |
| Open in sandbox mode. | https://sandbox-secure.xsolla.com/paystation4/?token={token} |
Note
Use sandbox mode during development and testing. Test purchases don't charge real accounts. You can use test bank cards.
Use sandbox mode during development and testing. Test purchases don't charge real accounts. You can use test bank cards.
After the first real payment is made, a strict sandbox payment policy takes effect. A payment in sandbox mode is available only to users specified in Publisher Account > Company settings > Users.
Buying virtual currency and items for real currency is possible only after signing a license agreement with Xsolla. To do this, in Publisher Account, go to Agreements & Taxes > Agreements, complete the agreement form, and wait for confirmation. It may take up to 3 business days to review the agreement.
To enable or disable sandbox mode, change the value of the sandbox parameter in the request for fast purchase and cart purchase. Sandbox mode is off by default.
Possible order statuses:
new— order createdpaid— payment receiveddone— item deliveredcanceled— order canceledexpired— order expired
Track order status using one of the following methods:
API calls that return large sets of records (for example, when building a catalog) return data in pages. Pagination is a mechanism that limits the number of items returned in a single API response and allows you to retrieve subsequent pages sequentially.
Use the following parameters to control the number of returned items:
limit— number of items per pageoffset— index of the first item on the page (numbering starts from 0)has_more— indicates whether another page is availabletotal_items_count— total number of items
Example request:
GET /items?limit=20&offset=40Response example:
{
"items": [...],
"has_more": true,
"total_items_count": 135
}It is recommended to send subsequent requests until the response returns has_more = false.
Dates and time values are passed in the ISO 8601 format.
The following are supported:
- UTC offset
nullvalue when there is no time restriction for displaying an item- Unix timestamp (in seconds) used in some fields
Format: YYYY-MM-DDTHH:MM:SS±HH:MM
Example: 2026-03-16T10:00:00+03:00
Xsolla supports localization of user-facing fields such as item name and description. Localized values are passed as an object where the language code is used as the key. The full list of supported languages is available in the documentation.
Supported fields
Localization can be specified for the following parameters:
namedescriptionlong_description
Locale format
The locale key can be specified in one of the following formats:
- Two-letter language code:
en,ru - Five-letter language code:
en-US,ru-RU,de-DE
Examples
Example with a two-letter language code:
{
"name": {
"en": "Starter Pack",
"ru": "Стартовый набор"
}
}Example with a five-letter language code:
{
"description": {
"en-US": "Premium bundle",
"de-DE": "Premium-Paket"
}
}The user's country determines catalog prices, the payment currency, and available payment methods in the payment UI. Depending on the API call, the country is determined as follows:
- In client-side API calls, the country is determined by the IP address of the request.
- In server-side API calls,
the country is determined by the value of the
user.country.valueparameter or by the user's IP address from theX-User-Ipheader. If both are passed, theuser.country.valueparameter takes precedence.
If an error occurs, the API returns an HTTP status and a JSON response body. The full list of store-related errors is available in the documentation.
Response example:
{
"errorCode": 1102,
"errorMessage": "Validation error",
"statusCode": 422,
"transactionId": "c9e1a..."
}errorCode— error code.errorMessage— short error description.statusCode— HTTP response status.transactionId— request ID. Returned only in some cases.errorMessageExtended— additional error details, such as request parameters. Returned only in some cases.
Extended response example:
{
"errorCode": 7001,
"errorMessage": "Chain not found",
"errorMessageExtended": {
"chain_id": "test_chain_id",
"project_id": "test_project_id",
"step_number": 2
},
"statusCode": 404
}Common HTTP status codes
400— invalid request401— authentication error403— insufficient permissions404— resource not found422— validation error429— rate limit exceeded
Recommendations
- Handle the HTTP status and the response body together.
- Use
errorCodeto process errors related to application logic. - Use
transactionIdto identify requests more quickly when analyzing errors.
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
Las claves de juego son códigos alfanuméricos únicos de un solo uso que permiten a los usuarios acceder a un juego o a contenido descargable (DLC) en las plataformas de videojuegos. Puede vender claves de juego a través de un enlace directo, mediante la interfaz de la tienda o mediante un widget. También puede configurar restricciones regionales para vender claves de juego en países específicos. Para obtener información detallada, consulte la sección Paquetes de claves de juego.
No es necesario autenticarse para vender claves de juego: las claves se envían a la dirección de correo electrónico que el usuario haya indicado al realizar la compra. Puede configurar la autenticación para habilitar otras opciones: personalización, límites de compra o un sistema de derechos. Para obtener información detallada, consulte la sección Cómo establecer la autenticación al vender claves de juego.
Flujo de ventas de claves de juego:
- Cree un juego mediante la llamada API Crear juego.
- Configure restricciones regionales.
- Suba las claves a un paquete de claves de juego mediante la llamada API Cargar códigos para que estén disponibles para su compra.
- Muestre el catálogo de juegos con los precios correspondientes a la región del usuario mediante la llamada API Obtener lista de juegos.
- Cree un pedido. Para una compra rápida, puede utilizar la llamada API Crear pedido con todos los artículos de la cesta actual, transmitiendo el SKU de la clave de juego. La respuesta devuelve un token para abrir la interfaz de pago.
- Implemente la apertura de la interfaz de pago para pagar el pedido.
Para recibir notificaciones inmediatas de los pagos completados y entregar los artículos al usuario, configure el seguimiento del estado de los pedidos, por ejemplo, mediante webhooks. Las claves se envían al correo electrónico que el usuario ha indicado al realizar la compra y el pedido pasa al estado done.
Descripción general
Los lotes son conjuntos de artículos que se venden como una sola unidad. Un lote puede incluir artículos virtuales, moneda virtual, paquetes de moneda virtual, claves de juego y otros lotes. Utilice los lotes para crear paquetes de bienvenida, ofertas de temporada y promociones especiales.
Utilice los siguientes grupos de llamadas API para trabajar con lotes:
- Utilice las llamadas API de la subsección Admin para crear, actualizar y eliminar lotes, así como para gestionar su visibilidad.
- Utilice las llamadas API de la subsección Catalog para obtener lotes.
Los límites de compra se configuran a través del objeto limits al crear o actualizar un lote. Para obtener más información, consulte la descripción general de Límites. También puede configurar restricciones regionales para vender artículos en países específicos.
Gestión de lotes:
- Cree un lote mediante la llamada API Crear lote. Para comprobar el lote creado, utilice la llamada API Obtener lote. Para obtener todos los lotes del proyecto, utilice la llamada API Obtener lista de lotes.
- Si es necesario, utilice la llamada API Actualizar lote para modificar el contenido o la configuración del lote.
- Implemente la lógica de visualización de los lotes en su escaparate utilizando la llamada API Obtener lista de lotes, Obtener lote especificado u Obtener lista de lotes por grupo especificado.
- Cree un pedido utilizando la sección Cesta y pago. Por ejemplo, para una compra rápida, puede utilizar la llamada API Crear pedido con un artículo especificado, transmitiendo el SKU del lote. La respuesta contiene un token para abrir la interfaz de pago.
- Implemente la apertura de la interfaz de pago para pagar el pedido.
- Configure el seguimiento del estado del pedido, por ejemplo, utilizando webhooks, para recibir rápidamente los datos sobre los artículos pagados y concedérselos al usuario.
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/bundle
- Mock serverhttps://xsolla.redocly.app/_mock/es/api/catalog/v2/project/{project_id}/admin/items/bundle
- 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/bundle?limit=50&offset=0'La lista de lotes 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.
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"}}]}]
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"
Tipo de lote. Se devuelve si el tipo de artículo es un lote.
Enum"standard""virtual_currency_package""partner_side_content"
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.
URL de la imagen. Para que la imagen se visualice correctamente y se cargue con rapidez en la interfaz de pago, consulte nuestras directrices sobre imágenes y URL:
- Formatos compatibles: WebP (recomendado), PNG y JPG.
- Tamaño del archivo: ≤ 50 KB (para WebP) o ≤ 150 KB (para PNG y JPG).
- Tamaño de la imagen: 280 x 280 píxeles.
- Espacio de color: sRGB.
- Protocolo: HTTPS con almacenamiento en caché de larga duración para las URL versionadas.
Si el artículo es o no una recompensa de pago aleatoria, p. ej., una caja de botín.
Grupos a los que pertenece el artículo.
Nombre del artículo. Debe contener pares clave/valor en los cuales clave es una configuración regional con formato "^[a-z]{2}", valor es una cadena (string).
Predeterminado {"en":"Horror"}
Ejemplo: {"en":"Horror","de":"Horror"}
Precios en monedas reales.
Divisa del precio del artículo. Código de tres letras según ISO 4217.
El precio por defecto se usa para crear un catálogo si no se especifica un 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"
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.
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.
URL de la imagen. Para que la imagen se visualice correctamente y se cargue con rapidez en la interfaz de pago, consulte nuestras directrices sobre imágenes y URL:
- Formatos compatibles: WebP (recomendado), PNG y JPG.
- Tamaño del archivo: ≤ 50 KB (para WebP) o ≤ 150 KB (para PNG y JPG).
- Tamaño de la imagen: 280 x 280 píxeles.
- Espacio de color: sRGB.
- Protocolo: HTTPS con almacenamiento en caché de larga duración para las URL versionadas.
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.
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.
URL de la imagen. Para que la imagen se visualice correctamente y se cargue con rapidez en la interfaz de pago, consulte nuestras directrices sobre imágenes y URL:
- Formatos compatibles: WebP (recomendado), PNG y JPG.
- Tamaño del archivo: ≤ 50 KB (para WebP) o ≤ 150 KB (para PNG y JPG).
- Tamaño de la imagen: 280 x 280 píxeles.
- Espacio de color: sRGB.
- Protocolo: HTTPS con almacenamiento en caché de larga duración para las URL versionadas.
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.
Enum"show""hide"
Limitación global de artículos.
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"
Un objeto JSON que contiene los atributos y valores del artículo.
Suma de los precios del contenido del lote.
Suma de los precios de los contenidos del lote con un descuento.
Ejemplo: "100.99"
Suma de los precios del contenido del lote.
Ejemplo: "100.99"
Divisa del precio del artículo. Código de tres letras según ISO 4217.
Respuesta
application/json
{ "items": [ { … }, { … } ] }
Solicitud
Crea un lote: un conjunto de artículos que se venden como una sola unidad. Un lote puede contener artículos virtuales, paquetes de moneda virtual, claves de juego y otros lotes. Para obtener más información, consulte la sección Lotes.
Aviso
Todos los artículos de la matriz
Todos los artículos de la matriz
content deben estar creados previamente en su proyecto. El sistema devuelve un error si el SKU indicado no existe.Seguridad
basicAuth
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 lote.
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.
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.
Nota. El valor de la cadena (string) se refiere al grupo `external_id`.
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"
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.
URL de la imagen. Para que la imagen se visualice correctamente y se cargue con rapidez en la interfaz de pago, consulte nuestras directrices sobre imágenes y URL:
- Formatos compatibles: WebP (recomendado), PNG y JPG.
- Tamaño del archivo: ≤ 50 KB (para WebP) o ≤ 150 KB (para PNG y JPG).
- Tamaño de la imagen: 280 x 280 píxeles.
- Espacio de color: sRGB.
- Protocolo: HTTPS con almacenamiento en caché de larga duración para las URL versionadas.
Precios en monedas reales.
Divisa del precio del artículo. Código de tres letras según ISO 4217.
El precio por defecto se usa para crear un catálogo si no se especifica un 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"
Any of:
Tipo de lote. Utilice standard para crear un lote con artículos y especifique los SKU de los artículos incluidos en el lote. Utilice partner_side_content para crear un lote vacío y añadir artículos en su lado utilizando un webhook. Este tipo solo se utiliza para la Personalización del catálogo en el lado del socio.
Enum"standard""partner_side_content"
Matriz de artículos incluidos en el lote. Cada entrada especifica el SKU y la cantidad del artículo. Todos los artículos deben haberse creado previamente en su proyecto. El sistema devuelve un error si el SKU especificado no existe.
Ejemplo: [{"sku":"com.xsolla.kg_1","quantity":1}]
SKU de un artículo que se va a incluir en el lote. El artículo debe haberse creado previamente en su proyecto. El sistema devuelve un error si el SKU especificado no existe. Caracteres permitidos: a–z, A–Z, 0–9, punto (.), guión (-), guión bajo (_).
Ejemplo: "com.xsolla.kg_1"
Si el artículo es o no una recompensa de pago aleatoria, p. ej., una caja de botín.
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.
Reinicio del límite de compra en el intervalo especificado en horas.
One of:
Reinicio del límite de compra en el intervalo especificado en horas.
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"
Un objeto JSON que contiene atributos y valores de artículos. Los artículos le permiten añadir más información a los artículos, tal como el nivel requerido del jugador para usar el artículo. Los atributos enriquecen la lógica interna del juego y son accesibles a través de métodos GET y webhooks específicos.
- https://store.xsolla.com/api/v2/project/{project_id}/admin/items/bundle
- Mock serverhttps://xsolla.redocly.app/_mock/es/api/catalog/v2/project/{project_id}/admin/items/bundle
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
https://store.xsolla.com/api/v2/project/44056/admin/items/bundle \
-H 'Content-Type: application/json' \
-d '{
"sku": "com.xsolla.armour_chest_1",
"name": {
"en": "Chest of armour",
"de": "Brustpanzer"
},
"is_enabled": true,
"is_free": true,
"is_paid_randomized_reward": true,
"order": 1,
"long_description": {
"en": "Chest of armour for soldiers",
"de": "Brustpanzer für Soldaten"
},
"description": {
"en": "Chest of armour for soldiers",
"de": "Brustpanzer für Soldaten"
},
"image_url": "https://picture.bundle-with-many-stuff.png",
"media_list": [
{
"type": "image",
"url": "https://test.com/image0"
},
{
"type": "image",
"url": "https://test.com/image1"
}
],
"groups": [
"chests"
],
"attributes": [
{
"external_id": "class",
"name": {
"en": "Class"
},
"values": [
{
"external_id": "soldier",
"value": {
"en": "Soldier"
}
},
{
"external_id": "officer",
"value": {
"en": "Officer"
}
}
]
}
],
"prices": [
{
"currency": "USD",
"amount": "9.99",
"is_default": true,
"is_enabled": true
},
{
"currency": "EUR",
"amount": "9.99",
"is_default": false,
"is_enabled": true
}
],
"vc_prices": [],
"content": [
{
"sku": "com.xsolla.iron_gloves_1",
"quantity": 1
},
{
"sku": "com.xsolla.iron_boots_1",
"quantity": 1
},
{
"sku": "com.xsolla.iron_shield_1",
"quantity": 1
},
{
"sku": "com.xsolla.iron_armour_1",
"quantity": 1
},
{
"sku": "com.xsolla.iron_helmet_1",
"quantity": 1
}
],
"limits": {
"per_user": null,
"per_item": null
},
"periods": [
{
"date_from": "2020-08-11T10:00:00+03:00",
"date_until": "2020-08-11T20:00:00+03:00"
}
],
"custom_attributes": {
"type": "lootbox",
"purchased": 0
}
}'Respuesta
application/json
{ "sku": "com.xsolla.kg_1" }
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/bundle/group/id/{group_id}
- Mock serverhttps://xsolla.redocly.app/_mock/es/api/catalog/v2/project/{project_id}/admin/items/bundle/group/id/{group_id}
- 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/bundle/group/id/10?limit=50&offset=0'La lista de lotes 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.
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"}}]}]
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"
Tipo de lote. Se devuelve si el tipo de artículo es un lote.
Enum"standard""virtual_currency_package""partner_side_content"
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.
URL de la imagen. Para que la imagen se visualice correctamente y se cargue con rapidez en la interfaz de pago, consulte nuestras directrices sobre imágenes y URL:
- Formatos compatibles: WebP (recomendado), PNG y JPG.
- Tamaño del archivo: ≤ 50 KB (para WebP) o ≤ 150 KB (para PNG y JPG).
- Tamaño de la imagen: 280 x 280 píxeles.
- Espacio de color: sRGB.
- Protocolo: HTTPS con almacenamiento en caché de larga duración para las URL versionadas.
Si el artículo es o no una recompensa de pago aleatoria, p. ej., una caja de botín.
Grupos a los que pertenece el artículo.
Nombre del artículo. Debe contener pares clave/valor en los cuales clave es una configuración regional con formato "^[a-z]{2}", valor es una cadena (string).
Predeterminado {"en":"Horror"}
Ejemplo: {"en":"Horror","de":"Horror"}
Precios en monedas reales.
Divisa del precio del artículo. Código de tres letras según ISO 4217.
El precio por defecto se usa para crear un catálogo si no se especifica un 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"
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.
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.
URL de la imagen. Para que la imagen se visualice correctamente y se cargue con rapidez en la interfaz de pago, consulte nuestras directrices sobre imágenes y URL:
- Formatos compatibles: WebP (recomendado), PNG y JPG.
- Tamaño del archivo: ≤ 50 KB (para WebP) o ≤ 150 KB (para PNG y JPG).
- Tamaño de la imagen: 280 x 280 píxeles.
- Espacio de color: sRGB.
- Protocolo: HTTPS con almacenamiento en caché de larga duración para las URL versionadas.
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.
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.
URL de la imagen. Para que la imagen se visualice correctamente y se cargue con rapidez en la interfaz de pago, consulte nuestras directrices sobre imágenes y URL:
- Formatos compatibles: WebP (recomendado), PNG y JPG.
- Tamaño del archivo: ≤ 50 KB (para WebP) o ≤ 150 KB (para PNG y JPG).
- Tamaño de la imagen: 280 x 280 píxeles.
- Espacio de color: sRGB.
- Protocolo: HTTPS con almacenamiento en caché de larga duración para las URL versionadas.
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.
Enum"show""hide"
Limitación global de artículos.
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"
Un objeto JSON que contiene los atributos y valores del artículo.
Suma de los precios del contenido del lote.
Suma de los precios de los contenidos del lote con un descuento.
Ejemplo: "100.99"
Suma de los precios del contenido del lote.
Ejemplo: "100.99"
Divisa del precio del artículo. Código de tres letras según ISO 4217.
Respuesta
application/json
{ "items": [ { … }, { … } ] }
Descripción general
La cesta es un mecanismo de compra que permite combinar múltiples artículos en un solo pedido. Un usuario puede comprar artículos de cualquier tipo en cualquier cantidad con moneda real, así como usar códigos promocionales.
La cesta se almacena en el lado de Xsolla. El almacenamiento de la cesta entre sesiones depende de si el usuario está autorizado:
En el caso de los usuarios autorizados, la cesta está vinculada a un usuario concreto y se guarda entre sesiones siempre que las solicitudes se envíen en nombre del mismo usuario.
Para los usuarios no autorizados, guardar la cesta depende de que se transmita el encabezado
x-unauthorized-id. Para guardar la cesta de un usuario no autorizado entre sesiones, transmita el mismox-unauthorized-iden cada solicitud. Esta opción solo está disponible para la venta de claves de juego.
Puede identificar la cesta de dos formas: automáticamente mediante el JWT del usuario o mediante el ID de la cesta (cart_id).
La gestión de la cesta está disponible tanto en el lado del cliente como en el lado del servidor.
En el lado del servidor, puede llenar la cesta con artículos; p. ej., al restaurar una sesión de usuario. Las siguientes acciones están disponibles en el lado del cliente:
- recuperar el carrito del usuario actual o una cesta mediante ID
- llenar la cesta
- actualizar artículos en la cesta
- eliminar artículos de la cesta
Para comprar artículos de la cesta, se usan llamadas del cliente y del servidor para la creación de pedidos.
El tiempo de vida (TTL) de la cesta es de 72 horas por defecto. Si su contenido cambia, por ejemplo, al añadir un artículo nuevo, el TTL se prolonga.
Una vez realizado el pago correctamente, la cesta no se vacía automáticamente. Para vaciar la cesta, utilice las siguientes llamadas API del lado del cliente:
Eliminar todos los artículos de la cesta por el ID de la cesta.
Eliminar artículo de la cesta por ID de la cesta y Eliminar artículo de la cesta actual: la cesta se vacía cuando se elimina el último artículo de la misma.
Escenario de uso de la cesta:
Implemente una interfaz de tienda en la que el usuario pueda seleccionar artículos.
Cuando el usuario seleccione artículos en la tienda, añádalos a la cesta, por ejemplo, utilizando la llamada Llenar la cesta con artículos. En la matriz de artículos, debe transmitir los SKU y la cantidad requerida de artículos.
Implemente la interfaz de visualización de la cesta. Cuando el usuario acceda a la cesta, muestre su contenido mediante la llamada Obtener la cesta del usuario actual. La respuesta proporcionará información sobre el precio final de los artículos, incluidos los descuentos y las promociones aplicadas.
Implemente la apertura de la interfaz de pago para abonar el pedido. Por ejemplo, puede utilizar la llamada Crear pedido con todos los artículos de la cesta. La respuesta devuelve un token para abrir la interfaz de pago.
Configure el seguimiento del estado de los pedidos, por ejemplo, mediante webhooks, para recibir sin demora los datos sobre los artículos cuyo pago se ha completado correctamente y concedérselos al usuario.
Nota:
Para implementar la venta de artículos dentro del juego y en línea, consulte la guía de integración.
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
Utilice las llamadas de esta sección para conceder artículos gratuitos a los usuarios.
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.
Regiones comunes
Las restricciones de venta regionales le permiten gestionar la disponibilidad de los artículos en países concretos o grupos de países. Por ejemplo, puede vender un videojuego únicamente en algunos países por restricciones de licencia.
Las restricciones se configuran mediante regiones. Cada región agrupa uno o varios países bajo un único identificador region_id. Puede vincular un artículo a una o varias regiones.
La disponibilidad de los artículos se determina de la siguiente forma:
- Si no se especifican regiones para un artículo, este está disponible para su compra en todos los países. * Si se especifican regiones para un artículo y el país del usuario está incluido en alguna de ellas, el artículo está disponible para este usuario. * Si se especifican regiones para un artículo y el país del usuario no está incluido en ninguna de ellas, el artículo no está disponible para este usuario.
El país del usuario se transmite en el parámetro country al solicitar el catálogo mediante llamadas API desde la subsección Catalog. Si no se transmite dicho parámetro, el país se determina en función de la dirección IP del usuario.
El país del usuario se coteja con las regiones del artículo en dos ocasiones: al solicitar el catálogo y al crear un pedido. Los artículos no disponibles no se incluyen en la respuesta del catálogo y no se creará ningún pedido que contenga dichos artículos.
Utilice las llamadas API del grupo Common regions para crear, actualizar y eliminar regiones.
Proceso de configuración de las restricciones de ventas regionales:
- Cree una región mediante la llamada API Crear región, especificando la lista de países. La respuesta devuelve un
region_idque se necesita en el siguiente paso. - Vincule un artículo virtual a la región transmitiendo su
region_iden la matrizregionsal crear o actualizar el artículo. - Muestre el catálogo al usuario mediante llamadas API de la subsección Catalog, por ejemplo, la llamada API Obtener lista de artículos virtuales. El país del usuario se determina mediante el parámetro
countryo, si no se proporciona, a partir de la dirección IP del usuario. Los artículos no disponibles en el país del usuario no se incluyen en la respuesta del catálogo. - Cuando el usuario proceda a pagar un artículo o la cesta, cree un pedido:
- Si el artículo se ha añadido a la cesta, mediante la llamada API Crear pedido con todos los artículos de la cesta o Crear pedido con todos los artículos de la cesta actual.
- Para una compra rápida de un único artículo, mediante la llamada API Crear pedido con un artículo especificado, transmitiendo el SKU del artículo.
La respuesta contiene un token para abrir la interfaz de pago.
Nota
Xsolla comprueba si el país del usuario está incluido en la región especificada para el artículo. Si el país no está incluido en la región del artículo, no se podrá crear el pedido.
Xsolla comprueba si el país del usuario está incluido en la región especificada para el artículo. Si el país no está incluido en la región del artículo, no se podrá crear el pedido.
- Implemente la apertura de la interfaz de pago para pagar el pedido.
Operaciones