Itens gratuitos

Como funciona

Itens grátis são um tipo de item que o usuário pode obter sem gastar moedas virtuais ou reais. Estes incluem:

• Itens virtuais
• Conjuntos
• Pacotes de moedas virtuais

Os itens grátis estão disponíveis apenas para usuários autorizados. Usuários não autorizados só podem visualizar o catálogo de itens grátis.

Exemplos de uso:

• Você pode dar itens grátis em datas importantes para o seu projeto (por exemplo, no dia em que o projeto foi fundado) para recompensar os usuários por sua lealdade.
• Você pode presentear pacotes de iniciante grátis do jogo na loja para atrair novos usuários ao jogo.

Você pode limitar a quantidade grátis de itens exclusivos caso o usuário já os possuam.

Quem pode usar

• Para parceiros que já têm o Shop Builder e desejam configurar um novo tipo de item — itens gratuitos.
• Para parceiros que desejam aumentar a fidelidade dos usuários atuais ou atrair novos jogadores.

Fluxo de integração

1. Crie itens gratuitos das seguintes maneiras:
   • via Conta de Distribuidor
   • via chamadas de API
2. Configure a Store.
3. Obtenha o status do pedido de um usuário.

Criar via Conta de Distribuidor

1. Abra seu projeto na Conta de Distribuidor.
2. Clique em Store no menu lateral.
3. No painel Virtual Items, clique em Configure.
4. Clique em + e selecione Create item na lista suspensa.
5. Especifique:
   • Imagem
   • SKU
   • Um ou vários grupos aos quais o item deve pertencer
   • Nome
   • Descrição
   • Propriedade de item: consumível, não consumível ou item de tempo limitado
6. No bloco Price settings, escolha Free item.
7. Se você quiser limitar a disponibilidade de itens a usuários específicos, defina a opção Limit number of times one user can buy this item como On.
8. Se você quiser mostrar um item na loja, defina a opção Show item in store como On.
9. Clique em Create item.

Criar via chamadas de API

1. Para criar itens gratuitos, use chamadas de API da subseção Admin:
   • Para itens virtuais — Obter pedido
   • Paca pacotes de moedas — Criar pacote de moedas virtuais
   • Para conjuntos — Criar conjunto
   Ao criar ou editar um item, passe is_free = true no corpo da solicitação.
2. Se você quiser limitar a disponibilidade de itens para usuários específicos, chame qualquer método de API para criar ou editar um item e especifique o valor do parâmetro limits.per_user.

Configurar a Store

Compra rápida

 1{
 2  "method": "POST",
 3  "url": "https://mybestgame.com/xsolla/notification",
 4  "body": {
 5    "items": [
 6      {
 7        "sku": "gift_direct_game_reward-supercoin",
 8        "type": "virtual_currency",
 9        "is_pre_order": false,
10        "quantity": 500,
11        "amount": "0",
12        "promotions": [
13
14        ]
15      },
16      {
17        "sku": "package-500_supercoin",
18        "type": "bundle",
19        "is_pre_order": false,
20        "quantity": 1,
21        "amount": "0",
22        "promotions": [
23
24        ]
25      },
26      {
27        "sku": "xsolla-giveaway_offer_11_14_22",
28        "type": "bundle",
29        "is_pre_order": false,
30        "quantity": 1,
31        "amount": "0",
32        "promotions": [
33
34        ]
35      }
36    ],
37    "notification_type": "order_paid",
38    "order": {
39      "id": 12345678,
40      "mode": "default",
41      "currency_type": "unknown",
42      "currency": null,
43      "amount": "0",
44      "status": "paid",
45      "platform": "xsolla",
46      "comment": null,
47      "invoice_id": null,
48      "promotions": [
49
50      ]
51    },
52    "user": {
53      "external_id": "1234567812345678",
54      "email": null
55    }
56  },
57  "headers": {
58    "Authorization": "Signature 3b840ccefea111dcdfd111db1fdc6df969a3ec11",
59    "Accept": "application/json",
60    "Content-Type": "application/json"
61  },
62  "type": "webhook_payment",
63  "callback_parameters": {
64    "order_id": 12345678
65  }
66}

• Se o ouvinte aceitou e processou corretamente o webhook — código de resposta HTTP 200 ou 204.
• Se o erro esperado ocorrer — código de resposta HTTP 4xx.
Observação
Neste caso, os itens são adicionados ao inventário do jogador e a ordem é marcada como bem-sucedida do lado da Xsolla.
• Seu ouvinte também pode retornar um código de resposta HTTP 5xx para erros temporários em seu servidor. Nesse caso, o serviço de alerta Xsolla usa um mecanismo de repetição.

Compra no carrinho

Se um usuário usar a compra de carrinho:

• Se o carrinho do usuário contiver itens pagos e gratuitos, chame o método API Criar pedido com todos os itens de um carrinho específico e Criar pedido com todos os itens do carrinho atual atual para criar pedidos. Os usuários efetuarão o pagamento do pedido através do formulário de pagamento Pay Station.
• Se o carrinho do usuário contiver apenas itens gratuitos, chame a API Criar pedido com carrinho grátis e Criar pedido com carrinho gratuito específico para obter um carrinho gratuito. Neste caso, a interface de pagamento não será usada.

O exemplo de webhook é semelhante ao exemplo de compra rápida.