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

# API b2bLicensePreview do Microsoft Store v8 Collections

> API b2bLicensePreview do Microsoft Store v8 Collections para que serviços de jogos consultem os produtos, direitos e consumíveis de propriedade de um usuário por ID de SKU do produto.

A API b2bLicensePreview permite que seus próprios serviços consultem os produtos e direitos de um usuário.
Você pode limitar a consulta a produtos específicos, tipos de produto ou usar outros filtros na consulta.
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.
Para obter mais informações sobre cenários de compartilhamento, confira [Modelo de compartilhamento de produtos para jogos](https://learn.microsoft.com/fundamentals/xstore-product-sharing-model-for-games).

<Note>Para evitar tempos limite de resposta e tempos de resposta longos, você sempre deve especificar os produtos exatos que deseja nos resultados usando o parâmetro `productSkuIds` na solicitação.</Note>
Chamar sem a lista `productSkuIds` resulta em tempos de resposta mais longos, que aumentam com base no número total de direitos e compras que o usuário fez no XBOX e no aplicativo Microsoft Store.

<Note>A b2bLicensePreview destina-se a chamadas de serviços de parceiros.</Note>
Aplicativos cliente ou jogos não devem chamar esse serviço diretamente.

## b2bLicensePreview (Collections v8) vs. publisherQuery (Collections v9) para consultar produtos

A b2bLicensePreview (Collections v8) é o serviço Collections anterior para consultar direitos de usuário, mas ainda está disponível para uso por parceiros.
A publisherQuery (Collections v9) é a mais recente e fornece recursos expandidos, como a exposição do status da assinatura do XBOX Game Pass.
Ainda existem cenários em que os parceiros podem querer usar a b2bLicensePreview, como o suporte a LegacyProductIds usados pelo serviço XBOX Inventory.

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)

## Solicitação

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

### Sintaxe da solicitação

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

### 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 do Microsoft Entra ID, com base no tipo de autenticação usado. |
| `Signature` | `string` | Obrigatório ao autenticar com X-tokens. Não é obrigatório para autenticação com User Store ID. |
| `User-Agent` | `string` | Opcional, mas recomendado. Ajuda a identificar seu serviço para registro em log e investigações. |
| `Host` | `string` | Deve ser definido com o valor `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>` | Se especificado, o serviço retorna apenas os produtos aplicáveis aos pares de produto/SKU fornecidos. Recomendado para todas as consultas de serviço a serviço, para resultados mais rápidos e confiáveis. Para obter mais informações, confira a tabela a seguir. | Não |
| `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. Para recuperar os resultados restantes da consulta, forneça o `continuationToken` nas chamadas seguintes. | Não |
| `maxPageSize` | `number` | O número máximo de produtos a serem retornados em uma resposta. O valor padrão e máximo é 100. | Não |
| `entitlementFilters` | `list<string>` | Especifica quais tipos de produto retornar nos resultados da consulta. Para obter uma lista de valores válidos, confira [Valores e significados do tipo de produto](#product-type-values-and-meaning). | Não |
| `market` | `string` | O país/região/mercado para o qual você deseja verificar o direito. Usar "neutral" (recomendado) pesquisa todos os mercados. Caso contrário, use o código de país/região ISO 3166 de dois caracteres, por exemplo, US. | Sim |
| `expandSatisfyingItems` | `bool` | Inclui nos resultados itens aos quais o usuário tem direito por meio de pacotes ou assinaturas. Se definido como `false`, os resultados conterão apenas os itens que o usuário comprou, como as informações de produto do pacote pai. Se você estiver usando este parâmetro, sempre especifique para quais produtos deseja resultados, para evitar solicitações longas ou com tempo limite esgotado. | 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>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/v8.0/collections/b2bLicensePreview HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1EtNTBjQ0g0e...
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
    "maxPageSize": 2,
    "excludeDuplicates": true,
    "entitlementFilters": [
        "*:Game",
        "*:Consumable",
        "*:UnmanagedConsumable",
        "*:Durable",
        "*:Pass"
    ],
    "market": "neutral",
    "expandSatisfyingItems": true,
    "productSkuIds": [
        {"productId": "9N30KZZF4BR9"},
        {"productId": "9MXL21XPWWWK"},
        {"productId": "9PLRFWZWWF91"},
        {"productId": "9MZ0MGGFPLTP"}
    ],
    "beneficiaries": [
        {
            "identityType": "b2b",
            "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4...",
            "localTicketReference": ""
        }
    ],
    "sbx": "XDKS.1"
}
```

## Resposta

### Corpo da resposta

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

