collections.mp.microsoft.com/v9.0/collections/publisherQuery

publisherQuery permite a sus propios servicios consultar los productos y derechos de un usuario, incluido su estado de suscripción a XBOX Game Pass. Su servicio no debe sondear con regularidad las compras del usuario para evitar los límites de frecuencia de llamadas basados en una ventana de tiempo por usuario. Actualmente, el límite es de 100 solicitudes de consulta dentro de una ventana de cinco minutos para el mismo usuario. Superar un límite de frecuencia genera una respuesta HTTP 429 con información sobre cuándo se puede realizar la siguiente solicitud. Los resultados solo incluyen productos de los que es propietaria directa 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. Consulte Modelo de uso compartido de productos para juegos. Para obtener información específica sobre cómo consultar el estado de la suscripción a Game Pass de un usuario, consulte Detección del acceso a la suscripción a XBOX Game Pass desde su servicio.

publisherQuery solo admite llamadas desde servicios de asociados.

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

Actualizaciones y mejoras en publisherQuery (Collections Query v9)

publisherQuery es la API de Collections Query más reciente (v9). Si migra desde b2bLicensePreview (v8), revise esta sección para conocer las diferencias de comportamiento. publisherQuery tiene los siguientes cambios y mejoras con respecto a b2bLicensePreview:

Capacidad de consultar el estado de la suscripción a XBOX Game Pass de un usuario
Requiere una lista predefinida de productos que devolver. Se trataba de una práctica recomendada, aunque no obligatoria con b2bLicensePreview de v8. Los títulos que no seguían esta práctica recomendada a menudo tenían problemas tras el lanzamiento en los que la solicitud agotaba el tiempo de espera debido al gran alcance del contenido según sus parámetros de consulta. Esto impedía que los usuarios recibieran crédito en el juego hasta que el servicio del juego se actualizaba para especificar qué ProductIds querían dentro de la solicitud de consulta.
Campos de datos de respuesta simplificados para quitar valores no utilizados o innecesarios
Parámetros de solicitud simplificados en función de los comentarios de los desarrolladores

Se ha quitado del cuerpo de la solicitud:

Market: todas las solicitudes tienen contexto para todas las regiones en publisherQuery
ExpandSatisfyingItems: todos los resultados expanden los derechos satisfactorios en publisherQuery
EntitlementsFilter: no se usa, ya que se requiere una lista predefinida de productIds en la consulta

publisherQuery no admite LegacyProductIds (ProductIds generados desde el ya retirado XBOX Developer Portal y usados como ProductId del servicio XBOX Inventory).

Si migra su servicio desde XBOX Inventory, deberá asignar internamente el StoreId (el valor de ProductId de Collections) al LegacyProductId correspondiente en su propio servicio. De lo contrario, puede considerar b2bLicensePreview de v8, que devuelve tanto StoreId como LegacyProductIds. Para obtener más información, consulte el artículo correspondiente Selección de la API de Collections Query adecuada para sus necesidades

Requisitos previos

Revise Requisitos previos para las API de servicio a servicio. Esta API admite tanto el tipo de autenticación de Microsoft Entra ID como el de X-token de autenticación delegada. Si la configuración del producto no está publicada en Partner Center, las llamadas pueden realizarse correctamente pero no devolver resultados.

Solicitud

Sintaxis de la solicitud

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

Encabezado de solicitud

