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

Artículo
01/31/2025

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 publicador intercambiar el token de identificación de compra del marketplace comercial (conocido como token en Comprado pero aún no activado) a un identificador de suscripción saaS comprado persistente y sus detalles.

Cuando se redirige a un cliente a la dirección URL de la página de aterrizaje del asociado, el token de identificación del cliente se pasa como el token de parámetro en esta llamada URL. Se espera que el asociado use este token y realice una solicitud para resolverlo. La respuesta de Resolve API contiene el identificador de suscripción de SaaS y otros detalles para identificar de forma única la compra. El token de proporcionado con la llamada URL de la página de aterrizaje es válido durante 24 horas. Si el token de 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 el Centro de administración de Microsoft 365 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.

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

parámetros de consulta de :

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

encabezados de solicitud de :

Parámetro	Valor
`content-type`	`application/json`
`x-ms-requestid`	Valor de cadena único para realizar el seguimiento de la solicitud desde el 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 correlaciona todos los eventos de la operación de cliente con eventos en el lado 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 publicador que realiza esta llamada API. El formato se `"Bearer <access_token>"` cuando el publicador recupera el valor del token, como se explica en Obtener un token basado en la aplicación Microsoft Entra.
`x-ms-marketplace-token`	El parámetro de identificación de compra token que se va a resolver. El token se pasa en la llamada URL de la página de aterrizaje cuando el cliente se redirige al sitio web del asociado de SaaS (por ejemplo: `https://contoso.com/signup?token=<token><authorization_token>`). El token de valor que se está codificando 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. Este es un ejemplo de una cadena codificada en la dirección URL: `contoso.com/signup?token=ab%2Bcd%2Fef`, donde 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. x-ms-marketplace-token falta, tiene un formato incorrecto, no es válido o ha expirado.

Código: 401 No autorizado. El token de autorización no es válido o ha expirado. 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 autenticación.

Código: 403 Prohibido. El token de autorización no es válido, no se proporcionó o se proporcionó con permisos insuficientes. Asegúrese de proporcionar un token de autorización válido.

Este error suele ser un síntoma de no realizar correctamente el registro de SaaS de .

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

Activación de una suscripción

Una vez configurada la cuenta de SaaS para un usuario final, el publicador debe llamar a la API Activar suscripción en el lado de Microsoft. El cliente no se factura a menos que esta llamada API se realice correctamente.

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

parámetros de consulta de :

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 de Marketplace comercial mediante la API de resolución de .

encabezados de solicitud de :

Parámetro	Valor
`content-type`	`application/json`
`x-ms-requestid`	Valor de cadena único para realizar el seguimiento de la solicitud desde el 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 correlaciona todos los eventos de la operación de cliente con eventos en el lado 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 publicador que realiza esta llamada API. El formato se `"Bearer <access_token>"` cuando el publicador recupera el valor del token, como se explica en Obtener 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, no se proporcionó o se proporcionó con permisos insuficientes. Asegúrese de proporcionar un token de autorización válido.

Este error suele ser un síntoma de no realizar correctamente el registro de SaaS de .

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

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

Obtener una lista de todas las suscripciones

Esta API recupera una lista de todas las suscripciones de SaaS compradas para todas las ofertas que el publicador publica 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.

La API devuelve resultados paginados, debe pasar continuationToken para obtener los resultados posteriores.

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

parámetros de consulta de :

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

encabezados de solicitud de :

Parámetro	Valor
`content-type`	`application/json`
`x-ms-requestid`	Valor de cadena único para realizar el seguimiento de la solicitud desde el 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 correlaciona todos los eventos de la operación de cliente con eventos en el lado 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 publicador que realiza esta llamada API. El formato se `"Bearer <access_token>"` cuando el publicador recupera el valor del token, como se explica en Obtener 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 publicador, se devuelve el cuerpo de respuesta vacío.

Código: 403 Prohibido. El token de autorización no es válido, no se proporcionó o se proporcionó con permisos insuficientes. Asegúrese de proporcionar un token de autorización válido.

Este error suele ser un síntoma de no realizar correctamente el registro de SaaS de .

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

Obtener suscripción

Esta API recupera una suscripción de SaaS comprada especificada para una oferta de SaaS que el publicador publica 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.

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

