Saltar al contenido

API de catálogo (2.0.0)

Descripción general

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

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

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

Llamadas API

La API se divide en los siguientes grupos:

  • Admin: llamadas para crear, actualizar, eliminar y configurar artículos de catálogo y grupos. La autenticación se realiza mediante autenticación de acceso básica con sus credenciales de comerciante o de proyecto. No está diseñado para uso en escaparates.
  • Catalog: llamadas para buscar artículos y crear escaparates personalizados para los usuarios finales. Diseñado para gestionar situaciones de alta carga. Admite la autorización JWT opcional de usuarios para devolver datos personalizados, como límites específicos para determinados usuarios y promociones activas.

Autenticación

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.

Autenticación mediante el JWT del usuario

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.

Autenticación HTTP básica

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.

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 que your_authorization_basic_key es el par project_id:api_key codificado en Base64
  • para basicMerchantAuth — Authorization: Basic <your_authorization_basic_key>, en las que your_authorization_basic_key es el par merchant_id:api_key codificado 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_key se 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 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.

Autenticación con compatibilidad con el acceso de invitado

El esquema de autenticación AuthForCart se utiliza para las compras con cesta y admite dos modos:

  1. Autenticación mediante el JWT del usuario. El token se transmite en el encabezado Authorization con 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.

  2. 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-id con un ID de solicitud
    • x-user con la dirección de correo electrónico del usuario codificada en Base64

Estructura de la entidad principal

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.

Identificación

  • merchant_id — ID de la empresa en Cuenta del editor
  • project_id — ID del proyecto en Cuenta del editor
  • sku — SKU del artículo, único dentro del proyecto

Visualización en la tienda

  • name — nombre del artículo
  • description — descripción del artículo
  • image_url — URL de la imagen
  • is_enabled — disponibilidad del artículo
  • is_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ículo
  • order — orden de visualización en el catálogo

Condiciones de venta

  • prices — precios en moneda real o virtual
  • limits — límites de compra
  • periods — periodos de disponibilidad
  • regions — 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": []
}

Flujo de compra básico

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.

Crear artículos y grupos (Admin)

Cree un catálogo de artículos para su tienda, como artículos virtuales, lotes o moneda virtual.

Ejemplos de llamadas API:

Establecer promociones, cadenas y límites (Admin)

Configure herramientas de adquisición de usuarios y monetización, como descuentos, bonificaciones, recompensas diarias o cadenas de ofertas.

Ejemplos de llamadas API:

Obtener información del artículo (cliente)

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.

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 "show_inactive_time_limited_items": 1 en la solicitud del catálogo.

Vender artículos

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.

Compra rápida

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.

Compra con cesta

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:

  1. 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).
  2. Actualice el contenido de la cesta basándose en las acciones de los usuarios:
Nota:

Para obtener el estado actual de la cesta, utilice la llamada API Obtener la cesta del usuario actual.
  1. 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:

  1. 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).
  2. 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.

Abrir interfaz de pago

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ónPunto 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.

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 creado
  • paid: pago recibido
  • done: artículo entregado
  • canceled: pedido cancelado
  • expired: pedido expirado

Haga un seguimiento del estado del pedido usando uno de los siguientes métodos:

Paginación

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ágina
  • offset — índice del primer artículo de la página (la numeración comienza desde 0)
  • has_more — indica si hay otra página disponible
  • total_items_count — número total de artículos

Ejemplo de solicitud:

GET /items?limit=20&offset=40

Ejemplo de respuesta:

{
  "items": [...],
  "has_more": true,
  "total_items_count": 135
}

Se recomienda enviar solicitudes posteriores hasta que la respuesta devuelva has_more = false.

Formato de fecha y hora

Las fechas y valores de tiempo se transmiten en el formato ISO 8601.

Se admiten los siguientes:

  • Desfase UTC (tiempo universal coordinado)
  • Valor null cuando 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

Localización

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:

  • name
  • description
  • long_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"
  }
}

Formato de respuesta de error

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álida
  • 401 — error de autenticación
  • 403 — permisos insuficientes
  • 404 — recurso no encontrado
  • 422 — error de validación
  • 429 — límite de frecuencia excedido

