Descripción general

La API de Xsolla incluye:

• Pay Station API: interfaz de pago y métodos de tokenización.
• IGS API: métodos para trabajar con los módulos In-Game Store y Buy Button.
• Subscriptions API: métodos para suscripciones.
• Login API: métodos para la autenticación de usuarios utilizando su propia interfaz (consulte la guía de integración ).

La API utiliza funciones HTTP integradas, como la autenticación HTTP y los verbos HTTP, que pueden ser interpretados por clientes HTTP estándar. También admite el uso compartido de recursos con orígenes cruzados, lo cual permite acceder a ella de forma segura desde una aplicación web cliente.

• https://api.xsolla.com - Pay Station API, Subscriptions API
• https://login.xsolla.com/api - Login API
• https://store.xsolla.com/api - IGS API

Solicitudes y respuestas

• enviarse a través de HTTPS,
• utilizar TLS 1.2 o superior,
• contener parámetros de autenticación,
• contener un encabezado adicional: Content-Type: application/json para solicitudes PUT y POST.

Authorization: Basic <your_authorization_basic_key>
Content-Type: application/json

Por defecto, todas las solicitudes devuelven una respuesta con datos en JSON en el cuerpo y Content-Type: application/json en el encabezado.

Cambios en la API

• Agregar nuevos recursos de API
• Agregar parámetros de solicitud opcionales
• Agregar nuevas propiedades a las respuestas de API existentes
• Agregar nuevos valores para los parámetros existentes con valores enumerables
• Agregar nuevos tipos de webhook y parámetros de JSON
• Agregar encabezados de solicitud HTTP opcionales
• Rechazar cualquier solicitud en la que los parámetros válidos contengan valores no válidos
• Rechazar solicitudes formadas erróneamente que fueron aceptadas previamente debido a un análisis tolerante, si se cambia la lógica de análisis
• Agregar, cambiar o eliminar funciones no documentadas en cualquier momento

Control de versiones

Autenticación

• Autenticación de acceso básica. Estas solicitudes a la API deben contener el encabezado Authorization: Basic <your_authorization_basic_key<, en el cual <your_authorization_basic_key> es el par ID de comerciante:clave de API, codificado según el estándar Base64. Acceda a Cuenta del editor para localizar estos parámetros:
  • El ID de comerciante se muestra:
    • en la sección Configuración de la empresa > Empresa.
    • en la URL de 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>/<Publisher Account section>.
  • La clave de API se muestra en Cuenta del editor una sola vez cuando se crea y debe almacenarse en su servidor. Puede crear una nueva clave en la siguiente sección:
    • Configuración de la empresa > Claves API
    • Configuración del proyecto > Claves API
• Autenticación mediante JWT de usuario. Estas solicitudes a la API deben contener el encabezado Authorization: Bearer <user_JWT>, en el que <user_JWT> es el token del usuario.
• Autenticación mediante el JWT del servidor. Estos métodos API deben contener el encabezado X-SERVER-AUTHORIZATION: <server_JWT>, en el que <server_JWT> es el token del servidor.
• Sin autenticación.

Llamadas API por modelo de interacción

• Llamadas API del lado del cliente: llamadas API para la interacción entre la parte cliente de la aplicación del socio y el servidor de Xsolla. Las acciones del usuario en el lado cliente inician el proceso de solicitud de estas llamadas API. Ejemplo de llamadas API del lado del cliente: obtención de una lista de artículos, autenticación de usuario, obtención de un token de pago en el lado del cliente.
• Llamadas API del lado del servidor: llamadas API para iniciar la interacción entre el servidor del socio y el servidor de Xsolla, las cuales están destinadas a las siguientes tareas:
  • Implementación del flujo de usuario.
    Las acciones del usuario en el lado del cliente desencadenan la invocación de la llamada API del lado cliente del socio y, después, se invoca la llamada API del lado del servidor Xsolla en el servidor del socio. Ejemplos de llamadas API del servidor para implementar el flujo de usuario: actualizar los atributos de usuario en el servidor, obtención de un token de pago en el lado del servidor.
  • Tareas administrativas o de configuración de productos de Xsolla realizadas por el socio.
    Las acciones del usuario en el lado del cliente no pueden iniciar una llamada a estos métodos. Ejemplos de llamadas API del servidor de administración: creación y edición de un artículo o una promoción.

