API b2bLicensePreview de Collections v8 de Microsoft Store

La API b2bLicensePreview permite que sus propios servicios consulten los productos y derechos de un usuario. Puede limitar la consulta a productos concretos, tipos de producto o usar otros filtros en la consulta. Su servicio no debería sondear con regularidad las compras del usuario para evitar los límites de velocidad de llamadas basados en una ventana de tiempo por usuario. Actualmente, el límite es de 100 solicitudes de consulta en una ventana de cinco minutos para el mismo usuario. Alcanzar un límite de velocidad genera una respuesta HTTP 429 con información sobre cuándo se puede realizar la siguiente solicitud. Los resultados solo incluyen los productos que posee directamente o a los que tiene derecho la cuenta de usuario en cuyo nombre llama su servicio. No se devuelven los derechos compartidos que pueden aparecer en el cliente. Para obtener más información sobre los escenarios de uso compartido, consulte Modelo de uso compartido de productos para juegos.

Para evitar tiempos de espera de respuesta y tiempos de respuesta largos, debe especificar siempre los productos exactos que quiere en los resultados mediante el parámetro productSkuIds de la solicitud.

Llamar sin la lista productSkuIds genera tiempos de respuesta más largos, que aumentan en función del número total de derechos y compras que el usuario haya realizado en XBOX y en la aplicación Microsoft Store.

b2bLicensePreview es para llamadas desde servicios de asociados.

Las aplicaciones cliente o los juegos no deben llamar a este servicio directamente.

b2bLicensePreview (Collections v8) frente a publisherQuery (Collections v9) para consultar productos

b2bLicensePreview (Collections v8) es el servicio de Collections anterior para consultar los derechos de usuario, pero sigue disponible para el uso de los asociados. publisherQuery (Collections v9) es el más reciente y proporciona características ampliadas, como la exposición del estado de suscripción a XBOX Game Pass. Aún hay escenarios en los que los asociados podrían querer usar b2bLicensePreview, como la compatibilidad con los LegacyProductIds usados por el servicio de inventario de XBOX. Para obtener más información, consulte el artículo correspondiente Selección de la API de consulta de Collections adecuada para sus necesidades

Solicitud

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. Si no publica la configuración del producto en Partner Center, las llamadas pueden completarse correctamente pero no devolver resultados.

Sintaxis de la solicitud

Método	URI de solicitud
`POST`	`https://collections.mp.microsoft.com/v8.0/collections/b2bLicensePreview`

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
`beneficiaries`	`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
`productSkuIds`	`list<ProductSkuId>`	Si se especifica, el servicio solo devuelve los productos aplicables a los pares producto/SKU proporcionados. Se recomienda para todas las consultas de servicio a servicio para obtener resultados más rápidos y confiables. Para obtener más información, consulte la tabla siguiente.	No
`continuationToken`	`string`	Si hay varios conjuntos de productos que no caben dentro de `maxPageSize`, el cuerpo de la respuesta devuelve un token de continuación cuando se alcanza el límite de la página. Para recuperar los resultados restantes de la consulta, proporcione el `continuationToken` en las llamadas posteriores.	No
`maxPageSize`	`number`	Número máximo de productos que se devuelven en una respuesta. El valor predeterminado y máximo es 100.	No
`entitlementFilters`	`list<string>`	Especifica qué tipos de producto se devuelven en los resultados de la consulta. Para obtener una lista de los valores válidos, consulte Valores de tipo de producto y su significado.	No
`market`	`string`	País/región/mercado para el que quiere comprobar el derecho. Con “neutral” (recomendado) se buscan todos los mercados. De lo contrario, use el código de país o región ISO 3166 de dos caracteres, por ejemplo, US.	Sí
`expandSatisfyingItems`	`bool`	Incluye en los resultados los artículos a los que se tiene derecho a través de agrupaciones o suscripciones. Si se establece en `false`, los resultados solo contienen los artículos que compró el usuario, como la información del producto de la agrupación principal. Si usa este parámetro, especifique siempre los productos de los que quiere resultados para evitar solicitudes largas o con tiempo de espera agotado.	No
`excludeDuplicates`	`bool`	Quita los derechos duplicados cuando el usuario puede tener derecho a un único producto desde varios orígenes.	No
`validityType`	`string`	Cuando se establece en All, se devuelven todos los productos de un usuario, incluidos los artículos expirados. Valid devuelve los productos con estado activo, fecha de inicio < ahora y fecha de finalización > ahora. Invalid devuelve los productos que no cumplen los requisitos de la opción Valid.	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.	No
`filterSatisfiedByProductIds`	`bool`	El valor predeterminado es False si no se proporciona. Cuando es False (valor recomendado), proporciona una vista completa de un derecho satisfecho a partir de las agrupaciones o productos que lo conceden en el campo satisfiedByProductIds. Cuando es True, filtra la mayoría de los ProductIDs que satisfacen el derecho del campo satisfiedByProductIds y se proporciona como opción de compatibilidad según lo necesiten los servicios.	No

El objeto ProductSkuId contiene los parámetros siguientes.

Parámetro	Tipo	Descripción	Obligatorio
`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í
`skuId`	`string`	Identificador de SKU específico si hay varias ofertas del producto en el catálogo de Microsoft Store. Un ejemplo de Store ID de una SKU es 0010.	No

