Obter informações de assinatura

Se você planeja vender assinaturas na Web Shop, implemente o recebimento de informações sobre ações com assinaturas de uma das seguintes maneiras:

• via API (adequado para integração sem servidor)
• via webhooks (notificações automáticas, adequado para integração de servidor)

Configure por meio de chamadas de API

No lado do cliente do seu aplicativo, implemente a obtenção de informações sobre assinaturas de usuário usando uma solicitação HTTP GET.

A Xsolla API usa autenticação de acesso HTTP. A solicitação deve conter um cabeçalho Authorization: Bearer <client_user_jwt>, onde <client_user_jwt> é um token exclusivo codificado de acordo com o padrão Base64. Para obtê-lo:

• Ao autorizar por login e senha, use as chamadas de API Register new user e Auth by username and password.
• Ao autorizar através de redes sociais, use as chamadas de API Auth via chamadas social network.

Especifique o ID do projeto como o parâmetro projectId do trajeto. Você pode encontrar esse parâmetro em sua Conta de Distribuidor ao lado do nome do projeto. Especifique como parâmetros de consulta:

• limit — limite para o número de elementos na página (15 elementos são exibidos por padrão).
• offset — número do elemento a partir do qual a lista é gerada (a contagem começa a partir de 0).
• locale — idioma da interface (inglês por padrão). Aceita valores de acordo com a norma ISO 639-1.

-X 'GET' \
  'https://subscriptions.xsolla.com/api/user/v1/projects/{projectId}/subscriptions?locale=ru&limit=5&offset=5 ' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer client_user_jwt'

Exemplo de resposta:

{
  "items": [
    {
      "id": 11111111,
      "plan_id": 11111
      "plan_external_id": "TestChangePlanBase",
      "plan_name": "package_recurrent_name_66053",
      "plan_description": "package_recurrent_description_66053",
      "product_id": null,
      "product_external_id": null,
      "product_name": null,
      "product_description": null,
      "status": "active",
      "date_create": "2021-03-11T13:50:11+03:00",
      "date_next_charge": "2031-04-11T13:51:02+03:00",
      "date_last_charge": "2021-03-11T13:51:02+03:00",
      "charge": {
        "amount": "0.2500",
        "currency": "USD"
      },
      "period": {
        "value": 1,
        "unit": "day"
      }
    }
  ],
  "has_more": true
}

Configuração via webhooks

1. Configure parâmetros para receber webhooks:
   1. Abra seu projeto na Conta de Distribuidor.
   2. Clique em Project settings no menu lateral e vá para a aba Webhooks.
   3. No campo Webhook server, especifique o URL do seu servidor onde deseja receber os webhooks no formato https://example.com. Você também pode especificar o URL que você encontra em uma ferramenta para testar webhooks.
   4. É gerada uma chave secreta para assinar webhooks de projeto por padrão. Se desejar gerar uma nova chave secreta, clique no ícone de atualização.
   5. Clique em Enable webhooks.

2. Implemente o processamento dos seguintes tipos de webhooks em seu aplicativo:
   • Para comprar e renovar uma assinatura:
     • Validação do usuário
     • Pagamento
     • Assinatura criada
     • Assinatura atualizada
   • Para cancelar uma assinatura: Assinatura cancelada
   • Para reembolsar: Reembolso

3. Teste webhooks:
   1. Na Conta de Distribuidor > Project settings > Webhooks, vá para a aba Subscriptions.

2. Para testar webhooks, especifique valores do seu projeto (ID do usuário, ID da fatura) a serem enviados em uma solicitação para o URL do webhook que você forneceu. Na ausência de valores reais, você pode inserir valores arbitrários. Preencha os seguintes campos de formulário:
   • ID do usuário
   • ID da fatura Xsolla
   • Valor
   • Moeda
   • ID do Plano
   • Produto da assinatura (opcional)
   • ID da Fatura — número do pedido interno (opcional)
   • Período de teste (Para testar uma compra de assinatura no modo sandbox ou testar a renovação de assinaturas, defina um valor 0)

3. Clique em Testar.
4. Verifique se você recebeu uma mensagem de êxito de teste. Se o teste for bem-sucedido, o servidor deverá responder com:
   • Código HTTP 204 sem um corpo de mensagem.
   • Código HTTP 400 ou 500 descrevendo o problema se o usuário especificado não foi encontrado ou se uma assinatura inválida foi passada.

4. Teste o recebimento dos webhooks restantes:
   1. Use o modo sandbox para testar a compra e a renovação de uma assinatura e obter os webhooks Assinatura criada, Assinatura atualizada e Assinatura cancelada.
   2. Use o modo online para testar a compra de assinatura em pagamentos reais e obter os webhooks Reembolso e Assinatura cancelada.

Próximos passos

1. Configure a autenticação do usuário.
2. Teste a Web Shop no modo sandbox.

Links úteis

Fluxo de integração