Programar cambios para una nueva suscripción comercial mediante las API del Centro de partners

Artículo
07/19/2024

Se aplica a: Centro de partners

En este artículo se describe cómo puede usar la API del Centro de partners para programar los cambios de una nueva suscripción comercial, que solo tienen lugar en la renovación. Esta API admite nuevas suscripciones de software y basadas en licencias comerciales.

Nota:

Las nuevas experiencias comerciales para los servicios basados en licencias incluyen muchas funcionalidades nuevas y están disponibles para todos los Proveedores de soluciones en la nube (CSP). Para más información, consulte Introducción a las nuevas experiencias comerciales.

La creación de cambios programados le permite modificar la suscripción, automáticamente, cuando se produce la siguiente renovación. Mediante la programación de cambios, puede optar por aumentar o disminuir el número de licencias, modificar el período de facturación y la frecuencia, e incluso elegir actualizar la SKU. La programación de cambios le permite realizar modificaciones en la suscripción durante la renovación, en lugar de inmediatamente durante el período actual.

Importante

Si realiza un cambio a medio plazo (inmediato) antes de la fecha de renovación, se eliminan todos los cambios programados que se programaron anteriormente para que se produzcan en la renovación.

Requisitos previos

Credenciales tal como se describen en el artículo Autenticación del Centro de partners. Este escenario admite la autenticación con credenciales de aplicación independiente y app+usuario.
Un id. de cliente (customer-tenant-id). Si no conoce el identificador del cliente, puede buscarlo en el Centro de partners seleccionando el área de trabajo Clientes , luego el cliente de la lista de clientes y, a continuación , Cuenta. En la página Cuenta del cliente, busque el identificador de Microsoft en la sección Información de la cuenta de cliente. El id. de Microsoft es el mismo que el de cliente (customer-tenant-id).
Un identificador de suscripción.
La renovación automática está habilitada en la suscripción.

Método del Centro de partners

Para programar los cambios de una suscripción en el Centro de partners:

Seleccione un cliente.
Seleccione la suscripción para la que desea programar los cambios.
Habilite La renovación automática.
Seleccione Administrar renovación.
Realice modificaciones en la suscripción para que se realicen en la renovación.
Seleccione Aceptar para cerrar el panel lateral.
Seleccione Enviar para guardar los cambios.

Nota:

Las renovaciones se procesan después del último día de un período, a partir de las 12:00 UTC del día siguiente. Las renovaciones se procesan en una cola y pueden tardar hasta 24 horas en procesarse.

C#

Para programar los cambios de la suscripción de un cliente:

Obtenga la suscripción por identificador.
Obtenga la idoneidad de la transición para el tipo de elegibilidad de transición programada.
Cree un objeto ScheduledNextTermInstructions y establézcalo en la propiedad de la suscripción.
Llame al método Patch() para actualizar la suscripción con los cambios programados.

var selectedSubscription = subscriptionOperations.Get();
selectedSubscription.ScheduledNextTermInstructions = new ScheduledNextTermInstructions
{
    Product = new ProductTerm
    {
        ProductId = changeToProductId,
        SkuId = changeToSkuId,
        AvailabilityId = changeToAvailabilityId,
        BillingCycle = changeToBillingCycle,
        TermDuration = changeToTermDuration,
    },
    Quantity = changeToQuantity,
    customTermEndDate = DateTime,
};
var updatedSubscription = subscriptionOperations.Patch(selectedSubscription);

Para programar cambios para la suscripción de un cliente, donde el cambio programado deseado es a un producto diferente:

Obtenga la suscripción por identificador.
Obtenga la idoneidad de la transición para el tipo de elegibilidad de transición programada.
Llame al método Patch() para actualizar la suscripción con los cambios programados.

Solicitud REST

Sintaxis de la solicitud

Método	URI de solicitud
PATCH	{baseURL}/v1/customers/{customer-tenant-id}/subscriptions/{subscription-id} HTTP/1.1

Parámetro de URI

En esta tabla se enumeran los parámetros de consulta necesarios para llamar a la API.

Nombre	Type	Obligatorio	Descripción
customer-tenant-id	guid	Y	GUID correspondiente al cliente.
subscription-id	guid	Y	GUID correspondiente a la suscripción.

Encabezados de solicitud

Para obtener más información, consulta Encabezados REST del Centro de partners.

Cuerpo de la solicitud

Se requiere un recurso de suscripción completo en el cuerpo de la solicitud, con la scheduledNextTermInstructions propiedad definida. Para programar los cambios de la suscripción, asegúrese de que la propiedad AutoRenewEnabled esté establecida en true.

Para el identificador de disponibilidad al final de la venta con conversiones (EndofSaleWithConversions) ofrece:

GetTransitionEligibility para devolver CatalogItemID.

a. Asegúrese de establecer el tipo de idoneidad programada; de lo contrario, el valor predeterminado es inmediato.
Use CatalogItemID para extraer availabilityID.

Nota:

Si usa GET Availabilities para determinar la disponibilidad de las instrucciones scheduledNextTerm y si todos los términos son estado EOS, recibirá una lista vacía. La mejor manera de determinar las rutas de acceso válidas es llamar a la API GetTransitionEligibilty para devolver las opciones válidas.

