> ## 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. # purchase.mp.microsoft.com/v8.0/b2b/recurrences/query > Ponto de extremidade recurrences/query do Microsoft Store v8 que retorna o status da assinatura de um usuário, incluindo detalhes do período de carência após uma falha na renovação automática. Este ponto de extremidade consulta o status de produtos de assinatura de um usuário na Microsoft Store. Ele fornece mais detalhes do que o Collections, incluindo dados do período de carência após uma falha na renovação automática. ## Pré-requisitos Revise os [Pré-requisitos para APIs de serviço a serviço](https://learn.microsoft.com/reference/service-to-service-nav#prerequisites-for-service-to-service-apis). Esta API dá suporte apenas ao tipo de autenticação Microsoft Entra ID. Se a configuração do produto não estiver publicada no Partner Center, a chamada poderá ter êxito, mas não retornará resultados. ## Solicitação ### Sintaxe da solicitação | Método | URI da solicitação | | - | - | | `POST` | `purchase.mp.microsoft.com/v8.0/b2b/recurrences/query` | ### Cabeçalho da solicitação | Cabeçalho | Tipo | Descrição | | - | - | - | | `Authorization` | `string` | Obrigatório. O token de acesso de serviço do Microsoft Entra ID no formato `Bearer` \<*token*>. | | `Host` | `string` | Deve ser definido com o valor `purchase.mp.microsoft.com`. | | `Content-Length` | `number` | O comprimento do corpo da solicitação. | | `Content-Type` | `string` | Especifica o tipo de solicitação e de resposta. Atualmente, o único valor com suporte é `application/json`. | ### Corpo da solicitação | Parâmetro | Tipo | Descrição | Obrigatório | | - | - | - | - | | `b2bKey` | `string` | A User Purchase ID que representa a identidade do usuário para o qual você está fazendo a solicitação. Confira [Chave de User Store ID](https://learn.microsoft.com/reference/xstore-requesting-a-userstoreid#step-4-create-a-user-store-id-key). | Sim | | `sbx` | `string` | Valor opcional para autenticação com UserStoreIds que especifica a área restrita (sandbox) à qual os resultados devem ser limitados. Sem esse valor, o padrão é a área restrita RETAIL. A autenticação com X-Token não precisa desse valor, pois a área restrita é especificada no X-Token. | Não | | `continuationToken` | `string` | Se houver vários conjuntos de produtos que não cabem em `maxPageSize`, o corpo da resposta retornará um token de continuação quando o limite de página for atingido. Forneça o token de continuação nas chamadas seguintes para obter mais resultados. | Não | ### Exemplo de solicitação ```html theme={null} POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/query HTTP/1.1 Host: purchase.mp.microsoft.com Authorization: Bearer [Microsoft Entra ID bearer token] User-Agent: MicrosoftStoreServiceSample_1.21.9.0 Content-Type: application/json; charset=utf-8 Content-Length: 2032 { "b2bKey":"[UserPurchaseId]", "sbx": "XDKS.1" } ``` ## Resposta ### Corpo da resposta | Parâmetro | Tipo | Descrição | Obrigatório | | - | - | - | - | | `continuationToken` | `string` | Esse token é retornado quando o limite de página é atingido. Você pode especificar esse token de continuação nas chamadas seguintes para recuperar os produtos restantes. | Não | | `items` | `list` | Uma matriz de produtos do usuário especificado. Para obter mais informações, confira a tabela a seguir. | Sim | O objeto `RecurrenceItem` contém os parâmetros a seguir. | Parâmetro | Tipo | Descrição | Obrigatório | | - | - | - | - | | `autoRenew` | `bool` | Indica se o usuário está inscrito para que a assinatura seja renovada automaticamente ao final do próximo ciclo de cobrança. | Sim | | `beneficiary` | `string` | A Publisher ID do beneficiário na User Purchase ID. | Sim | | `expirationTime` | `DateTime` | A data e a hora UTC em que a assinatura expira | Sim | | `expirationTimeWithGrace` | `DateTime` | A data e a hora UTC em que o período de carência do usuário termina se a renovação automática falhar no ExpirationTime. Durante a carência, os usuários ainda devem ter acesso e ser considerados assinantes válidos, mas devem ser notificados de que precisam corrigir o pagamento da renovação automática. | Sim | | `id` | `string` | Uma ID que distingue este item da coleção dos outros itens que o usuário possui. Essa ID é exclusiva por produto. | Sim | | `isTrial` | `bool` | Indica se o produto está em um período de avaliação, como uma assinatura. | Sim | | `lastModified` | `DateTime` | A data UTC em que este item foi modificado pela última vez. | Sim | | `market` | `string` | A região do marketplace em que o produto foi comprado, seguindo o código de região ISO 3166 de dois caracteres. Ex.: US. | Sim | | `productId` | `string` | Também chamado de Store ID do produto no catálogo da Microsoft Store. Um exemplo de Store ID de um produto é 9NBLGGH42CFD. | Sim | | `recurrenceState` | `string` | Estado atual da recorrência. Confira Estados de recorrência. | Sim | | `skuId` | `string` | O identificador de SKU específico, se houver várias ofertas do produto no catálogo da Microsoft Store. Um exemplo de Store ID de um SKU é 0010. | Sim | | `startTime` | `DateTime` | A data UTC em que a assinatura se torna válida. | Sim | | `cancellationDate` | `DateTime` | A data UTC em que a assinatura foi cancelada. | Não | ### Estados de recorrência | Valor | Descrição | | - | - | | `None` | Indica uma assinatura perpétua. | | `Active` | A assinatura é válida e o usuário tem direito aos benefícios da assinatura. | | `Inactive` | A assinatura passou da data de expiração e o usuário desativou a opção de renovação automática da assinatura. | | `Canceled` | A assinatura foi encerrada intencionalmente antes da data de expiração, com ou sem reembolso. | | `InDunning` | A assinatura está em cobrança (ou seja, a assinatura está perto de expirar e a Microsoft está tentando obter fundos para renová-la automaticamente). Se a data atual for anterior ao valor de expirationTimeWithGrace, o usuário ainda deverá ter direito aos benefícios da assinatura. Se a data atual for posterior ao valor de expirationTimeWithGrace, o usuário não deverá ter acesso aos benefícios da assinatura. | | `Failed` | O período de cobrança terminou e a assinatura não foi renovada após várias tentativas. | * *Inactive/Canceled/Failed* são estados terminais. Quando uma assinatura entra em um desses estados, o usuário precisa comprar a assinatura novamente para ativá-la de novo. O usuário não tem direito de usar os serviços nesses estados. * Quando uma assinatura é cancelada (Canceled), o expirationTime é atualizado com a data e a hora do cancelamento. * A ID da assinatura permanece a mesma durante toda a sua vida útil. Ela não muda se a opção de renovação automática for ativada ou desativada. Se um usuário comprar novamente uma assinatura depois de atingir um estado terminal, uma nova ID de assinatura será criada. * A ID de uma assinatura deve ser usada para executar qualquer operação em uma assinatura individual. * Quando um usuário compra novamente uma assinatura depois de cancelá-la ou descontinuá-la, se você consultar os resultados do usuário, obterá duas entradas: uma com a ID de assinatura antiga em um estado terminal e outra com a nova ID de assinatura em um estado ativo. * É sempre uma boa prática verificar tanto recurrenceState quanto expirationTime, pois as atualizações de recurrenceState podem atrasar alguns minutos (ou, ocasionalmente, horas). ### Exemplo de resposta ```json theme={null} HTTP/1.1 200 OK date: Tue, 17 Aug 2021 21:22:28 GMT content-type: application/json; charset=utf-8 content-length: 2382 ms-cv: aft4s000mwNmYF.0 x-content-type-options: nosniff x-envoy-upstream-service-time: 2099 { "items": [ { "autoRenew": true, "beneficiary": "pub:NoUserIdProvided", "expirationTime": "2021-08-25T23:59:59.00+00:00", "expirationTimeWithGrace": "2021-09-08T23:59:59.00+00:00", "id": "mdr:0:1ecc1424ed8f457ab6107f08033e6b50:907f0a31-035c-41a2-b70b-5a62925a4f92", "isTrial": false, "lastModified": "2021-07-26T22:59:55.99+00:00", "market": "US", "productId": "CFQ7TTC0HC8Z", "skuId": "0002", "startTime": "2021-07-26T00:00:00.00+00:00", "recurrenceState": "Active" }, { "autoRenew": true, "beneficiary": "pub:NoUserIdProvided", "expirationTime": "2021-07-26T21:08:30.52+00:00", "expirationTimeWithGrace": "2021-07-26T21:08:30.52+00:00", "id": "mdr:0:50c7396d0e5f4e7f9deeede3ba25f1a4:87c4cfae-ed1d-400f-a6b0-19fdb3c327f5", "isTrial": false, "lastModified": "2021-07-26T21:08:34.61+00:00", "market": "US", "productId": "CFQ7TTC0HC8Z", "skuId": "0002", "startTime": "2021-07-15T00:00:00.00+00:00", "recurrenceState": "Canceled", "cancellationDate": "2021-07-26T21:08:31.52+00:00" }, { "autoRenew": false, "beneficiary": "pub:NoUserIdProvided", "expirationTime": "2021-07-26T22:35:29.54+00:00", "expirationTimeWithGrace": "2021-07-26T22:35:29.54+00:00", "id": "mdr:0:528115d9771f4e49b79550790fd4a263:f30a646e-54cf-4fe8-8c95-7add9fc2ebde", "isTrial": false, "lastModified": "2021-07-26T22:35:33.96+00:00", "market": "US", "productId": "CFQ7TTC0HC8Z", "skuId": "0002", "startTime": "2021-07-26T00:00:00.00+00:00", "recurrenceState": "Canceled", "cancellationDate": "2021-07-26T22:35:30.54+00:00" }, ] } ``` ### Explicação do exemplo de resposta Esta resposta mostra três entradas de assinatura para o usuário: duas no estado `Canceled` e uma atualmente `Active`, iniciada em 26 de julho de 2021. O período da assinatura ativa termina em 26 de agosto de 2021 e está configurado para renovação automática nessa data. Se o pagamento da renovação falhar, a assinatura passará para a janela de carência, na qual o usuário ainda recebe os benefícios até `expirationTimeWithGrace` (8 de setembro de 2021 neste exemplo). Quando a assinatura passa para a janela de carência, o `recurrenceState` se torna `InDunning`. Após o término da carência, a assinatura passa para a janela de cobrança (Dunning). Durante esse período, seu serviço deixa de conceder benefícios e o usuário precisa corrigir a forma de pagamento. O usuário não pode cancelar nem iniciar uma nova assinatura durante esse período. Quando o pagamento é processado, o tempo de carência (duas semanas neste exemplo) é deduzido do próximo período pago. ### Solicitando os resultados restantes com o token de continuação Se a consulta tiver mais resultados do que podem ser retornados em uma única resposta, a resposta da consulta inicial terá um continuationToken. Você pode então usar esse continuationToken em uma solicitação subsequente, adicionando o token de continuação a uma cópia do corpo da solicitação anterior. Exemplo de solicitação de continuação: ```html theme={null} POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/query HTTP/1.1 Host: purchase.mp.microsoft.com Authorization: Bearer [Microsoft Entra ID bearer token] User-Agent: MicrosoftStoreServiceSample_1.21.9.0 Content-Type: application/json; charset=utf-8 Content-Length: 2032 { "continuationToken":"[Continuation Token]", "b2bKey":"[UserPurchaseId]", "sbx": "XDKS.1" } ``` ## Artigos relacionados [purchase.mp.microsoft.com/v8.0/b2b/recurrences/{recurrenceId}/change](/pt-BR/reference/microsoft-store-apis/xstore-v8-recurrence-change) [Gerenciar produtos a partir dos seus serviços](https://learn.microsoft.com/reference/service-to-service-nav) [Gerenciar reembolsos e estornos a partir do seu serviço](https://learn.microsoft.com/reference/xstore-managing-refunds-and-chargebacks) [Autenticar seu serviço com as APIs da Microsoft Store](https://learn.microsoft.com/reference/xstore-authenticating-your-service) [Usar publisherQuery (Collections v9) para consultar os produtos e direitos de um usuário](/pt-BR/reference/microsoft-store-apis/xstore-v9-query-for-products) ## Related topics - [purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](/reference/microsoft-store-apis/xstore-v8-recurrence-query.md) - [Microsoft Store v8 subscription recurrence change API](/reference/microsoft-store-apis/xstore-v8-recurrence-change.md) - [Managing subscription products from your service](/publishing/xstore-commerce/xstore-managing-subscriptions.md) - [从你的服务管理订阅产品](/zh-CN/publishing/xstore-commerce/xstore-managing-subscriptions.md) - [서비스에서 구독 제품 관리](/ko/publishing/xstore-commerce/xstore-managing-subscriptions.md)