Visão geral

A Xsolla API inclui:

• Pay Station API — interface de pagamento e métodos de tokenização.
• IGS API — métodos para trabalhar com os módulos In-Game Store.
• Subscriptions API — métodos de assinaturas.
• Login API — métodos para autenticação de usuário usando sua própria interface (consulte o guia de integração).

A API usa recursos HTTP internos, como autenticação HTTP e verbos HTTP, que podem ser interpretados por clientes HTTP prontos para uso. Ela também oferece suporte ao compartilhamento de recursos entre origens, permitindo que você acesse com segurança a partir de um aplicativo 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

Solicitações e respostas

• ser enviadas por HTTPS,
• usar TLS 1.2 ou superior,
• conter parâmetros de autenticação,
• conter um cabeçalho adicional:Content-Type: application/json para solicitações PUT e POST.

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

Por padrão, todas as solicitações retornam uma resposta com dados JSON no corpo e Content-Type: application/json no cabeçalho.

Alterações de API

• Adicionar novos recursos de API
• Adicionar parâmetros de solicitação opcionais
• Adicionar novas propriedades às respostas de API existentes
• Adicionar novos valores a parâmetros existentes com valores enumeráveis
• Adicionar novos tipos de webhook e parâmetros de JSON
• Adicionar cabeçalhos de solicitação HTTP opcionais
• Rejeitar qualquer solicitação na qual parâmetros válidos contenham valores inválidos
• Rejeitar solicitações formadas incorretamente que já tiverem sido aceitas devido à análise branda, se a lógica de análise for alterada
• Adicionar, alterar ou remover funcionalidades não documentadas a qualquer momento

Controle de versão

Autenticação

• O Merchant ID é exibido:
  • Na seção Company settings > Company.
  • No URL na barra de endereços do navegador em qualquer página da Conta de Distribuidor. O URL tem o seguinte formato: https:​//publisher.xsolla.com/<merchant ID>/<Publisher Account section>.

• A API key é mostrada na Conta de Distribuidor apenas uma vez, durante a criação, e deve ser armazenada por você. Você pode criar uma nova chave na seguinte seção:
  • Company settings > API keys
  • Project settings > API keys

Chamadas de API por modelo de interação

• Chamadas de API do lado do cliente — Chamadas de API para a interação entre a parte do cliente do aplicativo do parceiro e o servidor da Xsolla. As ações do usuário no cliente iniciam a solicitação dessas chamadas de API. Exemplo de chamadas de API do lado do cliente: obter uma lista de itens, autenticação de usuário, obtenção de um token de pagamento no lado do cliente.
• Chamadas de API do lado do servidor — Chamadas de API para interação entre o servidor do parceiro e o servidor da Xsolla, com destino às seguintes tarefas:
  • Implementação do fluxo do usuário.
    As ações do usuário no cliente acionam a invocação da chamada API do lado do cliente do parceiro, e então a chamada API do lado do servidor da Xsolla é acionada no servidor do parceiro. Exemplos das chamadas de API do servidor para a implementação de fluxo do usuário: updating user attributes on the server, obtaining a payment token on the server.
  • Tarefas administrativas ou a configuração de produtos Xsolla pelo parceiro.
    As ações do usuário no lado do cliente não podem iniciar um chamado a esses métodos. Exemplos de chamadas de API de administrador do servidor: criar e editar um item ou promoção.

• Excedendo os limites de transferência:
  • Os limites de transferência para chamadas API do lado do servidor são mais restritos do que para as chamadas de API do lado do cliente.
  • Os limites de transferência para chamadas API do lado do servidor como administrador são mais restritas do que para a implementação de fluxo de usuário nas chamadas API.
• Recebendo informações irrelevantes em resposta. Por exemplo, ao usar chamadas API do lado do servidor para obter uma lista de itens para o administrador em vez de chamadas API do lado do cliente para obter uma lista de itens para construir um catálogo.
• Alterações de dados pelos usuários não autorizadas. Por exemplo, ao usar chamadas API do lado do cliente para atualizar atributos em vez de chamadas de API do lado do servidor.
• A determinação incorreta do país ou moeda na interface de pagamento.

Você pode determinar se uma chamada de API ocorre no lado do cliente ou do servidor pelo esquema de autenticação:

• Lado do cliente — são chamados sem autenticação ou com o cabeçalho Authorization header: Bearer <user_JWT>, onde <user_JWT> — é o token do usuário.
• Chamadas de API do lado do servidor para implementar o fluxo do usuário — são chamadas com o cabeçalho:
  • X-SERVER-AUTHORIZATION: <server_JWT>, onde <server_JWT> — é o token do servidor.
  • Authorization: Basic <your_authorization_basic_key>, onde o par <your_authorization_basic_key> — project_id:api_key é codificado de acordo com o padrão Base64.
• Chamadas de API do lado do servidor para tarefas administrativas — são chamadas com o cabeçalhoAuthorization: Basic <your_authorization_basic_key>, onde o par <your_authorization_basic_key> — project_id:api_key é codificado de acordo com o padrão Base64.

Exemplo de uma chamada API do lado do servidor com autenticação do lado do servidor:

Exemplo de uma chamada API do lado do cliente com autenticação do lado do cliente:

Dependendo dos seus requisitos, você pode escolher como configurar a integração ao implementar o fluxo do usuário — Com chamadas API do lado do servidor ou do cliente. As chamadas API administrativas não devem ser usadas para implementar o fluxo do usuário.

Exemplo de implementação de um fluxo de usuário usando chamadas API do lado do cliente:

