API de alteração de recorrência de assinatura do Microsoft Store v8

Esta API só funciona se a assinatura estiver publicada em RETAIL. Se estiver usando uma área restrita de desenvolvimento, primeiro publique a assinatura em um grupo de pré-lançamento privado ou como oculta em RETAIL antes de chamar esta API. Se a assinatura não estiver publicada em RETAIL, a resposta será um erro HTTP 400 com uma mensagem informando “Requested catalog product data wasn’t found.”

Este ponto de extremidade é usado para alterar o estado de cobrança do produto de assinatura do usuário na Microsoft Store. Você pode cancelar, estender, reembolsar ou desabilitar a renovação automática de uma assinatura. A biblioteca Microsoft.StoreServices (GitHub) fornece a funcionalidade deste método por meio da API StoreServicesClient.RecurrenceChangeAsync.

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/{recurrenceId}/change`

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

Parâmetros da solicitação

Cabeçalho	Tipo	Descrição	Obrigatório
`recurrenceId`	`string`	Exclusivo da assinatura do usuário e é o mesmo valor de `id` da API RecurrenceQuery e de `recurrenceData` da API de consulta do Collections.	Sim

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
`changeType`	`string`	Identifica o tipo de alteração que você deseja fazer. Confira a tabela Operações de tipo de alteração para obter os valores possíveis.	Sim
`extensionTimeInDays`	`string`	Se o parâmetro changeType tiver o valor Extend, este parâmetro especificará o número de dias para estender a assinatura. Para cenários de teste, esse número pode ser negativo para remover dias da assinatura.	Sim, se changeType tiver o valor Extend; caso contrário, não.
`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

Operações de tipo de alteração

Tipo de alteração	Descrição
`Cancel`	Cancela a assinatura.
`Extend`	Estende a assinatura. Se você especificar este valor, também deverá incluir o parâmetro `extensionTimeInDays` no corpo da solicitação.
`Refund`	Reembolsa a assinatura ao cliente.
`ToggleAutoRenew`	Desabilita a renovação automática da assinatura. Se a renovação automática já estiver desabilitada para a assinatura, este valor não fará nada.

Exemplo de solicitação

O exemplo a seguir demonstra como usar este método para estender o período da assinatura em cinco dias. Substitua o valor de b2bKey pela chave de User Store ID que representa a identidade do usuário cuja assinatura você deseja alterar.

POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac/change HTTP/1.1
Authorization: Bearer <your access token>
Content-Type: application/json
Host: https://purchase.mp.microsoft.com

{
  "b2bKey":  "eyJ0eXAiOiJ...",
  "changeType": "Extend",
  "extensionTimeInDays": "5"
}

Resposta

Este método retorna um corpo de resposta JSON que descreve o complemento de assinatura atualizado, incluindo os campos modificados.

Este método tem o mesmo requisito de publicação em RETAIL descrito no início deste artigo.

Corpo da resposta

Parâmetro	Tipo	Descrição	Obrigatório
`continuationToken`	`string`	Se houver vários conjuntos de produtos, esse token será retornado quando o limite de página for 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`	O país/região em que o produto foi comprado, seguindo o código de país/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 começou.	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
Content-Type: application/json; charset=utf-8
Content-Length: 431
ms-correlationid: 95b2aee4-1118-437b-8910-a2f7d84d0766
ms-cv: Kl684e1htkqb19Ch.0
Date: Thu, 03 Mar 2022 23:19:12 GMT

{
    "autoRenew": true,
    "beneficiary": "pub:NoUserIdProvided",
    "expirationTime": "2022-03-03T23:59:59.00+00:00",
    "expirationTimeWithGrace": "2022-03-17T23:59:59.00+00:00",
    "id": "mdr:0:3172048a2d1849ba9a24fd305854d4a8:cedca1d3-9580-4229-9cb5-f00c4547078c",
    "isTrial": false,
    "lastModified": "2022-03-03T23:19:12.26+00:00",
    "market": "US",
    "productId": "CFQ7TTC0HC8Z",
    "skuId": "0003",
    "startTime": "2022-03-03T00:00:00.00+00:00",
    "recurrenceState": "Active"
}

Porting

Build Paths

API de alteração de recorrência de assinatura do Microsoft Store v8

Pré-requisitos

Solicitação

Sintaxe da solicitação

Cabeçalho da solicitação

Parâmetros da solicitação

Corpo da solicitação

Operações de tipo de alteração

Exemplo de solicitação

Resposta

Corpo da resposta

Estados de recorrência

Exemplo de resposta

Artigos relacionados

​Pré-requisitos

​Solicitação

​Sintaxe da solicitação

​Cabeçalho da solicitação

​Parâmetros da solicitação

​Corpo da solicitação

​Operações de tipo de alteração

​Exemplo de solicitação

​Resposta

​Corpo da resposta

​Estados de recorrência

​Exemplo de resposta

​Artigos relacionados

Pré-requisitos

Solicitação

Sintaxe da solicitação

Cabeçalho da solicitação

Parâmetros da solicitação

Corpo da solicitação

Operações de tipo de alteração

Exemplo de solicitação

Resposta

Corpo da resposta

Estados de recorrência

Exemplo de resposta

Artigos relacionados