API de suscripción de suministro de SaaS v2 en marketplace comercial de Microsoft

  • Artículo

En este artículo se describe la versión 2 de las API de suscripción de suministro de SaaS.

Nota:

Para poder llamar a las API de suscripción de suministro de SaaS, debe crear el token de autorización de un publicador mediante el identificador de recurso correcto. Obtenga información sobre cómo obtener el token de autorización del publicador

Resolución de una suscripción comprada

El punto de conexión de resolución permite al editor cambiar el token de identificación de la compra del marketplace comercial (conocido como token en Comprada pero todavía no activada) a un identificador de suscripción de SaaS comprada persistente y sus detalles.

Cuando se redirige a un cliente a la dirección URL de la página de aterrizaje del partner, se pasa el token de identificación del cliente como parámetro token en esta llamada a la URL. Se espera que el partner use este token y haga una solicitud para resolverlo. La respuesta de la API Resolve contiene el identificador de la suscripción de SaaS y otros detalles para identificar la compra de forma única. El token proporcionado con la llamada URL de la página de aterrizaje es válido durante 24 horas. Si el token que recibe ha expirado, se recomienda proporcionar las instrucciones siguientes al usuario final:

"No pudimos identificar esta compra. Vuelva a abrir esta suscripción de SaaS en Azure Portal o en Administración de Microsoft 365 Center y seleccione "Configurar cuenta" o "Administrar cuenta" de nuevo".

Al llamar a Resolve API, se devuelven los detalles de la suscripción y el estado de las suscripciones de SaaS en todos los estados admitidos.

Post https://marketplaceapi.microsoft.com/api/saas/subscriptions/resolve?api-version=<ApiVersion>

Parámetros de consulta:

Parámetro Valor
ApiVersion Use 2018-08-31.

Encabezados de la solicitud:

