Saltar al contenido

API de LiveOps (2.0.0)

Descripción general

LiveOps es un conjunto de herramientas para estimular el compromiso continuo de los jugadores a través de promociones y ofertas personalizadas.

Utilice la API para gestionar las siguientes funciones:

  • Promociones: crear y gestionar cupones, códigos promocionales, descuentos y campañas de bonificaciones.
  • Personalización: especificar las condiciones para mostrar el catálogo de artículos y aplicar promociones solo para ciertos usuarios autorizados.
  • Límites de promoción: establecer un límite en cuántas veces un usuario puede utilizar una promoción y configurar reinicios programados para estos límites.
  • Cadenas de recompensas y puntos de valor: configurar progresiones de recompensas vinculadas a la acumulación de puntos de valor.
  • Cadenas diarias: configurar recompensas diarias recurrentes para estimular inicios de sesión regulares.
  • Cadenas de ofertas: construir ofertas de compra secuenciales con precios por cada paso y opciones de recompensa gratuita.
  • Venta adicional: un método de ventas en el que se ofrece al usuario comprar un artículo que posee un valor adicional.

Llamadas API

La API se divide en los siguientes grupos:

  • Admin: llamadas para crear, actualizar, activar y eliminar campañas y configuraciones de cadenas. Se autentican a través de autenticación básica de acceso con sus credenciales de comerciante o de proyecto.
  • Client: llamadas para recuperar promociones disponibles, obtener cadenas activas, canjear códigos y reclamar recompensas en nombre de usuarios finales autenticados. Se autentican a través del JWT del usuario.

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 con el JWT de un usuario. El token se transmite en el encabezado Authorization en el siguiente formato: Authorization: Bearer <user_JWT>, en el que <user_JWT> es el token del usuario. El token identifica al usuario y proporciona acceso a datos personalizados. De forma alternativa, puede usar 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/liveops/

Descripción general

Las promociones son herramientas de marketing diseñadas para atraer nuevos usuarios y aumentar las ventas. Usando la API de Xsolla, puede configurar las siguientes promociones:

  • Descuentos: precios reducidos en artículos seleccionados.
  • Bonificaciones: artículos concedidos a los usuarios junto con su compra.
  • Cupones: códigos que permiten a los usuarios recibir uno o más artículos de bonificación al canjearlos.
  • Códigos promocionales: códigos que permiten a los usuarios recibir artículos de bonificación, un descuento en un artículo específico o un descuento en toda la cesta. A diferencia de los cupones que se canjean después de que el usuario los introduce, los códigos promocionales se canjean durante una compra (en el momento del pago).
  • Ofertas únicas: artículos ocultos que se muestran en el catálogo a los usuarios que han introducido un código de oferta única. Si no se introduce el código, los artículos no se muestran.

Flujo de ejemplo para configurar una promoción de descuento:

  1. Cree artículos usando las llamadas de la subsección Admin de los grupos Artículos virtuales y moneda, Lotes o Claves del juego.
  2. Cree una promoción usando la llamada Crear promoción de descuento para un artículo. En la matriz items, transmita los SKU de los artículos correspondientes.
  3. Configure los periodos de validez de la promoción. Para hacerlo, invoque los métodos Crear promoción de descuento para un artículo o Actualizar promoción del artículo, y transmita el campo promotion_periods como una matriz de objetos en la cual date_from define la fecha de inicio y date_until define la fecha de finalización del periodo de validez.
  4. Active una promoción usando la llamada Actualizar la promoción del artículo. Transmita el parámetro "is_enabled": true.
  5. Para obtener información sobre los precios de los artículos, incluidos los precios con descuento, llame a los métodos de la API del cliente para obtener un catálogo de artículos de las subsecciones Común > Catálogo, Artículos virtuales y moneda > Catálogo, y Lotes > Catálogo.

Ejemplo de configuración de promoción

Consulte nuestra documentación para obtener información detallada sobre la configuración de promociones:

Llamadas comunes de API

Puede llamar a los métodos API de esta subsección para gestionar diferentes tipos de promociones.

Operaciones

Cupones

