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

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

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

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 para obtener más detalles.

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<ConsumeOrderTransaction>`	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

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

Microsoft Store APIs

Uso de `trackingId` para validar la finalización del consumo

Requisitos previos

Códigos de error de autenticación con User Store ID

Códigos de error con la autenticación de X-token

Solicitud

Sintaxis de la solicitud

Encabezado de solicitud

Cuerpo de la solicitud

Ejemplos de solicitud de consumo

Solicitud de consumo administrado por la Store

Solicitud de consumo administrado por el desarrollador

Respuesta

Cuerpo de la respuesta

Ejemplo de respuesta de consumo

Artículos relacionados

​Uso de trackingId para validar la finalización del consumo

​Requisitos previos

​Códigos de error de autenticación con User Store ID

​Códigos de error con la autenticación de X-token

​Solicitud

​Sintaxis de la solicitud

​Encabezado de solicitud

​Cuerpo de la solicitud

​Ejemplos de solicitud de consumo

​Solicitud de consumo administrado por la Store

​Solicitud de consumo administrado por el desarrollador

​Respuesta

​Cuerpo de la respuesta

​Ejemplo de respuesta de consumo

​Artículos relacionados

Uso de `trackingId` para validar la finalización del consumo

Requisitos previos

Códigos de error de autenticación con User Store ID

Códigos de error con la autenticación de X-token

Solicitud

Sintaxis de la solicitud

Encabezado de solicitud

Cuerpo de la solicitud

Ejemplos de solicitud de consumo

Solicitud de consumo administrado por la Store

Solicitud de consumo administrado por el desarrollador

Respuesta

Cuerpo de la respuesta

Ejemplo de respuesta de consumo

Artículos relacionados