Skip to main content
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. Este artigo ajuda a entender e integrar com as APIs Query por meio de:
Examine os Pré-requisitos para APIs de serviço para serviço. 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.

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

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

​
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

​
Confira também

Visão geral de comércio Gerenciar produtos a partir dos seus serviços Referência da API XStore
Last modified on October 6, 2026