Compartir a través de

API de operaciones de suministro de SaaS v2 en el marketplace comercial de Microsoft

  • Artículo

Nota

Para poder llamar a las API de operaciones 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

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

Las operaciones son útiles para responder a las solicitudes que se producen a través del webhook como parte de las acciones ChangePlan, ChangeQuantity y Restablecer. Esto proporciona la oportunidad de aceptar o rechazar una solicitud mediante la revisión de esa operación de webhook con éxito o error mediante las API siguientes.

Esto solo se aplica a eventos de webhook como ChangePlan, ChangeQuantity y Restablecimiento que necesitan una ACK. No se necesita ninguna acción del proveedor de software independiente (ISV) en los eventos Renew, Suspend y Unsubscribe porque son eventos de solo notificación.

Enumerar las operaciones pendientes

Obtenga la lista de las operaciones pendientes para la suscripción de SaaS especificada. El publicador debe confirmar las operaciones devueltas llamando a la API de revisión de operaciones de .

Obtener https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations?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 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 operaciones pendientes en la suscripción de SaaS especificada.

ejemplo de carga de respuesta de :

{
  "operations": [
    {
      "id": "<guid>", //Operation ID, should be provided in the operations patch API call
      "activityId": "<guid>", //not relevant
      "subscriptionId": "<guid>", // subscriptionId of the SaaS subscription that is being reinstated
      "offerId": "offer1", // purchased offer ID
      "publisherId": "contoso",
      "planId": "silver", // purchased plan ID
      "quantity": 20, // purchased amount of seats, will be empty is not relevant
      "action": "Reinstate",
      "timeStamp": "2018-12-01T00:00:00", // UTC
      "status": "InProgress" // the only status that can be returned in this case
    }
  ]
}

Devuelve json vacío si no hay ninguna operación pendiente.

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

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: 404 No encontrado. No se encuentra la suscripción de SaaS con subscriptionId.

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.

Obtención del estado de la operación

Esta API permite al publicador realizar un seguimiento del estado de la operación asincrónica especificada: Cancelar suscripción, ChangePlano ChangeQuantity.

El operationId de esta llamada API se puede recuperar del valor devuelto por Operation-Location, la llamada a la API get pending Operations o el valor del parámetro <id> recibido en una llamada de webhook.

Obtener https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?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.
operationId Identificador único de la operación que se va a recuperar.

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 Obtiene detalles de la operación SaaS especificada.

ejemplo de carga de respuesta de :

Response body:
{
  "id  ": "<guid>", //Operation ID, should be provided in the patch operation API call
  "activityId": "<guid>", //not relevant
  "subscriptionId": "<guid>", // subscriptionId of the SaaS subscription for which this operation is relevant
  "offerId": "offer1", // purchased offer ID
  "publisherId": "contoso",
  "planId": "silver", // purchased plan ID
  "quantity": 20, // purchased amount of seats
  "action": "ChangePlan", // Can be ChangePlan, ChangeQuantity or Reinstate
  "timeStamp": "2018-12-01T00:00:00", // UTC
  "status": "InProgress", // Possible values: NotStarted, InProgress, Failed, Succeeded, Conflict (new quantity / plan is the same as existing)
  "errorStatusCode": "",
  "errorMessage": ""
}

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: 404 No encontrado.

  • No se encuentra la suscripción con subscriptionId.
  • No se encuentra la operación con operationId.

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.

Actualización del estado de una operación

Use esta API para actualizar el estado de una operación pendiente para indicar el éxito o error de la operación en el lado del publicador.

El operationId de esta llamada API se puede recuperar del valor devuelto por Operation-Location, la llamada a la API get pending Operations o el valor del parámetro <id> recibido en una llamada de webhook.

https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?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.
operationId Identificador único de la operación que se está completando.

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 :

{
  "status": "Success" // Allowed Values: Success/Failure. Indicates the status of the operation on ISV side.
}

códigos de respuesta :

Código: 200 Una llamada para informar de la finalización de una operación en el lado del asociado. Por ejemplo, esta respuesta podría indicar la finalización del cambio de puestos o planes en el lado del publicador.

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: 404 No encontrado.

  • No se encuentra la suscripción con subscriptionId.
  • No se encuentra la operación con operationId.

Código: 409 Conflicto. Por ejemplo, ya se ha completado una actualización más reciente.

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.

Contenido relacionado