> ## 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/v9.0/collections/publisherQuery > API publisherQuery de Collections de Microsoft Store v9 que permite a los servicios de juego consultar los productos, derechos y estado de la suscripción a XBOX Game Pass de un usuario. 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](https://learn.microsoft.com/fundamentals/xstore-product-sharing-model-for-games). 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](/publishing/xstore-commerce/xstore-detecting-game-pass). 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](https://learn.microsoft.com/reference/xstore-query-user-entitlements#selecting-the-right-collections-query-api-for-your-needs) ### Requisitos previos Revise [Requisitos previos para las API de servicio a servicio](https://learn.microsoft.com/reference/service-to-service-nav#prerequisites-for-service-to-service-apis). 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](https://learn.microsoft.com/reference/xstore-authenticating-your-service#authenticating-with-microsoft-entra-id-and-user-store-ids). No es obligatorio para la autenticación con X-token. | Solo para la autenticación con User Store ID | | `productSkuIds` | `list` | 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. ```html theme={null} 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](#product-acquisitiontype-values-and-meaning). | 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](#product-type-values-and-meaning). | 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](/reference/microsoft-store-apis/xstore-v8-recurrence-query) y `recurrenceId` en un evento de Clawback. | Sí | | `satisfiedByProductIds` | `list` | 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](#product-status-values-and-meaning). | Sí | | `tags` | `list` | 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 ```json theme={null} 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: ```html theme={null} 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](https://learn.microsoft.com/reference/service-to-service-nav) [Autenticación de su servicio con las API de Microsoft Store](https://learn.microsoft.com/reference/xstore-authenticating-your-service) [Administración de productos consumibles desde su servicio](https://learn.microsoft.com/reference/xstore-managing-consumables-and-refunds) ## Related topics - [APIs de servicio de Microsoft Store](/es/reference/microsoft-store-apis/xstore-nav.md) - [Detección del acceso a la suscripción a XBOX Game Pass desde su servicio](/es/publishing/xstore-commerce/xstore-detecting-game-pass.md) - [API b2bLicensePreview de Collections v8 de Microsoft Store](/es/reference/microsoft-store-apis/xstore-v8-query-for-products.md) - [collections.mp.microsoft.com/v8.0/collections/consume](/es/reference/microsoft-store-apis/xstore-v8-consume.md) - [purchase.mp.microsoft.com/v8.0/b2b/orders/query](/es/reference/microsoft-store-apis/xstore-v8-clawbackv1.md)