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

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

> Ponto de extremidade de alteração de recorrências do Microsoft Store v8 que permite que um serviço de jogo cancele, estenda ou reembolse a recorrência da assinatura de um usuário pela ID de recorrência.

<Note>
  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."
</Note>

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)](https://github.com/microsoft/Microsoft-Store-Services) 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](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/{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](/pt-BR/reference/microsoft-store-apis/xstore-v8-recurrence-query) e de `recurrenceData` da [API de consulta do Collections](/pt-BR/reference/microsoft-store-apis/xstore-v9-query-for-products). | 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](https://learn.microsoft.com/reference/xstore-requesting-a-userstoreid#step-4-create-a-user-store-id-key). | Sim |
| `changeType` | `string` | Identifica o tipo de alteração que você deseja fazer. Confira a tabela [Operações de tipo de alteração](#change-type-operations) 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.

```html theme={null}
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.

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

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

```json theme={null}
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"
}

```

## Artigos relacionados

[purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](/pt-BR/reference/microsoft-store-apis/xstore-v8-recurrence-query)

[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

- [API b2bLicensePreview de Collections v8 de Microsoft Store](/es/reference/microsoft-store-apis/xstore-v8-query-for-products.md)
- [APIs de servicio de Microsoft Store](/es/reference/microsoft-store-apis/xstore-nav.md)
- [Integração de Parceiro XBOX para acesso e publicação](/pt-BR/home/onboarding.md)
- [Guia de BVT de console da certificação](/pt-BR/publishing/game-publishing/concepts/certification/certification-console-bvt-guide.md)
- [Notas de versão do SDK C++ do PlayFab Multiplayer](/pt-BR/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/lobby-and-matchmaking-release-notes.md)