> ## 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 Microsoft Store v8 permettant de signaler comme utilisés, à partir du solde d'un utilisateur, des consommables gérés par le Store et gérés par le développeur dans les services de jeu.

Utilisez l'API Consume pour gérer ces types de consommables Microsoft Store :

* **Consommable géré par le Store :** signalez une quantité comme consommée et retirez-la du solde de quantité actuel de l'utilisateur spécifié.
  Les utilisateurs peuvent racheter des consommables gérés par le Store à plusieurs reprises sans que votre service ait à les signaler comme consommés ou traités.
  Pour plus d'informations, consultez [Requête de consommation gérée par le Store](#store-managed-consume-request).

* **Consommable géré par le développeur :** signalez un produit consommable comme traité pour un utilisateur spécifié.
  Avant qu'un utilisateur puisse racheter un produit consommable géré par le développeur, votre application ou votre service doit signaler le produit consommable comme traité pour cet utilisateur.
  Pour plus d'informations, consultez [Requête de consommation gérée par le développeur](#developer-managed-consume-request).

## Utilisation de `trackingId` pour valider l'achèvement du traitement

`trackingId` fournit une validation du traitement compatible avec les nouvelles tentatives.
Si votre service ne reçoit pas de réponse de confirmation, renvoyez le même corps de requête.
Le service reconnaît les requêtes antérieures et traite les nouvelles tentatives comme des vérifications de confirmation.

Chaque requête adressée à l'API doit avoir un `trackingId` unique.
Si la requête d'origine n'a pas abouti, ou si la réponse n'a pas été reçue, le service effectue la transaction demandée lors de la nouvelle tentative de la requête.
Si le traitement a été effectué lors d'une requête précédente, l'API reconnaît la requête et envoie une réponse de confirmation.
Dans ce cas, l'API n'effectue pas de second traitement ni de seconde déduction du solde de l'utilisateur.
L'API répond plutôt par un succès, comme si l'élément avait été consommé, avec le solde restant de l'utilisateur.

Par conséquent, mettez en cache les valeurs et le `trackingId` de chaque requête sur votre serveur ou dans vos journaux jusqu'à ce que vous receviez une réponse de confirmation indiquant que la requête a été traitée.
Pour obtenir un exemple, consultez l'[exemple de service de jeu](https://aka.ms/gdkdl).

Lorsque votre requête contient le paramètre `includeOrderIds`, les comportements suivants sont attendus en fonction du type de produit consommable :

| Type de consommable | Comportement de la première requête de consommation | Comportement d'une nouvelle tentative de requête de consommation |
| - | - | - |
| Géré par le Store | Les OrderIds utilisés pour traiter la requête sont renvoyés | Les mêmes OrderIds utilisés pour traiter la requête sont renvoyés |
| Géré par le développeur | Les OrderIds utilisés pour traiter la requête sont renvoyés | Aucun OrderID n'est renvoyé, car ces données ne sont pas suivies pour ce type de produit |

Si vous utilisez des consommables gérés par le développeur, vous ne pouvez pas obtenir les ID de commande à partir d'une nouvelle tentative de requête.

## Prérequis