Parámetro Valor
content-type application/json
x-ms-requestid Valor de cadena único para el seguimiento de la solicitud del cliente, preferiblemente un GUID. Si no se proporciona este valor, se genera uno y se proporciona en los encabezados de respuesta.
x-ms-correlationid Valor de cadena único para la operación en el cliente. Este parámetro pone en correlación todos los eventos de la operación del cliente con los eventos del servidor. Si no se proporciona este valor, se genera uno y se proporciona en los encabezados de respuesta.
authorization Token de acceso único que identifica al editor que realiza esta llamada API. El formato es "Bearer <access_token>" cuando el publicador recupera el valor del token, tal y como se explica en Obtención de un token basado en la aplicación Microsoft Entra.
x-ms-marketplace-token Parámetro token de identificación de la compra que se va a resolver. El token se pasa en la llamada a la dirección URL de la página de aterrizaje cuando se redirige al cliente al sitio web del partner de SaaS (por ejemplo, https://contoso.com/signup?token=<token><authorization_token>).

El valor del token que se va a codificar forma parte de la dirección URL de la página de aterrizaje, por lo que debe descodificarse antes de que se use como parámetro en esta llamada API.

Un ejemplo de una cadena codificada en la dirección URL tiene el siguiente aspecto: contoso.com/signup?token=ab%2Bcd%2Fef, donde el token es ab%2Bcd%2Fef. El mismo token descodificado es: Ab+cd/ef

Códigos de respuesta:

Código: 200 Devuelve identificadores de suscripción de SaaS únicos en función del x-ms-marketplace-token proporcionado.

Ejemplo de cuerpo de respuesta:

{
  "id": "<guid>", // purchased SaaS subscription ID
  "subscriptionName": "Contoso Cloud Solution", // SaaS subscription name
  "offerId": "offer1", // purchased offer ID
  "planId": "silver", // purchased offer's plan ID
  "quantity": 20, // number of purchased seats, might be empty if the plan is not per seat
  "subscription": { // full SaaS subscription details, see Get Subscription APIs response body for full description
    "id": "<guid>",
    "publisherId": "contoso",
    "offerId": "offer1",
    "name": "Contoso Cloud Solution",
    "saasSubscriptionStatus": " PendingFulfillmentStart ",
    "beneficiary": {
      "emailId": "test@test.com",
      "objectId": "<guid>",
      "tenantId": "<guid>",
      "puid": "<ID of the user>"
    },
    "purchaser": {
      "emailId": "test@test.com",
      "objectId": "<guid>",
      "tenantId": "<guid>",
      "puid": "<ID of the user>"
    },
    "planId": "silver",
    "term": {
      "termUnit": "P1M",
      "startDate": "2022-03-07T00:00:00Z", //This field is only available after the saas subscription is active.
      "endDate": "2022-04-06T00:00:00Z" //This field is only available after the saas subscription is active.
    },
      "autoRenew": true/false,
    "isTest": true/false,
    "isFreeTrial": false,
    "allowedCustomerOperations": <CSP purchases>["Read"] <All Others> ["Delete", "Update", "Read"],
      "sandboxType": "None",
      "lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
      "quantity": 5,
    "sessionMode": "None"
  }
}

Código: 400 Solicitud incorrecta. Falta el x-ms-marketplace-token, o bien tiene un formato incorrecto, no es válido o ha expirado.

Código: 403 Prohibido. El token de autorización no es válido, ha expirado o no se ha proporcionado. La solicitud intenta acceder a una suscripción de SaaS para una oferta publicada con un identificador de aplicación de Microsoft Entra diferente del que se usa para crear el token de autorización.

Este error suele indicar que no se ha realizado correctamente el registro de SaaS.

Código: 500 Error interno del servidor. Vuelva a intentar la llamada API. Si el error persiste, póngase en contacto con el servicio de soporte técnico de Microsoft.

Activar una suscripción

Después de configurar la cuenta de SaaS para un cliente final, el editor debe llamar a la API Activate Subscription en el lado de Microsoft. El cliente no se factura a menos que esta llamada API se realice correctamente.

Post https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/activate?api-version=<ApiVersion>

Parámetros de consulta:

Parámetro Valor
ApiVersion Use 2018-08-31.
subscriptionId Identificador único de la suscripción de SaaS comprada. Este identificador se obtiene después de resolver el token de autorización del marketplace comercial mediante la API Resolve.

Encabezados de la solicitud:

Parámetro Valor
content-type application/json
x-ms-requestid Valor de cadena único para el seguimiento de la solicitud del cliente, preferiblemente un GUID. Si no se proporciona este valor, se genera uno y se proporciona en los encabezados de respuesta.
x-ms-correlationid Valor de cadena único para la operación en el cliente. Esta cadena pone en correlación todos los eventos de la operación en el cliente con los eventos en el servidor. Si no se proporciona este valor, se genera uno y se proporciona en los encabezados de respuesta.
authorization Token de acceso único que identifica al editor que realiza esta llamada API. El formato es "Bearer <access_token>" cuando el publicador recupera el valor del token, tal y como se explica en Obtención de un token basado en la aplicación Microsoft Entra.

Códigos de respuesta:

Código: 200 Solicitud para actualizar la suscripción y marcar como "Suscrito" se recibe. Los proveedores de software independientes (ISV) pueden comprobar el estado de la suscripción después de unos minutos (lea para obtener la operación para comprobar el estado de la suscripción). Esto le proporciona la respuesta definitiva si la suscripción se actualizó correctamente. Si no se suscribe, se envía automáticamente un webhook "Cancelar suscripción".

No hay ningún cuerpo de respuesta para esta llamada.

Código: 400 Solicitud incorrecta: error de validación.

  • La suscripción de SaaS está en estado Suspendido .

Código: 403 Prohibido. El token de autorización no es válido, ha expirado o no se ha proporcionado. La solicitud intenta acceder a una suscripción de SaaS para una oferta publicada con un identificador de aplicación de Microsoft Entra diferente del que se usa para crear el token de autorización.

Este error suele indicar que no se ha realizado correctamente el registro de SaaS.

Código: 404 No encontrado. La suscripción de SaaS se encuentra en el estado Suscripción cancelada.

Código: 500 Error interno del servidor. Vuelva a intentar la llamada API. Si el error persiste, póngase en contacto con el servicio de soporte técnico de Microsoft.

Obtención de una lista de todas las suscripciones

Esta API recupera una lista de todas las suscripciones de SaaS compradas para todas las ofertas que el editor ha publicado en el marketplace comercial. Se devuelven las suscripciones de SaaS en todos los estados posibles. Las suscripciones de SaaS canceladas también se devuelven porque esta información no se elimina en el lado de Microsoft.

Esta API devuelve resultados paginados (100 por página).

Get https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>

Parámetros de consulta:

Parámetro Valor
ApiVersion Use 2018-08-31.
continuationToken Parámetro opcional. Para recuperar la primera página de resultados, déjelo vacío. Use el valor devuelto en el parámetro @nextLink para recuperar la página siguiente.

Encabezados de la solicitud:

Parámetro Valor
content-type application/json
x-ms-requestid Valor de cadena único para el seguimiento de la solicitud del cliente, preferiblemente un GUID. Si no se proporciona este valor, se genera uno y se proporciona en los encabezados de respuesta.
x-ms-correlationid Valor de cadena único para la operación en el cliente. Este parámetro pone en correlación todos los eventos de la operación del cliente con los eventos del servidor. Si no se proporciona este valor, se genera uno y se proporciona en los encabezados de respuesta.
authorization Token de acceso único que identifica al editor que realiza esta llamada API. El formato es "Bearer <access_token>" cuando el publicador recupera el valor del token, tal y como se explica en Obtención de un token basado en la aplicación Microsoft Entra.

Códigos de respuesta:

Código: 200 Devuelve la lista de todas las suscripciones existentes para todas las ofertas realizadas por este publicador, en función del token de autorización del publicador.

Ejemplo de cuerpo de respuesta:

{
  "subscriptions": [
    {
      "id": "<guid>", // purchased SaaS subscription ID
      "name": "Contoso Cloud Solution", // SaaS subscription name
      "publisherId": "contoso", // publisher ID
      "offerId": "offer1", // purchased offer ID
      "planId": "silver", // purchased plan ID
      "quantity": 10, // purchased amount of seats, is empty if plan is not per seat
      "beneficiary": { // email address, user ID and tenant ID for which SaaS subscription was purchased.
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "purchaser": { // email address, user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) purchase
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "term": { // The period for which the subscription was purchased.
        "startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
        "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
        "termUnit": "P1M" // where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values
      },
      "autoRenew": true,
      "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
      "sessionMode": "None", // not relevant
      "isFreeTrial": true, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. (Optional field -– if not returned, the value is false.)
      "isTest": false, // not relevant
      "sandboxType": "None", // not relevant
      "saasSubscriptionStatus": "Subscribed" // Indicates the status of the operation. Can be one of the following: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
    },
    // next SaaS subscription details, might be a different offer
    {
      "id": "<guid1>",
      "name": "Contoso Cloud Solution1",
      "publisherId": "contoso",
      "offerId": "offer2",
      "planId": "gold",
      "quantity": "",
      "beneficiary": {
        "emailId": " test@contoso.com",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "purchaser": {
        "emailId": "purchase@csp.com ",
        "objectId": "<guid>",
        "tenantId": "<guid>",
        "puid": "<ID of the user>"
      },
      "term": {
        "startDate": "2019-05-31", /This field is only available after the saas subscription is active.
        "endDate": "2020-04-30",  //This field is only available after the saas subscription is active.
        "termUnit": "P1Y"
      },
      "autoRenew": false,
      "allowedCustomerOperations": ["Read"],
      "sessionMode": "None",
      "isFreeTrial": false,
      "isTest": false,
      "sandboxType": "None",
      "saasSubscriptionStatus": "Suspended"
    }
  ],
  "@nextLink": "https:// https://marketplaceapi.microsoft.com/api/saas/subscriptions/?continuationToken=%5b%7b%22token%22%3a%22%2bRID%3a%7eYeUDAIahsn22AAAAAAAAAA%3d%3d%23RT%3a1%23TRC%3a2%23ISV%3a1%23FPC%3aAgEAAAAQALEAwP8zQP9%2fFwD%2b%2f2FC%2fwc%3d%22%2c%22range%22%3a%7b%22min%22%3a%22%22%2c%22max%22%3a%2205C1C9CD673398%22%7d%7d%5d&api-version=2018-08-31" // url that contains continuation token to retrieve next page of the SaaS subscriptions list, if empty or absent, this is the last page. ISV can use this url as is to retrieve the next page or extract the value of continuation token from this url.
}

Si no se encuentra ninguna suscripción de SaaS comprada para este editor, el cuerpo de respuesta se devuelve vacío.

Código: 403 Prohibido. El token de autorización no está disponible, no es válido o ha expirado.

Este error suele indicar que no se ha realizado correctamente el registro de SaaS.

Código: 500 Error interno del servidor. Vuelva a intentar la llamada API. Si el error persiste, póngase en contacto con el servicio de soporte técnico de Microsoft.

Obtener una suscripción

Esta API recupera una suscripción de SaaS comprada especificada para una oferta de SaaS que el editor ha publicado en el marketplace comercial. Use esta llamada para obtener toda la información disponible para una suscripción de SaaS específica por su identificador, en lugar de llamar a la API que se usa para obtener una lista de todas las suscripciones.

Get https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Parámetros de consulta:

Parámetro Valor
ApiVersion Use 2018-08-31.
subscriptionId Identificador único de la suscripción de SaaS comprada. Este identificador se obtiene después de resolver el token de autorización del marketplace comercial mediante la API Resolve.

Encabezados de la solicitud:

Parámetro Valor
content-type application/json
x-ms-requestid Valor de cadena único para el seguimiento de la solicitud del cliente, preferiblemente un GUID. Si no se proporciona este valor, se genera uno y se proporciona en los encabezados de respuesta.
x-ms-correlationid Valor de cadena único para la operación en el cliente. Este parámetro pone en correlación todos los eventos de la operación del cliente con los eventos del servidor. Si no se proporciona este valor, se genera uno y se proporciona en los encabezados de respuesta.
authorization Token de acceso único que identifica al editor que realiza esta llamada API. El formato es "Bearer <access_token>" cuando el publicador recupera el valor del token, tal y como se explica en Obtención de un token basado en la aplicación Microsoft Entra.

Códigos de respuesta:

Código: 200 Devuelve los detalles de una suscripción de SaaS en función del subscriptionId proporcionado.

Ejemplo de cuerpo de respuesta:

{
  "id": "<guid>", // purchased SaaS subscription ID
  "name": "Contoso Cloud Solution", // SaaS subscription name
  "publisherId": "contoso", // publisher ID
  "offerId": "offer1", // purchased offer ID
  "planId": "silver", // purchased plan ID
  "quantity": 10, // purchased amount of seats is empty if plan is not per seat
  "beneficiary": { // email address, user ID and tenant ID for which SaaS subscription is purchased.
    "emailId": "test@contoso.com",
    "objectId": "<guid>",
    "tenantId": "<guid>",
    "puid": "<ID of the user>"
  },
  "purchaser": { // email address ,user ID and tenant ID that purchased the SaaS subscription. These could be different from beneficiary information for reseller (CSP) scenario
    "emailId": "test@test.com",
    "objectId": "<guid>",
    "tenantId": "<guid>",
    "puid": "<ID of the user>"
  },
  "allowedCustomerOperations": ["Read", "Update", "Delete"], // Indicates operations allowed on the SaaS subscription for beneficiary. For CSP-initiated purchases, this is always "Read" because the customer cannot update or delete subscription in this flow. Purchaser can perform all operations on the subscription.
  "sessionMode": "None", // not relevant
  "isFreeTrial": false, // true - the customer subscription is currently in free trial, false - the customer subscription is not currently in free trial. Optional field – if not returned the value is false.
  "autoRenew": true,
  "isTest": false, // not relevant
  "sandboxType": "None", // not relevant
  "created": "2022-03-01T22:59:45.5468572Z",
     "lastModified": "0001-01-01T00:00:00", //[Deprecated] Do not use.
  "saasSubscriptionStatus": " Subscribed ", // Indicates the status of the operation: PendingFulfillmentStart, Subscribed, Suspended or Unsubscribed.
  "term": { // the period for which the subscription was purchased
    "startDate": "2022-03-04T00:00:00Z", //format: YYYY-MM-DD. This is the date when the subscription was activated by the ISV and the billing started. This field is only available after the saas subscription is active.
    "endDate": "2022-04-03T00:00:00Z", // This is the last day the subscription is valid. Unless stated otherwise, the automatic renew happens the next day. This field is only available after the saas subscription is active.
    "termUnit": "P1M" //where P1M is monthly and P1Y is yearly. Also reflected in the startDate and endDate values.
  }
}

Código: 403 Prohibido. El token de autorización no es válido, ha expirado o no se ha proporcionado. La solicitud intenta acceder a una suscripción de SaaS para una oferta publicada con un identificador de aplicación de Microsoft Entra diferente del que se usa para crear el token de autorización.

Este error suele indicar que no se ha realizado correctamente el registro de SaaS.

Código: 404 No encontrado. No se encuentra la suscripción de SaaS con el valor de subscriptionId especificado.

Código: 500 Error interno del servidor. Vuelva a intentar la llamada API. Si el error persiste, póngase en contacto con el servicio de soporte técnico de Microsoft.

Lista de planes disponibles

Esta API recupera todos los planes de una oferta de SaaS identificados por el valor subscriptionId de una compra específica de esta oferta. Use esta llamada para obtener una lista de todos los planes públicos y privados que el beneficiario de una suscripción de SaaS puede actualizar para la suscripción. Los planes devueltos están disponibles en la misma geografía que el plan ya adquirido.

Esta llamada devuelve una lista de los planes disponibles para ese cliente, además de los que se han comprado. La lista se puede presentar a un usuario final en el sitio del editor. Un usuario final puede cambiar el plan de suscripción a uno de los planes de la lista devuelta. Cambiar el plan a un plan que no está en la lista no funciona.

Esta API también recupera el identificador de oferta privado activo asociado (si llama a la API con el filtro planId). La llamada a la API con el filtro planId muestra los GUID de identificador de oferta privada activos en el cuerpo de la respuesta en el nodo sourceOffers. El planId pasado en el parámetro de filtro debe coincidir con el planId que compró el cliente.

Get https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>

Parámetros de consulta:

Parámetro Valor
ApiVersion Use 2018-08-31.
subscriptionId Identificador único de la suscripción de SaaS comprada. Este identificador se obtiene después de resolver el token de autorización del marketplace comercial mediante la API Resolve.
planId (Optional) Identificador de plan de un plan específico que desea capturar. Esto es opcional y, si se omite, devuelve todos los planes.

Encabezados de la solicitud:

Parámetro Valor
content-type application/json
x-ms-requestid Valor de cadena único para el seguimiento de la solicitud del cliente, preferiblemente un GUID. Si no se proporciona este valor, se genera uno y se proporciona en los encabezados de respuesta.
x-ms-correlationid Valor de cadena único para la operación en el cliente. Este parámetro pone en correlación todos los eventos de la operación del cliente con los eventos del servidor. Si no se proporciona este valor, se genera uno y se proporciona en los encabezados de respuesta.
authorization Token de acceso único que identifica al editor que realiza esta llamada API. El formato es "Bearer <access_token>" cuando el publicador recupera el valor del token, tal y como se explica en Obtención de un token basado en la aplicación Microsoft Entra.

Códigos de respuesta:

Código: 200 Devuelve una lista de todos los planes disponibles para una suscripción de SaaS existente, incluida la que ya se ha comprado.

Pasar planId no válido (opcional) devuelve una lista vacía de planes.

Ejemplo de cuerpo de respuesta:

{
  "plans": [
    {
      "planId": "Platinum001",
      "displayName": "plan display name",
      "isPrivate": true, //returns true for private plans and customized plans created within a private offer.
      "description": "plan description",
      "minQuantity": 5,
      "maxQuantity": 100,
      "hasFreeTrials": false,
      "isPricePerSeat": true,
      "isStopSell": false,
      "market": "US",
      "planComponents": {
        "recurrentBillingTerms": [
          {
            "currency": "USD",
            "price": 1,
            "termUnit": "P1M",
            "termDescription": "term description",
            "meteredQuantityIncluded": [
              {
                "dimensionId": "Dimension001",
                "units": "Unit001"
              }
            ]
          }
        ],
        "meteringDimensions": [
          {
            "id": "MeteringDimension001",
            "currency": "USD",
            "pricePerUnit": 1,
            "unitOfMeasure": "unitOfMeasure001",
            "displayName": "unit of measure display name"
          }
        ]
      },
      "sourceOffers": [ //sourceOffers is returned when planId is passed as filter parameter (note that this is the plan that customer has purchased).
        {
          "externalId": "<guid>" //private offer id, returned when purchase is made through private offer.
        }
      ]
    }
  ]
}

Código: 404 No encontrado. No se ha encontrado subscriptionId.

Código: 403 Prohibido. El token de autorización no es válido, ha expirado o no se ha proporcionado. Es posible que la solicitud intente acceder a una suscripción de SaaS para una oferta que se cancele o publique con otro identificador de aplicación de Microsoft Entra del que se usa para crear el token de autorización.

Este error suele indicar que no se ha realizado correctamente el registro de SaaS.

Código: 500 Error interno del servidor. Vuelva a intentar la llamada API. Si el error persiste, póngase en contacto con el servicio de soporte técnico de Microsoft.

Cambiar el plan de la suscripción

Use esta API para actualizar el plan existente que se ha comprado para una suscripción de SaaS a un nuevo plan (público o privado). El editor debe llamar a esta API cuando se cambia un plan en el lado del editor para una suscripción de SaaS comprada en el marketplace comercial.

Solo se puede llamar a esta API para suscripciones activas. Un plan se puede cambiar a cualquier otro plan existente (público o privado), pero no a sí mismo. En el caso de los planes privados, el inquilino del cliente debe definirse como parte del público del plan en el Centro de partners.

Patch https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Parámetros de consulta:

Parámetro Valor
ApiVersion Use 2018-08-31.
subscriptionId Identificador único de la suscripción de SaaS comprada. Este identificador se obtiene después de resolver el token de autorización del marketplace comercial mediante la API Resolve.

Encabezados de la solicitud:

Parámetro Valor
content-type application/json
x-ms-requestid Valor de cadena único para el seguimiento de la solicitud del cliente, preferiblemente un GUID. Si no se proporciona este valor, se genera uno y se proporciona en los encabezados de respuesta.
x-ms-correlationid Valor de cadena único para la operación en el cliente. Este parámetro pone en correlación todos los eventos de la operación del cliente con los eventos del servidor. Si no se proporciona este valor, se genera uno y se proporciona en los encabezados de respuesta.
authorization Token de acceso único que identifica al editor que realiza esta llamada API. El formato es "Bearer <access_token>" cuando el publicador recupera el valor del token, tal y como se explica en Obtención de un token basado en la aplicación Microsoft Entra.

Ejemplo de solicitud de carga:

{
  "planId": "gold" // the ID of the new plan to be purchased
}

Códigos de respuesta:

Código: 202 La solicitud para cambiar el plan se ha aceptado y controlado de forma asincrónica. Se espera que el partner sondee la dirección URL de Operation-Location para determinar si la solicitud de cambio de plan se ha realizado correctamente o no. El sondeo debe realizarse cada pocos segundos hasta que se reciba el estado final de Error, Correcto o Conflicto para la operación. El estado de la operación final debe devolverse rápidamente, pero en algunos casos puede tardar varios minutos.

El asociado también obtiene una notificación de webhook cuando la acción está lista para completarse correctamente en el marketplace comercial. Solo entonces debe el editor cambiar el plan en su lado.

Encabezados de respuesta:

Parámetro Valor
Operation-Location Dirección URL para obtener el estado de la operación. Por ejemplo: https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31

Código: 400 Solicitud incorrecta: errores de validación.

  • No se encuentra el plan solicitado o el plan no está disponible para el usuario.
  • El plan solicitado es el mismo que el plan suscrito.
  • El estado de la suscripción de SaaS es Suscripción cancelada.
  • Una Proveedor de soluciones en la nube (CSP) adquiere la suscripción de SaaS que se está actualizando. Debe trabajar con el proveedor de CSP para realizar esta acción.

Código: 403 Prohibido. El token de autorización no es válido, ha expirado o no se ha proporcionado. La solicitud intenta acceder a una suscripción de SaaS para una oferta publicada con un identificador de aplicación de Microsoft Entra diferente del que se usa para crear el token de autorización.

Este error suele indicar que no se ha realizado correctamente el registro de SaaS.

Código: 404 No encontrado. No se encuentra la suscripción de SaaS con el especificado subscriptionId .

Código: 500 Error interno del servidor. Vuelva a intentar la llamada API. Si el error persiste, póngase en contacto con el servicio de soporte técnico de Microsoft.

Nota:

Se puede cambiar el plan o la cantidad de puestos de cada vez, pero no ambos.

Solo se puede llamar a esta API después de obtener la aprobación explícita del usuario final para el cambio.

Cambio de la cantidad de puestos de la suscripción de SaaS

Use esta API para actualizar (es decir, aumentar o disminuir) la cantidad de puestos comprados para una suscripción de SaaS. El editor debe llamar a esta API cuando se cambia el número de puestos en el lado del editor para una suscripción de SaaS creada en el marketplace comercial.

La cantidad de puestos no puede ser mayor que la cantidad permitida en el plan actual. En este caso, el editor debe cambiar el plan antes de cambiar la cantidad de puestos.

Patch https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Parámetros de consulta:

Parámetro Valor
ApiVersion Use 2018-08-31.
subscriptionId Identificador único de la suscripción de SaaS comprada. Este identificador se obtiene después de resolver el token de autorización del marketplace comercial mediante la API Resolve.

Encabezados de la solicitud:

Parámetro Valor
content-type application/json
x-ms-requestid Valor de cadena único para el seguimiento de la solicitud del cliente, preferiblemente un GUID. Si no se proporciona este valor, se genera uno y se proporciona en los encabezados de respuesta.
x-ms-correlationid Valor de cadena único para la operación en el cliente. Este parámetro pone en correlación todos los eventos de la operación del cliente con los eventos del servidor. Si no se proporciona este valor, se genera uno y se proporciona en los encabezados de respuesta.
authorization Token de acceso único que identifica al editor que realiza esta llamada API. El formato es "Bearer <access_token>" cuando el publicador recupera el valor del token, tal y como se explica en Obtención de un token basado en la aplicación Microsoft Entra.

Ejemplo de solicitud de carga:

{
  "quantity": 5 // the new amount of seats to be purchased
}

Códigos de respuesta:

Código: 202 La solicitud para cambiar la cantidad se ha aceptado y controlado de forma asincrónica. Se espera que el partner sondee la dirección URL de Operation-Location para determinar si la solicitud de cambio de cantidad se ha realizado correctamente o no. El sondeo debe realizarse cada pocos segundos hasta que se reciba el estado final de Error, Correcto o Conflicto para la operación. El estado de la operación final debe devolverse rápidamente, pero en algunos casos puede tardar varios minutos.

El asociado también obtiene una notificación de webhook cuando la acción está lista para completarse correctamente en el marketplace comercial. Solo entonces debe el editor cambiar la cantidad en su lado.

Encabezados de respuesta:

Parámetro Valor
Operation-Location Vínculo a un recurso para obtener el estado de la operación. Por ejemplo, https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31.

Código: 400 Solicitud incorrecta: errores de validación.

  • La nueva cantidad no está dentro del intervalo permitido.
  • Falta la nueva cantidad o 0.
  • La nueva cantidad es la misma que la actual.
  • El estado de la suscripción de SaaS es Suscripción cancelada.
  • Una Proveedor de soluciones en la nube (CSP) adquiere la suscripción de SaaS que se está actualizando. Debe trabajar con el proveedor de CSP para realizar esta acción.

Código: 403 Prohibido. El token de autorización no es válido, ha expirado o no se ha proporcionado. La solicitud intenta acceder a una suscripción de SaaS para una oferta publicada con un identificador de aplicación de Microsoft Entra diferente del que se usa para crear el token de autorización.

Este error suele indicar que no se ha realizado correctamente el registro de SaaS.

Código: 404 No encontrado. No se encuentra la suscripción de SaaS con el especificado subscriptionId .

Código: 500 Error interno del servidor. Vuelva a intentar la llamada API. Si el error persiste, póngase en contacto con el servicio de soporte técnico de Microsoft.

Nota:

Solo se puede cambiar un plan o cantidad a la vez, pero no ambos.

Solo se puede llamar a esta API después de obtener la aprobación explícita del usuario final para el cambio.

Cancelación de una suscripción

Use esta API para cancelar una suscripción de SaaS especificada. No es necesario que el editor use esta API. Se recomienda redirigir a los clientes al marketplace comercial para cancelar las suscripciones de SaaS.

Si el editor decide implementar la cancelación de una suscripción de SaaS comprada en el marketplace comercial en el lado del editor, debe llamar a esta API. Después de la finalización de esta llamada, el estado de la suscripción se convierte en Cancelación de suscripción en el lado de Microsoft.

El cliente no se factura si se cancela una suscripción en un plazo de 72 horas desde la compra.

El cliente se factura si se cancela una suscripción después del período de gracia anterior. El cliente pierde el acceso a la suscripción de SaaS en microsoft inmediatamente después de la cancelación.

Delete https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Parámetros de consulta:

Parámetro Valor
ApiVersion Use 2018-08-31.
subscriptionId Identificador único de la suscripción de SaaS comprada. Este identificador se obtiene después de resolver el token de autorización del marketplace comercial mediante la API Resolve.

Encabezados de la solicitud:

Parámetro Valor
content-type application/json
x-ms-requestid Valor de cadena único para el seguimiento de la solicitud del cliente, preferiblemente un GUID. Si no se proporciona este valor, se genera uno y se proporciona en los encabezados de respuesta.
x-ms-correlationid Valor de cadena único para la operación en el cliente. Este parámetro pone en correlación todos los eventos de la operación del cliente con los eventos del servidor. Si no se proporciona este valor, se genera uno y se proporciona en los encabezados de respuesta.
authorization Token de acceso único que identifica al editor que realiza esta llamada API. El formato es "Bearer <access_token>" cuando el publicador recupera el valor del token, tal y como se explica en Obtención de un token basado en la aplicación Microsoft Entra.

Códigos de respuesta:

Código: 202 La solicitud para cancelar la suscripción se ha aceptado y controlado de forma asincrónica. Se espera que el partner sondee la dirección URL de Operation-Location para determinar si la solicitud se ha realizado correctamente o no. El sondeo debe realizarse cada pocos segundos hasta que se reciba el estado final de Error, Correcto o Conflicto para la operación. El estado de la operación final debe devolverse rápidamente, pero en algunos casos puede tardar varios minutos.

El asociado también obtiene una notificación de webhook cuando la acción se completa correctamente en el marketplace comercial. Solo entonces debe el editor cancelar la suscripción en su lado.

Código: 200 La suscripción ya está en estado de cancelación de suscripción.

Encabezados de respuesta:

Parámetro Valor
Operation-Location Vínculo a un recurso para obtener el estado de la operación. Por ejemplo, https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31.

Código: 400 Solicitud incorrecta. La operación de eliminación no está en la lista allowedCustomerOperations para esta suscripción de SaaS.

Código: 403 Prohibido. El token de autorización no es válido, ha expirado o no está disponible.

Este error suele indicar que no se ha realizado correctamente el registro de SaaS.

Código: 404 No encontrado. No se encuentra la suscripción de SaaS con el valor de subscriptionId.

Código: 409

No se puede completar la eliminación porque la suscripción está bloqueada debido a operaciones pendientes.

Código: 500 Error interno del servidor. Vuelva a intentar la llamada API. Si el error persiste, póngase en contacto con el servicio de soporte técnico de Microsoft.

Contenido relacionado