> ## 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 de Microsoft Store para notificar consumibles administrados por la Store y administrados por el desarrollador como usados desde el saldo de un usuario en los servicios de juegos.
Use la API Consume para administrar estos tipos de consumibles de Microsoft Store:
* **Consumible administrado por la Store:** Notifique una cantidad como consumida y quítela del saldo de cantidad actual del usuario especificado.
Los usuarios pueden volver a comprar consumibles administrados por la Store repetidamente sin que su servicio tenga que notificarlos como consumidos o completados.
Para obtener más información, consulte [Solicitud de consumo administrado por la Store](#store-managed-consume-request).
* **Consumible administrado por el desarrollador:** Notifique un producto consumible como completado para un usuario especificado.
Antes de que un usuario pueda volver a comprar un producto consumible administrado por el desarrollador, su aplicación o servicio debe notificar el producto consumible como completado para ese usuario.
Para obtener más información, consulte [Solicitud de consumo administrado por el desarrollador](#developer-managed-consume-request).
## Uso de `trackingId` para validar la finalización del consumo
`trackingId` proporciona una validación del consumo segura frente a reintentos.
Si su servicio no recibe una respuesta de confirmación, vuelva a enviar el mismo cuerpo de solicitud.
El servicio reconoce las solicitudes anteriores y trata los reintentos como comprobaciones de confirmación.
Cada solicitud a la API debe tener un `trackingId` único.
Si la solicitud original no se completó correctamente, o no se recibió la respuesta, el servicio completa la transacción solicitada cuando se reintenta la solicitud.
Si el consumo se completó en una solicitud anterior, la API reconoce la solicitud y envía una respuesta de confirmación.
En este caso, la API no realiza el consumo ni deduce por segunda vez del saldo del usuario.
En su lugar, la API responde con un resultado correcto como si el artículo se hubiera consumido con el saldo restante del usuario.
Por lo tanto, almacene en caché los valores y el `trackingId` de cada solicitud en su servidor o en sus registros hasta que reciba una respuesta de confirmación de que la solicitud se completó.
Para ver un ejemplo, consulte el [ejemplo de Game Service](https://aka.ms/gdkdl).
Cuando la solicitud incluye el parámetro `includeOrderIds`, se esperan estos comportamientos según el tipo de producto del consumible:
| Tipo de consumible | Comportamiento de la primera solicitud de consumo | Comportamiento de la solicitud de consumo reintentada |
| --------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| Administrado por la Store | Se devuelven los OrderIds usados para completar la solicitud | Se devuelven los mismos OrderIds usados para completar la solicitud |
| Administrado por el desarrollador | Se devuelven los OrderIds usados para completar la solicitud | No se devuelven OrderIDs, ya que estos datos no se registran para este tipo de producto |
Si usa consumibles administrados por el desarrollador, no puede obtener los identificadores de pedido de una solicitud de reintento.
## Requisitos previos
Revise los [Requisitos previos para las APIs de servicio a servicio](https://learn.microsoft.com/reference/service-to-service-nav#prerequisites-for-service-to-service-apis).
Esta API admite los tipos de autenticación de Microsoft Entra ID y de X-token de autenticación delegada.
**Limitación de sandbox para los consumibles administrados por el desarrollador:** Cuando se consumen productos consumibles administrados por el desarrollador en un sandbox de desarrollo (no RETAIL), no se admite la autenticación mediante User Store ID o Microsoft Entra ID. En entornos de sandbox, debe usar tokens XSTS de autorización delegada para consumir correctamente productos consumibles administrados por el desarrollador. Esta limitación no se aplica a los consumibles administrados por la Store ni al sandbox RETAIL.
Si no publica la configuración del producto en Partner Center, las llamadas pueden completarse correctamente pero no devolver resultados.
### Códigos de error de autenticación con User Store ID
| Código | Error | Código de error interno | Descripción |
| ------ | ------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 401 | Unauthorized | AuthenticationTokenInvalid | El token de acceso de Microsoft Entra ID no es válido. En algunos casos, el detalle de `ServiceError` contiene más información, como cuando el token ha expirado o falta la notificación `appid`. |
| 401 | Unauthorized | PartnerAadTicketRequired | No se pasó un token de acceso de Microsoft Entra ID al servicio en el encabezado de autorización. |
| 401 | Unauthorized | InconsistentClientId | La notificación `clientId` de la clave de Microsoft Store ID en el cuerpo de la solicitud y la notificación `appid` del token de acceso de Microsoft Entra ID en el encabezado de autorización no coinciden. |
### Códigos de error con la autenticación de X-token
| Código | Error | Código de error interno | Descripción |
| ------ | ------------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 | Unauthorized | Expired Token | El X-token expiró y se necesita uno nuevo para completar la llamada. |
| 403 | Unauthorized | Invalid Token | El token usado no está autorizado para autenticarse con este punto de conexión. El token podría ser para el sandbox o el usuario autenticado (Relying Party) incorrectos. |
| 429 | Throttled | Too frequent calls | El servicio llamó demasiadas veces para el usuario dentro de los límites de llamadas especificados. Para obtener información sobre cuándo su servicio puede realizar otra llamada para este usuario al servicio, consulte la respuesta. |
## Solicitud
### Sintaxis de la solicitud
| Método | URI de solicitud |
| ------ | --------------------------------------------------------------- |
| `POST` | `https://collections.mp.microsoft.com/v8.0/collections/consume` |
### Encabezado de solicitud
| Encabezado | Tipo | Descripción |
| ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `Authorization` | `string` | Obligatorio. El X-token de autorización delegada o el token de acceso de Microsoft Entra ID, según el tipo de autenticación que se use. |
| `Signature` | `string` | Obligatorio cuando se autentica con X-tokens. No es necesario para la autenticación con User Store ID. |
| `User-Agent` | `string` | Opcional pero recomendado. Ayuda a identificar su servicio para el registro y las investigaciones. |
| `Host` | `string` | Debe establecerse en el valor `collections.mp.microsoft.com`. |
| `Content-Length` | `number` | Longitud del cuerpo de la solicitud. |
| `Content-Type` | `string` | Especifica el tipo de solicitud y respuesta. Actualmente, el único valor admitido es `application/json`. |
### Cuerpo de la solicitud
| Parámetro | Tipo | Descripción | Obligatorio |
| ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `beneficiary` | `UserIdentity` | Usuario para el que se consume este artículo. Para obtener más información, consulte [Autenticación con Microsoft Entra ID y User Store IDs](https://learn.microsoft.com/reference/xstore-authenticating-your-service#authenticating-with-microsoft-entra-id-and-user-store-ids). No es necesario para la autenticación con X-token. | Solo para la autenticación con User Store ID |
| `trackingId` | `guid` | Un `trackingId` único proporcionado por el desarrollador para las comprobaciones de redundancia. El GUID debe ser único para cada solicitud. Para obtener más información, consulte [Uso de trackingId para validar la finalización del consumo](#using-trackingid-to-validate-fulfillment-completion). | Sí |
| `productId` | `string` | El `productId` del consumible al que corresponde la solicitud. Se puede obtener en Partner Center o mediante la [consulta de los productos y derechos de un usuario desde un servicio](/reference/microsoft-store-apis/xstore-v9-query-for-products). | Sí |
| `removeQuantity` | `int` | Cantidad que se va a consumir del saldo actual del usuario. | Solo se aplica a los consumibles administrados por la Store. |
| `includeOrderIds` | `bool` | Incluye los OrderIds y LineItemIds de los pedidos usados para completar la solicitud de consumo. Estos valores se pueden usar después con los resultados del [servicio de eventos de Clawback](https://learn.microsoft.com/reference/xstore-managing-refunds-and-chargebacks) para identificar transacciones de consumo reembolsadas en su servicio de juego. | No |
| `sbx` | `string` | Valor opcional para la autenticación con UserStoreIds que especifica el sandbox al que se deben limitar los resultados. Sin este valor, el valor predeterminado es el sandbox RETAIL. La autenticación con X-Token no necesita este valor, ya que el sandbox se especifica dentro del X-Token. **Nota:** Para los consumibles administrados por el desarrollador, no se admite la autenticación con User Store ID con el parámetro `sbx` dirigido a un sandbox de desarrollo. Use la autenticación con tokens XSTS para las pruebas en sandbox de consumibles administrados por el desarrollador. | No |
### Ejemplos de solicitud de consumo
Los ejemplos siguientes usan un User Store ID para la autenticación y requieren el objeto beneficiary en el cuerpo JSON de la solicitud.
#### Solicitud de consumo administrado por la 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
}
```
#### Solicitud de consumo administrado por el desarrollador
El ejemplo siguiente usa la autenticación con User Store ID. Sin embargo, este método de autenticación no funciona para los consumibles administrados por el desarrollador en sandboxes de desarrollo. Si está realizando pruebas en un entorno de sandbox, use en su lugar la autenticación con tokens XSTS. Consulte [Autenticación mediante tokens XSTS de autenticación delegada](https://learn.microsoft.com/reference/xstore-authenticating-your-service#authenticating-with-delegated-authentication-x-tokens) para obtener más detalles.
```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
}
```
## Respuesta
### Cuerpo de la respuesta
| Parámetro | Tipo | Descripción | Obligatorio |
| ------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `itemId` | string | Identificador que distingue el elemento de la colección de otros elementos que posee el usuario. Este identificador es único por producto. | Sí |
| `productId` | `string` | También denominado Store ID del producto dentro del catálogo de Microsoft Store. Un ejemplo de Store ID de un producto es 9NBLGGH42CFD. | Sí |
| `trackingId` | `GUID` | `trackingId` único proporcionado por el autor de la llamada para la solicitud de consumo. | Sí |
| `newQuantity` | `int` | Cantidad restante del saldo del usuario para este producto consumible. El valor es 0 para los consumibles administrados por el desarrollador. | Sí |
| `orderTransactions` | `List` | Matriz de objetos ConsumeOrderTransaction que indica los pedidos usados para completar la solicitud. Solo se devuelve si el parámetro `includeOrderIds` se establece en true en la solicitud. Para obtener más información, consulte la tabla siguiente. | No |
El objeto `ConsumeOrderTransaction` contiene los parámetros siguientes.
| Parámetro | Tipo | Descripción | Obligatorio |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `orderId` | `GUID` | Identificador del pedido de compra del usuario usado para completar total o parcialmente la solicitud de consumo. | Sí |
| `orderLineItemId` | `GUID` | Identificador del artículo de línea en el que se encontraba el consumible dentro del pedido de compra realizado por el usuario. Este identificador es más único para una compra de consumible que OrderId, ya que puede haber varios LineItemIds por OrderID. | Sí |
| `quantityConsumed` | `int` | Cantidad de la solicitud completada por este OrderId / LineItemId específico | Sí |
### Ejemplo de respuesta 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
}
]
}
```
## Artículos relacionados
[Administración de productos desde sus servicios](https://learn.microsoft.com/reference/service-to-service-nav)
[Autenticación de su servicio con las APIs de Microsoft Store](https://learn.microsoft.com/reference/xstore-authenticating-your-service)
[Uso de publisherQuery (Collections v9) para consultar los productos y derechos de un usuario](/reference/microsoft-store-apis/xstore-v9-query-for-products)
[Administración de productos consumibles desde su servicio](https://learn.microsoft.com/reference/xstore-managing-consumables-and-refunds)
[Administración de reembolsos y contracargos desde su servicio](https://learn.microsoft.com/reference/xstore-managing-refunds-and-chargebacks)
## Related topics
- [APIs de servicio de Microsoft Store](/es/reference/microsoft-store-apis/xstore-nav.md)
- [Administración de productos consumibles desde su servicio](/es/publishing/xstore-commerce/xstore-managing-consumables.md)
- [collections.mp.microsoft.com/v9.0/collections/publisherQuery](/es/reference/microsoft-store-apis/xstore-v9-query-for-products.md)
- [API b2bLicensePreview de Collections v8 de Microsoft Store](/es/reference/microsoft-store-apis/xstore-v8-query-for-products.md)
- [purchase.mp.microsoft.com/v8.0/b2b/orders/query](/es/reference/microsoft-store-apis/xstore-v8-clawbackv1.md)