Encabezado	Tipo	Descripción
`Authorization`	`string`	Obligatorio. El X-token de autorización delegada o el token de acceso de servicio de Microsoft Entra ID, según el tipo de autenticación que se use.
`Signature`	`string`	Obligatorio al autenticarse con X-tokens.
`User-Agent`	`string`	Recomendado. Ayuda a identificar su servicio para el registro y las investigaciones.
`Host`	`string`	Debe ser `collections.mp.microsoft.com`.
`Content-Length`	`number`	La 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 elemento. Para obtener más información, consulte Autenticación con Microsoft Entra ID y User Store IDs. No es obligatorio para la autenticación con X-token.	Solo para la autenticación con User Store ID
`productSkuIds`	`list<ProductSkuId>`	Lista de productos de destino. Para obtener más información, consulte la tabla siguiente. La API publisherQuery de v9 admite un máximo de 100 productSkuIds por solicitud.	Sí
`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 página. Proporcione el token de continuación en las llamadas posteriores para obtener más resultados.	No
`maxPageSize`	`number`	El número máximo de productos que se devuelven en una respuesta. El valor predeterminado es 100 y el valor máximo es de 200 elementos por página.	No
`excludeDuplicates`	`bool`	Quita los derechos duplicados en los que el usuario podría tener derecho a un mismo producto desde varios orígenes.	No
`validityType`	`string`	Cuando se establece en All, se devuelven todos los productos de un usuario, incluidos los elementos expirados. Valid devuelve los productos que tienen un 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. El valor predeterminado sin este valor 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 satisfactorio de los paquetes o productos que lo conceden en el campo satisfiedByProductIds. Cuando es True, filtra la mayoría de los ProductIDs satisfactorios del campo satisfiedByProductIds y se proporciona como una opción de compatibilidad según lo necesiten los servicios.	No

El objeto ProductSkuId contiene los siguientes parámetros.

Parámetro	Tipo	Descripción	Obligatorio
`productId`	`string`	También conocido como Store ID del producto dentro del catálogo de Microsoft Store. Un ejemplo de Store ID de un producto es 9NBLGGH42CFD.	Sí
`skuId`	`string`	El 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

La API publisherQuery de v9 admite un máximo de 100 productSkuIds por solicitud. Si se proporcionan más de 100 productIds en productSkuIds, la API devuelve un error HTTP 400.

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

POST https://collections.mp.microsoft.com/v9.0/collections/publisherQuery HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1...
User-Agent: {identifier string of your service}
Content-Type: application/json; charset=utf-8
Content-Length: 2243

{
  "maxPageSize":2,
  "excludeDuplicates":true,
  "productSkuIds":[
    {"productId": "9N30KZZF4BR9"},
    {"productId": "9MXL21XPWWWK"},
    {"productId": "9PLRFWZWWF91"},
    {"productId": "9MZ0MGGFPLTP"}
  ],
  "beneficiaries": [
    {
      "identityType": "b2b",
      "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
      "localTicketReference": ""
    }
  ],
  "sbx":"XDKS.1",
}

Respuesta

Cuerpo de la respuesta

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

El objeto PublisherQueryItemContractV9 contiene los siguientes parámetros.

Parámetro	Tipo	Descripción	Obligatorio
`acquiredDate`	`datetime`	Fecha en que el usuario adquirió el elemento.	Sí
`acquisitionType`	`string`	Indica cómo obtuvo el usuario este derecho. Para obtener más información, consulte Valores y significado de acquisitionType del producto.	No
`endDate`	`datetime`	La fecha de finalización del elemento.	Sí
`id`	`string`	Un identificador que distingue este elemento de la colección de otros elementos que posee el usuario. Este identificador es único por producto.	Sí
`modifiedDate`	`datetime`	La fecha en que se modificó por última vez este elemento. Con productos consumibles, este valor cambia cuando el saldo de cantidad del usuario cambia por otra compra del producto consumible o cuando se emite una solicitud de consumo.	Sí
`productId`	`string`	También conocido como Store ID del producto dentro del catálogo de Microsoft Store. Un ejemplo de Store ID de un producto es 9NBLGGH42CFD.	Sí
`productKind`	`string`	Indica el tipo de producto. Para obtener más información, consulte Valores y significado del tipo de producto.	Sí
`quantity`	`number`	La cantidad del elemento. En productos no consumibles siempre es 1. En productos consumibles, el valor representa el saldo restante que se puede consumir o completar para el usuario.	No
`recurrenceData`	`string`	Identificador del elemento que se usa como parámetro `recurrenceId` de las API de administración de periodicidad. Es el mismo valor que `id` de la API RecurrenceQuery y `recurrenceId` en un evento de Clawback.	Sí
`satisfiedByProductIds`	`list<string>`	Si el derecho a este producto se debe a un paquete o una suscripción, aquí se proporcionan los `ProductIds` de esos productos primarios. NOTA: usar el parámetro de solicitud `filterSatisfiedByProductIds` con el valor `True` provocará que falten algunos resultados en este parámetro.	No
`skuId`	`string`	El 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`	La fecha en que el elemento empieza a ser válido.	Sí
`status`	`string`	El estado del elemento. Para obtener más información, consulte Valores y significado del estado del producto.	Sí
`tags`	`list<string>`	N/D.	Sí
`transactionId`	`GUID`	El identificador de transacción resultante de la compra de este elemento. Puede usarse para notificar un elemento como completado. Este valor es el OrderID asociado al momento en que el usuario compró el elemento. 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
`isInTrialPeriod`	`bool`	Indica si el producto está en un período de prueba, como una suscripción	Sí
`isTrial`	`bool`	Indica si la licencia de este producto proviene de una versión de prueba	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 y significado del tipo de producto

