collections.mp.microsoft.com/v8.0/collections/consume

Use a API Consume para gerenciar estes tipos de consumíveis da Microsoft Store:

Consumível gerenciado pela Store: relate uma quantidade como consumida e remova-a do saldo de quantidade atual do usuário especificado. Os usuários podem recomprar consumíveis gerenciados pela Store repetidamente sem que o seu serviço precise relatá-los como consumidos ou com fulfillment feito. Para obter mais informações, confira Solicitação de consumo gerenciado pela Store.
Consumível gerenciado pelo desenvolvedor: relate um produto consumível como com fulfillment feito para um usuário especificado. Antes que um usuário possa recomprar um produto consumível gerenciado pelo desenvolvedor, seu aplicativo ou serviço deve relatar o produto consumível como com fulfillment feito para esse usuário. Para obter mais informações, confira Solicitação de consumo gerenciado pelo desenvolvedor.

Usar `trackingId` para validar a conclusão do fulfillment

trackingId fornece validação de fulfillment segura para novas tentativas. Se o seu serviço não receber uma resposta de confirmação, reenvie o mesmo corpo de solicitação. O serviço reconhece solicitações anteriores e trata as novas tentativas como verificações de confirmação. Cada solicitação à API deve ter um trackingId exclusivo. Se a solicitação original não tiver sido bem-sucedida, ou se a resposta não tiver sido recebida, o serviço concluirá a transação solicitada quando a solicitação for repetida. Se o fulfillment tiver sido concluído em uma solicitação anterior, a API reconhecerá a solicitação e enviará uma resposta de confirmação. Nesse caso, a API não faz o fulfillment nem deduz uma segunda vez do saldo do usuário. Em vez disso, a API responde com êxito como se o item tivesse sido consumido, com o saldo restante do usuário. Portanto, armazene em cache os valores e o trackingId de cada solicitação no seu servidor ou nos seus logs até receber uma resposta de confirmação de que a solicitação foi atendida. Para obter um exemplo, confira o Game Service Sample. Quando sua solicitação tem o parâmetro includeOrderIds, estes comportamentos são esperados com base no tipo de produto do consumível:

Tipo de consumível	Comportamento da primeira solicitação de consumo	Comportamento da nova tentativa de solicitação de consumo
Gerenciado pela Store	As OrderIds usadas para atender à solicitação são retornadas	As mesmas OrderIds usadas para atender à solicitação são retornadas
Gerenciado pelo desenvolvedor	As OrderIds usadas para atender à solicitação são retornadas	Nenhuma OrderID é retornada, pois esses dados não são rastreados para este tipo de produto

Se você usar consumíveis gerenciados pelo desenvolvedor, não poderá obter as IDs de pedido de uma nova tentativa de solicitação.

Pré-requisitos

Revise os Pré-requisitos para APIs de serviço a serviço. Esta API oferece suporte aos tipos de autenticação Microsoft Entra ID e X-token de autenticação delegada.

Limitação de área restrita para consumíveis gerenciados pelo desenvolvedor: ao consumir produtos consumíveis gerenciados pelo desenvolvedor em uma área restrita de desenvolvimento (não RETAIL), não há suporte para autenticação usando User Store ID ou Microsoft Entra ID. Em ambientes de área restrita, você deve usar tokens XSTS de autorização delegada para consumir com êxito produtos consumíveis gerenciados pelo desenvolvedor. Essa limitação não se aplica a consumíveis gerenciados pela Store nem à área restrita RETAIL.

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

Códigos de erro de autenticação por User Store ID

Código	Erro	Código de erro interno	Descrição
401	Unauthorized	AuthenticationTokenInvalid	O token de acesso do Microsoft Entra ID é inválido. Em alguns casos, o detalhe de `ServiceError` contém mais informações, como quando o token expirou ou a declaração `appid` está ausente.
401	Unauthorized	PartnerAadTicketRequired	Um token de acesso do Microsoft Entra ID não foi passado ao serviço no cabeçalho de autorização.
401	Unauthorized	InconsistentClientId	A declaração `clientId` na chave de Microsoft Store ID no corpo da solicitação e a declaração `appid` no token de acesso do Microsoft Entra ID no cabeçalho de autorização não correspondem.