Ejemplo de solicitud

El valor predeterminado de maxPageSize es 100, pero en el ejemplo es menor para demostrar cómo solicitar los artículos restantes.

POST https://collections.mp.microsoft.com/v8.0/collections/b2bLicensePreview HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1EtNTBjQ0g0e...
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
    "maxPageSize": 2,
    "excludeDuplicates": true,
    "entitlementFilters": [
        "*:Game",
        "*:Consumable",
        "*:UnmanagedConsumable",
        "*:Durable",
        "*:Pass"
    ],
    "market": "neutral",
    "expandSatisfyingItems": true,
    "productSkuIds": [
        {"productId": "9N30KZZF4BR9"},
        {"productId": "9MXL21XPWWWK"},
        {"productId": "9PLRFWZWWF91"},
        {"productId": "9MZ0MGGFPLTP"}
    ],
    "beneficiaries": [
        {
            "identityType": "b2b",
            "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4...",
            "localTicketReference": ""
        }
    ],
    "sbx": "XDKS.1"
}

Respuesta

Cuerpo de la respuesta

Parámetro	Tipo	Descripción	Obligatorio
`continuationToken`	`string`	Si hay varios conjuntos de productos, este token se devuelve cuando se alcanza el límite de la página. Puede especificar este token de continuación en llamadas posteriores para recuperar los productos restantes.	No
`items`	`CollectionItemContractV8`	Matriz de productos del usuario especificado. Para obtener más información, consulte la tabla siguiente.	No

El objeto CollectionItemContractV8 contiene los parámetros siguientes.