Llame a los métodos API de esta subsección para configurar y gestionar promociones de cupones.

Nota:

Consulte nuestra documentación para obtener información detallada sobre los cupones.

Operaciones

Códigos promocionales

Llame a los métodos API de esta subsección para configurar y gestionar promociones de códigos promocionales.

Nota:

Consulte nuestra documentación para obtener información detallada sobre los códigos promocionales.

Operaciones

Ofertas únicas por catálogo

Llame a los métodos API de esta subsección para configurar y gestionar ofertas exclusivas de catálogo.

Nota:

Consulte nuestra documentación para obtener información detallada sobre las ofertas exclusivas.

Operaciones

Descuentos

Llame a los métodos API de esta subsección para configurar y gestionar promociones de descuento.

Nota:

Consulte nuestra documentación para obtener información detallada sobre los descuentos.

Operaciones

Bonificaciones

Llame a los métodos API de esta subsección para configurar y gestionar promociones de bonificaciones.

Nota:

Consulte nuestra documentación para obtener información detallada sobre las bonificaciones.

Operaciones

Catálogo personalizado

La personalización le permite especificar las condiciones para mostrar el catálogo de artículos y aplicar promociones únicamente para usuarios autorizados específicos. Las condiciones se definen en función de los atributos de usuario y le permiten ofrecer artículos y promociones que sean más relevantes para usuarios concretos.

Los siguientes tipos de personalización están disponibles:

  • Personalización en el lado de Xsolla. Las reglas y la lógica de personalización se configuran y almacenan en el lado de Xsolla. Transmite los atributos del usuario, y Xsolla los utiliza para generar un catálogo personalizado.
  • Personalización del lado del socio. Configura las reglas y la lógica de personalización en su lado y envía una carga útil del catálogo final para un usuario específico a Xsolla.
Nota:

Solo puede usar un tipo de personalización. Para cambiarlo, siga las instrucciones.

Para configurar la personalización en el lado de Xsolla usando la API de Xsolla:

  1. Cree artículos usando las llamadas API de la subsección Admin de los grupos Artículos virtuales y moneda, Lotes o Claves del juego.

  2. Configure los atributos del usuario usando la API de Xsolla Login y manténgalos sincronizados actualizando los datos en Xsolla cada vez que se produzcan cambios en su juego.

  3. Configure la personalización para artículos o promociones:

  4. Transmita el JWT del usuario con los atributos del usuario a las llamadas API de recuperación de catálogo para recibir un catálogo personalizado.

Secuencia para configurar y aplicar la personalización en el lado de Xsolla para el catálogo de artículos:

Personalización para el catálogo de artículos

Secuencia para configurar y aplicar la personalización en el lado de Xsolla para las promociones:

Personalización para las promociones

Nota:

Se proporciona información detallada:
Operaciones

Descripción general

Los límites de uso de promociones le permiten restringir el número de veces que un usuario específico puede usar una promoción. También puede configurar restablecimientos programados de los límites.

Los límites se almacenan en el lado de Xsolla y se configuran en la configuración de la promoción en 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.promotions.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 los límites en el catálogo, consulte la sección Límites de uso de promociones.

Puede configurar limits.per_user: un límite en el número de veces que un solo usuario puede usar una promoción.

Los usuarios no autenticados siempre ven el número máximo de veces que se puede usar la promoción.

Para mostrar los usos restantes de la promoción del usuario con el límite activo aplicado, transmita los datos de autorización del usuario al solicitar el catálogo de artículos.

Para configurar un periodo de restablecimiento programado —diario, semanal o mensual— transmita el objeto limits.recurrent_schedule al crear o actualizar una promoción.