Códigos de erro ao usar autenticação por X-token

Código	Erro	Código de erro interno	Descrição
401	Unauthorized	Expired Token	O X-token expirou e é necessário um novo para concluir a chamada.
403	Unauthorized	Invalid Token	O token usado não está autorizado a autenticar com este ponto de extremidade. O token pode ser da área restrita ou da Relying Party errada.
429	Throttled	Too frequent calls	O serviço foi chamado muitas vezes para o usuário dentro dos limites de chamada especificados. Para obter informações sobre quando seu serviço pode fazer outra chamada ao serviço para este usuário, confira a resposta.

Solicitação

Sintaxe da solicitação

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

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 por 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
`beneficiary`	`UserIdentity`	O usuário para o qual este item está sendo consumido. Para obter mais informações, confira Autenticar com Microsoft Entra ID e User Store IDs. Não é obrigatório para autenticação por X-token.	Somente para autenticação por User Store ID
`trackingId`	`guid`	Um `trackingId` exclusivo fornecido pelo desenvolvedor para verificações de redundância. O GUID deve ser exclusivo para cada solicitação. Para obter mais informações, confira Usar trackingId para validar a conclusão do fulfillment.	Sim
`productId`	`string`	O `productId` do consumível ao qual a solicitação se refere. Pode ser obtido no Partner Center ou consultando os produtos e direitos de um usuário a partir de um serviço.	Sim
`removeQuantity`	`int`	A quantidade a ser consumida do saldo atual do usuário.	Aplica-se somente a consumíveis gerenciados pela Store.
`includeOrderIds`	`bool`	Inclui as OrderIds e LineItemIds dos pedidos usados para atender à solicitação de consumo. Esses valores podem então ser usados com os resultados do serviço de eventos de Clawback para identificar transações de consumo reembolsadas no seu serviço de jogo.	Não
`sbx`	`string`	Valor opcional para autenticação com UserStoreIds que especifica a área restrita à qual os resultados devem se limitar. Sem esse valor, o padrão é a área restrita RETAIL. A autenticação por X-Token não precisa desse valor, pois a área restrita é especificada no X-Token. Observação: para consumíveis gerenciados pelo desenvolvedor, não há suporte para autenticação por User Store ID com o parâmetro `sbx` direcionado a uma área restrita de desenvolvimento. Use a autenticação por token XSTS para testes em área restrita de consumíveis gerenciados pelo desenvolvedor.	Não

Exemplos de solicitação de consumo

Os exemplos a seguir usam uma User Store ID para autenticação e exigem o objeto beneficiary no corpo JSON da solicitação.

Solicitação de consumo gerenciado pela Store

POST https://collections.mp.microsoft.com/v8.0/collections/consume HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1...
Host: collections.mp.microsoft.com
Content-Type: application/json

{
    "beneficiary" : {
        "localTicketReference": "testReference",
        "identityValue": "eyJ0eXAiOiJ...",
        "identityType": "b2b"
    },
    "productId": "9N0297GK108W",
    "trackingId": "1b3afaa8-8644-40e9-9073-266a3bb8804f",
    "removeQuantity": 1,
    "sandbox": "XDKS.1",
    "includeOrderIds": true
}

Solicitação de consumo gerenciado pelo desenvolvedor

O exemplo a seguir usa autenticação por User Store ID. No entanto, esse método de autenticação não funciona para consumíveis gerenciados pelo desenvolvedor em áreas restritas de desenvolvimento. Se você estiver testando em um ambiente de área restrita, use a autenticação por token XSTS. Confira Autenticar por meio de tokens XSTS de autenticação delegada para obter detalhes.

POST https://collections.mp.microsoft.com/v8.0/collections/consume HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1...
Content-Type: application/json
Host: collections.md.mp.microsoft.com

{
    "beneficiary" : {
        "localTicketReference" : "testReference",
        "identityValue": "eyJ0eXAiOiJ...",
        "identityType": "b2b"
    },
    "productId" : "9NBLGGH5WVP6",
    "trackingId" : "08a14c7c-1892-49fc-9135-190ca4f10490",
    "sbx" : "XDKS.1",
    "includeOrderIds": true
}

Resposta

Corpo da resposta