1. O usuário realiza as ações no cliente. Por exemplo, preenche o carrinho, faz a compra de um item.
2. O cliente do jogo envia uma solicitação com dados para o servidor da Xsolla.
3. O servidor da Xsolla envia uma resposta ao cliente do jogo.
4. O cliente do jogo exibe os resultados ao usuário.

Nesse fluxo, a autenticação via JWT do usuário é utilizada.

Exemplo de implementação de um fluxo de usuário usando chamadas API do lado do servidor:

1. O usuário realiza as ações no cliente. Por exemplo, preenche o carrinho, faz a compra de um item.
2. O cliente do jogo envia uma solicitação para o servidor do jogo.
3. Se necessário, o parceiro implementa o processamento de dados adicional no servidor do jogo.
4. O servidor do jogo envia uma solicitação ao servidor da Xsolla.
5. O servidor da Xsolla envia uma resposta ao servidor do jogo.
6. O servidor do jogo processa os dados e envia uma resposta ao cliente do jogo.
7. O cliente do jogo exibe os resultados ao usuário.

Nesse fluxo, é usada a autenticação de acesso básica ou um token de servidor.

O fluxo de interação ao usar as chamadas API de administrador no lado do servidor:

1. O parceiro envia uma solicitação do cliente ou servidor do aplicativo deles para o servidor da Xsolla.
2. O servidor Xsolla retorna uma resposta com o resultado do processamento da solicitação.

Tipos de extremidade

Formato de data

Paginação

Tratamento de erros

• 200, 201, 204 — Sem erro
• 400 Bad Request — Costuma indicar a falta de parâmetro obrigatório. Consulte o corpo da resposta para saber mais
• 401 Unauthorized — Não foi fornecida chave API válida
• 402 Request Failed — Falha na solicitação apesar de parâmetros válidos
• 403 Forbidden — Sem permissão. Consulte o corpo da resposta para saber mais
• 404 Not Found — O item solicitado não existe
• 409, 422 — Parâmetros de solicitação inválidos
• 412 Precondition Failed — O projeto ainda não foi ativado (usado no método Criar token)
• 415 Unused Media Type — Content-Type: application/json cabeçalho HTTP ausente
• 500, 502, 503, 504 Server Errrors — Ocorreu um problema

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

Limites de taxa

Informações gerais

Causas comuns de ultrapassagem dos limites de taxa

• Um aumento repentino no tráfego do lado do parceiro como resultado de:
  • Promoções sazonais
  • Início dos testes fechados e abertos
• Aumento repentino do tráfego como resultado de ataques DDoS do lado do parceiro.
• Integração configurada incorretamente, por exemplo:
  • Utilização dos métodos da subseção Admin não destinados ao uso frequente, em vez dos métodos da subseção Catálogo
  • Chamada frequente do método Obter pedido para obter o status de um pedido e a lista de itens dele. Por exemplo: 1 por segundo, quando o intervalo recomendado entre solicitações deve ser de 3 segundos
• Lançamento de um número excessivamente alto de solicitações em um período determinado. Por exemplo: mais de 200 chamadas por segundo para o método Obter lista de itens virtuais para exibir um catálogo de itens.

Tratamento de limites de taxa

• Acompanhe os códigos de status 429 e crie um mecanismo de nova tentativa. Você pode usar o padrão Retry com valores fixos ou exponential backoff entre tentativas, em vez de tentativas contínuas.
• Otimize o código para obter apenas os dados necessários. Certifique-se de fazer apenas solicitações que seu aplicativo requer e evite chamadas de API desnecessárias. Se você estiver usando a IGS API, use a WebSocket API para reduzir o número de chamadas.
• Armazene em cache os dados que são usados com frequência pelo seu aplicativo. Você pode manter os dados estáticos do seu lado e reduzir o número de solicitações para da API externa.
• Evite ataques DDoS que possam quebrar sua API.
• Ajuste a taxa de suas solicitações para uma distribuição mais suave. Se o erro 429 ocorrer regularmente, considere incluir um processo em seu código para regular a taxa de solicitações para permitir que elas sejam distribuídas de forma mais uniforme.

Chaves de API

Uma chave de API é uma chave exclusiva usada para criptografar dados do usuário e autenticar as solicitações de API. Em Conta de Distribuidor, você pode criar chaves de API para todos os projetos da empresa e um projeto individual.

Criar chave API

1. Abra uma Conta de Distribuidor.
2. Vá para Company settings > API keys ou Project settings > API keys.
3. Clique em Create API key.
4. Preencha os campos:
   • Key name que será exibido na lista de chaves. Defina um nome que permita identificar facilmente a chave.
   • Key type — permanente ou temporária.
   • Expiration date — apenas para uma chave temporária. Após a data de validade, a chave não será mais válida e será necessário criar uma chave nova.
   • Project — onde a chave é válida (este campo não é exibido quando você cria uma chave API na página do projeto). Por padrão, todos os projetos são selecionados.
5. Clique em Create.
6. Na janela que se abre, clique em Copy API key para salvar a chave API criada do seu lado.

Excluir chave API

1. Abra a Conta de Distribuidor.
2. Vá para Company settings > API keys ou Project settings > API keys.
3. Na linha API Key, clique no ícone da lixeira e confirme a ação.

• o recebimento de pagamentos nos projetos em que essa chave API foi usada
• chamadas de métodos de API que utilizem essa chave de API

1. Crie uma nova chave API.
2. Altere seu aplicativo ara usar a nova chave API.
3. Exclua a chave API inicial.

Webhooks

Webhooks permitem receber notificações instantâneas de eventos configurados no lado de Xsolla. Você pode configurar webhooks de processamento para automatizar seu aplicativo. Consulte nossa documentação para obter a lista de webhooks disponíveis e descrições detalhadas de funcionamento.