Consultez [Prérequis pour les API de service à service](https://learn.microsoft.com/reference/service-to-service-nav#prerequisites-for-service-to-service-apis).

Cette API prend en charge les types d'authentification Microsoft Entra ID et X-token d'authentification déléguée.

<Info>**Limitation de sandbox pour les consommables gérés par le développeur :** lorsque vous consommez des produits consommables gérés par le développeur dans un sandbox de développement (non RETAIL), l'authentification à l'aide de l'ID Store utilisateur ou de Microsoft Entra ID n'est pas prise en charge. Dans les environnements sandbox, vous devez utiliser des jetons XSTS d'autorisation déléguée pour consommer correctement les produits consommables gérés par le développeur. Cette limitation ne s'applique pas aux consommables gérés par le Store ni au sandbox RETAIL.</Info>

Si vous ne publiez pas la configuration du produit dans Partner Center, les appels peuvent réussir mais ne renvoyer aucun résultat.

### Codes d'erreur d'authentification par ID Store utilisateur

| Code | Erreur | Code d'erreur interne | Description |
| - | - | - | - |
| 401 | Unauthorized | AuthenticationTokenInvalid | Le jeton d'accès Microsoft Entra ID n'est pas valide. Dans certains cas, le détail de `ServiceError` contient plus d'informations, par exemple lorsque le jeton a expiré ou que la revendication `appid` est manquante. |
| 401 | Unauthorized | PartnerAadTicketRequired | Aucun jeton d'accès Microsoft Entra ID n'a été transmis au service dans l'en-tête d'autorisation. |
| 401 | Unauthorized | InconsistentClientId | La revendication `clientId` de la clé d'ID Microsoft Store dans le corps de la requête et la revendication `appid` du jeton d'accès Microsoft Entra ID dans l'en-tête d'autorisation ne correspondent pas. |

### Codes d'erreur lors de l'utilisation de l'authentification X-token

| Code | Erreur | Code d'erreur interne | Description |
| - | - | - | - |
| 401 | Unauthorized | Expired Token | Le X-token a expiré et un nouveau jeton est nécessaire pour effectuer l'appel. |
| 403 | Unauthorized | Invalid Token | Le jeton utilisé n'est pas autorisé à s'authentifier auprès de ce point de terminaison. Le jeton concerne peut-être le mauvais sandbox ou la mauvaise partie de confiance. |
| 429 | Throttled | Too frequent calls | Le service a été appelé trop de fois pour l'utilisateur dans les limites d'appel spécifiées. Pour savoir quand votre service peut effectuer un autre appel au service pour cet utilisateur, consultez la réponse. |

## Requête

### Syntaxe de la requête

| Méthode | URI de requête |
| - | - |
| `POST` | `https://collections.mp.microsoft.com/v8.0/collections/consume` |

### En-tête de la requête

| En-tête | Type | Description |
| - | - | - |
| `Authorization` | `string` | Obligatoire. X-token d'autorisation déléguée ou jeton d'accès Microsoft Entra ID, selon le type d'authentification utilisé. |
| `Signature` | `string` | Obligatoire en cas d'authentification avec des X-tokens. Non obligatoire pour l'authentification par ID Store utilisateur. |
| `User-Agent` | `string` | Facultatif, mais recommandé. Permet d'identifier votre service à des fins de journalisation et d'investigation. |
| `Host` | `string` | Doit être défini sur la valeur `collections.mp.microsoft.com`. |
| `Content-Length` | `number` | Longueur du corps de la requête. |
| `Content-Type` | `string` | Spécifie le type de la requête et de la réponse. Actuellement, la seule valeur prise en charge est `application/json`. |

### Corps de la requête

| Paramètre | Type | Description | Obligatoire |
| - | - | - | - |
| `beneficiary` | `UserIdentity` | Utilisateur pour lequel cet élément est consommé. Pour plus d'informations, consultez [Authentification avec Microsoft Entra ID et les ID Store utilisateur](https://learn.microsoft.com/reference/xstore-authenticating-your-service#authenticating-with-microsoft-entra-id-and-user-store-ids). Non obligatoire pour l'authentification X-token. | Uniquement pour l'authentification par ID Store utilisateur |
| `trackingId` | `guid` | `trackingId` unique fourni par le développeur pour les vérifications de redondance. Le GUID doit être unique pour chaque requête. Pour plus d'informations, consultez [Utilisation de trackingId pour valider l'achèvement du traitement](#using-trackingid-to-validate-fulfillment-completion). | Oui |
| `productId` | `string` | `productId` du consommable concerné par la requête. Peut être obtenu à partir de Partner Center ou en [interrogeant les produits et les droits d'un utilisateur à partir d'un service](/fr/reference/microsoft-store-apis/xstore-v9-query-for-products). | Oui |
| `removeQuantity` | `int` | Quantité à consommer à partir du solde actuel de l'utilisateur. | S'applique uniquement aux consommables gérés par le Store. |
| `includeOrderIds` | `bool` | Inclut les OrderIds et LineItemIds des commandes utilisées pour traiter la requête de consommation. Ces valeurs peuvent ensuite être utilisées avec les résultats du [service d'événements Clawback](https://learn.microsoft.com/reference/xstore-managing-refunds-and-chargebacks) pour identifier les transactions de consommation remboursées dans votre service de jeu. | Non |
| `sbx` | `string` | Valeur facultative pour l'authentification avec des UserStoreIds qui spécifie le sandbox auquel les résultats doivent être limités. Sans cette valeur, le sandbox RETAIL est utilisé par défaut. L'authentification X-Token n'a pas besoin de cette valeur, car le sandbox est spécifié dans le X-Token. **Remarque :** pour les consommables gérés par le développeur, l'authentification par ID Store utilisateur avec le paramètre `sbx` ciblant un sandbox de développement n'est pas prise en charge. Utilisez l'authentification par jeton XSTS pour tester en sandbox les consommables gérés par le développeur. | Non |

### Exemples de requêtes de consommation

Les exemples suivants utilisent un ID Store utilisateur pour l'authentification et nécessitent l'objet beneficiary dans le corps JSON de la requête.

#### Requête de consommation gérée par le 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
}
```

#### Requête de consommation gérée par le développeur

<Note>L'exemple suivant utilise l'authentification par ID Store utilisateur. Toutefois, cette méthode d'authentification ne fonctionne pas pour les consommables gérés par le développeur dans les sandbox de développement. Si vous effectuez des tests dans un environnement sandbox, utilisez plutôt l'authentification par jeton XSTS. Pour plus de détails, consultez [Authentification par jetons XSTS d'authentification déléguée](https://learn.microsoft.com/reference/xstore-authenticating-your-service#authenticating-with-delegated-authentication-x-tokens).</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
}
```

## Réponse

### Corps de la réponse

| Paramètre | Type | Description | Obligatoire |
| - | - | - | - |
| `itemId` | string | ID qui distingue l'élément de collection des autres éléments que possède l'utilisateur. Cet ID est unique par produit. | Oui |
| `productId` | `string` | Également appelé ID Store du produit dans le catalogue du Microsoft Store. Exemple d'ID Store pour un produit : 9NBLGGH42CFD. | Oui |
| `trackingId` | `GUID` | `trackingId` unique fourni par l'appelant pour la requête de consommation. | Oui |
| `newQuantity` | `int` | Quantité restante du solde de l'utilisateur pour ce produit consommable. La valeur est 0 pour les consommables gérés par le développeur. | Oui |
| `orderTransactions` | `List<ConsumeOrderTransaction>` | Tableau d'objets ConsumeOrderTransaction indiquant les commandes utilisées pour traiter la requête. Renvoyé uniquement si le paramètre `includeOrderIds` est défini sur true dans la requête. Pour plus d'informations, consultez le tableau suivant. | Non |

L'objet `ConsumeOrderTransaction` contient les paramètres suivants.

| Paramètre | Type | Description | Obligatoire |
| - | - | - | - |
| `orderId` | `GUID` | ID du bon de commande de l'utilisateur utilisé pour traiter tout ou partie de la requête de consommation. | Oui |
| `orderLineItemId` | `GUID` | ID de la ligne de commande contenant le consommable dans le bon de commande passé par l'utilisateur. Cet ID est plus spécifique à un achat de consommable que l'OrderId, car il peut y avoir plusieurs LineItemIds par OrderID. | Oui |
| `quantityConsumed` | `int` | Partie de la requête traitée par cet OrderId / LineItemId spécifique | Oui |

### Exemple de réponse de consommation

```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
        }
    ]
}
```

## Articles connexes

[Gérer les produits à partir de vos services](https://learn.microsoft.com/reference/service-to-service-nav)

[Authentification de votre service avec les API Microsoft Store](https://learn.microsoft.com/reference/xstore-authenticating-your-service)

[Utilisation de publisherQuery (Collections v9) pour interroger les produits et les droits d'un utilisateur](/fr/reference/microsoft-store-apis/xstore-v9-query-for-products)

[Gestion des produits consommables à partir de votre service](https://learn.microsoft.com/reference/xstore-managing-consumables-and-refunds)

[Gestion des remboursements et des rétrofacturations à partir de votre service](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)