Parâmetro	Tipo	Descrição	Obrigatório
`itemId`	string	Uma ID que distingue o item da coleção dos outros itens que o usuário possui. Essa ID é exclusiva por produto.	Sim
`productId`	`string`	Também conhecida como Store ID do produto no catálogo da Microsoft Store. Um exemplo de Store ID de um produto é 9NBLGGH42CFD.	Sim
`trackingId`	`GUID`	`trackingId` exclusivo fornecido pelo chamador para a solicitação de consumo.	Sim
`newQuantity`	`int`	Quantidade restante do saldo do usuário para este produto consumível. O valor é 0 para consumíveis gerenciados pelo desenvolvedor.	Sim
`orderTransactions`	`List<ConsumeOrderTransaction>`	Uma matriz de objetos ConsumeOrderTransaction que indicam os pedidos usados para atender à solicitação. Retornada somente se o parâmetro `includeOrderIds` estiver definido como true na solicitação. Para obter mais informações, confira a tabela a seguir.	Não

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

Parâmetro	Tipo	Descrição	Obrigatório
`orderId`	`GUID`	ID do pedido de compra do usuário usado para atender a toda ou parte da solicitação de consumo.	Sim
`orderLineItemId`	`GUID`	ID do item de linha em que o consumível estava no pedido de compra feito pelo usuário. Essa ID é mais exclusiva de uma compra de consumível do que a OrderId, pois pode haver várias LineItemIds por OrderID.	Sim
`quantityConsumed`	`int`	Quantidade da solicitação atendida por esta OrderId / LineItemId específica	Sim

Exemplo de resposta de consumo

HTTP/1.1 200 OK
Date: Sat, 04 Sep 2021 01:59:13 GMT
Content-Type: application/json; charset=utf-8
Server: Kestrel
Content-Length: 140
MS-CorrelationId: c7ed3826-c332-4394-af7e-32800e492695
MS-RequestId: 0702fbcf-01ec-4591-995e-13b92149df4d
MS-CV: rJGMXgDq8E2A1EmX.0
X-Content-Type-Options: nosniff
MS-ServerId: 6

{
    "newQuantity": 0,
    "itemId": "c95fef434d1241d6bdb09090b130b6f4",
    "trackingId": "1b3afaa8-8644-40e9-9073-266a3bb8804f",
    "productId": "9N0297GK108W",
    "orderTransactions": [
        {
            "orderId": "8060a406-85c8-4d01-a105-ff11725499c9",
            "orderLineItemId": "cb054aa0-7392-4cc6-af06-53b285e39259",
            "quantityConsumed": 1
        }
    ]
}

Porting

Build Paths

Usar `trackingId` para validar a conclusão do fulfillment

Pré-requisitos

Códigos de erro de autenticação por User Store ID

Códigos de erro ao usar autenticação por X-token

Solicitação

Sintaxe da solicitação

Cabeçalho da solicitação

Corpo da solicitação

Exemplos de solicitação de consumo

Solicitação de consumo gerenciado pela Store

Solicitação de consumo gerenciado pelo desenvolvedor

Resposta

Corpo da resposta

Exemplo de resposta de consumo

Artigos relacionados

​Usar trackingId para validar a conclusão do fulfillment

​Pré-requisitos

​Códigos de erro de autenticação por User Store ID

​Códigos de erro ao usar autenticação por X-token

​Solicitação

​Sintaxe da solicitação

​Cabeçalho da solicitação

​Corpo da solicitação

​Exemplos de solicitação de consumo

​Solicitação de consumo gerenciado pela Store

​Solicitação de consumo gerenciado pelo desenvolvedor

​Resposta

​Corpo da resposta

​Exemplo de resposta de consumo

​Artigos relacionados

Usar `trackingId` para validar a conclusão do fulfillment

Pré-requisitos

Códigos de erro de autenticação por User Store ID

Códigos de erro ao usar autenticação por X-token

Solicitação

Sintaxe da solicitação

Cabeçalho da solicitação

Corpo da solicitação

Exemplos de solicitação de consumo

Solicitação de consumo gerenciado pela Store

Solicitação de consumo gerenciado pelo desenvolvedor

Resposta

Corpo da resposta

Exemplo de resposta de consumo

Artigos relacionados