Recomendaciones

  • Gestione el estado HTTP y el cuerpo de la respuesta juntos.
  • Utilice errorCode para procesar errores relacionados con la lógica de la aplicación.
  • Utilice transactionId para identificar solicitudes más rápidamente al analizar errores.
Descargar descripción de OpenAPI
index.json
index.yaml
Idiomas
Servidores
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/es/api/catalog/

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.

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.

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:

Ejemplo de flujo de compra con moneda virtual

Admin

Operaciones

Catálogo

Operaciones

Obtener lista de artículos virtualesClient-side

Solicitud

Obtiene una lista de artículos virtuales para crear un catálogo.

Aviso:

Todos los proyectos tienen la limitación en el número de artículos que puede obtener en la respuesta. El valor predeterminado y máximo es 50 artículos por cada respuesta. Para obtener más datos página por página, utilice los campos límite y offset.

Nota:

Esta llamada de API devuelve datos genéricos del catálogo de artículos cuando se utiliza sin autorización. Usa la autorización para recuperar datos personalizados del usuario, como límites y promociones asociadas con el artículo. Para hacer esto, transmita el JWT del usuario en el encabezado Authorization. Para obtener más información sobre el JWT del usuario, consulte el bloque Seguridad para esta llamada.


Ver también: La llamada API Obtener la lista de todos los artículos virtuales para búsqueda o indexación en el lado del cliente.

Seguridad
XsollaLoginUserJWT
Ruta
project_idintegerrequerido

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
Consulta
limitinteger>= 1

Límite para el número de elementos presentes en la página.

Ejemplo: limit=50
offsetinteger>= 0

Número del elemento a partir del cual se genera la lista (el conteo empieza desde el 0).

Ejemplo: offset=0
localestring

Idioma de respuesta. Código de idioma de dos letras minúsculas según la norma ISO 639-1. (p. ej., en). Los códigos de configuración regional de cinco caracteres (p. ej., en-US) se admiten en campos de localización como name y description, pero se normalizan como códigos de dos letras en las respuestas. Puede consultar la lista completa de idiomas admitidos en la documentación.

Predeterminado "en"
additional_fields[]Array of strings

La lista de campos adicionales. Estos campos estarán en la respuesta si los envía en su solicitud.

Elementos Enumeración"media_list""order""long_description""custom_attributes""item_order_in_group"
countrystring

Código de país de dos letras mayúsculas de conformidad con la norma ISO 3166-1 alpha-2. Consulte la documentación para obtener información detallada sobre los países admitidos por Xsolla y el proceso de determinación del país.

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

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

Ejemplo: promo_code=WINTER2021
show_inactive_time_limited_itemsinteger

Muestra los artículos de duración limitada que no están disponibles para el usuario. El periodo de validez de dichos artículos no ha comenzado o ya ha expirado.

Predeterminado 0
Ejemplo: show_inactive_time_limited_items=1
curl -i -X GET \
  'https://store.xsolla.com/api/v2/project/44056/items/virtual_items?limit=50&offset=0&locale=en&additional_fields%5B%5D=media_list&country=US&promo_code=WINTER2021&show_inactive_time_limited_items=1' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Respuestas

La lista de artículos virtuales se recibió correctamente.

Cuerpoapplication/json
has_moreboolean(Pagination_has-more)

Se utiliza como indicador de que hay más páginas.

itemsArray of objects(Virtual-Items-Currency_item)
items[].​item_idnumber

ID del artículo.

items[].​skustring

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

Ejemplo: "big_rocket"
items[].​nameobject

Nombre del artículo.

Ejemplo: "Big Rocket"
items[].​name.​property name*string or nullpropiedad adicional
items[].​groupsArray of objects(items_client_groups_response)

Grupos a los que pertenece el artículo.

items[].​groups[].​external_idstring

Un identificador único para el grupo, que suele utilizarse para referenciarlo en solicitudes de API o en sistemas externos.

Ejemplo: "exclusive"
items[].​groups[].​namestring

Nombre del grupo.

Ejemplo: "Exclusive"
items[].​groups[].​item_order_in_groupinteger

