Saltar al contenido
/
Obtener todas las reglas...

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

Crear regla de filtrado del catálogoServer-sideAdmin

Solicitud

Crear regla para atributos de usuario.

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/json
namestring[ 1 .. 255 ] characters^\Srequerido

Nombre legible de una regla. Se utiliza para visualizar una regla en Cuenta del editor.

is_enabledbooleanrequerido

Si la regla está habilitada.

is_satisfied_for_unauthboolean

Si el artículo se muestra a usuarios no autorizados. Si es true, el artículo se muestra al usuario no autorizado independientemente de las reglas de visualización del catálogo. Es false por defecto.

attribute_conditionsArray of objects[ 1 .. 100 ] itemsrequerido

Conditions for validating user attributes. Determine item availability in the catalog based on whether user attributes match all specified conditions.

One of:
attribute_conditions[].​attributestring[ 1 .. 255 ] characters^[-_.\d\w]+$requerido

Código de atributo de usuario.

attribute_conditions[].​typestringrequerido

Tipo de atributo de usuario.

Valor"string"
attribute_conditions[].​operatorstringrequerido

Tipo de operación realizada por condición. Para el tipo de atributo string.

Valores posibles:

  • eq — Igual que
  • ne — No es igual que
Enumeración"eq""ne"
attribute_conditions[].​valuestring<= 255 charactersrequerido

Valor de la condición con el que se comparará el valor de atributo del usuario. El tipo depende del tipo de atributo.

attribute_conditions[].​can_be_missingboolean

Indica que se cumple la condición aunque falte el atributo en los atributos del usuario. Transmita true para mostrar el elemento a los usuarios que no tengan este atributo. Los usuarios que tengan el atributo, pero el valor no coincida con el especificado en la condición, no verán el artículo. false - Los usuarios que tengan el atributo, pero el valor no coincida con el especificado en la condición, o falte el atributo, no verán el artículo.

itemsArray of objects[ 1 .. 100 ] itemsrequerido
One of:

Artículos que se muestran a un usuario si los valores de sus atributos cumplen las condiciones.

items[].​item_idnumberrequerido

ID del artículo.

curl -i -X POST \
  -u <username>:<password> \
  https://store.xsolla.com/api/v2/project/44056/admin/user/attribute/rule \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Ork race armor rule",
    "is_enabled": true,
    "attribute_conditions": [
      {
        "attribute": "race",
        "operator": "eq",
        "value": "ork",
        "type": "string",
        "can_be_missing": false
      }
    ],
    "items": [
      {
        "item_id": 1
      }
    ],
    "is_satisfied_for_unauth": false
  }'

Respuestas

La regla se creó correctamente.

Cuerpoapplication/json
rule_idnumber

ID de regla.

Respuesta
application/json
{
  "rule_id": 1
}

Obtener todas las reglas del catálogo para la búsqueda en el lado del clienteServer-sideAdmin

Solicitud

Obtiene una lista de todas las reglas del catálogo para buscar en el lado del cliente.

Atención:

Devuelve solamente el ID de la regla, el nombre y is_enabled
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
curl -i -X GET \
  -u <username>:<password> \
  https://store.xsolla.com/api/v2/project/44056/admin/user/attribute/rule/all

Respuestas

Las reglas se recibieron correctamente.

Cuerpoapplication/json
itemsArray of objects
items[].​rule_idnumberrequerido

ID de regla.

items[].​namestringrequerido

Nombre legible de una regla. Se utiliza para visualizar una regla en Cuenta del editor.

items[].​is_enabledbooleanrequerido

Si la regla está habilitada.

items[].​is_satisfied_for_unauthboolean

Si el artículo se muestra a usuarios no autorizados. Si es true, el artículo se muestra al usuario no autorizado independientemente de las reglas de visualización del catálogo. Es false por defecto.

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

Obtener regla de filtro del catálogoServer-sideAdmin

Solicitud

Obtiene una regla específica que se aplica a los atributos del usuario.

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
rule_idnumberrequerido

ID de regla.

Ejemplo: 1
curl -i -X GET \
  -u <username>:<password> \
  https://store.xsolla.com/api/v2/project/44056/admin/user/attribute/rule/1

Respuestas

La regla se recibió correctamente.

Cuerpoapplication/json
rule_idnumberrequerido

ID de regla.

namestringrequerido

Nombre legible de una regla. Se utiliza para visualizar una regla en Cuenta del editor.

is_enabledbooleanrequerido

Si la regla está habilitada.

is_satisfied_for_unauthboolean

Si el artículo se muestra a usuarios no autorizados. Si es true, el artículo se muestra al usuario no autorizado independientemente de las reglas de visualización del catálogo. Es false por defecto.

attribute_conditionsArray of objects[ 1 .. 100 ] itemsrequerido

Conditions for validating user attributes. Determine item availability in the catalog based on whether user attributes match all specified conditions.

One of:
attribute_conditions[].​attributestring[ 1 .. 255 ] characters^[-_.\d\w]+$

Código de atributo de usuario.

attribute_conditions[].​typestring

Tipo de atributo de usuario.

Valor"string"
attribute_conditions[].​operatorstring

Tipo de operación realizada por condición. Para el tipo de atributo string.

Valores posibles:

  • eq — Igual que
  • ne — No es igual que
Enumeración"eq""ne"
attribute_conditions[].​valuestring<= 255 characters

Valor de la condición con el que se comparará el valor de atributo del usuario. El tipo depende del tipo de atributo.

attribute_conditions[].​can_be_missingboolean

Indica que se cumple la condición aunque falte el atributo en los atributos del usuario. Transmita true para mostrar el elemento a los usuarios que no tengan este atributo. Los usuarios que tengan el atributo, pero el valor no coincida con el especificado en la condición, no verán el artículo. false - Los usuarios que tengan el atributo, pero el valor no coincida con el especificado en la condición, o falte el atributo, no verán el artículo.

itemsArray of objectsrequerido
items[].​item_idnumber

ID del artículo.

items[].​skustring

Código (SKU) del artículo.

items[].​namestring

Nombre del artículo.

items[].​typestring

Tipo de artículo.

Enumeración"virtual_good""virtual_currency""bundle""physical_good""unit"
items[].​bundle_typestring

Tipo de lote. Se devuelve si el tipo de artículo es un lote.

Enumeración"standard""virtual_currency_package"
Respuesta
application/json
{
  "rule_id": 1,
  "name": "Ork race armor rule",
  "is_enabled": true,
  "is_satisfied_for_unauth": true,
  "attribute_conditions": [
    { … }
  ],
  "items": [
    { … }
  ]
}

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

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