Primeiros passos

Visão geral

A Xsolla API inclui:

A Xsolla API usa a arquitetura REST. A API tem URLs previsíveis e orientadas a recursos e usa códigos de resposta HTTP para indicar erros de API. A API sempre responde no formato JSON , inclusive em caso de erros.

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.

A Xsolla API usa os seguintes trajetos de pontos de extremidade:
  • https://api.xsolla.com — Pay Station API, Subscriptions API
  • https://login.xsolla.com/api — Login API
  • https://store.xsolla.com/api — IGS API
A maior parte dos trajetos de pontos de extremidade incluem o parâmetro merchant_id. Isso indica que o aplicativo solicitante está sendo executado por sua conta.

Solicitações e respostas

As solicitações à Xsolla API devem:
  • 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.
Copy
Full screen
Small screen
    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

    Xsolla pode alterar a funcionalidade da API da seguinte maneira:
    • 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
    Seu cliente deve permanecer funcional independentemente dessas alterações. Por exemplo, novos parâmetros JSON não reconhecidos pelo cliente não devem prejudicar sua operação normal.

    Controle de versão

    Todos os métodos da Xsolla API oferecem suporte ao controle de versão. Lançaremos uma nova versão sempre que houver alterações incompatíveis com a versão atual. A versão é identificada por “v1”/“v2”/etc., seguindo o prefixo “/merchant” no URL. Se esta for sua primeira vez trabalhando com a API, use a versão mais recente. Se você omitir a versão, usaremos a primeira versão por padrão.
    Observação
    Tenha em mente que só podemos garantir a integridade da API dentro da mesma versão.

    Autenticação

    A Xsolla API utiliza os seguintes tipos de autenticação:
    • Autenticação de acesso básica. Tais solicitações à API devem conter o cabeçalho Authorization: Basic <your_authorization_basic_key<, onde <your_authorization_basic_key> é o par ID do comerciante:chave API, codificado de acordo com o padrão Base64. Vá para Conta de Distribuidor para encontrar estes parâmetros:
      • ID de Comerciante é 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>.
      • Chave API é exibida na Conta de Distribuidor somente uma vez ao ser criada e deve ser armazenada do seu lado. Você pode criar uma nova chave na seguinte seção:
        • Company settings > API keys
        • Project settings > API keys
    • Autenticação utilizando o JWT do usuário. Tais solicitações à API devem conter o cabeçalho Authorization: Bearer <user_JWT>, onde <user_JWT> é o token do usuário.
    • Autenticação usando o JWT do servidor. Tais métodos de API devem conter o cabeçalho X-SERVER-AUTHORIZATION: <server_JWT>, onde <server_JWT> é o token do servidor.
    • Sem autenticação.
      Aviso

      Para obter mais informações sobre como trabalhar com chaves de API, consulte a Referência de API.

      Principais recomendações:

      • Salve a chave de API gerada cuidadosamente. Você pode visualizar a chave de API na Conta de Distribuidor apenas uma vez, durante sua criação.
      • Mantenha sua chave de API em segredo. Ela fornece acesso à sua conta pessoal e aos seus projetos na Conta de Distribuidor.
      • A chave de API deve ser armazenada em seu servidor, e jamais em arquivos binários ou no frontend.

      Se uma chamada de API que você precisa não contiver o trajeto-parâmetro project_id, use a chave de API que for válida em todos os projetos da empresa para configurar a autorização.

      Chamadas de API por modelo de interação

      Ao interagir com os produtos Xsolla pelo API Xsolla, é importante usar as chamadas de API de acordo com o uso planejado.
      • 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.
      Uma integração configurada corretamente ajuda a evitar os erros mais comuns:
      • 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.
      Lado do clienteLado do servidor
      Para implementação do fluxo de usuárioPara tarefas administrativas
      InteraçãoCliente-para-servidor.
      A solicitação é enviada do cliente do jogo diretamente ao servidor da Xsolla.      		Servidor-para-sercidor.
      A solicitação é enviada do cliente do jogo ao servidor do jogo, e então para do servidor do jogo para o servidor da Xsolla.      		Servidor-para-servidor.
      A solicitação é enviada do servidor do sistema do parceiro ao servidor da Xsolla.
      AutenticaçãoJSON Web Token (JWT) do usuário ou sem autenticação.Autenticação de acesso básica ou servidor JWT.Autenticação de acesso básica.
      Limites de transferênciaSuporta altas cargas.Suporta altas cargas.Desenvolvido apenas para uso de parceiros, de forma que essas chamadas de API tenham requisitos de desempenho baixos e limites de transferência restritos.
      Acesso superiorChamadas de API são usadas no lado do cliente, o que permite que dados sejam rapidamente exibidos ao usuário. Por exemplo, um catálogo de itens ou atributos de usuário — a quantidade de compras ou o nível no jogo.
      Todos os dados ficam acessíveis no código do cliente.
      Não use essas chamadas de API para trabalhar com dados que não deveriam ser disponibilizados para edição ao usuário. Por exemplo, para atualizar os atributos do usuário.      		Chamadas de API são usadas para a interação entre os servidores, de forma que o usuário não tenha acesso aos dados.
      Use essas chamadas de API para trabalhar com os dados que o usuário não pode modificar.      		Chamadas de API não são usadas para implementar o fluxo do usuário.
      Determinação de país e moedaO país e moeda são determinados pelo endereço IP do cliente a partir do qual a solicitação é enviada.
      Portanto, é importante usar essas chamadas de API no lado do cliente, não no servidor.      		O país e moeda são determinados pelo endereço IP do servidor a partir do qual a solicitação é enviada.

      Portanto, é importante passar os dados do país/moeda do usuário no cabeçalho ou parâmetro de acordo com a descrição na chamada de API usada.      		Chamadas de API não são usadas para implementar o fluxo do usuário.

      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.
      Nesse fluxo, a autenticação de acesso básico é usada.

      Tipos de extremidade

      O tipo de extremidade indica que tipo de dados ele manipula e que ações executa. As ações mais comuns são:
      AçãoMétodo HTTPDescrição
      CreatePOSTCria e salva uma entidade do tipo especificado.
      ListGETRetorna uma lista de entidades correspondentes à consulta. Para saber mais sobre uma entidade, primeiro descubra o ID usando a extremidade Lisa correspondente e, em seguida, forneça esse ID à extremidade Retrieve correspondente.
      RetrieveGETFornece informações sobre a entidade com o ID especificado.
      ReplacePUTModifica todos os campos da entidade com o ID especificado.
      UpdatePATCHModifica campos especificados da entidade com o ID especificado.
      DeleteDELETEExclui a entidade com o ID especificado.

      Formato de data

      Todas as datas são especificadas como cadeias de caracteres segundo ISO 8601. Você pode especificar cadeias de caracteres de data em UTC (por exemplo, 2013-01-15T00:00:00Z) ou indicando o mudança em relação a UTC (por exemplo, 2013-01-15T00:00:00-08:00 para oito horas antes de UTC). Neste último caso, não se esqueça de considerar o horário de verão, se aplicável.

      Paginação

      As extremidades da lista podem paginar os resultados retornados. Isso significa que, em vez de retornar todos os resultados em uma única resposta, essas extremidades podem retornar alguns dos resultados, juntamente com um cabeçalho de resposta que vincula ao próximo conjunto de resultados. Para isso, utilizamos parâmetros de compensação e limite.

      Tratamento de erros

      Lista de erros HTTP suportados:
      • 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
      Xsolla usa códigos de resposta HTTP convencionais para indicar se a solicitação de API foi bem-sucedida. Em geral, 2xx indica sucesso, 4xx indica um erro nas informações fornecidas (por exemplo, um parâmetro necessário ausente, falha na autorização, etc.) e 5xx indica um problema com os servidores Xsolla. Mas nem todos os erros correspondem perfeitamente aos códigos de resposta HTTP. Por exemplo, se uma solicitação foi válida, mas falhou, a API retornará o código de erro: 422. Todas as respostas de erro da API fornecem um objeto JSON com os seguintes campos:
      NomeTipoDescrição
      http_status_codeintegerCódigo HTTP.
      messagestringUma mensagem legível que descreve o erro. Esta mensagem está sempre em inglês. Não confie nesse valor para nenhum erro específico, porque ele pode mudar no futuro.
      extended_messagestringDescrição mais detalhada do erro.
      request_idstringID de solicitação exclusivo que pode ser usado para resolução de problemas.
      Copy
      Full screen
      Small screen
      • http
      {
    "http_status_code": 500,
    "message": "Internal Server Error",
    "extended_message": null,
    "request_id": "6445b85"
}

      Limites de taxa

      Informações gerais

      Para evitar sobrecarregar os sistemas Xsolla e protegê-los de picos de tráfego, Xsolla limita o número de solicitações recebidas pela Xsolla API dentro de um período de tempo especificado. Caso o limite seja excedido, a Xsolla API retorna uma resposta HTTP com o código de status 429. Os limites variam de acordo com o método, o projeto e outros fatores. Os limites atuais são atualizados regularmente para garantir a operação estável e ininterrupta dos sistemas Xsolla. Em alguns casos, é possível ajustar os limites especificados mediante solicitação prévia. Você pode entrar em contato com seu Gerente de Sucesso do Cliente ou enviar um e-mail para csm@xsolla.com com sua solicitação.

      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

      Para evitar erros causados por limites de taxa, recomendamos que você:
      • 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.

      Observação
      As chaves de API válidas em todos os projetos da empresa não são exibidas nas páginas de projetos individuais.
      Aviso

      Você pode trabalhar com chaves de API (exibir a lista, criar e excluir) se tiver uma das seguintes funções:

      • desenvolvedor
      • proprietário

      Somente o proprietário do projeto pode alterar funções na Conta de Distribuidor em Company settings > Users.

      Criar chave API

      Para criar uma 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.
      Observação
      Se você criar uma chave API na página do projeto, a chave só será válida neste projeto específico.
      Aviso

      Principais recomendações:

      • Salve a chave de API gerada cuidadosamente. Você pode visualizar a chave de API na Conta de Distribuidor apenas uma vez, durante sua criação.
      • Mantenha sua chave de API em segredo. Ela fornece acesso à sua conta pessoal e aos seus projetos na Conta de Distribuidor.
      • A chave de API deve ser armazenada em seu servidor, e jamais em arquivos binários ou no frontend.

      Se uma chamada de API que você precisa não contiver o trajeto-parâmetro project_id, use a chave de API que for válida em todos os projetos da empresa para configurar a autorização.

      Excluir chave API

      Para excluir uma 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.
      Excluir uma chave API cessa:
      • 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
      Para impedir que isso ocorra:
      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.

      Este artigo foi útil?
      Obrigado!
      Podemos melhorar alguma coisa? Mensagem
      Que pena ouvir isso
      Explique porque este artigo não foi útil para você. Mensagem
      Obrigado pelo seu feedback!
      Avaliaremos sua mensagem e a usaremos para melhorar sua experiência.
      Última atualização: 18 de Novembro de 2024

      Encontrou um erro de texto ou digitação? Selecione o texto e pressione Ctrl+Enter.