Programar cambios para una nueva suscripción de comercio mediante las API de Partner Center

Se aplica a: Partner Center

En este artículo se describe cómo puede usar la API del Centro de partners para programar cambios en 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 obtener más información, consulte información general sobre las nuevas experiencias comerciales.

La creación de cambios programados le permite modificar su suscripción, automáticamente, cuando se produce la próxima renovación. Al programar cambios, puede optar por aumentar o disminuir el número de licencias, modificar el plazo y la frecuencia de facturación, e incluso optar por actualizar el SKU. La programación de cambios le permite realizar modificaciones en su suscripción en 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 eliminarán todos los cambios programados que estaban programados anteriormente para producirse en el momento de la renovación.

Prerrequisitos

  • Credenciales tal como se describe en Autenticación del Centro de asociados. 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 Partner Center 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 Id. de Microsoft en la sección Información de la cuenta de cliente. El ID de Microsoft es el mismo que el ID de cliente (customer-tenant-id).

  • Un identificador de suscripción.

  • La renovación automática está habilitada en la suscripción.

Método de Partner Center

Para programar cambios de una suscripción en Partner Center:

  1. Seleccione un cliente.

  2. Seleccione la suscripción para la que desea programar cambios.

  3. Habilite la renovación automática.

  4. Seleccione Administrar renovación.

  5. Realice modificaciones en la suscripción que tendrán lugar en el momento de la renovación.

  6. Seleccione Aceptar para cerrar el panel lateral.

  7. 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 a. m. UTC del día siguiente. Las renovaciones se procesan en una cola y pueden tardar hasta 24 horas en procesarse.

C#

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

  1. Obtenga la suscripción por ID.
  2. Obtenga la elegibilidad de transición para el tipo de elegibilidad de transición programada.
  3. Cree un objeto ScheduledNextTermInstructions y establézcalo en la propiedad de la suscripción.
  4. 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 en la suscripción de un cliente, donde el cambio programado deseado es en un producto diferente:

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

Solicitud REST

Sintaxis de la solicitud

Método Solicitud de URI
PARCHE {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 Tipo Obligatorio Descripción
id de cliente-arrendatario guid Y Un GUID correspondiente al cliente.
id-de-suscripción guid Y Un GUID correspondiente a la suscripción.

Cabeceras de solicitud

Para más información, consulte 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 cambios en la suscripción, asegúrese de que la propiedad AutoRenewEnabled esté establecida en true.

Para el identificador de disponibilidad de las ofertas de fin de venta con conversiones (EndofSaleWithConversions):

  1. GetTransitionEligibility devuelve CatalogItemID.

    a) Asegúrese de establecer el tipo de elegibilidad «Programada»; de lo contrario, se aplicará la opción inmediata de forma predeterminada.

  2. Utilice CatalogItemID para extraer después availabilityID.

Si está utilizando GET Availabilities para determinar la disponibilidad de las instrucciones scheduledNextTerm y si todos los términos están en 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
Instrucciones para el siguiente plazo programado objeto Y Define las instrucciones para el siguiente plazo de la suscripción. La propiedad contiene el product objeto y el quantity campo.

Uso de scheduledActions para establecer instrucciones para el próximo período (cambios programados)

Los términos de servicio extendidos presentan una nueva manera de establecer instrucciones de fin de término. El nuevo constructo scheduledActions ofrece a los partners una única forma de definir las actualizaciones para el próximo período, incluida la cancelación, la renovación a períodos de servicio ampliados o la renovación a otros destinos de fin de período. Los asociados pueden establecer las instrucciones scheduledActions RenewToNewTerm en lugar de las instrucciones scheduledNextTermInstructions anteriores. Puede obtener más información sobre el uso de scheduledActions para establecer las instrucciones para el siguiente plazo en la documentación ampliada sobre el plazo de servicio.

Los socios que usan scheduledActions deben evitar enviar también scheduledNextTermInstructions al actualizar suscripciones elegibles para períodos de servicio ampliados. Los asociados pueden optar por pasar ambos deben darse cuenta de que solo se tienen en cuenta scheduledActions. Los socios pueden seguir pasando solo scheduledNextTermInstructions para establecer las instrucciones del siguiente término.

Importante

Evite pasar instrucciones de término siguiente tanto en scheduledActions como en nextTermInstructions. Use uno u otro. Si se pasan ambos, las instrucciones scheduledActions tienen como valor predeterminado.

Solicitud mediante acciones programadas

{
  "autoRenewEnabled": true,
  "scheduledActions": [
    {
      "scheduledType": "TermEnd",
      "actionType": "RenewToNewTerm",
      "instructions": {
        "product": {
          "productId": "CFQ7TTC0LHXH",
          "skuId": "0001",
          "availabilityId": "CFQ7TTC0LHXH",
          "billingCycle": "annual",
          "termDuration": "P1Y",
          "promotionId": "39NFJQT20KJ2:0001:39NFJQT1Q5KK"
        },
        "quantity": 25,
        "customTermEndDate": "2027-11-31T23:59:59.000Z"
      }
    }
  ]
}

Respuesta mediante acciones programadas

{
  "autoRenewEnabled": true,
  "scheduledNextTermInstructions" : {
     "product": {
        "productId": "CFQ7TTC0LHXH",
        "skuId": "0001",
        "availabilityId": "CFQ7TTC0LHXH",
        "billingCycle": "annual",
        "termDuration": "P1Y",
        "promotionId": "39NFJQT20KJ2:0001:39NFJQT1Q5KK"
      },
      "quantity": 25,
      "customTermEndDate": "2027-11-31T23:59:59.000Z"
  },
  "scheduledActions":   "scheduledActions": [
    {
      "scheduledType": "TermEnd",
      "actionType": "RenewToNewTerm",
      "instructions": {
        "product": {
          "productId": "CFQ7TTC0LHXH",
          "skuId": "0001",
          "availabilityId": "CFQ7TTC0LHXH",
          "billingCycle": "annual",
          "termDuration": "P1Y",
          "promotionId": "39NFJQT20KJ2:0001:39NFJQT1Q5KK"
        },
        "quantity": 25,
        "customTermEndDate": "2027-11-31T23:59:59.000Z"
      }
    }
  ]
}

Solicitud con instrucciones programadas para el próximo término

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 de suscripción en el cuerpo de la respuesta.

Códigos de éxito y de error de la respuesta

Cada respuesta viene con 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.

Respuesta mediante instrucciones programadas para el siguiente término

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"},
}
  • Last updated on