Saltar al contenido
/
Obtener grupo de artículo...

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

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

Obtener lista de grupos de artículos filtrada por tipo de artículoServer-sideAdmin

Solicitud

Recupera la lista de grupos de artículos filtrada por tipo de artículo. Solo se tienen en cuenta para el grupo los artículos del tipo especificado. Esta operación es similar al punto final Obtener lista de grupos de artículos, pero con un filtrado adicional de los artículos por tipo a la hora de contabilizarlos.

Seguridad
basicAuth
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_typestringrequerido

Tipo de artículo usado para filtrar grupos. Determina qué artículos se incluyen en items_count. Los valores que contengan / (p. ej., virtual_currency/package o game/key) deben codificarse según el formato URL (p. ej., virtual_currency%2Fpackage).

Enumeración"virtual_items""virtual_currency""virtual_currency/package""game/key""bundle""game""value_points""subscription_plans"
Ejemplo: virtual_items
curl -i -X GET \
  -u <username>:<password> \
  https://store.xsolla.com/api/v2/project/44056/admin/items/virtual_items/groups

Respuestas

Se recuperó correctamente la lista de grupos de artículos. El campo items_count incluye solamente artículos del tipo especificado.

Cuerpoapplication/json
groupsArray of objects(admin-group-response-by-item-type)
groups[].​idintegerrequerido

ID del grupo de artículos asignado por Xsolla.

Ejemplo: 1
groups[].​external_idstringrequerido

ID externo del grupo de artículos especificado durante la creación.

Ejemplo: "weapons"
groups[].​name(de dos letras (object or null)) or (cinco letras (object or null))(group-name-localization-object)requerido

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.

groups[].​name.​enstring or null

Inglés

groups[].​name.​arstring or null

Árabe

groups[].​name.​bgstring or null

Búlgaro

groups[].​name.​cnstring or null

Chino (simplificado)

groups[].​name.​csstring or null

Checo

groups[].​name.​destring or null

Alemán

groups[].​name.​esstring or null

Español (España)

groups[].​name.​frstring or null

Francés

groups[].​name.​hestring or null

Hebreo

groups[].​name.​itstring or null

Italiano

groups[].​name.​jastring or null

Japonés

groups[].​name.​kostring or null

Coreano

groups[].​name.​plstring or null

Polaco

groups[].​name.​ptstring or null

Portugués

groups[].​name.​rostring or null

Rumano

groups[].​name.​rustring or null

Ruso

groups[].​name.​thstring or null

Tailandés

groups[].​name.​trstring or null

Turco

groups[].​name.​twstring or null

Chino (tradicional)

groups[].​name.​vistring or null

Vietnamita

groups[].​name.​kmstring or null

Jemer

groups[].​name.​idstring or null

Indonesio

groups[].​name.​lostring or null

Laosiano

groups[].​name.​mystring or null

Birmano

groups[].​name.​phstring or null

Filipino

groups[].​name.​nestring or null

Nepalí

groups[].​description(de dos letras (object or null)) or (cinco letras (object or null))(group-description-localization-object)

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

Any of:

Códigos lingüísticos de dos letras minúsculas.

groups[].​description.​enstring or null

Inglés

groups[].​description.​arstring or null

Árabe

groups[].​description.​bgstring or null

Búlgaro

groups[].​description.​cnstring or null

Chino (simplificado)

groups[].​description.​csstring or null

Checo

groups[].​description.​destring or null

Alemán

groups[].​description.​esstring or null

Español (España)

groups[].​description.​frstring or null

Francés

groups[].​description.​hestring or null

Hebreo

groups[].​description.​itstring or null

Italiano

groups[].​description.​jastring or null

Japonés

groups[].​description.​kostring or null

Coreano

groups[].​description.​plstring or null

Polaco

groups[].​description.​ptstring or null

Portugués

groups[].​description.​rostring or null

Rumano

groups[].​description.​rustring or null

Ruso

groups[].​description.​thstring or null

Tailandés

groups[].​description.​trstring or null

Turco

groups[].​description.​twstring or null

Chino (tradicional)

groups[].​description.​vistring or null

Vietnamita

groups[].​description.​kmstring or null

Jemer

groups[].​description.​idstring or null

Indonesio

groups[].​description.​lostring or null

Laosiano

groups[].​description.​mystring or null

Birmano

groups[].​description.​phstring or null

Filipino

groups[].​description.​nestring or null

Nepalí

groups[].​image_urlstring or null(group-image-url)

URL de la imagen del grupo de artículos.

groups[].​orderinteger(group-display-order)

Orden de visualización de los grupos de artículos que hay en el catálogo. Cuanto mayor sea el valor, más abajo aparecerá el grupo en la lista. Si los valores son iguales, los grupos se ordenan por fecha de creación, y los más recientes aparecerán más arriba.

groups[].​is_enabledboolean(group-is-enabled)requerido

Si el grupo de artículos está habilitado en el catálogo.

groups[].​items_countinteger

Número total de artículos presentes en el grupo.

Ejemplo: 5
groups[].​is_contains_any_itemsboolean(group-is-contains-any-items)

Independientemente de si el grupo contiene algún elemento o no, y con independencia del item_type especificado. Un grupo puede tener items_count: 0 para el tipo especificado, cuando is_contains_any_items es true si el grupo contiene artículos de otros tipos.

Respuesta
application/json
{
  "groups": [
    { … },
    { … },
    { … }
  ]
}

Obtener grupo de artículos por ID externo filtrado por tipo de artículoServer-sideAdmin

Solicitud

Retrieves an item group by external ID. Only items of the specified type are counted for the group. This is similar to the Get item group by external ID endpoint, with additional filtering of items by type when counting them.