Posición del artículo dentro del grupo, que se emplea para determinar su orden de visualización. Este campo solamente se incluye en la respuesta si se solicita mediante el parámetro de consulta additional_fields[].

Ejemplo: 1
items[].​attributesArray of objects(Virtual-Items-Currency_client-attributes)

Lista de atributos y sus valores correspondientes al artículo. Puede utilizarse para filtrar el catálogo.

items[].​attributes[].​external_idstring(admin-attribute-external_id)[ 1 .. 255 ] characters^[a-zA-Z0-9-_]+$

ID único del atributo. external_id solo puede contener caracteres alfanuméricos latinos en minúsculas y mayúsculas, guiones y guiones bajos.

items[].​attributes[].​nameobject

Nombre del atributo.

Ejemplo: "Genre"
items[].​attributes[].​name.​property name*string or nullpropiedad adicional
items[].​attributes[].​valuesArray of objects
items[].​attributes[].​values[].​external_idstring(value-external_id)[ 1 .. 255 ] characters^[-_.\d\w]+$

ID del valor único para un atributo. external_id solo puede contener caracteres alfanuméricos latinos en minúsculas, guiones y guiones bajos.

items[].​attributes[].​values[].​valuestring

Valor del atributo.

Ejemplo: "Strategy"
items[].​typestring

Tipo de artículo: virtual_good/virtual_currency/bundle.

Ejemplo: "virtual_good"
items[].​descriptionobject

Descripción del artículo.

Ejemplo: "Big Rocket - description"
items[].​description.​property name*string or nullpropiedad adicional
items[].​image_urlstring

URL de la imagen.

Ejemplo: "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png"
items[].​is_freeboolean(value-is_free)

Si el artículo es gratuito.

items[].​priceobject or null

Precios de artículos.

items[].​price.​amountstring

Precio del artículo con descuento.

Ejemplo: "100.99"
items[].​price.​amount_without_discountstring

Precio del artículo.

Ejemplo: "100.99"
items[].​price.​currencystring

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: "USD"
items[].​virtual_pricesArray of objects

Precios virtuales.

items[].​virtual_prices[].​amountinteger

Precio del artículo con descuento en moneda virtual.

Ejemplo: 100
items[].​virtual_prices[].​amount_without_discountinteger

Precio del artículo.

Ejemplo: 200
items[].​virtual_prices[].​skustring

SKU del artículo de la moneda virtual.

Ejemplo: "vc_test"
items[].​virtual_prices[].​is_defaultboolean

Si el precio está predeterminado para el artículo.

Ejemplo: true
items[].​virtual_prices[].​image_urlstring

Imagen de la moneda virtual.

Ejemplo: "http://image.png"
items[].​virtual_prices[].​namestring

Nombre de la moneda virtual.

Ejemplo: "SHOTGUN FOR TRUE RAIDERS"
items[].​virtual_prices[].​typestring

Tipo de moneda virtual.

Ejemplo: "virtual_currency"
items[].​virtual_prices[].​descriptionstring

Virtual currency description.

Ejemplo: "Big Rocket - description"
items[].​can_be_boughtboolean(Can_be_bought)

Si es true, el usuario puede comprar un artículo.

items[].​virtual_item_typestring

Tipo de artículo virtual.

Valores posibles:

  • consumable: Un objeto que desaparece del inventario tras su utilización (p. ej., munición).
  • non_consumable: Un objeto que permanece en el inventario durante un tiempo ilimitado.
  • non_renewing_subscription: Objeto de duración limitada que puede representar el acceso a servicios o contenidos durante un periodo limitado.
Enumeración"consumable""non_consumable""non_renewing_subscription"
Ejemplo: "non-consumable"
items[].​promotionsArray of objects(Catalog_item_promotions)

Promociones aplicadas para artículos específicos de la cesta. La matriz se devuelve en los siguientes casos:

  • Se configura un descuento promocional para un artículo específico.

  • Se aplica un código promocional con el parámetro Descuento en artículos seleccionados.

Si no se aplican promociones a nivel de artículo, se devuelve una matriz vacía.

