API b2bLicensePreview do Microsoft Store v8 Collections

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.

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.

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.

A b2bLicensePreview destina-se a chamadas de serviços de parceiros.

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

Solicitação

Pré-requisitos

Revise os Pré-requisitos para APIs de serviço a serviço. 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. 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.	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

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

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

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:

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"
}

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.

Confira também

Gerenciar produtos a partir dos seus serviços Autenticar seu serviço com as APIs da Microsoft Store Gerenciar produtos consumíveis a partir do seu serviço Renovar uma chave de User Store ID

Porting

Build Paths

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

Solicitação

Pré-requisitos

Sintaxe da solicitação

Cabeçalho da solicitação

Corpo da solicitação

Exemplo de solicitação

Resposta

Corpo da resposta

Valores e significados do tipo de produto

Valores e significados do status do produto

Valores e significados de acquisitionType do produto

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

Exemplo de resposta

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

Confira também

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

​Solicitação

​Pré-requisitos

​Sintaxe da solicitação

​Cabeçalho da solicitação

​Corpo da solicitação

​Exemplo de solicitação

​Resposta

​Corpo da resposta

​Valores e significados do tipo de produto

​Valores e significados do status do produto

​Valores e significados de acquisitionType do produto

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

​Exemplo de resposta

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

​Confira também

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

Solicitação

Pré-requisitos

Sintaxe da solicitação

Cabeçalho da solicitação

Corpo da solicitação

Exemplo de solicitação

Resposta

Corpo da resposta

Valores e significados do tipo de produto

Valores e significados do status do produto

Valores e significados de acquisitionType do produto

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

Exemplo de resposta

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

Confira também