> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gerenciando produtos consumíveis a partir do seu serviço

> Descreve como criar um sistema robusto que gerencia consumíveis no serviço do seu jogo, incluindo o gerenciamento de reembolsos de itens consumidos pelos usuários.

Para economias baseadas em consumíveis, use um serviço de back-end confiável para validar e gerenciar transações. Chamadas serviço a serviço são mais seguras e confiáveis do que o atendimento gerenciado pelo cliente, que pode ser afetado por adulteração ou perda de rede.

Este artigo mostra como gerenciar consumíveis e reconciliar reembolsos para reduzir fraudes e perda de receita.

Para gerenciar produtos consumíveis e lidar com reembolsos, chame as seguintes APIs da Microsoft Store a partir do seu serviço. Confira as páginas de documentação para obter detalhes sobre como fazer as chamadas e analisar os resultados.

| API da Microsoft Store | Função |
| - | - |
| [collections.mp.microsoft.com/v8.0/collections/consume](/pt-BR/reference/microsoft-store-apis/xstore-v8-consume) | Consumir ou atender um produto consumível que o usuário possui. |
| [purchase.mp.microsoft.com/v8.0/b2b/orders/query](/pt-BR/reference/microsoft-store-apis/xstore-v8-clawbackv1) | Pedidos de compra - Relata as compras de consumíveis feitas pelo usuário nos últimos 90 dias. |
| [purchase.mp.microsoft.com/v8.0/b2b/clawback/sastoken](/pt-BR/reference/microsoft-store-apis/xstore-v8-clawbackv2-sastoken) | Fornece um token SAS usado para consultar a fila de mensagens do serviço de eventos Clawback em busca de eventos de reembolso relacionados aos seus produtos. |