Escenario de configuración y aplicación de límites

  1. Crea una promoción usando la llamada API Crear promoción de descuento para un artículo o Crear promoción de bonificación y pasa el objeto limits.
  2. Solicita el catálogo para un usuario no autenticado: la respuesta devuelve el número máximo de usos de la promoción en el objeto items.promotions.limits.
  3. El usuario inicia sesión.
  4. Solicita el catálogo con el token de autorización del usuario: la respuesta devuelve el número restante de usos con el límite activo aplicado.
  5. El usuario selecciona un artículo promocional y hace una compra.
  6. Después del pago realizado correctamente, Xsolla actualiza el valor items.promotions.limits.per_user. Cuando llega a 0, el artículo se devuelve en las llamadas API del catálogo sin descuento ni bonificación.
  7. Puede actualizar el límite usando las llamadas API de la subsección Gestión:
  8. Recupera el valor de límite actualizado en items.promotions.limits en la siguiente solicitud de catálogo realizada con el token de autorización del usuario y lo muestra al usuario.

Límites de promoción

Gestión

Operaciones

Descripción general

Las cadenas de recompensas animan a los usuarios a comprar en la tienda utilizando moneda real. Por cada compra, los usuarios ganan puntos de valor y avanzan en la cadena de recompensas. Si los usuarios forman parte de clanes, sus compras aportan puntos de valor a todo el clan. Para obtener información detallada sobre cómo configurar las cadenas de recompensas, consulte la sección Sistema de recompensas.

Para configurar las cadenas de recompensas, utilice las llamadas API de la subsección Admin. Para mostrar las cadenas y reclamar recompensas, utilice las llamadas API de la subsección Client. Para gestionar las cadenas de recompensas de clanes, utilice las llamadas API de la subsección Clans client.

Ejemplo del flujo de configuración de la cadena de recompensas:

  1. Cree artículos usando las llamadas API de la subsección Admin de los grupos Artículos virtuales y moneda o Lotes.
  2. Cree puntos de valor mediante la llamada API Crear punto de valor.
  3. Asigne puntos de valor a los artículos mediante la llamada API Fijar puntos de valor para los artículos. Los usuarios reciben puntos de valor tras comprar estos artículos.
  4. Cree una cadena mediante la llamada API Crear cadena de recompensas. Para activar la cadena, transmita el parámetro is_enabled: true.
  5. Implemente la visualización de la cadena de recompensas. Para ello, solicite la lista de cadenas disponibles mediante la llamada API Obtener las cadenas de recompensas del usuario actual. La respuesta contiene todas las cadenas activas con sus pasos y estados.
  6. Implemente la visualización del saldo de puntos de valor. Para ello, utilice la llamada API Obtener el saldo de puntos de valor del usuario actual.
  7. Implemente la reclamación de recompensas por pasos. Para ello, utilice la llamada API Reclamar recompensa por paso.
  8. Configure el seguimiento del estado de los pedidos, por ejemplo, mediante webhooks, para recibir sin demora los datos sobre las recompensas reclamadas y concedérselas al usuario.

Flujo de configuración de la cadena de recompensas

Admin

Operaciones

Cliente

Operaciones

Obtener las cadenas de recompensas del usuario actualClient-side

Solicitud

Punto final de cliente. Obtiene las cadenas de recompensas del usuario actual.

Atención:

Todos los proyectos tienen una limitación en el número de artículos que puede obtener en la respuesta. El valor predeterminado y máximo es de 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 API utiliza un JWT de usuario para la autorización.

Incluya el token en el encabezado Authorization con el siguiente formato: Bearer <user_JWT>. Para obtener más información sobre el JWT de usuario, consulte el bloque 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
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
curl -i -X GET \
  'https://store.xsolla.com/api/v2/project/44056/user/reward_chain?limit=50&offset=0' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Respuestas

La cadena de recompensas del usuario se recuperó correctamente.

Cuerpoapplication/json
has_moreboolean

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

Ejemplo: true
total_items_countinteger

Número total de cadenas de recompensas del sistema.

Ejemplo: 10
itemsArray of objects
items[].​reward_chain_idinteger

ID de la cadena de recompensas.

Ejemplo: 9
items[].​namestring

Nombre de la cadena de recompensas.

Ejemplo: "Weekly quest"
items[].​descriptionstring or null

Reward chain description.

Ejemplo: "Major weekly quest"
items[].​long_descriptionstring or null

Descripción larga de la cadena de recompensas.

Ejemplo: "You can get a lot of additional items just by shopping during the week"
items[].​image_urlstring or null