parámetros de consulta de :

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 de Marketplace comercial mediante resolve API.

encabezados de solicitud de :

Parámetro	Valor
`content-type`	`application/json`
`x-ms-requestid`	Valor de cadena único para realizar el seguimiento de la solicitud desde el 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 correlaciona todos los eventos de la operación de cliente con eventos en el lado 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 publicador que realiza esta llamada API. El formato se `"Bearer <access_token>"` cuando el publicador recupera el valor del token, como se explica en Obtener un token basado en la aplicación Microsoft Entra.

códigos de respuesta :

Código: 200 Devuelve detalles de una suscripción de SaaS en función de la subscriptionId proporcionada.

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, no se proporcionó o se proporcionó con permisos insuficientes. Asegúrese de proporcionar un token de autorización válido.

Este error suele ser un síntoma de no realizar correctamente el registro de SaaS de .

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

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

Enumerar los planes disponibles

Esta API recupera todos los planes de una oferta de SaaS identificada por el subscriptionId de una compra específica de esta oferta. Use esta llamada para obtener una lista de todos los planes privados y públicos 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 planes disponibles para ese cliente además del que ya se ha comprado. La lista se puede presentar a un usuario final en el sitio del publicador. Un usuario final puede cambiar el plan de suscripción a cualquiera 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.

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

