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

# Administración de productos de suscripción desde su servicio

> Describe cómo usar el servicio Recurrence para consultar y administrar sus productos de suscripción y gestionar los distintos estados de suscripción de un usuario.

Para los productos de suscripción, use un servicio back-end para validar el estado y administrar las operaciones del ciclo de vida. El uso de las API de Recurrence proporciona a sus equipos de soporte y de operaciones en vivo una forma confiable de inspeccionar, extender o cancelar suscripciones.

Este artículo explica cómo usar los puntos de conexión de Recurrence para esos escenarios.

## Uso de la biblioteca .NET Microsoft.StoreServices y del ejemplo

Para ayudar a ilustrar los principios y flujos descritos en este artículo, revise el ejemplo de Microsoft.StoreServices. El ejemplo usa la biblioteca Microsoft.StoreServices para administrar la autenticación y realizar las llamadas a los servicios de Microsoft Store. El propio servicio de ejemplo tiene lógica de ejemplo para administrar productos de suscripción y proporciona una guía de configuración para ponerlo en marcha.

* [Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services)
* [Ejemplo de Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services-Sample)

## Tipos de producto de suscripción

Tanto los tipos de producto de suscripción administrados por la Store como los de complemento funcionan con el servicio Recurrence para ver y administrar la suscripción del usuario. Para obtener más información sobre cada uno de estos tipos de producto, consulte [Elección del tipo de producto correcto](/publishing/xstore-commerce/xstore-choosing-product-type#subscriptions)

## Consulta de la suscripción de un usuario

Use [purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](/reference/microsoft-store-apis/xstore-v8-recurrence-query) como punto de conexión principal para el estado de la suscripción. Devuelve los períodos de suscripción activos e históricos, además del `subscriptionId` necesario para las operaciones de cambio. También incluye los campos necesarios para distinguir los períodos de gracia (Grace) y de reclamación de pagos (Dunning).

Las API de Collections ([b2bLicensePreview (v8)](/reference/microsoft-store-apis/xstore-v8-query-for-products) y [publisherQuery (v9)](/reference/microsoft-store-apis/xstore-v9-query-for-products)) pueden mostrar el derecho de suscripción activo, pero no el mismo nivel de detalle de recurrencia.

## Retraso entre las comprobaciones de derechos satisfactorios en el cliente y de servidor a servidor

Cuando publica una actualización que agrega nuevos artículos (derechos satisfactorios) a un lote, existe un retraso entre la visibilidad de los nuevos artículos en las consultas de las API del cliente y las de servidor a servidor. Este retraso se produce porque los distintos sistemas de la Store actualizan sus cachés de catálogo a intervalos diferentes. Cuando el cambio se publica en el catálogo, los servicios de licencias locales suelen obtener primero la información actualizada, y las cachés que usa publisherQuery, entre dos y tres horas después. Por lo tanto, prevea unas horas entre que las API del lado cliente conceden acceso y sus llamadas de servidor a servidor aún no reflejan la propiedad de los nuevos artículos.

El propio servicio Recurrence no se ve afectado; solo los puntos de conexión publisherQuery o b2bLicensePreview que consultan derechos satisfactorios sobre los artículos recién agregados.

### Explicación de las fechas de inicio, renovación y expiración de la suscripción

La fecha `StartTime` de una suscripción es la fecha en la que comenzó la suscripción activa. Si la suscripción está configurada para renovación automática, la fecha de inicio se mantiene igual, pero las fechas de expiración cambian a medida que la suscripción se renueva en los meses siguientes. Si una suscripción se cancela, expira o se revoca, se crea un nuevo objeto de suscripción cuando el usuario vuelve a comprar la suscripción. El nuevo período de suscripción activo tiene como `StartTime` el día en que activaron o compraron la nueva suscripción.

Los períodos de suscripción dentro de Microsoft Store se configuran normalmente como una cantidad de meses. Por ejemplo, 1 mes, 3 meses o 12 meses. Cuando un usuario compra una suscripción de un mes, `StartTime` es la medianoche UTC (00:00:00) del día en que inició la suscripción. `ExpirationTime` es el número de meses (no días) agregado a `StartTime` menos un segundo (23:59:59 UTC).<br />Este valor es para que la suscripción expire justo antes de la medianoche UTC.

Sin embargo, algunos meses tienen un número de días diferente, lo que crea un conflicto con las suscripciones que comienzan un 29, 30 o 31 de un mes.<br />Si el `StartTime` del usuario cae en cualquiera de esos días, `ExpirationTime` se modifica para ser las 23:59:59 UTC del último día del mes que expira. De esta manera, la fecha de renovación siempre es la medianoche UTC (00:00:00) del primer día del mes en adelante y `ExpirationTime` siempre es las 23:59:59 UTC del último día del mes.

#### Ejemplo del comportamiento de las fechas de inicio, renovación y expiración de una suscripción de un mes

| Fecha de compra      | StartTime            | ExpireTime           | Fecha de renovación automática | Días activos      |
| -------------------- | -------------------- | -------------------- | ------------------------------ | ----------------- |
| 2023-02-27T12:00:00Z | 2023-02-27T00:00:00Z | 2023-03-26T23:59:59Z | 2023-03-27T00:00:00Z           | 28                |
| 2023-03-27T12:00:00Z | 2023-03-27T00:00:00Z | 2023-04-26T23:59:59Z | 2023-05-27T00:00:00Z           | 31                |
| 2023-03-29T12:00:00Z | 2023-03-29T00:00:00Z | 2023-04-30T23:59:59Z | 2023-05-01T00:00:00Z           | 32                |
| 2023-04-29T12:00:00Z | 2023-04-29T00:00:00Z | 2023-05-31T23:59:59Z | 2023-06-01T00:00:00Z           | 33                |
| 2023-04-30T12:00:00Z | 2023-04-30T00:00:00Z | 2023-05-31T23:59:59Z | 2023-06-01T00:00:00Z           | 32                |
| 2024-02-27T12:00:00Z | 2024-02-27T00:00:00Z | 2024-03-26T23:59:59Z | 2024-03-27T00:00:00Z           | 29 (año bisiesto) |

### Explicación de los estados Grace y Dunning

Si un pago de renovación automática produce un error en `ExpirationTime`, la suscripción entra en Grace y, a continuación, en Dunning si sigue sin resolverse. Ambos períodos notifican el estado `InDunning`, así que determine el período actual comparando la hora UTC actual con `ExpirationTimeWithGrace`.

Mientras la suscripción de un usuario está en Grace o Dunning, debe notificar a los usuarios que comprueben su estado de facturación en [Servicios y suscripciones de la cuenta de Microsoft](https://account.microsoft.com/services).

Para establecer correctamente una cuenta en cada uno de estos estados con fines de prueba, consulte [Prueba de productos de suscripción](#testing-subscription-products).

#### Período de gracia (Grace)

Durante el período de gracia, mantenga habilitadas las ventajas de la suscripción mientras la Store reintenta el pago de la renovación. Si la renovación se realiza correctamente, los días de gracia usados se deducen del período siguiente. Si el pago no se resuelve antes de `ExpirationTimeWithGrace`, la suscripción pasa a Dunning.

#### Período de reclamación de pagos (Dunning)

El período de Dunning comienza cuando termina el de Grace. Deshabilite las ventajas de la suscripción durante este período. Los usuarios no pueden volver a comprar ni canjear la misma suscripción durante el Dunning. Si el pago sigue sin resolverse durante todo el Dunning, la suscripción pasa a estar inactiva.

### Duración de los períodos Grace y Dunning

| Tipo de suscripción                   | Duración de la suscripción | Grace  | Dunning (después de Grace) |
| ------------------------------------- | -------------------------- | ------ | -------------------------- |
| Suscripción de complemento            | Cualquiera                 | 3 días | 39 días                    |
| Suscripción administrada por la Store | Cualquiera                 | 7 días | 36 días                    |

## Cambio de la suscripción de un usuario

Sus servicios también pueden modificar suscripciones con [purchase.mp.microsoft.com/v8.0/b2b/recurrences/](/reference/microsoft-store-apis/xstore-v8-recurrence-change){recurrenceId}[/change](/reference/microsoft-store-apis/xstore-v8-recurrence-change). Las operaciones admitidas incluyen agregar días, deshabilitar la renovación automática y cancelar la suscripción. Su servicio necesita el `recurrenceId` (el mismo valor que `id` de la [API RecurrenceQuery](/reference/microsoft-store-apis/xstore-v8-recurrence-query) y los valores de `recurrenceData` de la [API de consulta de Collections](/reference/microsoft-store-apis/xstore-v9-query-for-products)) para operar sobre la suscripción del usuario.

A continuación se muestran algunos ejemplos de cómo el punto de conexión Recurrence Change puede ser útil con sus servicios:

* Agregar tiempo a las suscripciones de los usuarios que experimentaron un tiempo de inactividad del servicio.
* Integración con sus equipos de soporte al cliente para ayudar a los usuarios con información sobre el estado de su suscripción, cancelaciones, etc.
* Interfaz de usuario del juego que permite a los usuarios cambiar configuraciones como la renovación automática o finalizar sus suscripciones.

## Prueba de productos de suscripción

La [API Recurrence Change](/reference/microsoft-store-apis/xstore-v8-recurrence-change) también se puede usar para pruebas. `Extend` acepta valores de días negativos, lo que le permite avanzar una suscripción de prueba hacia los estados objetivo.

### Prueba de los estados Active, Inactive y Canceled

Cuando pruebe los estados Active, Inactive y Canceled de una suscripción, puede usar un precio base de \$0.00 en la suscripción. Agregue la suscripción a la cuenta de prueba para verificar el estado Active y use el punto de conexión Recurrence Change para deshabilitar la renovación automática. A continuación, use el punto de conexión Recurrence Change para cancelar la suscripción o restar suficientes días para que `ExpirationTime` quede anterior a la fecha y hora UTC actuales.

### Prueba de los estados Grace y Dunning

Para probar los estados Grace y Dunning, la suscripción debe tener un precio distinto de cero.<br />Además, la cuenta de prueba debe estar configurada de forma que los pagos posteriores no se realicen correctamente cuando pase `ExpirationTime`. Actualmente, Microsoft Store no tiene instrumentos de pago de prueba, por lo que la forma más fácil de configurar una cuenta es usar códigos de moneda prepagada de la siguiente manera:

1. Configure la suscripción con un precio bajo, como \$0.99, en su entorno de prueba.
2. [Compre una tarjeta de regalo prepagada de XBOX](https://www.microsoft.com/en-us/p/xbox-gift-card-digital-code/cfq7ttc0k63h/0002?activetab=pivot:overviewtab) de $1.00 o $2.00 para cubrir la primera compra de la suscripción (más impuestos), pero no la renovación.
3. Canjee la tarjeta de regalo en su cuenta de prueba.
4. Compre la suscripción en la cuenta de prueba.
5. Asegúrese de que la renovación automática esté habilitada para la suscripción, pero de que no haya fondos suficientes para renovarla.
6. Use Recurrence Change para mover el `ExpirationTime` de la suscripción de modo que quede dentro de las próximas 24 horas (consulte la nota siguiente).
7. Espere a que `ExpirationTime` pase de forma natural y a que el estado muestre `InDunning` (puede tardar hasta 24 horas después de `ExpirationTime`).

Para obtener un comportamiento preciso de Grace -> Dunning -> Inactive, deje que la cuenta progrese de forma natural después de configurar la prueba.

<Note>
  Para llevar correctamente una cuenta al estado 'InDunning' para los períodos de Grace y Dunning, la cuenta debe pasar las fechas `ExpirationTime` y `ExpirationTimeWithGrace` de forma natural. Al restar días, apunte a un `ExpirationTime` dentro de las próximas 24 horas y, a continuación, deje que el tiempo pase de forma natural. Si mueve `ExpirationTime` a un punto que ya está en el pasado, es posible que `InDunning` no aparezca y el estado de prueba puede quedar no válido. La única manera de resolver este problema es cancelar la suscripción y crear una nueva suscripción de prueba.
</Note>

## Consulte también

[Información general sobre comercio](/publishing/xstore-commerce/xstore-commerce-overview)

[API de servicio de Microsoft Store](/reference/microsoft-store-apis/index)

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

[purchase.mp.microsoft.com/v8.0/b2b/recurrences/](/reference/microsoft-store-apis/xstore-v8-recurrence-change){recurrenceId}[/change](/reference/microsoft-store-apis/xstore-v8-recurrence-change)

[Biblioteca Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services)

[Ejemplo de Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services-Sample)


## Related topics

- [Administración de productos consumibles desde su servicio](/es/publishing/xstore-commerce/xstore-managing-consumables.md)
- [Administración de reembolsos y contracargos desde su servicio](/es/publishing/xstore-commerce/xstore-managing-refunds.md)
- [Concesión de acceso a los jugadores al contenido de complemento](/es/publishing/xstore-commerce/xstore-granting-access.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)
- [purchase.mp.microsoft.com/v8.0/b2b/orders/query](/es/reference/microsoft-store-apis/xstore-v8-clawbackv1.md)