items[].​promotions[].​namestring
items[].​promotions[].​date_startstring or null(date-time)
items[].​promotions[].​date_endstring or null(date-time)
items[].​promotions[].​discountobject or null
items[].​promotions[].​discount.​percentstring or null
items[].​promotions[].​discount.​valuestring or null
items[].​promotions[].​bonusArray of objects
items[].​promotions[].​bonus[].​skustring
items[].​promotions[].​bonus[].​quantityinteger
items[].​promotions[].​bonus[].​typestring

Tipo de artículo de bonificación.

Enumeración"virtual_good""virtual_currency""bundle""physical_good""game_key""nft"
items[].​promotions[].​bonus[].​namestring

Nombre del artículo de bonificación. No disponible para el tipo de artículo de bonificación physical_good.

items[].​promotions[].​bonus[].​image_urlstring

URL de la imagen del artículo de bonificación. No disponible para el tipo de artículo de bonificación physical_good.

items[].​promotions[].​bonus[].​bundle_typestring

Tipo de artículo del lote de bonificación. Disponible solo para el tipo de artículo de bonificación bundle.

Enumeración"standard""virtual_currency_package"
items[].​promotions[].​limitsobject
items[].​promotions[].​limits.​per_userobject
items[].​promotions[].​limits.​per_user.​availableinteger
items[].​promotions[].​limits.​per_user.​totalinteger
items[].​limitsobject or null(client-item-limit-response)

Límites del artículo.

items[].​limits.​per_userobject or null

Limitación de artículos para un usuario independiente.

items[].​limits.​per_user.​totalinteger

Número máximo de artículos que un mismo usuario puede comprar.

items[].​limits.​per_user.​availableinteger

Número restante de artículos que el usuario actual puede comprar.

items[].​limits.​per_user.​recurrent_schedule(object or null)(catalog_recurrent_schedule_client_response)
One of:

Periodo de actualización recurrente de los límites del artículo para un usuario.

object or null
items[].​limits.​per_user.​limit_exceeded_visibilitystring(limit_exceeded_visibility)

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 indicador can_be_bought: false. La La próxima fecha de restablecimiento se devuelve el día reset_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"
items[].​limits.​per_itemobject or null

Limitación global de artículos.

items[].​limits.​per_item.​totalinteger

Número máximo de artículos que pueden comprar todos los usuarios.

items[].​limits.​per_item.​availableinteger

Número restante de artículos que todos los usuarios pueden comprar.

items[].​periodsArray of objects(item-periods-response)

Periodo de venta del artículo.

items[].​periods[].​date_fromstring or null(date-time)

Fecha en la que el artículo especificado estará disponible para la venta.

Ejemplo: "2020-08-11T10:00:00+03:00"
items[].​periods[].​date_untilstring or null(date-time)

Fecha en la que el artículo especificado dejará de estar disponible para la venta. Puede ser null.

Ejemplo: "2020-08-11T20:00:00+03:00"
items[].​custom_attributesobject(json)(item-custom-attributes-response)

Un objeto JSON que contiene los atributos y valores del artículo.

items[].​vp_rewardsArray of objects(client-item-value-point-reward)

Recompensa de artículo del punto de valor.

items[].​vp_rewards[].​item_idinteger(item_id)

ID único interno del artículo.

items[].​vp_rewards[].​skustring(value-point-sku)

ID único del punto de valor.

items[].​vp_rewards[].​amountinteger(value-point-amount)

Cantidad de puntos de valor.

items[].​vp_rewards[].​namestring(value-point-name)

Nombre del punto de valor.

items[].​vp_rewards[].​image_urlstring(Common_admin-image_url)

URL de la imagen.

items[].​vp_rewards[].​is_clanboolean(is_clan)

Si el punto de valor se utiliza en las cadenas de recompensas de clanes.

Respuesta
application/json
{
  "has_more": true,
  "items": [
    { … },
    { … },
    { … }
  ]
}

Obtener artículo virtual por SKUClient-side

Solicitud

Obtiene un artículo virtual por SKU para crear un catálogo.

Aviso:

Esta llamada API devuelve datos genéricos del catálogo de artículos cuando se usa sin autorización. Utilice la autorización para recuperar datos de usuario personalizados, como límites y promociones asociadas al artículo. Para hacerlo, transmita el JWT del usuario en el encabezado Authorization. Para obtener más información sobre el JWT del usuario, consulte el bloque de Seguridad para esta llamada.
Seguridad
XsollaLoginUserJWT
Ruta
project_idintegerrequerido

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
item_skustringrequerido