parámetros de consulta de :

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 de Marketplace comercial mediante resolve API.
`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 solicitud de :

Parámetro	Valor
`content-type`	`application/json`
`x-ms-requestid`	Valor de cadena único para realizar el seguimiento de la solicitud desde el 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 correlaciona todos los eventos de la operación de cliente con eventos en el lado 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 publicador que realiza esta llamada API. El formato se `"Bearer <access_token>"` cuando el publicador recupera el valor del token, como se explica en Obtener 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 encuentra subscriptionId.

Código: 403 Prohibido. El token de autorización no es válido, no se proporcionó o se proporcionó con permisos insuficientes. Asegúrese de proporcionar un token de autorización válido.

Este error suele ser un síntoma de no realizar correctamente el registro de SaaS de .

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

Cambiar el plan de la suscripción

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

Solo se puede llamar a esta API para suscripciones de Active. Cualquier 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 de la audiencia del plan en el Centro de partners.

`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>` de revisión

parámetros de consulta de :

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 de Marketplace comercial mediante resolve API.

encabezados de solicitud de :

Parámetro	Valor
`content-type`	`application/json`
`x-ms-requestid`	Valor de cadena único para realizar el seguimiento de la solicitud desde el 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 correlaciona todos los eventos de la operación de cliente con eventos en el lado 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 publicador que realiza esta llamada API. El formato se `"Bearer <access_token>"` cuando el publicador recupera el valor del token, como se explica en Obtener un token basado en la aplicación Microsoft Entra.

Ejemplo de carga de solicitud de :

{
  "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 asociado sondee la dirección URL de Operation-Location para determinar si la solicitud de plan de cambio se ha realizado correctamente o no. El sondeo debe realizarse cada varios segundos hasta que se reciba el estado final de Error, Correctoo Conflicto para la operación. El estado de la operación final debe devolverse rápidamente, pero puede tardar varios minutos en algunos casos.

El asociado también obtiene una notificación de webhook cuando la acción está lista para completarse correctamente en el marketplace comercial. Solo debe el publicador realizar el cambio del plan en el lado del publicador.

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 no se suscrito.
Un 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, no se proporcionó o se proporcionó con permisos insuficientes. Asegúrese de proporcionar un token de autorización válido.

Este error suele ser un síntoma de no realizar correctamente el registro de SaaS de .

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

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

Nota

El plan o la cantidad de puestos se pueden cambiar al mismo tiempo, no ambos.

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

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

Use esta API para actualizar (aumentar o disminuir) la cantidad de puestos adquiridos para una suscripción de SaaS. El publicador debe llamar a esta API cuando se cambie el número de puestos del lado del publicador 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 publicador debe cambiar el plan antes de cambiar la cantidad de puestos.

`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>` de revisión

parámetros de consulta de :

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 de Marketplace comercial mediante resolve API.

encabezados de solicitud de :

Parámetro	Valor
`content-type`	`application/json`
`x-ms-requestid`	Valor de cadena único para realizar el seguimiento de la solicitud desde el 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 correlaciona todos los eventos de la operación de cliente con eventos en el lado 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 publicador que realiza esta llamada API. El formato se `"Bearer <access_token>"` cuando el publicador recupera el valor del token, como se explica en Obtener un token basado en la aplicación Microsoft Entra.

Ejemplo de carga de solicitud de :

{
  "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 asociado sondee la dirección URL de Operation-Location para determinar si la solicitud de cantidad de cambios se ha realizado correctamente o no. El sondeo debe realizarse cada varios segundos hasta que se reciba el estado final de Error, Correctoo Conflicto para la operación. El estado final de la operación debe devolverse rápidamente, pero puede tardar varios minutos en algunos casos.

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

encabezados de respuesta :

Parámetro	Valor
`Operation-Location`	Vincule 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 cantidad actual.
El estado de la suscripción de SaaS no está suscrito.
Un 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, no se proporcionó o se proporcionó con permisos insuficientes. Asegúrese de proporcionar un token de autorización válido.

Este error suele ser un síntoma de no realizar correctamente el registro de SaaS de .

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

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

Nota

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

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

Cancelar una suscripción

Use esta API para cancelar la suscripción de SaaS especificada. El publicador no tiene que usar esta API y se recomienda que los clientes se dirijan al marketplace comercial para cancelar las suscripciones de SaaS.

Si el publicador decide implementar la cancelación de una suscripción de SaaS comprada en el marketplace comercial en el lado del publicador, debe llamar a esta API. Después de completar esta llamada, el estado de la suscripción se convierte en cancelada 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.

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

parámetros de consulta de :

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 de Marketplace comercial mediante resolve API.

encabezados de solicitud de :

Parámetro	Valor
`content-type`	`application/json`
`x-ms-requestid`	Valor de cadena único para realizar el seguimiento de la solicitud desde el 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 correlaciona todos los eventos de la operación de cliente con eventos en el lado 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 publicador que realiza esta llamada API. El formato se `"Bearer <access_token>"` cuando el publicador recupera el valor del token, como se explica en Obtener 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 asociado sondee la dirección URL de Operation-Location para determinar si esta solicitud se ha realizado correctamente o no. El sondeo debe realizarse cada varios segundos hasta que se reciba el estado final de Error, Correctoo Conflicto para la operación. El estado final de la operación debe devolverse rápidamente, pero puede tardar varios minutos en algunos casos.

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

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

encabezados de respuesta :

Parámetro	Valor
`Operation-Location`	Vincule 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 eliminación no está en allowedCustomerOperations lista para esta suscripción de SaaS.

Código: 403 Prohibido. El token de autorización no es válido, no se proporcionó o se proporcionó con permisos insuficientes. Asegúrese de proporcionar un token de autorización válido.

Este error suele ser un síntoma de no realizar correctamente el registro de SaaS de .

Código: 404 No encontrado. No se encuentra la suscripción de SaaS con 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 soporte técnico de Microsoft.

Para obtener más opciones para las ofertas de SaaS en el marketplace comercial, consulte las API del servicio de medición de marketplace comercial
Revise y use los clientes de para diferentes lenguajes de programación y ejemplos
Para obtener instrucciones de prueba, consulte Implementación de un webhook en el servicio SaaS

Compartir a través de

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

Resolución de una suscripción comprada

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

Activación de una suscripción

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

Obtener una lista de todas las suscripciones

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

Obtener suscripción

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

Enumerar los planes disponibles

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

Cambiar el plan de la suscripción

`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>` de revisión

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

`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>` de revisión

Cancelar una suscripción

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

Comentarios

Recursos adicionales

Compartir a través de

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

Resolución de una suscripción comprada

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

Activación de una suscripción

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

Obtener una lista de todas las suscripciones

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

Obtener suscripción

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

Enumerar los planes disponibles

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

Cambiar el plan de la suscripción

https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion> de revisión

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

https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion> de revisión

Cancelar una suscripción

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

Contenido relacionado

Comentarios

Recursos adicionales

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

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

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

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

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

`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>` de revisión

`https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>` de revisión

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