Compartir a través de

SaaS Fulfillment Operations API 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 SaaS Fulfillment Operations API.

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 siguientes API.

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.

Lista de operaciones pendientes

Obtiene una lista de las operaciones pendientes para la suscripción de SaaS especificada. El editor debe confirmar las operaciones devueltas mediante una llamada a la API Operation Patch.

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

Ejemplo de carga de respuesta:

{
  "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 operaciones pendientes.

Código: 400 Solicitud incorrecta: errores de validació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 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.

Obtener el estado de la operación

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

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

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

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

Ejemplo de carga de respuesta:

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: 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 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 el servicio de soporte técnico de Microsoft.

Actualizar el estado de una operación

Use esta API para actualizar el estado de una operación pendiente para indicar si se ha realizado correctamente en el lado del editor.

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

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

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:

{
  "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 la finalización del cambio de puestos o planes en el lado del editor.

Código: 403

  • Prohibido. El token de autorización no está disponible, no es válido o ha expirado. Es posible que la solicitud intente acceder a una suscripción que no pertenezca al publicador actual.
  • 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 con subscriptionId .
  • No se encuentra la operación con operationId .

Código: 409 Conflicto. Por ejemplo, ya se suministra 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 el servicio de soporte técnico de Microsoft.

Contenido relacionado