Campo	Tipo	Obligatorio	Descripción
scheduledNextTermInstructions	object	Y	Define las instrucciones de término siguiente para la suscripción. La propiedad contiene el `product` objeto y el `quantity` campo .

Ejemplo de solicitud

PATCH https://api.partnercenter.microsoft.com/v1/customers/<customer-tenant-id>/subscriptions/<subscription-id> HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: ca7c39f7-1a80-43bc-90d8-ee7d1cad3831
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
If-Match: <etag>
Content-Type: application/json
Content-Length: 1029
Expect: 100-continue
Connection: Keep-Alive

{
    "id": "6e7aa601-629e-461b-8933-0898c3cc3c7c",
    "offerId": "DZH318Z0BXWC:0001:DZH318Z0BMJX",
    "offerName": "offer Name",
    "friendlyName": "friendly Name",
    "quantity": 1,
    "customTermEndDate": "2019-01-09T00:21:45.9263727",
    "unitType": "License(s)",
    "hasPurchasableAddons": false,
    "creationDate": "2019-01-04T01:00:12.6647304Z",
    "effectiveStartDate": "2019-01-09T00:21:45.9263727+00:00",
    "commitmentEndDate": "2019-02-08T00:21:45.9263727+00:00",
    "status": "active",
    "autoRenewEnabled": true,
    "scheduledNextTermInstructions": { 
      "product": { 
         "productId":  "DG7GMGF0DVSV", 
         "skuId":  "000P", 
         "availabilityId":  "DG7GMGF0F3Q9", 
         "billingCycle":  "Annual", 
         "termDuration":  "P3Y",
         "promotionId": "39NFJQT1PFPJ:000H:39NFJQT1Q5DK"
        }, 
      "quantity":  1 
      "customTermEndDate" : "2019-01-09T00:21:45.9263727",
     },  // original value = null 
    "isTrial": false,
    "billingType": "license",
    "billingCycle": "monthly",
    "termDuration": "P1M",
    "refundOptions": [{
        "type": "Full",
        "expiresAt": "2019-01-10T00:21:45.9263727+00:00"
    }],
    "isMicrosoftProduct": false,
    "partnerId": "",
    "contractType": "subscription",
    "publisherName": "publisher Name",
    "orderId": "ImxjLNL4_fOc-2KoyOxGTZcrlIquzls11",
    "attributes": {"objectType": "Subscription"},
}

Respuesta REST

Si la solicitud se realiza correctamente, este método devuelve las propiedades actualizadas del recurso Subscription en el cuerpo de la respuesta.

Códigos de error y de respuesta correctos

Cada respuesta incluye un código de estado HTTP que indica éxito o error y otra información de depuración. Use una herramienta de seguimiento de red para leer este código, tipo de error y otros parámetros. Para obtener la lista completa, consulte Códigos de error.

Ejemplo de respuesta

HTTP/1.1 200 OK
Content-Length: 1322
Content-Type: application/json; charset=utf-8
MS-RequestId: ca7c39f7-1a80-43bc-90d8-ee7d1cad3831
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
X-Locale: en-US

{
    "id": "6e7aa601-629e-461b-8933-0898c3cc3c7c",
    "offerId": "DZH318Z0BXWC:0001:DZH318Z0BMJX",
    "offerName": "offer Name",
    "friendlyName": "friendly Name",
    "quantity": 1,
    "customTermEndDate": "2019-01-09T00:21:45.9263727",
    "unitType": "License(s)",
    "hasPurchasableAddons": false,
    "creationDate": "2019-01-04T01:00:12.6647304Z",
    "effectiveStartDate": "2019-01-09T00:21:45.9263727+00:00",
    "commitmentEndDate": "2019-02-08T00:21:45.9263727+00:00",
    "status": "active",
    "autoRenewEnabled": true,
    "scheduledNextTermInstructions": { 
      "product": { 
         "productId":  "DG7GMGF0DVSV", 
         "skuId":  "000P", 
         "availabilityId":  "DG7GMGF0F3Q9", 
         "billingCycle":  "Annual", 
         "termDuration":  "P3Y",
         "promotionId": "39NFJQT1PFPJ:000H:39NFJQT1Q5DK"
        }, 
      "quantity":  1 
      "customTermEndDate": "2019-01-09T00:21:45.9263727",
     },  // original value = null 
    "isTrial": false,
    "billingType": "license",
    "billingCycle": "monthly",
    "termDuration": "P1M",
    "refundOptions": [{
        "type": "Full",
        "expiresAt": "2019-01-10T00:21:45.9263727+00:00"
    }],
    "isMicrosoftProduct": false,
    "partnerId": "",
    "contractType": "subscription",
    "publisherName": "publisher Name",
    "orderId": "ImxjLNL4_fOc-2KoyOxGTZcrlIquzls11",
    "attributes": {"objectType": "Subscription"},
}

Compartir a través de

Programar cambios para una nueva suscripción comercial mediante las API del Centro de partners

Requisitos previos

Método del Centro de partners

C#

Solicitud REST

Sintaxis de la solicitud

Parámetro de URI

Encabezados de solicitud

Cuerpo de la solicitud

Ejemplo de solicitud

Respuesta REST

Códigos de error y de respuesta correctos

Ejemplo de respuesta

Comentarios

Recursos adicionales