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

# collections.mp.microsoft.com/v9.0/collections/publisherQuery

> API publisherQuery do Microsoft Store v9 Collections que permite que serviços de jogos consultem os produtos, direitos e o status da assinatura do XBOX Game Pass de um usuário.

A publisherQuery permite que seus próprios serviços consultem os produtos e direitos de um usuário, incluindo o status da assinatura do XBOX Game Pass.
Seu serviço não deve sondar regularmente as compras do usuário, para evitar limites de taxa de chamadas baseados em uma janela de tempo por usuário.
Atualmente, o limite é de 100 solicitações de consulta em uma janela de cinco minutos para o mesmo usuário.
Acionar um limite de taxa causa uma resposta HTTP 429 com informações sobre quando a próxima solicitação poderá ser feita.

Os resultados incluem apenas produtos de propriedade direta da conta de usuário em nome da qual seu serviço está chamando, ou aos quais essa conta tem direito.
Direitos compartilhados que podem aparecer no cliente não são retornados. Confira [Modelo de compartilhamento de produtos para jogos](https://learn.microsoft.com/fundamentals/xstore-product-sharing-model-for-games).

Para obter informações específicas sobre como consultar o status da assinatura do Game Pass de um usuário, confira [Detectar o acesso à assinatura do XBOX Game Pass a partir do seu serviço](/pt-BR/publishing/xstore-commerce/xstore-detecting-game-pass).

<Note>A publisherQuery dá suporte apenas a chamadas de serviços de parceiros.</Note>
Aplicativos cliente ou jogos não podem chamar esse serviço diretamente.

## Atualizações e melhorias na publisherQuery (Collections Query v9)

A publisherQuery é a API de consulta do Collections mais recente (v9).
Se estiver migrando da b2bLicensePreview (v8), revise esta seção para conhecer as diferenças de comportamento.

A publisherQuery tem as seguintes alterações e melhorias em relação à b2bLicensePreview:

* Capacidade de consultar o status da assinatura do XBOX Game Pass de um usuário
* Exige uma lista predefinida de produtos a serem retornados.
  Uma prática recomendada, mas não obrigatória com a b2bLicensePreview v8.
  Títulos que não seguiam essa prática recomendada frequentemente tinham problemas após o lançamento, em que a solicitação atingia o tempo limite devido ao grande escopo de conteúdo com base nos parâmetros de consulta.
  Isso impedia que os usuários recebessem créditos no jogo até que o serviço do jogo fosse atualizado para especificar quais ProductIds desejava na solicitação de consulta.
* Campos de dados de resposta simplificados para remover valores não usados ou desnecessários
* Parâmetros de solicitação simplificados com base nos comentários dos desenvolvedores

Removidos do corpo da solicitação:

* Market - Todas as solicitações têm contexto para todas as regiões na publisherQuery
* ExpandSatisfyingItems - Todos os resultados expandem os direitos satisfeitos na publisherQuery
* EntitlementsFilter - Não é usado, pois uma lista predefinida de productIds da consulta é obrigatória

<Note>A publisherQuery não dá suporte a LegacyProductIds (ProductIds gerados a partir do XBOX Developer Portal desativado e usados como ProductId pelo serviço XBOX Inventory).</Note>
Se estiver migrando seu serviço do XBOX Inventory, você precisará mapear internamente o StoreId (valor de ProductId do Collections) para o LegacyProductId correspondente no seu próprio serviço.
Caso contrário, você pode usar a b2bLicensePreview v8, que retorna tanto o StoreId quanto os LegacyProductIds.

Para obter mais informações, confira o artigo correspondente [Selecionar a API de consulta do Collections certa para suas necessidades](https://learn.microsoft.com/reference/xstore-query-user-entitlements#selecting-the-right-collections-query-api-for-your-needs)

### Pré-requisitos

Revise os [Pré-requisitos para APIs de serviço a serviço](https://learn.microsoft.com/reference/service-to-service-nav#prerequisites-for-service-to-service-apis).

Esta API dá suporte aos tipos de autenticação Microsoft Entra ID e X-token de autenticação delegada.

Se a configuração do produto não estiver publicada no Partner Center, as chamadas poderão ter êxito, mas não retornarão resultados.

## Solicitação

### Sintaxe da solicitação

| Método | URI da solicitação |
| - | - |
| `POST` | `https://collections.mp.microsoft.com/v9.0/collections/publisherQuery` |

### Cabeçalho da solicitação

| Cabeçalho | Tipo | Descrição |
| - | - | - |
| `Authorization` | `string` | Obrigatório. O X-token de autorização delegada ou o token de acesso de serviço do Microsoft Entra ID, com base no tipo de autenticação usado. |
| `Signature` | `string` | Obrigatório ao autenticar com X-tokens. |
| `User-Agent` | `string` | Recomendado. Ajuda a identificar seu serviço para registro em log e investigações. |
| `Host` | `string` | Deve ser `collections.mp.microsoft.com`. |
| `Content-Length` | `number` | O comprimento do corpo da solicitação. |
| `Content-Type` | `string` | Especifica o tipo de solicitação e de resposta. Atualmente, o único valor com suporte é `application/json`. |

### Corpo da solicitação

| Parâmetro | Tipo | Descrição | Obrigatório |
| - | - | - | - |
| `beneficiaries` | `UserIdentity` | Usuário para o qual este item está sendo consumido. Para obter mais informações, confira [Autenticação com Microsoft Entra ID e User Store IDs](https://learn.microsoft.com/reference/xstore-authenticating-your-service#authenticating-with-microsoft-entra-id-and-user-store-ids). Não é obrigatório para autenticação com X-token. | Somente para autenticação com User Store ID |
| `productSkuIds` | `list<ProductSkuId>` | Lista de produtos de destino. Para obter mais informações, confira a tabela a seguir. A API publisherQuery v9 dá suporte a no máximo 100 productSkuIds por solicitação. | Sim |
| `continuationToken` | `string` | Se houver vários conjuntos de produtos que não cabem em `maxPageSize`, o corpo da resposta retornará um token de continuação quando o limite de página for atingido. Forneça o token de continuação nas chamadas seguintes para obter mais resultados. | Não |
| `maxPageSize` | `number` | O número máximo de produtos a serem retornados em uma resposta. O padrão é 100 e o valor máximo é 200 itens por página. | Não |
| `excludeDuplicates` | `bool` | Remove direitos duplicados quando o usuário pode ter direito a um único produto a partir de várias fontes. | Não |
| `validityType` | `string` | Quando definido como **All**, todos os produtos de um usuário são retornados, incluindo itens expirados. **Valid** retorna produtos que têm status ativo, data de início \< agora e data de término > agora). **Invalid** retorna produtos que não atendem aos requisitos da opção Valid. | Não |
| `sbx` | `string` | Valor opcional para autenticação com UserStoreIds que especifica a área restrita (sandbox) à qual os resultados devem ser limitados. Sem esse valor, o padrão é a área restrita RETAIL. A autenticação com X-Token não precisa desse valor, pois a área restrita é especificada no X-Token. | Não |
| `filterSatisfiedByProductIds` | `bool` | O valor padrão é False se não for fornecido. Quando False (valor recomendado), fornece uma visão completa de um direito satisfeito a partir dos pacotes ou produtos concessores no campo satisfiedByProductIds.  Quando True, filtra a maioria dos ProductIDs concessores do campo satisfiedByProductIds e é fornecido como uma opção de compatibilidade, conforme necessário para os serviços. | Não |

O objeto `ProductSkuId` contém os parâmetros a seguir.

| Parâmetro | Tipo | Descrição | Obrigatório |
| - | - | - | - |
| `productId` | `string` | Também chamado de Store ID do produto no catálogo da Microsoft Store. Um exemplo de Store ID de um produto é 9NBLGGH42CFD. | Sim |
| `skuId` | `string` | O identificador de SKU específico, se houver várias ofertas do produto no catálogo da Microsoft Store. Um exemplo de Store ID de um SKU é 0010. | Não |

### Exemplo de solicitação

<Note>A API publisherQuery v9 dá suporte a no máximo 100 productSkuIds por solicitação. Se você fornecer mais de 100 productIds em productSkuIds, a API retornará um erro HTTP 400.</Note>

<Note>O `maxPageSize` padrão é 100, mas no exemplo ele é menor para demonstrar a solicitação dos itens restantes.</Note>

```html theme={null}
POST https://collections.mp.microsoft.com/v9.0/collections/publisherQuery HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1...
User-Agent: {identifier string of your service}
Content-Type: application/json; charset=utf-8
Content-Length: 2243

{
  "maxPageSize":2,
  "excludeDuplicates":true,
  "productSkuIds":[
    {"productId": "9N30KZZF4BR9"},
    {"productId": "9MXL21XPWWWK"},
    {"productId": "9PLRFWZWWF91"},
    {"productId": "9MZ0MGGFPLTP"}
  ],
  "beneficiaries": [
    {
      "identityType": "b2b",
      "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
      "localTicketReference": ""
    }
  ],
  "sbx":"XDKS.1",
}
```

## Resposta

### Corpo da resposta

| Parâmetro | Tipo | Descrição | Obrigatório |
| - | - | - | - |
| `continuationToken` | `string` | Esse token é retornado quando o limite de página é atingido. Você pode especificar esse token de continuação nas chamadas seguintes para recuperar os produtos restantes. | Não |
| `items` | `PublisherQueryItemContractV9` | Uma matriz de produtos do usuário especificado. Para obter mais informações, confira a tabela a seguir. | Não |

O objeto `PublisherQueryItemContractV9` contém os parâmetros a seguir.

| Parâmetro | Tipo | Descrição | Obrigatório |
| - | - | - | - |
| `acquiredDate` | `datetime` | Data em que o usuário adquiriu o item. | Sim |
| `acquisitionType` | `string` | Indica como o usuário possui esse direito. Para obter mais informações, confira [Valores e significados de acquisitionType do produto](#product-acquisitiontype-values-and-meaning). | Não |
| `endDate` | `datetime` | A data de término do item. | Sim |
| `id` | `string` | Uma ID que distingue este item da coleção dos outros itens que o usuário possui. Essa ID é exclusiva por produto. | Sim |
| `modifiedDate` | `datetime` | A data em que este item foi modificado pela última vez. Com produtos consumíveis, esse valor muda quando o saldo de quantidade do usuário muda por meio de outra compra do produto consumível ou quando uma solicitação de consumo é emitida. | Sim |
| `productId` | `string` | Também chamado de Store ID do produto no catálogo da Microsoft Store. Um exemplo de Store ID de um produto é 9NBLGGH42CFD. | Sim |
| `productKind` | `string` | Indica o tipo de produto. Para obter mais informações, confira [Valores e significados do tipo de produto](#product-type-values-and-meaning). | Sim |
| `quantity` | `number` | A quantidade do item. Produtos não consumíveis são sempre 1. Para produtos consumíveis, o valor representa o saldo restante que pode ser consumido ou atendido para o usuário. | Não |
| `recurrenceData` | `string` | ID do item usada como parâmetro `recurrenceId` das APIs de gerenciamento de recorrência. Mesmo valor de `id` da [API RecurrenceQuery](/pt-BR/reference/microsoft-store-apis/xstore-v8-recurrence-query) e de `recurrenceId` em um evento de Clawback. | Sim |
| `satisfiedByProductIds` | `list<string>` | Se o usuário tiver direito a este produto por causa de um pacote ou assinatura, os `ProductIds` desses produtos pais serão fornecidos aqui. OBSERVAÇÃO: usar o parâmetro de solicitação `filterSatisfiedByProductIds` como `True` resultará na ausência de alguns resultados neste parâmetro. | Não |
| `skuId` | `string` | O identificador de SKU específico, se houver várias ofertas do produto no catálogo da Microsoft Store. Um exemplo de Store ID de um SKU é 0010. | Sim |
| `startDate` | `datetime` | A data em que o item começa a ser válido. | Sim |
| `status` | `string` | O status do item. Para obter mais informações, confira [Valores e significados do status do produto](#product-status-values-and-meaning). | Sim |
| `tags` | `list<string>` | N/D. | Sim |
| `transactionId` | `GUID` | A ID da transação resultante da compra deste item. Pode ser usada para relatar um item como atendido. Esse valor é a OrderID associada ao momento em que o usuário comprou o item. Não deve ser usada como identificador exclusivo do direito deste usuário | Não |
| `trialData` | `TrialInformation` | Informações sobre este produto: se é uma avaliação e o tempo restante. | Sim |

O objeto `TrialInformation` contém os parâmetros mostrados na tabela a seguir.

| Parâmetro | Tipo | Descrição | Obrigatório |
| - | - | - | - |
| `isInTrialPeriod` | `bool` | Indica se o produto está em um período de avaliação, como uma assinatura | Sim |
| `isTrial` | `bool` | Indica se este produto está licenciado por meio de uma avaliação | Sim |
| `trialTimeRemaining` | `timespan` | Indica o tempo restante de validade da avaliação, no formato DD:HH:MM:SS.MS | Não |

### Valores e significados do tipo de produto

| Valor | Descrição |
| - | - |
| `Application` | Um aplicativo na Microsoft Store que não está listado como jogo. |
| `Consumable` | Um consumível gerenciado pela Store, em que o saldo (ou quantidade) do usuário é mantido e gerenciado no serviço Collections. Na compra, a quantidade é adicionada ao saldo do usuário e pode ser removida por meio de uma solicitação de consumo. Os usuários podem comprar esse tipo de consumível novamente sem que ele seja atendido primeiro. |
| `Durable` | Um conteúdo para download comprado uma vez e de propriedade do usuário até a data de término do produto. Também é o tipo de produto para pacotes de complementos e pacotes de Season Pass. |
| `Game` | Um produto de jogo base. |
| `Pass` | Alguns tipos de assinatura, como o Game Pass |
| `UnmanagedConsumable` | Também chamado de consumível gerenciado pelo desenvolvedor. Deve ser atendido pelo jogo ou pelo serviço do jogo antes que o usuário possa comprar o produto novamente. |
| `Pass` | Uma assinatura gerenciada pela Store. Diferente de um tipo de assinatura de complemento configurado na página Complementos de um aplicativo no Partner Center. |

### Valores e significados do status do produto

| Valor | Descrição |
| - | - |
| `Active` | O usuário tem direito ativo ao produto (incluindo itens em pré-venda). O usuário deve ter acesso a ele. |
| `Revoked` | Geralmente indica que o usuário solicitou um reembolso. |
| `Expired` | O produto fazia parte de um direito (geralmente uma assinatura) que já expirou. |
| `Banned` | N/D. |
| `Suspended` | N/D. |

### Valores e significados de acquisitionType do produto

| Valor | Descrição |
| - | - |
| `Single` | Compra digital direta ou resgate de código. |
| `Recurring` | De propriedade do usuário ou com direito por meio de uma assinatura. |
| `Conditional` | De propriedade do usuário, mas requer outros produtos para continuar o uso. Ex.: jogos obtidos pelo Games With Gold |

#### Noções básicas sobre os resultados de direitos satisfeitos com o campo `satisfiedByProductIds`

Se a matriz `satisfiedByProductIds` estiver vazia, o usuário tem um direito direto ao item, proveniente de uma compra direta.
Caso contrário, se a matriz `satisfiedByProductIds` tiver um ou mais ProductIds, o usuário tem direito ao item por meio desses produtos (pacotes, assinaturas etc.).

Se o usuário tiver um direito direto e um direito satisfeito a um item, e `excludeDuplicates` na solicitação for `True`, o direito direto terá prioridade e `satisfiedByProductIds` ficará vazio.

### Exemplo de resposta

```json theme={null}
HTTP/1.1 200 OK
Date: Wed, 10 Nov 2021 02:21:22 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1115
MS-CorrelationId: d46cbd11-c2cf-4d8b-99b3-ea63ea976f39
MS-RequestId: 76b82179-2c83-41b2-b9f7-6e775f2c0fed
MS-CV: zpiOM+izH0iubCuw.0

{
    "continuationToken": "{\"checkSatisfactionIndex\":2}",
    "items": [
        {
            "acquiredDate": "2021-08-30T21:53:08.2565331+00:00",
            "acquisitionType": "Single",
            "endDate": "2021-08-31T21:53:07.4374279+00:00",
            "id": "1046015f83a8478397064c915224e5d3",
            "modifiedDate": "2021-08-30T21:53:08.2589804+00:00",
            "productId": "9N30KZZF4BR9",
            "productKind": "Durable",
            "quantity": 1,
            "satisfiedByProductIds": [],
            "skuId": "0010",
            "startDate": "2021-08-30T21:53:07.4374279+00:00",
            "status": "Active",
            "tags": [],
            "transactionId": "995ec667-8114-4ab9-9f11-597a8419a775",
            "trialData": {
                "isInTrialPeriod": false,
                "isTrial": false
            }
        },
        {
            "acquiredDate": "2021-08-30T19:55:44.7994325+00:00",
            "acquisitionType": "Single",
            "endDate": "9999-12-31T23:59:59.9999999+00:00",
            "id": "27662ad4749342608ec09130b76601f9",
            "modifiedDate": "2021-08-30T19:55:44.8043849+00:00",
            "productId": "9MXL21XPWWWK",
            "productKind": "Game",
            "quantity": 1,
            "satisfiedByProductIds": [],
            "skuId": "0010",
            "startDate": "2021-08-30T19:40:44.7994325+00:00",
            "status": "Active",
            "tags": [
                "4c584d39-3132-3058-c050-5757574b8500"
            ],
            "transactionId": "8d5ed958-6c72-4812-87fc-57b105d3d197",
            "trialData": {
                "isInTrialPeriod": true,
                "isTrial": true,
                "trialTimeRemaining": "09:43:52.8580690"
            }
        }
    ]
}
```

### Solicitando os resultados restantes com o token de continuação

Se a consulta tiver mais resultados do que podem ser retornados em uma única resposta (controlado pelo maxPageSize), a resposta da consulta inicial terá um continuationToken.
Você pode então usar esse continuationToken em uma solicitação subsequente, adicionando o token de continuação a uma cópia do corpo da solicitação anterior.

Exemplo de solicitação de continuação:

```html theme={null}
POST https://collections.mp.microsoft.com/v9.0/collections/publisherQuery HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1...
User-Agent: {identifier string of your service}
Content-Type: application/json; charset=utf-8
Content-Length: 2243

{
  "continuationToken":"{\"checkSatisfactionIndex\":2}",
  "maxPageSize":2,
  "excludeDuplicates":true,
  "productSkuIds":[
    {"productId": "9N30KZZF4BR9"},
    {"productId": "9MXL21XPWWWK"},
    {"productId": "9PLRFWZWWF91"},
    {"productId": "9MZ0MGGFPLTP"}
  ],
  "beneficiaries": [
    {
      "identityType": "b2b",
      "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
      "localTicketReference": ""
    }
  ],
  "sbx":"XDKS.1",
}
```

<Note>Mesmo que você especifique o sinalizador excludeDuplicates, ao usar um token de continuação é possível obter entradas de direitos com status diferentes. Portanto, verifique se há entradas duplicadas nos resultados e se elas têm um status diferente de Active.</Note>

## Confira também

[Gerenciar produtos a partir dos seus serviços](https://learn.microsoft.com/reference/service-to-service-nav)

[Autenticar seu serviço com as APIs da Microsoft Store](https://learn.microsoft.com/reference/xstore-authenticating-your-service)

[Gerenciar produtos consumíveis a partir do seu serviço](https://learn.microsoft.com/reference/xstore-managing-consumables-and-refunds)


## Related topics

- [collections.mp.microsoft.com/v9.0/collections/publisherQuery](/reference/microsoft-store-apis/xstore-v9-query-for-products.md)
- [Microsoft Store service APIs](/reference/microsoft-store-apis/xstore-nav.md)
- [Detect XBOX Game Pass subscription access from your service](/publishing/xstore-commerce/xstore-detecting-game-pass.md)
- [APIs de servicio de Microsoft Store](/es/reference/microsoft-store-apis/xstore-nav.md)
- [Detección del acceso a la suscripción a XBOX Game Pass desde su servicio](/es/publishing/xstore-commerce/xstore-detecting-game-pass.md)