Código (SKU) del artículo.

Ejemplo: booster_mega_1
Consulta
localestring

Idioma de respuesta. Código de idioma de dos letras minúsculas según la norma ISO 639-1. (p. ej., en). Los códigos de configuración regional de cinco caracteres (p. ej., en-US) se admiten en campos de localización como name y description, pero se normalizan como códigos de dos letras en las respuestas. Puede consultar la lista completa de idiomas admitidos en la documentación.

Predeterminado "en"
countrystring

Código de país de dos letras mayúsculas de conformidad con la norma ISO 3166-1 alpha-2. Consulte la documentación para obtener información detallada sobre los países admitidos por Xsolla y el proceso de determinación del país.

Ejemplo: country=US
show_inactive_time_limited_itemsinteger

Muestra los artículos de duración limitada que no están disponibles para el usuario. El periodo de validez de dichos artículos no ha comenzado o ya ha expirado.

Predeterminado 0
Ejemplo: show_inactive_time_limited_items=1
additional_fields[]Array of strings

La lista de campos adicionales. Estos campos estarán en la respuesta si los envía en su solicitud.

Elementos Enumeración"media_list""order""long_description""custom_attributes""item_order_in_group"
curl -i -X GET \
  'https://store.xsolla.com/api/v2/project/44056/items/virtual_items/sku/booster_mega_1?locale=en&country=US&show_inactive_time_limited_items=1&additional_fields%5B%5D=media_list' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Respuestas

El artículo virtual se recibió correctamente.

Cuerpoapplication/json
item_idnumber

ID del artículo.

skustring

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

Ejemplo: "big_rocket"
nameobject

Nombre del artículo.

Ejemplo: "Big Rocket"
name.​property name*string or nullpropiedad adicional
groupsArray of objects(items_client_groups_response)

Grupos a los que pertenece el artículo.

groups[].​external_idstring

Un identificador único para el grupo, que suele utilizarse para referenciarlo en solicitudes de API o en sistemas externos.

Ejemplo: "exclusive"
groups[].​namestring

Nombre del grupo.

Ejemplo: "Exclusive"
groups[].​item_order_in_groupinteger

Posición del artículo dentro del grupo, que se emplea para determinar su orden de visualización. Este campo solamente se incluye en la respuesta si se solicita mediante el parámetro de consulta additional_fields[].

Ejemplo: 1
attributesArray of objects(Virtual-Items-Currency_client-attributes)

Lista de atributos y sus valores correspondientes al artículo. Puede utilizarse para filtrar el catálogo.

attributes[].​external_idstring(admin-attribute-external_id)[ 1 .. 255 ] characters^[a-zA-Z0-9-_]+$

ID único del atributo. external_id solo puede contener caracteres alfanuméricos latinos en minúsculas y mayúsculas, guiones y guiones bajos.

attributes[].​nameobject

Nombre del atributo.

Ejemplo: "Genre"
attributes[].​name.​property name*string or nullpropiedad adicional
attributes[].​valuesArray of objects
attributes[].​values[].​external_idstring(value-external_id)[ 1 .. 255 ] characters^[-_.\d\w]+$

ID del valor único para un atributo. external_id solo puede contener caracteres alfanuméricos latinos en minúsculas, guiones y guiones bajos.

attributes[].​values[].​valuestring

Valor del atributo.

Ejemplo: "Strategy"
typestring

Tipo de artículo: virtual_good/virtual_currency/bundle.

Ejemplo: "virtual_good"
descriptionobject

Descripción del artículo.

Ejemplo: "Big Rocket - description"
description.​property name*string or nullpropiedad adicional
image_urlstring

URL de la imagen.

Ejemplo: "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png"
is_freeboolean(value-is_free)

Si el artículo es gratuito.

priceobject or null

Precios de artículos.

price.​amountstring

Precio del artículo con descuento.

Ejemplo: "100.99"
price.​amount_without_discountstring

Precio del artículo.