URL de la imagen.

items[].​orderinteger

Define el orden de disposición.

items[].​date_startstring(date-time)

Fecha de inicio de su cadena de recompensas.

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

Fecha en la que finaliza la promoción de su cadena de recompensas. Puede ser null. Si date_end es null, la cadena de recompensas será ilimitada en el tiempo.

items[].​clan_typestring or null

Tipo de clan.

Enumeración"clan""guild""faction""community""team""squad""alliance""association""coalition""union"
items[].​top_contributorsArray of objects or null
items[].​top_contributors[].​namestring

El ID de usuario que se envía a Xsolla durante el proceso de autorización. El ID de usuario se utiliza para vincular al usuario con su proyecto de Xsolla Login y se muestra como un apodo. Si utiliza la autorización por ID de usuario, le recomendamos transmitir el parámetro name en la respuesta del webhook. Este parámetro contiene el nombre de usuario que se utilizará como apodo.

Ejemplo: "Rocket"
items[].​top_contributors[].​contributed_amountinteger

La cantidad de puntos de valor ganados por el usuario.

Ejemplo: 100
items[].​value_pointobject
items[].​value_point.​skustring

ID único del punto de valor.

items[].​value_point.​namestring

Nombre del punto de valor.

items[].​value_point.​image_urlstring

URL de la imagen.

items[].​value_point.​descriptionstring or null

Descripción del punto de valor.

items[].​value_point.​long_descriptionstring or null

Descripción larga del punto de valor.

items[].​value_point.​amountinteger

Cantidad de puntos de valor.

items[].​value_point.​is_clanboolean

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

items[].​stepsArray of objects
items[].​steps[].​step_idinteger

ID del paso.

Ejemplo: 10
items[].​steps[].​namestring

Nombre del paso.

Ejemplo: "Level 1"
items[].​steps[].​is_claimedboolean

Si se reclama la recompensa del paso.

Ejemplo: false
items[].​steps[].​image_urlstring

URL de la imagen.

items[].​steps[].​priceobject
items[].​steps[].​price.​amountinteger

El número de puntos de valor que un usuario reclama para el paso.

Ejemplo: 100
items[].​steps[].​rewardArray of objects
items[].​steps[].​reward[].​skustring[ 1 .. 255 ] characters^[a-zA-Z0-9_\-–.]*$

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.

items[].​steps[].​reward[].​namestring

Nombre del artículo.

Ejemplo: "Super box"
items[].​steps[].​reward[].​typestring

Tipo de artículo.

Ejemplo: "bundle"
items[].​steps[].​reward[].​descriptionstring

Item description.

Ejemplo: "Super box with items"
items[].​steps[].​reward[].​image_urlstring

URL de la imagen.

items[].​steps[].​reward[].​quantityinteger

Cantidad del artículo.

Ejemplo: 2
items[].​recurrent_scheduleobject or null

Periodo de reinicio recurrente de la cadena de recompensas.

items[].​recurrent_schedule.​interval_typestring
One of:

Frecuencia del reinicio recurrente de la cadena de recompensas.

string
Valor"weekly"
items[].​recurrent_schedule.​reset_next_dateinteger

Fecha y hora estimadas en las que se restablecerá la cadena de recompensas la próxima vez (Marca de tiempo Unix).

Por ejemplo, la cadena de recompensas se reinicia mensualmente, a partir del 1 de marzo de 2024, a las 01:00 h de Kuala Lumpur (GMT+8). La fecha y hora del próximo reinicio de la cadena de recompensas, el día 1 de abril de 2024 a las 01:00 h de Kuala Lumpur (GMT+8), lo cual equivale al 31 de marzo de 2024 a las 17:00 GMT+0 o "1711904400000" en el formato Marca de tiempo Unix.

Ejemplo: "1711904400000"

items[].​popup_headerobject or null

Objeto con traducciones para el encabezado de una ventana emergente con información sobre la cadena de recompensas de un clan. Código de idioma de dos letras minúsculas.