Seguridad
basicAuth
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_typestringrequerido

Tipo de artículo usado para filtrar grupos. Determina qué artículos se incluyen en items_count. Los valores que contengan / (p. ej., virtual_currency/package o game/key) deben codificarse según el formato URL (p. ej., virtual_currency%2Fpackage).

Enumeración"virtual_items""virtual_currency""virtual_currency/package""game/key""bundle""game""value_points""subscription_plans"
Ejemplo: virtual_items
external_idstringrequerido

ID externo del grupo de artículos especificado durante la creación.

Ejemplo: weapons
curl -i -X GET \
  -u <username>:<password> \
  https://store.xsolla.com/api/v2/project/44056/admin/items/virtual_items/groups/weapons

Respuestas

Se recuperó correctamente el grupo de artículos, con items_count filtrados por el tipo de artículo especificado.

Cuerpoapplication/json
idintegerrequerido

ID del grupo de artículos asignado por Xsolla.

Ejemplo: 1
external_idstringrequerido

ID externo del grupo de artículos especificado durante la creación.

Ejemplo: "weapons"
name(de dos letras (object or null)) or (cinco letras (object or null))(group-name-localization-object)requerido

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.

name.​enstring or null

Inglés

name.​arstring or null

Árabe

name.​bgstring or null

Búlgaro

name.​cnstring or null

Chino (simplificado)

name.​csstring or null

Checo

name.​destring or null

Alemán

name.​esstring or null

Español (España)

name.​frstring or null

Francés

name.​hestring or null

Hebreo

name.​itstring or null

Italiano

name.​jastring or null

Japonés

name.​kostring or null

Coreano

name.​plstring or null

Polaco

name.​ptstring or null

Portugués

name.​rostring or null

Rumano

name.​rustring or null

Ruso

name.​thstring or null

Tailandés

name.​trstring or null

Turco

name.​twstring or null

Chino (tradicional)

name.​vistring or null

Vietnamita

name.​kmstring or null

Jemer

name.​idstring or null

Indonesio

name.​lostring or null

Laosiano

name.​mystring or null

Birmano

name.​phstring or null

Filipino

name.​nestring or null

Nepalí

description(de dos letras (object or null)) or (cinco letras (object or null))(group-description-localization-object)

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

Any of:

Códigos lingüísticos de dos letras minúsculas.

description.​enstring or null

Inglés

description.​arstring or null

Árabe

description.​bgstring or null

Búlgaro

description.​cnstring or null

Chino (simplificado)

description.​csstring or null

Checo

description.​destring or null

Alemán

description.​esstring or null

Español (España)

description.​frstring or null

Francés

description.​hestring or null

Hebreo

description.​itstring or null

Italiano

description.​jastring or null

Japonés

description.​kostring or null

Coreano

description.​plstring or null

Polaco

description.​ptstring or null

Portugués

description.​rostring or null

Rumano

description.​rustring or null

Ruso

description.​thstring or null

Tailandés

description.​trstring or null

Turco

description.​twstring or null

Chino (tradicional)

description.​vistring or null

Vietnamita

description.​kmstring or null

Jemer

description.​idstring or null

Indonesio

description.​lostring or null

Laosiano

description.​mystring or null

Birmano

description.​phstring or null

Filipino

description.​nestring or null

Nepalí

image_urlstring or null(group-image-url)

URL de la imagen del grupo de artículos.

orderinteger(group-display-order)

Orden de visualización de los grupos de artículos que hay en el catálogo. Cuanto mayor sea el valor, más abajo aparecerá el grupo en la lista. Si los valores son iguales, los grupos se ordenan por fecha de creación, y los más recientes aparecerán más arriba.

is_enabledboolean(group-is-enabled)requerido

Si el grupo de artículos está habilitado en el catálogo.

items_countinteger

Número total de artículos presentes en el grupo.

Ejemplo: 5
is_contains_any_itemsboolean(group-is-contains-any-items)

Independientemente de si el grupo contiene algún elemento o no, y con independencia del item_type especificado. Un grupo puede tener items_count: 0 para el tipo especificado, cuando is_contains_any_items es true si el grupo contiene artículos de otros tipos.

Respuesta
application/json
{
  "id": 1,
  "external_id": "weapons",
  "name": {
    "en": "Weapons"
  },
  "description": {
    "en": "Player weapons"
  },
  "image_url": "https://example.com/weapons.png",
  "order": 1,
  "is_enabled": true,
  "items_count": 3,
  "is_contains_any_items": true
}

Reordenar grupos de artículosServer-sideAdmin

Solicitud

Establece el orden de visualización para grupos de artículos dentro de un proyecto. Transmita una matriz de grupos con sus nuevos valores de orden.

Seguridad
basicAuth
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
Cuerpoapplication/jsonrequerido

Matriz de grupos con nuevos valores de orden. Todos los artículos deben usar el mismo método de identificación (ya sea todos por id o todos por external_id).

One of:
unique
Array [
idinteger>= 0requerido

ID del grupo de artículos asignado por Xsolla.

Ejemplo: 1
orderinteger>= 0requerido

Nuevo valor del orden de visualización.

Ejemplo: 1
]
curl -i -X PUT \
  -u <username>:<password> \
  https://store.xsolla.com/api/v2/project/44056/admin/group/order \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "id": 1,
      "order": 1
    },
    {
      "id": 2,
      "order": 2
    },
    {
      "id": 3,
      "order": 3
    }
  ]'

Respuestas

El grupo de artículos se reordenó correctamente.

Respuesta
Sin contenido

Catálogo

Operaciones