• Superar los límites de frecuencia:
  • Los límites de frecuencia de las llamadas API del lado del servidor son más estrictos que los de las llamadas API del lado del cliente.
  • Los límites de frecuencia de las llamadas API del lado del servidor del administrador son más estrictos que los de las llamadas API de implementación del flujo de usuario.
• Recibir información irrelevante como respuesta. Por ejemplo, cuando se usan llamadas API del lado del servidor para obtener una lista de artículos para el administrador en lugar de llamadas API del lado cliente para obtener una lista de artículos para generar un catálogo.
• Cambios de datos no autorizados por los usuarios. Por ejemplo, cuando se usan llamadas API del lado cliente para actualizar atributos en lugar de llamadas API del lado del servidor.
• Determinación incorrecta de país y moneda en la interfaz de pago.

Puede determinar si una llamada API es del lado del cliente o del lado del servidor por el esquema de autenticación:

• Lado del cliente: se invocan sin autenticación o con el encabezado Authorization header: Bearer <user_JWT>, en el cual <user_JWT> es el token de usuario.
• Las llamadas API del servidor para implementar el flujo de usuario - se invocan con el encabezado:
  • X-SERVER-AUTHORIZATION: <server_JWT>, en el cual <server_JWT> - es el token del servidor.
  • Authorization: Basic <your_authorization_basic_key>, en el cual el par <your_authorization_basic_key>-project_id:api_key, codificado según el estándar Base64.
• Llamadas API del lado del servidor para tareas administrativas - se invocan con el encabezado Authorization: Basic <your_authorization_basic_key>, en el cual el par<your_authorization_basic_key>-project_id:api_key, codificado según el estándar Base64.

Ejemplo de llamadas API del lado del servidor con autenticación en el lado del servidor:

Ejemplo de llamadas API del lado cliente con autenticación en el lado cliente:

En función de sus requisitos, puede elegir cómo establecer la integración a la hora de implementar el flujo del usuario: con llamadas API del lado del servidor o del lado del cliente. Las llamadas API administrativas del servidor no deben usarse para implementar el flujo del usuario.

Ejemplo de implementación del flujo de usuario utilizando llamadas API del lado cliente:

1. El usuario ejecuta acciones en el lado cliente. Por ejemplo: llena la cesta o hace una compra de artículos.
2. El cliente del juego envía una solicitud con datos al servidor de Xsolla.
3. El servidor de Xsolla envía una respuesta al cliente del juego.
4. El cliente del juego muestra el resultado al usuario.

En este flujo se usa la autenticación a través de un JWT de usuario.

Ejemplo de implementación de un flujo de usuario utilizando llamadas API del lado del servidor:

1. El usuario ejecuta acciones en el lado cliente. Por ejemplo: llena la cesta o hace una compra de artículos.
2. El cliente del juego envía una solicitud al servidor del juego.
3. Si es preciso, el socio implementa un procesamiento de datos adicional en el servidor del juego.
4. El servidor del juego envía una solicitud al servidor de Xsolla.
5. El servidor de Xsolla envía una respuesta al servidor del juego.
6. El servidor del juego procesa los datos y envía una respuesta al cliente del juego.
7. El cliente del juego muestra el resultado al usuario.

En este flujo, se emplea la autenticación de acceso básica o un token de servidor.

Flujo de interacción cuando se usan llamadas API de administración del lado del servidor:

1. El socio envía una solicitud desde el cliente o el servidor de su aplicación al servidor de Xsolla.
2. El servidor de Xsolla devuelve una respuesta con el resultado del procesamiento de la solicitud.

Tipos de puntos finales

Formato de fecha

Paginación

Gestión de errores

• 200, 201, 204 - Ningún error
• 400 Bad Request: suele indicar que falta un parámetro obligatorio. Consulte el cuerpo de la respuesta para obtener más información
• 401 Unauthorized: no se proporcionó una clave de API válida
• 402 Request Failed: error de solicitud aunque los parámetros son válidos
• 403 Forbidden: sin autorización. Consulte el cuerpo de la respuesta para obtener más información
• 404 Not Found: el elemento solicitado no existe
• 409, 422: parámetros de solicitud no válidos
• 412 Precondition Failed: el proyecto aún no ha sido activado (utilizado en el método Crear token)
• 415 Unsupported Media Type: falta Content-Type: application/json en el encabezado HTTP
• Errores de servidor 500, 502, 503 y 504: Se ha producido un error

