purchase.mp.microsoft.com/v8.0/b2b/recurrences/query

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

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

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:

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

Porting

Build Paths

Pré-requisitos

Solicitação

Sintaxe da solicitação

Cabeçalho da solicitação

Corpo da solicitação

Exemplo de solicitação

Resposta

Corpo da resposta

Estados de recorrência

Exemplo de resposta

Explicação do exemplo de resposta

Solicitando os resultados restantes com o token de continuação

Artigos relacionados

​Pré-requisitos

​Solicitação

​Sintaxe da solicitação

​Cabeçalho da solicitação

​Corpo da solicitação

​Exemplo de solicitação

​Resposta

​Corpo da resposta

​Estados de recorrência

​Exemplo de resposta

​Explicação do exemplo de resposta

​Solicitando os resultados restantes com o token de continuação

​Artigos relacionados

Pré-requisitos

Solicitação

Sintaxe da solicitação

Cabeçalho da solicitação

Corpo da solicitação

Exemplo de solicitação

Resposta

Corpo da resposta

Estados de recorrência

Exemplo de resposta

Explicação do exemplo de resposta

Solicitando os resultados restantes com o token de continuação

Artigos relacionados