Valor	Descripción
`Application`	Una aplicación dentro de Microsoft Store que no está publicada como juego.
`Consumable`	Un consumible administrado por la Store, en el que el saldo (o la cantidad) del usuario se mantiene y administra en el servicio de Collections. Al comprar, la cantidad se agrega al saldo del usuario y luego se puede quitar mediante una solicitud de consumo. Los usuarios pueden volver a comprar este tipo de consumible sin que se haya completado primero.
`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 los paquetes de complementos y los paquetes de pase de temporada.
`Game`	Un producto de juego base.
`Pass`	Algunos tipos de suscripción, como Game Pass
`UnmanagedConsumable`	También llamado 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 un tipo de suscripción de complemento configurado en la página de complementos de una aplicación en Partner Center.

Valores y significado del estado del producto

Valor	Descripción
`Active`	El producto tiene un derecho activo (incluidos los elementos reservados). El usuario debe tener acceso a él.
`Revoked`	Lo más habitual es que indique que el usuario solicitó un reembolso.
`Expired`	El producto formaba parte de un derecho (normalmente una suscripción) que ya ha expirado.
`Banned`	N/D.
`Suspended`	N/D.

Valores y significado de acquisitionType del producto

Valor	Descripción
`Single`	Compra digital directa o canje de código.
`Recurring`	Se posee o se tiene derecho a través de una suscripción.
`Conditional`	Se posee, pero requiere otros productos para seguir usándose. Ej.: juegos obtenidos con Games With Gold

Comprensión de los resultados de los derechos satisfactorios con el campo `satisfiedByProductIds`

Si la matriz satisfiedByProductIds está vacía, el usuario tiene un derecho directo sobre el elemento por una compra directa. De lo contrario, si la matriz satisfiedByProductIds tiene uno o más ProductIds, el usuario tiene derecho al elemento a partir de esos productos (paquetes, suscripciones, etc.). Si el usuario tiene tanto un derecho directo como un derecho satisfactorio sobre un elemento, 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:21:22 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1115
MS-CorrelationId: d46cbd11-c2cf-4d8b-99b3-ea63ea976f39
MS-RequestId: 76b82179-2c83-41b2-b9f7-6e775f2c0fed
MS-CV: zpiOM+izH0iubCuw.0

{
    "continuationToken": "{\"checkSatisfactionIndex\":2}",
    "items": [
        {
            "acquiredDate": "2021-08-30T21:53:08.2565331+00:00",
            "acquisitionType": "Single",
            "endDate": "2021-08-31T21:53:07.4374279+00:00",
            "id": "1046015f83a8478397064c915224e5d3",
            "modifiedDate": "2021-08-30T21:53:08.2589804+00:00",
            "productId": "9N30KZZF4BR9",
            "productKind": "Durable",
            "quantity": 1,
            "satisfiedByProductIds": [],
            "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",
            "endDate": "9999-12-31T23:59:59.9999999+00:00",
            "id": "27662ad4749342608ec09130b76601f9",
            "modifiedDate": "2021-08-30T19:55:44.8043849+00:00",
            "productId": "9MXL21XPWWWK",
            "productKind": "Game",
            "quantity": 1,
            "satisfiedByProductIds": [],
            "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 su consulta tiene más resultados de los que se pueden devolver en una única respuesta (controlado por maxPageSize), la respuesta de la consulta inicial incluye un continuationToken. Después, puede usar este continuationToken en una solicitud de seguimiento agregando el token de continuación a una copia del cuerpo de la solicitud anterior. Ejemplo de solicitud de continuación:

POST https://collections.mp.microsoft.com/v9.0/collections/publisherQuery HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1...
User-Agent: {identifier string of your service}
Content-Type: application/json; charset=utf-8
Content-Length: 2243

{
  "continuationToken":"{\"checkSatisfactionIndex\":2}",
  "maxPageSize":2,
  "excludeDuplicates":true,
  "productSkuIds":[
    {"productId": "9N30KZZF4BR9"},
    {"productId": "9MXL21XPWWWK"},
    {"productId": "9PLRFWZWWF91"},
    {"productId": "9MZ0MGGFPLTP"}
  ],
  "beneficiaries": [
    {
      "identityType": "b2b",
      "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
      "localTicketReference": ""
    }
  ],
  "sbx":"XDKS.1",
}

Aunque especifique la marca excludeDuplicates, al usar un token de continuación es posible obtener entradas de derechos que tengan un estado diferente. Por lo tanto, compruebe si en los resultados hay entradas duplicadas y si tienen un estado que no sea Active.

Consulte también

Administración de productos desde sus servicios Autenticación de su servicio con las API de Microsoft Store Administración de productos consumibles desde su servicio

​Actualizaciones y mejoras en publisherQuery (Collections Query v9)

​Requisitos previos

​Solicitud

​Sintaxis de la solicitud

​Encabezado de solicitud

​Cuerpo de la solicitud

​Ejemplo de solicitud

​Respuesta

​Cuerpo de la respuesta

​Valores y significado del tipo de producto

​Valores y significado del estado del producto

​Valores y significado de acquisitionType del producto

​Comprensión de los resultados de los derechos satisfactorios con el campo satisfiedByProductIds

​Ejemplo de respuesta

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

​Consulte también

Actualizaciones y mejoras en publisherQuery (Collections Query v9)

Requisitos previos

Solicitud

Sintaxis de la solicitud

Encabezado de solicitud

Cuerpo de la solicitud

Ejemplo de solicitud

Respuesta

Cuerpo de la respuesta

Valores y significado del tipo de producto

Valores y significado del estado del producto

Valores y significado de acquisitionType del producto

Comprensión de los resultados de los derechos satisfactorios con el campo `satisfiedByProductIds`

Ejemplo de respuesta

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

Consulte también