items[].​popup_header.​enstring or null
Ejemplo: "How to unlock rewards"
items[].​popup_header.​arstring or null
Ejemplo: null
items[].​popup_header.​bgstring or null
Ejemplo: null
items[].​popup_header.​cnstring or null
Ejemplo: null
items[].​popup_header.​csstring or null
Ejemplo: null
items[].​popup_header.​destring or null
Ejemplo: "Wie man Belohnungen freischaltet"
items[].​popup_header.​esstring or null
Ejemplo: "Cómo desbloquear recompensas"
items[].​popup_header.​frstring or null
Ejemplo: "Comment débloquer des récompenses"
items[].​popup_header.​hestring or null
Ejemplo: null
items[].​popup_header.​itstring or null
Ejemplo: "Come sbloccare ricompense"
items[].​popup_header.​jastring or null
Ejemplo: "報酬をアンロックする方法"
items[].​popup_header.​kostring or null
Ejemplo: null
items[].​popup_header.​plstring or null
Ejemplo: null
items[].​popup_header.​ptstring or null
Ejemplo: null
items[].​popup_header.​rostring or null
Ejemplo: null
items[].​popup_header.​rustring or null
Ejemplo: null
items[].​popup_header.​thstring or null
Ejemplo: null
items[].​popup_header.​trstring or null
Ejemplo: null
items[].​popup_header.​twstring or null
Ejemplo: null
items[].​popup_header.​vistring or null
Ejemplo: null
items[].​popup_instructionobject or null

Objeto con traducciones para una ventana emergente con información sobre la cadena de recompensas de un clan. Código de idioma de dos letras minúsculas.

items[].​popup_instruction.​enstring or null
Ejemplo: "You must be a clan member to get clan rewards. You join a clan when a clan member invites you to the clan, and you accept the invite. You can also create your own clan."
items[].​popup_instruction.​arstring or null
Ejemplo: null
items[].​popup_instruction.​bgstring or null
Ejemplo: null
items[].​popup_instruction.​cnstring or null
Ejemplo: null
items[].​popup_instruction.​csstring or null
Ejemplo: null
items[].​popup_instruction.​destring or null
Ejemplo: "Du musst ein Clanmitglied sein, um Clananreize zu erhalten. Du trittst einem Clan bei, wenn ein Clanmitglied dich einlädt, und du die Einladung annimmst. Du kannst auch deinen eigenen Clan erstellen."
items[].​popup_instruction.​esstring or null
Ejemplo: "Debes ser miembro de un clan para obtener las recompensas del clan. Te unes a un clan cuando un miembro del clan te invita al clan y aceptas la invitación. También puedes crear tu propio clan."
items[].​popup_instruction.​frstring or null
Ejemplo: "Vous devez être membre d'un clan pour obtenir les récompenses du clan. Vous rejoignez un clan lorsque qu'un membre du clan vous invite au clan et que vous acceptez l'invitation. Vous pouvez également créer votre propre clan."
items[].​popup_instruction.​hestring or null
Ejemplo: null
items[].​popup_instruction.​itstring or null
Ejemplo: "Devi essere un membro del clan per ottenere le ricompense del clan. Ti unisci a un clan quando un membro del clan ti invita al clan e accetti l'invito. Puoi anche creare il tuo clan."
items[].​popup_instruction.​jastring or null
Ejemplo: "クランリワードを受け取るには、クランメンバーでなければなりません。 クランメンバーがあなたをクランに招待し、招待を受け入れると、クランに参加できます。 あなた自身のクランを作成することもできます。"
items[].​popup_instruction.​kostring or null
Ejemplo: null
items[].​popup_instruction.​plstring or null
Ejemplo: null
items[].​popup_instruction.​ptstring or null
Ejemplo: null
items[].​popup_instruction.​rostring or null
Ejemplo: null
items[].​popup_instruction.​rustring or null
Ejemplo: null
items[].​popup_instruction.​thstring or null
Ejemplo: null
items[].​popup_instruction.​trstring or null
Ejemplo: null
items[].​popup_instruction.​twstring or null
Ejemplo: null
items[].​popup_instruction.​vistring or null
Ejemplo: null
items[].​popup_image_urlstring or null(uri)