<Note>
  **Limitação da sandbox:** ao consumir produtos consumíveis gerenciados pelo desenvolvedor em uma sandbox de desenvolvimento, somente a autenticação por token XSTS tem suporte. A autenticação por User Store ID ou Microsoft Entra ID não funciona para chamadas de consumo de Dev-Managed Consumable em ambientes de sandbox. Planeje seus testes de acordo. Para obter mais informações, confira a [seção Pré-requisitos da API Consume](/pt-BR/reference/microsoft-store-apis/xstore-v8-consume#prerequisites).
</Note>

## Utilizando a biblioteca .NET Microsoft.StoreServices e o exemplo

Para ajudar a demonstrar os princípios e fluxos descritos neste artigo, revise o Microsoft.StoreServices Sample, que fornece:

* Uso da biblioteca Microsoft.StoreServices para gerenciar a autenticação e fazer as chamadas aos Microsoft Store Services.
* Lógica de exemplo para gerenciar produtos consumíveis, acompanhar solicitações de consumo pendentes, reconciliar compras reembolsadas, renovar User Store IDs expiradas e muito mais.
* Um guia de configuração que inclui as etapas deste artigo sobre como configurar o seu Microsoft Entra ID para esse método de autenticação.
* [Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services)
* [Microsoft.StoreServices Sample (GitHub)](https://github.com/microsoft/Microsoft-Store-Services-Sample)

## Gerenciando consumíveis

### Estrutura recomendada de um serviço de gerenciamento de consumíveis

Use um único fluxo de servidor para validar a propriedade, atender o uso e reconciliar reembolsos. A estrutura a seguir mantém essas responsabilidades explícitas e seguras para novas tentativas.

| Etapa | Ação do serviço |
| - | - |
| Recebimento de solicitações | Receber solicitações do cliente para usar ou comprar itens com moeda consumível. |
| Autenticação | Autenticar-se nas APIs do Microsoft Store Service. |
| Verificações de saldo | Validar o saldo do usuário dos produtos consumíveis na Store. |
| Atendimento | Consumir ou atender a quantidade necessária do saldo do usuário. |
| Segurança de novas tentativas | Acompanhar solicitações de consumo pendentes e repetir com segurança quando as respostas forem perdidas. |
| Conceder saldo | Conceder o saldo do produto comprado à conta do usuário. |
| Registrar transações | Manter um banco de dados de acompanhamento das transações de consumo e concessão relacionadas ao usuário. |
| Resposta ao cliente | Retornar os resultados da transação ou os itens concedidos ao cliente do jogo. |
| Reconciliação | Processar transações de consumíveis reembolsadas e aplicar ações corretivas. |

### Gerenciando o saldo do usuário no seu serviço vs. na Microsoft Store

Os produtos consumíveis gerenciados pela loja podem ser totalmente gerenciados no serviço do seu jogo consumindo qualquer saldo diferente de zero da Microsoft Store. Como alternativa, o saldo de consumíveis do usuário pode ser gerenciado pela Microsoft Store, consumindo a quantidade somente quando usada para itens no jogo. Os produtos consumíveis gerenciados pelo desenvolvedor, no entanto, exigem gerenciamento em um serviço de jogo. Confira [Escolhendo o tipo de produto certo](/pt-BR/publishing/xstore-commerce/xstore-choosing-product-type) para obter mais informações sobre consumíveis gerenciados pelo desenvolvedor vs. gerenciados pela Microsoft Store.

A abordagem mais comum é acompanhar o saldo efetivo de moeda do usuário no seu serviço. Nesse design, seu serviço consulta saldos de consumíveis diferentes de zero, os consome e credita o valor equivalente em moeda do jogo na conta do usuário. Esse fluxo reduz chamadas repetidas à API da Store após o atendimento, simplifica o tratamento de saldos multiplataforma e oferece às equipes de suporte um sistema central para ajustes de saldo.

Configuração típica: configure cada nível de moeda como um consumível gerenciado pela loja separado que concede a quantidade `1` por compra e, em seguida, mapeie cada produto para seu valor no jogo. Exemplo: um consumível de "500 moedas" aumenta a quantidade na Store para `1`; após o consumo, a quantidade na Store volta para `0` e seu serviço credita 500 moedas.

Os consumíveis gerenciados pela loja podem conceder o valor total diretamente à quantidade na Store no momento da compra (por exemplo, 500 por compra). Nesse modelo, a Store acompanha o crescimento do saldo e seu serviço deduz a quantidade quando os usuários gastam moeda no jogo. No entanto, colocar todos os níveis como SKUs em uma única ID de produto limita recursos como preços promocionais específicos por nível e tokens de resgate 5x5. Confira [Práticas recomendadas para oferecer moeda do jogo](/pt-BR/publishing/xstore-commerce/xstore-consumables#best-practices-for-offering-in-game-currency).

### Usar TrackingIds como um sistema redundante para validação de consumo

Inclua uma `TrackingId` em cada solicitação de consumo. Se uma resposta for perdida, repita com a mesma `TrackingId`, usuário, `productId` e quantidade para confirmar se o consumo original foi bem-sucedido. Essa nova tentativa evita concessões duplicadas e ainda permite repetições seguras.

O fluxo a seguir mostra um padrão de consumo seguro para novas tentativas.

O Produto A (500 moedas do jogo) é um consumível configurado para conceder uma quantidade de 1 na loja.

1. O usuário compra o Produto A e agora tem uma quantidade de `1` do produto ao chamar o serviço de consulta.
2. O serviço do jogo consulta o saldo de consumíveis do usuário na API de consulta da Microsoft Store e vê que o saldo do usuário é `1`.
3. O serviço do jogo gera uma TrackingID, cria uma solicitação de consumo para consumir uma quantidade do produto e adiciona as informações da solicitação a uma lista de transações pendentes.
4. O serviço do jogo envia a solicitação para a API de consumo da Microsoft Store.
5. O serviço do jogo não recebe uma resposta da API de consumo (perda de pacotes de rede, interrupção do serviço, queda de energia e assim por diante). Nesse ponto, o serviço não consegue confirmar se a transação foi concluída. Consultar apenas o inventário pode ser ambíguo se o usuário tiver comprado novamente durante a interrupção. Use a lista de transações pendentes e repita com os mesmos valores de solicitação.
6. O serviço do jogo determina quando deve repetir a solicitação de consumo.
7. O serviço do jogo recria a solicitação de consumo usando o mesmo usuário, ProductId, TrackingId e quantidade.
8. O serviço do jogo envia a solicitação para a API de consumo da Microsoft Store.
9. O serviço do jogo recebe uma resposta de que a solicitação foi bem-sucedida e de que o novo saldo do usuário é '0'.
10. O serviço do jogo adiciona 500 moedas ao saldo de moeda do usuário acompanhado no servidor.
11. O serviço do jogo remove a solicitação de consumo da lista de transações pendentes, pois o item foi consumido, verificado e o usuário recebeu a moeda do jogo correta no serviço.

### Comportamento da API de consumo da Microsoft Store ao verificar solicitações de transações anteriores

Se uma solicitação chegar com valores diferentes, a API a tratará como uma nova solicitação de consumo.

Se a API detectar uma nova tentativa com a mesma `TrackingId`, usuário, quantidade e `productId`, ela não consumirá uma segunda vez. Em vez disso, retornará uma resposta bem-sucedida com o saldo restante atual. Devido a esse comportamento, repetir uma solicitação que atingiu o tempo limite é seguro, desde que os valores da solicitação sejam idênticos.

Se você usar a autenticação X-Token na API de consumo, poderá atualizar e obter um novo X-Token, desde que o novo X-Token seja para o mesmo usuário XBOX da solicitação anterior.

### Mitigando fraudes de devolução e reembolso de consumíveis com o serviço de eventos Clawback

Para ajudar a evitar abusos e devoluções ou reembolsos fraudulentos de produtos consumíveis, seu serviço deve usar o serviço de eventos Clawback. O Clawback permite que seu serviço receba eventos quando um produto consumível é devolvido ou reembolsado. Seu serviço deve remover o valor adicionado da conta do usuário para esse consumível.

Para agir com base em eventos Clawback, use a opção `"includeOrderIds": TRUE` na sua solicitação de consumo para [collections.mp.microsoft.com/v8.0/collections/consume](/pt-BR/reference/microsoft-store-apis/xstore-v8-consume). Seu serviço deve armazenar os dados das transações de consumo das respostas da API usando as seguintes variáveis:

| Variável | Origem | Descrição |
| - | - | - |
| `Key / Unique ID` | \[OrderID]:\[LineItemID]:\[ProductID]:\[TrackingId] | Inclua `ProductID`, pois os pacotes podem reutilizar o mesmo `OrderID` e `LineItemID` em produtos diferentes. Se o seu consumível conceder uma quantidade maior que `1`, inclua `TrackingId` para distinguir operações de consumo individuais. |
| `ProductId` | ProductId da solicitação de consumo | Como o mesmo orderID e orderLineItemID podem ser compartilhados entre diferentes produtos concedidos por meio da compra de um pacote, você também deve acompanhar o ProductID do item consumido. |
| `UserId` | UserId que seu sistema usa para identificar o usuário que recebe o valor do consumível | Os eventos Clawback não fornecem userIds, portanto, você deve acompanhar no seu sistema o usuário que recebe o conteúdo para executar ações de reconciliação. |
| `OrderID` | orderTransactions -> orderId (ao usar "includeOrderIds": true na solicitação /consume) | ID do pedido de compra do usuário usado para atender toda ou parte da solicitação de consumo. Exemplo: ID relacionada à compra de todo o carrinho de compras. |
| `LineItemID` | orderTransactions -> orderLineItemId (ao usar "includeOrderIds": true na solicitação /consume) | ID que representa um produto exclusivo no pedido de compra do usuário usado para atender a solicitação de consumo. Exemplo: ID relacionada a um item exclusivo no carrinho de compras durante a compra. |
| `Qty` | orderTransactions -> quantityConsumed (ao usar "includeOrderIds": true na solicitação /consume) | Quantidade da solicitação atendida por este OrderId / LineItemId específico. Observação: deve ser 1 na configuração padrão de consumível, mas pode ser maior que 1 se o seu consumível estiver configurado para conceder uma quantidade maior que 1 em cada compra. |
| `Status` | Estado atual da transação de consumo no seu sistema, para seu próprio acompanhamento | Útil para que você possa marcar quando uma transação de consumo for reconciliada com um evento Clawback. Também é necessário para Chargebacks e reversões de Chargeback. Por exemplo, se um item for revogado devido à reconciliação de um evento de Chargeback, você poderá desfazer a ação posteriormente se ocorrer um ChargebackReversal. |

Configure esse banco de dados de acompanhamento cedo, de preferência antes da integração com a fila Clawback. Dados antecipados fornecem transações históricas para reconciliações futuras e uma linha de base limpa para medir os efeitos do processamento do Clawback.

Para obter mais informações, confira [Gerenciando reembolsos e estornos a partir do seu serviço](/pt-BR/publishing/xstore-commerce/xstore-managing-refunds).

## Confira também

[Visão geral do Commerce](/pt-BR/publishing/xstore-commerce/xstore-commerce-overview)

[Ecossistemas baseados em consumíveis](/pt-BR/publishing/xstore-commerce/xstore-consumables)

[Gerenciando reembolsos e estornos a partir do seu serviço](/pt-BR/publishing/xstore-commerce/xstore-managing-refunds)

[APIs do Microsoft Store Service](/pt-BR/reference/microsoft-store-apis/index)

[Biblioteca Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services)

[Microsoft.StoreServices Sample (GitHub)](https://github.com/microsoft/Microsoft-Store-Services-Sample)


## Related topics

- [Ecossistemas baseados em consumíveis](/pt-BR/publishing/xstore-commerce/xstore-consumables.md)
- [Solicitar uma ID da Store do Usuário para autenticação de serviço para serviço](/pt-BR/publishing/xstore-commerce/xstore-requesting-userstoreid.md)
- [Escolhendo o tipo de produto certo](/pt-BR/publishing/xstore-commerce/xstore-choosing-product-type.md)
- [Gerenciando reembolsos e estornos a partir do seu serviço](/pt-BR/publishing/xstore-commerce/xstore-managing-refunds.md)
- [Gerenciar produtos de assinatura a partir do seu serviço](/pt-BR/publishing/xstore-commerce/xstore-managing-subscriptions.md)