Ejemplo: "100.99"
price.​currencystring

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: "USD"
virtual_pricesArray of objects

Precios virtuales.

virtual_prices[].​amountinteger

Precio del artículo con descuento en moneda virtual.

Ejemplo: 100
virtual_prices[].​amount_without_discountinteger

Precio del artículo.

Ejemplo: 200
virtual_prices[].​skustring

SKU del artículo de la moneda virtual.

Ejemplo: "vc_test"
virtual_prices[].​is_defaultboolean

Si el precio está predeterminado para el artículo.

Ejemplo: true
virtual_prices[].​image_urlstring

Imagen de la moneda virtual.

Ejemplo: "http://image.png"
virtual_prices[].​namestring

Nombre de la moneda virtual.

Ejemplo: "SHOTGUN FOR TRUE RAIDERS"
virtual_prices[].​typestring

Tipo de moneda virtual.

Ejemplo: "virtual_currency"
virtual_prices[].​descriptionstring

Virtual currency description.

Ejemplo: "Big Rocket - description"
can_be_boughtboolean(Can_be_bought)

Si es true, el usuario puede comprar un artículo.

virtual_item_typestring

Tipo de artículo virtual.

Valores posibles:

  • consumable: Un objeto que desaparece del inventario tras su utilización (p. ej., munición).
  • non_consumable: Un objeto que permanece en el inventario durante un tiempo ilimitado.
  • non_renewing_subscription: Objeto de duración limitada que puede representar el acceso a servicios o contenidos durante un periodo limitado.
Enumeración"consumable""non_consumable""non_renewing_subscription"
Ejemplo: "non-consumable"
promotionsArray of objects(Catalog_item_promotions)

Promociones aplicadas para artículos específicos de la cesta. La matriz se devuelve en los siguientes casos:

  • Se configura un descuento promocional para un artículo específico.

  • Se aplica un código promocional con el parámetro Descuento en artículos seleccionados.

Si no se aplican promociones a nivel de artículo, se devuelve una matriz vacía.

promotions[].​namestring
promotions[].​date_startstring or null(date-time)
promotions[].​date_endstring or null(date-time)
promotions[].​discountobject or null
promotions[].​discount.​percentstring or null
promotions[].​discount.​valuestring or null
promotions[].​bonusArray of objects
promotions[].​bonus[].​skustring
promotions[].​bonus[].​quantityinteger
promotions[].​bonus[].​typestring

Tipo de artículo de bonificación.

Enumeración"virtual_good""virtual_currency""bundle""physical_good""game_key""nft"
promotions[].​bonus[].​namestring

Nombre del artículo de bonificación. No disponible para el tipo de artículo de bonificación physical_good.

promotions[].​bonus[].​image_urlstring

URL de la imagen del artículo de bonificación. No disponible para el tipo de artículo de bonificación physical_good.

promotions[].​bonus[].​bundle_typestring

Tipo de artículo del lote de bonificación. Disponible solo para el tipo de artículo de bonificación bundle.

Enumeración"standard""virtual_currency_package"
promotions[].​limitsobject
promotions[].​limits.​per_userobject
promotions[].​limits.​per_user.​availableinteger
promotions[].​limits.​per_user.​totalinteger
limitsobject or null(client-item-limit-response)

Límites del artículo.

limits.​per_userobject or null

Limitación de artículos para un usuario independiente.

limits.​per_user.​totalinteger

Número máximo de artículos que un mismo usuario puede comprar.

limits.​per_user.​availableinteger

Número restante de artículos que el usuario actual puede comprar.

limits.​per_user.​recurrent_schedule(object or null)(catalog_recurrent_schedule_client_response)
One of:

Periodo de actualización recurrente de los límites del artículo para un usuario.

object or null
limits.​per_user.​limit_exceeded_visibilitystring(limit_exceeded_visibility)

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 indicador can_be_bought: false. La La próxima fecha de restablecimiento se devuelve el día reset_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"
limits.​per_itemobject or null

Limitación global de artículos.

limits.​per_item.​totalinteger

Número máximo de artículos que pueden comprar todos los usuarios.

limits.​per_item.​availableinteger

Número restante de artículos que todos los usuarios pueden comprar.