Imagen de la ventana emergente de una cadena de recompensas de clan.

Respuesta
application/json
{
  "has_more": false,
  "total_items_count": 1,
  "items": [
    { … },
    { … }
  ]
}

Obtener el saldo de puntos de valor del usuario actualClient-side

Solicitud

Punto final del cliente. Obtiene el saldo actual de puntos de valor del usuario.

Nota:

Esta llamada API utiliza un JWT de usuario para la autorización.

Incluya el token en el encabezado Authorization con el siguiente formato: Bearer <user_JWT>. Para obtener más información sobre el JWT de usuario, consulte el bloque 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
reward_chain_idintegerrequerido

ID de la cadena de recompensas.

Ejemplo: 101
curl -i -X GET \
  https://store.xsolla.com/api/v2/project/44056/user/reward_chain/101/balance \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Respuestas

Se recuperó correctamente el saldo de puntos de valor del usuario.

Cuerpoapplication/json
skustring

ID único del punto de valor.

namestring

Nombre del punto de valor.

image_urlstring

URL de la imagen.

descriptionstring or null

Descripción del punto de valor.

long_descriptionstring or null

Descripción larga del punto de valor.

amountinteger

Cantidad de puntos de valor.

is_clanboolean

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

Respuesta
application/json
{
  "sku": "com.xsolla.value_point_1",
  "name": "Value point",
  "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg",
  "description": null,
  "long_description": null,
  "amount": 130,
  "is_clan": false
}

Reclamar recompensa por pasoClient-side

Solicitud

Punto final del cliente. Reclama la recompensa por paso del usuario actual en una cadena de recompensas.

Nota:

Esta llamada API utiliza un JWT de usuario para la autorización.

Incluya el token en el encabezado Authorization con el siguiente formato: Bearer <user_JWT>. Para obtener más información sobre el JWT de usuario, consulte el bloque 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
reward_chain_idintegerrequerido

ID de la cadena de recompensas.

Ejemplo: 101
step_idintegerrequerido

ID del paso de la cadena de recompensas.

Ejemplo: 120
curl -i -X POST \
  https://store.xsolla.com/api/v2/project/44056/user/reward_chain/101/step/120/claim \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Respuestas

Ha reclamado correctamente la recompensa por paso del usuario actual de una cadena de recompensas.

Respuesta
Sin contenido

Cliente de clanes

Operaciones

Admin

Operaciones

Cliente

Operaciones

Descripción general

Las cadenas de ofertas son una secuencia de pasos, cada uno de los cuales contiene un artículo que los usuarios reciben gratis o que compran como parte de una oferta activa. Las cadenas de ofertas pueden incluir artículos exclusivos que solo están disponibles dentro de la cadena, así como artículos a precios rebajados en comparación con los precios de tienda. Para obtener información detallada sobre cómo configurar esta herramienta de marketing, consulte la sección Offer chains.

Para configurar las cadenas de ofertas, utilice las llamadas API de la subsección Admin. Para mostrar las cadenas e implementar la lógica para gestionar los artículos que reciben los usuarios, utilice las llamadas API de la subsección Client.

Ejemplo del flujo de configuración de la cadena de ofertas:

  1. Cree artículos usando las llamadas API de la subsección Admin de los grupos Artículos virtuales y moneda o Lotes.

  2. Cree una cadena mediante la llamada API Crear cadena de ofertas. Para activar la cadena, transmita el parámetro is_enabled: true.

  3. Implemente la visualización de la cadena de ofertas. Para ello, solicite la lista de cadenas disponibles mediante la llamada API Obtener las cadenas de ofertas del usuario actual. La respuesta contiene todas las cadenas activas con sus pasos y estados.

  4. Implemente la lógica para gestionar los artículos que reciben los usuarios:

  5. Configure el seguimiento del estado de los pedidos, por ejemplo, mediante webhooks, para recibir sin demora los datos de los artículos reclamados o comprados y concedérselos al usuario.

Flujo de configuración de la cadena de recompensas

Admin

Operaciones

Cliente

Operaciones

Admin

Operaciones

Cliente

Operaciones