Parámetro	Tipo	Descripción	Obligatorio
`acquiredDate`	`datetime`	Fecha en que el usuario adquirió el artículo.	Sí
`acquisitionType`	`string`	Indica cómo tiene el usuario este derecho. Para obtener más información, consulte Valores de acquisitionType del producto y su significado.	No
`devOfferId`	`string`	Identificador de oferta de una compra desde la aplicación.	No
`endDate`	`datetime`	Fecha de finalización del artículo.	Sí
`inAppOfferToken`	`string`	Cadena de identificador de producto especificada por el desarrollador y asignada al artículo en Partner Center. Un ejemplo de identificador de producto es product123.	No
`id`	`string`	Identificador que distingue este elemento de la colección de otros elementos que posee el usuario. Este identificador es único por producto.	Sí
`legacyOfferInstanceId`	`string`	Valor `offerInstanceId` proporcionado si la solicitud se realizó al antiguo servicio de inventario de XBOX. No debería ser necesario en la mayoría de los casos.	No
`legacyProductId`	`string`	Formato antiguo de `ProductID` del portal para desarrolladores de XBOX y usado por el servicio de inventario de XBOX. Los productos nuevos creados en Partner Center no tienen este valor de forma predeterminada, pero se pueden inscribir para tenerlo si es necesario.	No
`localTicketReference`	`string`	Identificador del `localTicketReference` proporcionado previamente en el cuerpo de la solicitud.	Sí
`modifiedDate`	`datetime`	Fecha en que se modificó por última vez este artículo. Con los productos consumibles, este valor cambia cuando el saldo de cantidad del usuario cambia mediante otra compra del producto consumible o cuando se emite una solicitud de consumo.	Sí
`productFamily`	`string`	Indica con qué tipo de producto se relaciona el producto. Normalmente es “Games”, pero también puede estar en blanco para contenido relacionado con juegos.	No
`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í
`productType`	`string`	Indica el tipo de producto. Para obtener más información, consulte Valores de tipo de producto y su significado.	Sí
`purchasedCountry`	`string`	Código de país o región ISO 3166 de dos caracteres que indica la tienda regional desde la que se adquirió el producto.	No
`quantity`	`number`	Cantidad del artículo. Para los productos no consumibles siempre es 1. Para los productos consumibles, este valor representa el saldo restante que se puede consumir o completar para el usuario.	No
`satisfiedByProductIds`	`list<string>`	Si se tiene derecho a este producto debido a una agrupación o suscripción, aquí se proporcionan los `ProductIds` de esos productos principales. NOTA: usar el parámetro de solicitud `filterSatisfiedByProductIds` como `True` provocará que falten algunos resultados en este parámetro.	No
`sharingSource`	`string`	Indica si se tiene derecho al artículo debido a un escenario de uso compartido. Sin embargo, con las llamadas de servicio a servicio, los resultados siempre se limitan a los derechos de propiedad directa y el valor debe devolverse siempre como `None`.	No
`skuId`	`string`	Identificador de SKU específico si hay varias ofertas del producto en el catálogo de Microsoft Store. Un ejemplo de Store ID de una SKU es 0010.	Sí
`startDate`	`datetime`	Fecha en que el artículo empieza a ser válido.	Sí
`status`	`string`	Estado del artículo. Para obtener más información, consulte Valores de estado del producto y su significado.	Sí
`tags`	`string`	N/D.	Sí
`transactionId`	`GUID`	Identificador de transacción resultante de la compra de este artículo. Se puede usar para notificar un artículo como completado. Este valor es el OrderID asociado al momento en que el usuario compró el artículo. No debe usarse como identificador único del derecho de este usuario	No
`trialData`	`TrialInformation`	Información sobre este producto: si es una versión de prueba y el tiempo restante.	Sí

El objeto TrialInformation contiene los parámetros que se muestran en la tabla siguiente.

Parámetro	Tipo	Descripción	Obligatorio
`isTrial`	`bool`	Indica si este producto tiene licencia mediante una versión de prueba	Sí
`isInTrialPeriod`	`bool`	Indica si el producto está en un período de prueba, como una suscripción	Sí
`trialTimeRemaining`	`timespan`	Indica el tiempo restante de validez de la versión de prueba con el formato DD:HH:MM:SS.MS	No

Valores de tipo de producto y su significado

Valor	Descripción
`Game`	Un producto de juego base o una agrupación de juegos.
`Application`	Una aplicación de Microsoft Store que no aparece como juego.
`Durable`	Contenido descargable que se compra una vez y se posee hasta la fecha de finalización del producto. También es el tipo de producto de las agrupaciones de complementos y de las agrupaciones de pases de temporada.
`Consumable`	Consumible administrado por la Store, donde el saldo (o cantidad) del usuario se mantiene y administra en el servicio de Collections. Al comprarlo, la cantidad se agrega al saldo del usuario y después se puede quitar realizando una solicitud de consumo. Los usuarios pueden volver a comprar este tipo de consumible sin que se haya consumido primero.
`UnmanagedConsumable`	También denominado consumible administrado por el desarrollador. Debe completarse desde el juego o el servicio del juego antes de que el usuario pueda volver a comprar el producto.
`Pass`	Una suscripción administrada por la Store. Es diferente de una suscripción de complemento, que se configura en la página de complementos de una aplicación en Partner Center.

Valores de estado del producto y su significado

Valor	Descripción
`Active`	El producto tiene un derecho activo. El usuario debería tener acceso a él.
`Revoked`	Normalmente indica que el usuario solicitó un reembolso.
`Expired`	El producto formaba parte de un derecho (normalmente una suscripción) que ha expirado desde entonces.
`Banned`	N/D.
`Suspended`	N/D.

Valores de acquisitionType del producto y su significado

Valor	Descripción
`Single`	Compra digital directa o canje de código.
`Recurring`	Se posee o se tiene derecho mediante una suscripción.
`Conditional`	Se posee pero requiere otros productos para seguir usándolo. Ejemplo: juegos obtenidos con Games With Gold

Descripción de los resultados de derechos satisfechos con el campo `satisfiedByProductIds`

Si la matriz satisfiedByProductIds está vacía, el usuario tiene un derecho directo sobre el artículo derivado de una compra directa. De lo contrario, si la matriz satisfiedByProductIds tiene uno o varios ProductIds, el usuario tiene derecho al artículo a partir de esos productos (agrupaciones, suscripciones, etc.). Si el usuario tiene un derecho directo y otro satisfecho sobre un artículo, y excludeDuplicates en la solicitud es True, el derecho directo tendrá prioridad y satisfiedByProductIds estará vacío.

Ejemplo de respuesta

HTTP/1.1 200 OK
Date: Wed, 10 Nov 2021 02:29:18 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1744
MS-CorrelationId: aadb976e-634e-4e63-92b1-93af49883b43
MS-RequestId: afeb8062-41e3-486e-b6c5-ec53a417bef3
MS-CV: BW/uJSvAbU6p3rbS.0
X-Content-Type-Options: nosniff

{
    "continuationToken": "{\"checkSatisfactionIndex\":2}",
    "items": [
        {
            "acquiredDate": "2021-08-30T21:53:08.2565331+00:00",
            "acquisitionType": "Single",
            "beneficiary": {
                "identityType": "pub",
                "identityValue": "NoUserIdProvided"
            },
            "devOfferId": "",
            "endDate": "2021-08-31T21:53:07.4374279+00:00",
            "id": "1046015f83a8478397064c915224e5d3",
            "legacyOfferInstanceId": "fb758141-05cf-406d-b004-57e2a7c0d889",
            "legacyProductId": "fb758141-05cf-406d-b004-57e2a7c0d889",
            "localTicketReference": "",
            "modifiedDate": "2021-08-30T21:53:08.2589804+00:00",
            "purchasedCountry": "US",
            "productFamily": "",
            "productId": "9N30KZZF4BR9",
            "productKind": "Durable",
            "quantity": 1,
            "recurrenceData": {},
            "satisfiedByProductIds": [],
            "sharingSource": "None",
            "skuId": "0010",
            "startDate": "2021-08-30T21:53:07.4374279+00:00",
            "status": "Active",
            "tags": [],
            "transactionId": "995ec667-8114-4ab9-9f11-597a8419a775",
            "trialData": {
                "isInTrialPeriod": false,
                "isTrial": false
            }
        },
        {
            "acquiredDate": "2021-08-30T19:55:44.7994325+00:00",
            "acquisitionType": "Single",
            "beneficiary": {
                "identityType": "pub",
                "identityValue": "NoUserIdProvided"
            },
            "endDate": "9999-12-31T23:59:59.9999999+00:00",
            "id": "27662ad4749342608ec09130b76601f9",
            "legacyOfferInstanceId": "4c584d39-3132-3058-c050-5757574b8500",
            "legacyProductId": "4c584d39-3132-3058-c050-5757574b8500",
            "localTicketReference": "",
            "modifiedDate": "2021-08-30T19:55:44.8043849+00:00",
            "purchasedCountry": "US",
            "productFamily": "Games",
            "productId": "9MXL21XPWWWK",
            "productKind": "Game",
            "quantity": 1,
            "recurrenceData": {},
            "satisfiedByProductIds": [],
            "sharingSource": "None",
            "skuId": "0010",
            "startDate": "2021-08-30T19:40:44.7994325+00:00",
            "status": "Active",
            "tags": [
                "4c584d39-3132-3058-c050-5757574b8500"
            ],
            "transactionId": "8d5ed958-6c72-4812-87fc-57b105d3d197",
            "trialData": {
                "isInTrialPeriod": true,
                "isTrial": true,
                "trialTimeRemaining": "09:43:52.8580690"
            }
        }
    ]
}

Solicitud de los resultados restantes con el token de continuación

Si la consulta tiene más resultados de los que se pueden devolver en una sola respuesta, se proporciona un continuationToken en la respuesta más reciente. Use este continuationToken en una solicitud de seguimiento agregándolo a una copia del cuerpo de la solicitud anterior. Ejemplo:

POST https://collections.mp.microsoft.com/v8.0/collections/b2bLicensePreview HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1EtNTBjQ0g0e...
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
    "continuationToken": "{\"checkSatisfactionIndex\":2}",
    "maxPageSize": 2,
    "excludeDuplicates": true,
    "entitlementFilters": [
        "*:Game",
        "*:Consumable",
        "*:UnmanagedConsumable",
        "*:Durable",
        "*:Pass"
    ],
    "market": "neutral",
    "expandSatisfyingItems": true,
    "productSkuIds": [
        {"productId": "9N30KZZF4BR9"},
        {"productId": "9MXL21XPWWWK"},
        {"productId": "9PLRFWZWWF91"},
        {"productId": "9MZ0MGGFPLTP"}
    ],
    "beneficiaries": [
        {
            "identityType": "b2b",
            "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4...",
            "localTicketReference": ""
        }
    ],
    "sbx": "XDKS.1"
}

Incluso si especifica la marca excludeDuplicates, cuando se usa un token de continuación es posible obtener entradas de derechos con estados diferentes. Por lo tanto, compruebe si hay entradas duplicadas en los resultados y si tienen un estado distinto de Active.

Consulte también

Administración de productos desde sus servicios Autenticación de su servicio con las APIs de Microsoft Store Administración de productos consumibles desde su servicio Renovación de una clave de User Store ID

​b2bLicensePreview (Collections v8) frente a publisherQuery (Collections v9) para consultar productos

​Solicitud

​Requisitos previos

​Sintaxis de la solicitud

​Encabezado de solicitud

​Cuerpo de la solicitud

​Ejemplo de solicitud

​Respuesta

​Cuerpo de la respuesta

​Valores de tipo de producto y su significado

​Valores de estado del producto y su significado

​Valores de acquisitionType del producto y su significado

​Descripción de los resultados de derechos satisfechos con el campo satisfiedByProductIds

​Ejemplo de respuesta

​Solicitud de los resultados restantes con el token de continuación

​Consulte también

b2bLicensePreview (Collections v8) frente a publisherQuery (Collections v9) para consultar productos

Solicitud

Requisitos previos

Sintaxis de la solicitud

Encabezado de solicitud

Cuerpo de la solicitud

Ejemplo de solicitud

Respuesta

Cuerpo de la respuesta

Valores de tipo de producto y su significado

Valores de estado del producto y su significado

Valores de acquisitionType del producto y su significado

Descripción de los resultados de derechos satisfechos con el campo `satisfiedByProductIds`

Ejemplo de respuesta

Solicitud de los resultados restantes con el token de continuación

Consulte también