periodsArray of objects(item-periods-response)

Periodo de venta del artículo.

periods[].​date_fromstring or null(date-time)

Fecha en la que el artículo especificado estará disponible para la venta.

Ejemplo: "2020-08-11T10:00:00+03:00"
periods[].​date_untilstring or null(date-time)

Fecha en la que el artículo especificado dejará de estar disponible para la venta. Puede ser null.

Ejemplo: "2020-08-11T20:00:00+03:00"
custom_attributesobject(json)(item-custom-attributes-response)

Un objeto JSON que contiene los atributos y valores del artículo.

vp_rewardsArray of objects(client-item-value-point-reward)

Recompensa de artículo del punto de valor.

vp_rewards[].​item_idinteger(item_id)

ID único interno del artículo.

vp_rewards[].​skustring(value-point-sku)

ID único del punto de valor.

vp_rewards[].​amountinteger(value-point-amount)

Cantidad de puntos de valor.

vp_rewards[].​namestring(value-point-name)

Nombre del punto de valor.

vp_rewards[].​image_urlstring(Common_admin-image_url)

URL de la imagen.

vp_rewards[].​is_clanboolean(is_clan)

Si el punto de valor se utiliza en las cadenas de recompensas de clanes.

Respuesta
application/json
{
  "item_id": 488833,
  "sku": "com.xsolla.swords_1",
  "type": "virtual_good",
  "name": {
    "en": "Sword Xsolla Skin"
  },
  "description": {
    "en": "Honshu Boshin Wakizashi - Modern Tactical Samurai / Ninja Sword - Hand Forged 1060 Carbon Steel - Full Tang, Fully Functional, Battle Ready - Black TPR, Steel Guard and Pommel"
  },
  "image_url": "https://cdn.xsolla.net/img/misc/images/8ab44fe99038a56de01950ba4a971b77.png",
  "price": {
    "amount": "4.99",
    "amount_without_discount": "4.99",
    "currency": "USD"
  },
  "virtual_prices": [],
  "can_be_bought": true,
  "promotions": [],
  "limits": {
    "per_user": { … },
    "per_item": null
  },
  "periods": [
    { … }
  ],
  "attributes": [
    { … }
  ],
  "is_free": false,
  "groups": [
    { … }
  ],
  "virtual_item_type": "non_consumable",
  "vp_rewards": [],
  "custom_attributes": {
    "purchased": 0,
    "attr": "value"
  }
}

Obtener la lista de todos los artículos virtualesClient-side

Solicitud

Obtiene una lista de todos los artículos virtuales para hacer búsquedas en el lado del cliente.

Aviso:

Devuelve solo el SKU del artículo, nombre, grupos y descripción.

Nota:

Esta llamada de API devuelve datos genéricos del catálogo de artículos cuando se utiliza sin autorización. Usa la autorización para recuperar datos personalizados del usuario, como límites y promociones asociadas con el artículo. Para hacer esto, transmita el JWT del usuario en el encabezado Authorization. Para obtener más información sobre el JWT del usuario, consulte el bloque Seguridad para esta llamada.


Vea también: La llamada API Obtener lista de artículos virtuales para recuperar datos detallados del artículo con paginación.

Seguridad
XsollaLoginUserJWT
Ruta
project_idintegerrequerido

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
Consulta
localestring

Idioma de respuesta. Código de idioma de dos letras minúsculas según la norma ISO 639-1. (p. ej., en). Los códigos de configuración regional de cinco caracteres (p. ej., en-US) se admiten en campos de localización como name y description, pero se normalizan como códigos de dos letras en las respuestas. Puede consultar la lista completa de idiomas admitidos en la documentación.

Predeterminado "en"
promo_codestring[ 1 .. 128 ] characters

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

Ejemplo: promo_code=WINTER2021
curl -i -X GET \
  'https://store.xsolla.com/api/v2/project/44056/items/virtual_items/all?locale=en&promo_code=WINTER2021' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Respuestas

La lista de todos los artículos virtuales se recibió correctamente.