O objeto `CollectionItemContractV8` 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 |
| `devOfferId` | `string` | A ID da oferta de uma compra no aplicativo. | Não |
| `endDate` | `datetime` | A data de término do item. | Sim |
| `inAppOfferToken` | `string` | A cadeia de caracteres de ID do produto especificada pelo desenvolvedor e atribuída ao item no Partner Center. Um exemplo de ID de produto é product123. | Não |
| `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 |
| `legacyOfferInstanceId` | `string` | O valor `offerInstanceId` fornecido se a solicitação foi feita ao antigo serviço XBOX Inventory. Não deve ser necessário na maioria dos casos. | Não |
| `legacyProductId` | `string` | O formato `ProductID` mais antigo do XBOX Developer Portal, usado pelo serviço XBOX Inventory. Novos produtos criados no Partner Center não têm esse valor por padrão, mas podem ser inscritos para ter esse valor, se necessário. | Não |
| `localTicketReference` | `string` | A ID do `localTicketReference` fornecido anteriormente no corpo da solicitação. | 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 |
| `productFamily` | `string` | Indica a que tipo de produto o produto está relacionado. Geralmente "Games", mas também pode estar em branco para conteúdo relacionado a jogos. | Não |
| `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 |
| `productType` | `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 |
| `purchasedCountry` | `string` | O código de país/região ISO 3166 de dois caracteres que indica a loja regional na qual o produto foi adquirido. | Não |
| `quantity` | `number` | A quantidade do item. Produtos não consumíveis são sempre 1. Para produtos consumíveis, esse valor representa o saldo restante que pode ser consumido ou atendido para o usuário. | Não |
| `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 |
| `sharingSource` | `string` | Indica se o usuário tem direito ao item por causa de um cenário de compartilhamento. No entanto, com chamadas de serviço a serviço, os resultados são sempre limitados a direitos de propriedade direta e o valor sempre deve retornar como `None`. | 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` | `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 |
| - | - | - | - |
| `isTrial` | `bool` | Indica se este produto está licenciado por meio de uma avaliação | Sim |
| `isInTrialPeriod` | `bool` | Indica se o produto está em um período de avaliação, como uma assinatura | 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 |
| - | - |
| `Game` | Um produto de jogo base ou um pacote de jogo. |
| `Application` | Um aplicativo na Microsoft Store que não está listado como jogo. |
| `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. |
| `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. |
| `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 uma assinatura de complemento, que é configurada 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. 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:29:18 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1744
MS-CorrelationId: aadb976e-634e-4e63-92b1-93af49883b43
MS-RequestId: afeb8062-41e3-486e-b6c5-ec53a417bef3
MS-CV: BW/uJSvAbU6p3rbS.0
X-Content-Type-Options: nosniff

{
    "continuationToken": "{\"checkSatisfactionIndex\":2}",
    "items": [
        {
            "acquiredDate": "2021-08-30T21:53:08.2565331+00:00",
            "acquisitionType": "Single",
            "beneficiary": {
                "identityType": "pub",
                "identityValue": "NoUserIdProvided"
            },
            "devOfferId": "",
            "endDate": "2021-08-31T21:53:07.4374279+00:00",
            "id": "1046015f83a8478397064c915224e5d3",
            "legacyOfferInstanceId": "fb758141-05cf-406d-b004-57e2a7c0d889",
            "legacyProductId": "fb758141-05cf-406d-b004-57e2a7c0d889",
            "localTicketReference": "",
            "modifiedDate": "2021-08-30T21:53:08.2589804+00:00",
            "purchasedCountry": "US",
            "productFamily": "",
            "productId": "9N30KZZF4BR9",
            "productKind": "Durable",
            "quantity": 1,
            "recurrenceData": {},
            "satisfiedByProductIds": [],
            "sharingSource": "None",
            "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",
            "beneficiary": {
                "identityType": "pub",
                "identityValue": "NoUserIdProvided"
            },
            "endDate": "9999-12-31T23:59:59.9999999+00:00",
            "id": "27662ad4749342608ec09130b76601f9",
            "legacyOfferInstanceId": "4c584d39-3132-3058-c050-5757574b8500",
            "legacyProductId": "4c584d39-3132-3058-c050-5757574b8500",
            "localTicketReference": "",
            "modifiedDate": "2021-08-30T19:55:44.8043849+00:00",
            "purchasedCountry": "US",
            "productFamily": "Games",
            "productId": "9MXL21XPWWWK",
            "productKind": "Game",
            "quantity": 1,
            "recurrenceData": {},
            "satisfiedByProductIds": [],
            "sharingSource": "None",
            "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, um continuationToken será fornecido na resposta mais recente.
Use esse continuationToken em uma solicitação subsequente, adicionando-o a uma cópia do corpo da solicitação anterior.

Exemplo:

```html theme={null}
POST https://collections.mp.microsoft.com/v8.0/collections/b2bLicensePreview HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1EtNTBjQ0g0e...
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
    "continuationToken": "{\"checkSatisfactionIndex\":2}",
    "maxPageSize": 2,
    "excludeDuplicates": true,
    "entitlementFilters": [
        "*:Game",
        "*:Consumable",
        "*:UnmanagedConsumable",
        "*:Durable",
        "*:Pass"
    ],
    "market": "neutral",
    "expandSatisfyingItems": true,
    "productSkuIds": [
        {"productId": "9N30KZZF4BR9"},
        {"productId": "9MXL21XPWWWK"},
        {"productId": "9PLRFWZWWF91"},
        {"productId": "9MZ0MGGFPLTP"}
    ],
    "beneficiaries": [
        {
            "identityType": "b2b",
            "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4...",
            "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)

[Renovar uma chave de User Store ID](https://learn.microsoft.com/reference/xstore-renew-a-user-store-id-key)


## Related topics

- [Microsoft Store v8 Collections b2bLicensePreview API](/reference/microsoft-store-apis/xstore-v8-query-for-products.md)
- [API b2bLicensePreview de Collections v8 de Microsoft Store](/es/reference/microsoft-store-apis/xstore-v8-query-for-products.md)
- [Microsoft Store service APIs](/reference/microsoft-store-apis/xstore-nav.md)
- [collections.mp.microsoft.com/v9.0/collections/publisherQuery](/reference/microsoft-store-apis/xstore-v9-query-for-products.md)
- [APIs de servicio de Microsoft Store](/es/reference/microsoft-store-apis/xstore-nav.md)