{
    "http_status_code": 500,
    "message": "Internal Server Error",
    "extended_message": null,
    "request_id": "6445b85"
}

Límites de frecuencia

Información general

Causas habituales de superación de los límites de frecuencia

• Un aumento repentino del tráfico en el lado del socio como consecuencia de:
  • rebajas de temporada
  • inicio de pruebas cerradas y abiertas
• Aumento repentino del tráfico a raíz de ataques DDoS en el lado del socio.
• Una integración mal configurada, por ejemplo:
  • usar los métodos de la subsección Admin que no están destinados a un uso frecuente en lugar de los métodos de la subsección Catálogo
  • llamada frecuente del método Obtener pedido para obtener el estado de un pedido y la lista de artículos que lo componen. Por ejemplo: 1 por segundo cuando el retraso recomendado entre solicitudes debería ser de 3 segundos
• Lanzar un número excesivamente elevado de solicitudes en un periodo determinado. Por ejemplo: más de 200 llamadas por segundo al método Obtener lista de artículos virtuales para mostrar un catálogo de artículos.

Gestión de los límites de frecuencia

• Haga un seguimiento de los códigos de estado 429 y crea un mecanismo de reintento. Puede utilizar el patrón de reintentos con un retroceso fijo o exponencial entre reintentos en vez de reintentos continuos.
• Optimice el código para obtener solo los datos requeridos. Asegúrese de realizar sólo las solicitudes que requiere su aplicación y evite las llamadas API innecesarias. Si utiliza la API IGS API, puede usar la API WebSocket para reducir el número de llamadas.
• Almacene en caché los datos que su aplicación usa con frecuencia. Puede mantener los datos estáticos en su lado y reducir el número de solicitudes a la API externa.
• Evite los ataques DDoS que pueden dañar su API.
• Ajuste la frecuencia de sus solicitudes para lograr una distribución más uniforme. Si el error 429 se produce con regularidad, considere la opción de incluir un proceso en su código que regule la frecuencia de sus solicitudes y permita que se distribuyan de forma más uniforme.

Claves API

Una clave API es una clave única que se usa para el cifrado de datos de usuarios y la autenticación de solicitudes API. En Cuenta del editor, puede crear claves API para todos los proyectos de la empresa y para un proyecto individual.

Crear clave de API

1. Abra Cuenta del editor.
2. Vaya a la sección Company settings > API keys o Project settings > API keys.
3. Haga clic en Create API key.
4. Rellene los campos:
   • Key name que se mostrará en la lista de claves. Establezca un nombre que le permita identificar fácilmente la clave.
   • Key type: permanente o temporal.
   • Expiration date: solo para una clave temporal. Después de la fecha de expiración, la clave deja de ser válida y es necesario crear una nueva.
   • Project en el que la clave es válida (el campo no se muestra cuando se crea una clave de API en la página del proyecto). Todos los proyectos están seleccionados por defecto.
5. Haga clic en Create.
6. En la ventana que se abre, haga clic en Copy API key y guarde la clave API creada en su lado.

Eliminar una clave API

1. Abra Cuenta del editor.
2. Vaya a la sección Company settings > API keyso Project settings > API keys.
3. En la fila de la clave API, haga clic en el icono de la papelera y confirme la acción.

• recibir pagos en los proyectos en los que se utilizó esta clave de API
• llamando a métodos API que utilizaron esta clave de API

1. Cree una nueva clave de API.
2. Cambie su aplicación para que use la nueva clave de API.
3. Elimine la clave de API inicial.

Webhooks

Los webhooks le permiten recibir notificaciones instantáneas de eventos configurados en el lado de Xsolla. Puede establecer webhooks de procesamiento para automatizar su aplicación. Consulte nuestra documentación para obtener la lista de webhooks disponibles y descripciones detalladas de cómo funcionan.