> ## 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.

# Consultar os direitos do usuário a partir dos seus serviços

> Consulte os direitos do usuário a partir dos seus serviços usando as APIs Collections Query da Microsoft Store, incluindo direitos satisfatórios e estado de propriedade.

As APIs Collections Query são a principal maneira de os serviços determinarem a propriedade e o estado dos direitos do usuário. Em comparação com as APIs XStore do lado do cliente, as consultas de serviço para serviço dão suporte a cenários mais amplos no nível do editor e a arquiteturas de serviço centralizadas.

Os resultados das APIs de Collections incluem apenas produtos que o usuário de destino possui diretamente ou aos quais tem direito diretamente. Direitos compartilhados válidos no cliente não são retornados nas respostas de serviço para serviço. Para obter mais informações sobre cenários de compartilhamento, consulte [Modelo de compartilhamento de produtos para jogos](/pt-BR/publishing/xstore-commerce/xstore-product-sharing).

Este artigo ajuda a entender e integrar com as APIs Query por meio de:

* [Selecionar a API Collections Query certa para suas necessidades](#selecting-the-right-collections-query-api-for-your-needs)
* [Entender os direitos satisfatórios na resposta](#understanding-satisfying-entitlements-in-the-response)
* [Entender itens duplicados na resposta](#understanding-duplicate-items-in-the-response)

<Note>
  Examine os [Pré-requisitos para APIs de serviço para serviço](/pt-BR/publishing/xstore-commerce/xstore-authenticating-service). Se os produtos não estiverem configurados corretamente para o seu tipo de autenticação, as chamadas podem ser bem-sucedidas, mas não retornar resultados.
</Note>

## Selecionar a API Collections Query certa para suas necessidades

Há duas versões do Collections Query: `b2bLicensePreview` (v8) e `publisherQuery` (v9). Na maioria dos casos, use `publisherQuery`, pois ele tem parâmetros de solicitação simplificados e dá suporte ao status do XBOX Game Pass. Use `b2bLicensePreview` quando precisar de comportamentos legados, como suporte a LegacyProductId.

| Recurso da API Query | [b2bLicensePreview (v8)](/pt-BR/reference/microsoft-store-apis/xstore-v8-query-for-products) | [publisherQuery (v9)](/pt-BR/reference/microsoft-store-apis/xstore-v9-query-for-products) |
| - | - | - |
| Exibir o status da assinatura do XBOX Game Pass de um usuário | Não | Sim |
| Autenticação por X-token | Sim | Sim |
| Autenticação por Microsoft Entra ID / ID de usuário da Store | Sim | Sim |
| StoreIds do Partner Center | Sim | Sim |
| LegacyProductIds (ID do produto do XBOX Inventory / XBOX Developer Portal) | Sim | Não |
| Capacidade de desativar resultados de direitos satisfatórios | Sim | Não |

<Note>
  Embora não haja um URI v9 equivalente para a funcionalidade de consumo, você pode usar o publisherQuery e o URI de consumo v8 juntos sem problemas.
</Note>

## Entender os direitos satisfatórios na resposta

Um usuário pode ter direito a um produto diretamente (compra/resgate) ou indiretamente (pacote/assinatura). Se o direito for indireto, a matriz `satisfiedByProductIds` contém os ProductIds de onde o direito é proveniente.

Exemplo: um usuário comprou o pacote Deluxe Edition de um jogo. Chamar as APIs Query mostra o produto do jogo e todos os produtos incluídos no pacote retornados no resultado. Cada um desses itens tem o ProductID do pacote Deluxe Edition na lista `satisfiedByProductIds`.

## Entender itens duplicados na resposta

Você pode ver vários itens com o mesmo ProductId/SKU quando os usuários têm várias fontes de direito. As diferenças geralmente aparecem em campos como `acquisitionType`, datas e `satisfiedByProductIds`. Defina `excludeDuplicates` como true para recolher várias fontes de direito em um único item com o direito de propriedade mais direto, nesta ordem:

* Compra direta / código de resgate
* Satisfeito por um pacote comprado diretamente
* Satisfeito por uma assinatura
* Satisfeito por uma compra promocional (por exemplo: Games With Gold)

Se as duplicatas vierem da mesma fonte (por exemplo, períodos de assinatura `Active` e `Expired`), apenas um item será retornado (mesmo que `excludeDuplicates` esteja desativado), usando a seguinte prioridade de status:

* `Active`
* `Invalid` (se houver vários direitos inválidos, o item invalidado mais recentemente será retornado)
* `Revoked`

Cenários comuns de duplicatas e seus resultados são mostrados na tabela a seguir.

| Cenário | `excludeDuplicates: false` | `excludeDuplicates: true` |
| - | - | - |
| Compra direta + direito de pacote | Ambos os itens podem aparecer. | O item de compra direta é retornado. |
| Compra direta + direito do Game Pass | Ambos os itens podem aparecer (`Single` e `Recurring`). | O item de compra direta é retornado. |
| Mesma fonte de direito com vários períodos (por exemplo, períodos de assinatura Active + Expired) | Um item é retornado com base na prioridade de status. | Um item é retornado com base na prioridade de status. |

### Exemplo

Um usuário compra o Jogo A e o Complemento B e, mais tarde, compra um Season Pass que também inclui o Complemento B. A resposta pode conter duas entradas para o complemento B: a compra direta e o direito satisfeito pelo Season Pass. Se `excludeDuplicates` for true, apenas a entrada da compra direta será retornada.

## Documentação de referência da API

* [XStore (conteúdo da API)](/pt-BR/reference/system/xstore/xstore_members)

## Confira também

[Visão geral de comércio](/pt-BR/publishing/xstore-commerce/xstore-commerce-overview)

[Gerenciar produtos a partir dos seus serviços](/pt-BR/publishing/xstore-commerce/xstore-authenticating-service)

[Referência da API XStore](/pt-BR/reference/system/xstore/xstore_members)


## Related topics

- [Requisitos do XBOX para jogos do XBOX](/pt-BR/publishing/certification/xbox-requirements.md)
- [XR-037 Dependências de pacotes de conteúdo](/pt-BR/publishing/certification/xr/xr-037.md)
- [Requisitos XBOX testados na certificação para jogos de console XBOX](/pt-BR/publishing/certification/console-cert-tested-requirements.md)
- [XR-013 Vinculação de contas Microsoft a contas do publisher](/pt-BR/publishing/certification/xr/xr-013.md)
- [XR-015 Gerenciamento das comunicações do jogador](/pt-BR/publishing/certification/xr/xr-015.md)