> ## 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/v8.0/collections/consume

> API consume de Collections v8 da Microsoft Store para relatar consumíveis gerenciados pela Store e gerenciados pelo desenvolvedor como usados do saldo de um usuário em serviços de jogos.

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](#store-managed-consume-request).

* **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](#developer-managed-consume-request).

## 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](https://aka.ms/gdkdl).

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](https://learn.microsoft.com/reference/service-to-service-nav#prerequisites-for-service-to-service-apis).

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

<Info>**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.</Info>

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](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 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](#using-trackingid-to-validate-fulfillment-completion). | 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](/pt-BR/reference/microsoft-store-apis/xstore-v9-query-for-products). | 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](https://learn.microsoft.com/reference/xstore-managing-refunds-and-chargebacks) 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

```syntax theme={null}
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

<Note>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](https://learn.microsoft.com/reference/xstore-authenticating-your-service#authenticating-with-delegated-authentication-x-tokens) para obter detalhes.</Note>

```syntax theme={null}
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

```syntax theme={null}
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
        }
    ]
}
```

## Artigos relacionados

[Gerenciar produtos 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)

[Usar publisherQuery (Collections v9) para consultar os produtos e direitos de um usuário](/pt-BR/reference/microsoft-store-apis/xstore-v9-query-for-products)

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

[Gerenciar reembolsos e estornos do seu serviço](https://learn.microsoft.com/reference/xstore-managing-refunds-and-chargebacks)


## Related topics

- [collections.mp.microsoft.com/v8.0/collections/consume](/reference/microsoft-store-apis/xstore-v8-consume.md)
- [Microsoft Store service APIs](/reference/microsoft-store-apis/xstore-nav.md)
- [APIs de servicio de Microsoft Store](/es/reference/microsoft-store-apis/xstore-nav.md)
- [Managing consumable products from your service](/publishing/xstore-commerce/xstore-managing-consumables.md)
- [Microsoft Store 服务 API](/zh-CN/reference/microsoft-store-apis/xstore-nav.md)