Cuerpoapplication/json
itemsArray of objects
Ejemplo: [{"sku":"com.xsolla.big_rocket_1","name":"Big Rocket","description":"Big Rocket - description","groups":[{"external_id":"accessory","name":{"en":"accessory"}}]},{"sku":"com.xsolla.shotgun_raider_1","name":"SHOTGUN FOR TRUE RAIDERS","description":"description","groups":[{"external_id":"weapons","name":{"en":"Weapons"}}]},{"sku":"com.xsolla.shotgun_raider_2","name":"SHOTGUN FOR TRUE RAIDERS","description":"description","groups":[]}]
items[].​skustring

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

Ejemplo: "com.xsolla.big_rocket_1"
items[].​namestring

Nombre del artículo.

Ejemplo: "Big Rocket"
items[].​groupsArray of arrays
items[].​descriptionstring

Descripción del artículo.

Ejemplo: "Big Rocket - description"
Respuesta
application/json
{
  "items": [
    { … },
    { … },
    { … }
  ]
}

Pago virtual

Operaciones

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:

  1. Create a game using the Create game API call.
  2. Configure regional restrictions.
  3. Upload keys to a game key package using the Upload codes API call to make them available for purchase.
  4. Display the game catalog with prices for the user's region using the Get games list API call.
  5. 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.
  6. 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.

Game keys

Catálogo

Operaciones

Derechos

Operaciones

Admin

Operaciones

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.

Note

For detailed information on configuring bundles, refer to the Bundles section.

Bundle management scenario:

  1. 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.
  2. If needed, use the Update bundle API call to modify the bundle content or settings.
  3. 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.
  4. 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.
  5. Implement opening the payment UI to pay for the order.
  6. Set up order status tracking, for example using webhooks, to promptly receive data on successfully paid items and grant them to the user.

Bundle management scenario

Admin

Operaciones

Catálogo

Operaciones

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.

The cart is linked to a specific user and is stored on the Xsolla side. You can identify the cart in two ways: automatically by user's JWT or by cart ID (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.

Escenario de uso de la cesta:

  1. Implemente una interfaz de tienda donde el usuario seleccionará artículos.
  2. Cuando el usuario seleccione artículos en la tienda, agréguelos a la cesta, p. ej., usando la llamada Llenar la cesta con artículos. En la matriz de artículos, tiene que transmitir los códigos de artículo (SKU) y la cantidad requerida de artículos.
  3. Implemente la interfaz de visualización de la cesta. Cuando el usuario navegue a la cesta, muestre su contenido usando la llamada Obtener la cesta del usuario actual. La respuesta devolverá información sobre el precio final de los artículos, incluidos descuentos y promociones aplicadas.
  4. Implemente la apertura de la interfaz de pago para pagar el pedido. Por ejemplo, puede usar la llamada Crear pedido con todos los artículos de la cesta. La respuesta devuelve un token para abrir la interfaz de pago.
  5. Configure el seguimiento del estado del pedido; p. ej., usando webhooks, para recibir rápidamente datos sobre los artículos pagados correctamente y concederlos al usuario.

Nota:

Para implementar la venta de artículos dentro del juego y en línea, consulte la guía de integración.

Cesta y flujo de pago

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:

EstadoDescripciónNotas
newSe 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.
paidEl 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.
doneEl artículo se concede al usuario. —
canceledTSe 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.

Ciclo de vida del pedido

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.

Cesta (lado del cliente)

Utilice las llamadas de esta sección para gestionar la cesta en el lado del cliente.

Operaciones

Cesta (lado del servidor)

Utilice las llamadas de esta sección para gestionar la cesta en el lado del servidor.

Operaciones

Pago (lado del cliente)

Utilice las llamadas de esta sección para crear un token de pago en el lado del cliente.

Operaciones

Pago (lado del servidor)

Utilice las llamadas de esta sección para crear un token de pago en el lado del servidor.

Operaciones

Pedido

Utilice las llamadas de esta sección para obtener información sobre los pedidos.

Operaciones

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:

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.

Gestión

Operaciones

Admin

Operaciones

Pedidos anticipados

Operaciones

Comerciante

Operaciones

Catálogo

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

Operaciones

Regiones comunes

Operaciones

Admin

Operaciones

Admin

Operaciones

Catálogo

Operaciones