API d’abonnement de traitement SaaS v2 sur la Place de marché commerciale Microsoft

  • Article

Cet article décrit la version 2 des API d’abonnement au traitement SaaS.

Résoudre un abonnement acheté

Le point de terminaison de résolution permet à l’éditeur d’échanger le jeton d’identification d’achat de la Place de marché commerciale (appelé token dans Acheté mais pas encore activé) contre un ID d’abonnement SaaS acheté de manière permanente et ses détails.

Lorsqu’un client est redirigé vers l’URL de la page d’arrivée du partenaire, le jeton d’identification du client est transmis comme paramètre token dans cet appel d’URL. Le partenaire doit utiliser ce jeton et effectuer une requête pour le résoudre. La réponse de l’API Résolution contient l’ID d’abonnement SaaS et d’autres détails permettant d’identifier l’achat de manière unique. Le jeton fourni avec l’appel d’URL de la page d’accueil est valide pendant 24 heures. Si le jeton que vous recevez a expiré, nous vous recommandons de fournir les instructions suivantes à l’utilisateur final :

« Nous n’avons pas pu identifier cet achat. Rouvrez cet abonnement SaaS dans le Portail Azure ou dans Centre d'administration Microsoft 365 Center, puis sélectionnez à nouveau « Configurer le compte » ou « Gérer le compte ».

L’appel de l’API Resolve retourne les détails de l’abonnement et l’état des abonnements SaaS dans tous les états pris en charge.

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

Paramètres de requête :

Paramètre Valeur
ApiVersion Utilisez 2018-08-31.

En-têtes de demande :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la requête du client, de préférence un GUID. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
x-ms-correlationid Valeur de chaîne unique pour l’opération sur le client. Ce paramètre sert à corréler tous les événements de l’opération client avec les événements côté serveur. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse
authorization Jeton d’accès unique qui identifie le serveur de publication qui effectue cet appel d’API. Le format est "Bearer <access_token>" le moment où la valeur du jeton est récupérée par l’éditeur, comme expliqué dans Obtenir un jeton basé sur l’application Microsoft Entra.
x-ms-marketplace-token Paramètre token d’identification d’achat de la Place de marché à résoudre. Le jeton est transmis dans l’appel de l’URL de la page d’arrivée lorsque le client est redirigé vers le site web du partenaire SaaS (par exemple : https://contoso.com/signup?token=<token><authorization_token>).

La valeur du jeton encodée fait partie de l’URL de la page d’accueil. Elle doit donc être décodée avant d’être utilisée comme paramètre dans cet appel d’API.

Voici un exemple de chaîne codée dans l’URL : contoso.com/signup?token=ab%2Bcd%2Fef, où token est ab%2Bcd%2Fef. Le même jeton décodé est le suivant : Ab+cd/ef

Codes de réponse :

Code : 200 Retourne des identificateurs d’abonnement SaaS uniques en fonction du x-ms-marketplace-token code fourni.

Exemple de corps de réponse :

{
  "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"
  }
}

Code : 400 Demande incorrecte. x-ms-marketplace-token est manquant, incorrect, non valide ou arrivé à expiration.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, a expiré ou n’a pas été fourni. La demande tente d’accéder à un abonnement SaaS pour une offre publiée avec un ID d’application Microsoft Entra différent de celui utilisé pour créer le jeton d’autorisation.

Cette erreur est souvent le symptôme de l’absence d’une inscription SaaS correcte.

Code : erreur de serveur interne 500. Renouvelez l’appel d’API. Si l’erreur persiste, contactez le support technique Microsoft.

Activer un abonnement

Une fois le compte SaaS configuré pour un utilisateur final, l’éditeur doit appeler l’API Activer l’abonnement côté Microsoft. Le client n’est pas facturé, sauf si cet appel d’API réussit.

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

Paramètres de requête :

Paramètre Valeur
ApiVersion Utilisez 2018-08-31.
subscriptionId Identificateur unique de l’abonnement SaaS acheté. Cet ID est obtenu après résolution du jeton d’autorisation de la Place de marché commerciale à l’aide de l’API Résolution.

En-têtes de demande :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la requête du client, de préférence un GUID. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
x-ms-correlationid Valeur de chaîne unique pour l’opération sur le client. Cette chaîne sert à corréler tous les événements de l’opération client avec les événements côté serveur. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
authorization Jeton d’accès unique qui identifie le serveur de publication qui effectue cet appel d’API. Le format est "Bearer <access_token>" le moment où la valeur du jeton est récupérée par l’éditeur, comme expliqué dans Obtenir un jeton basé sur l’application Microsoft Entra.

Codes de réponse :

Code : 200 Demande de mise à jour de l’abonnement et marque comme « Abonné » est reçue. Les éditeurs de logiciels indépendants (ISV) peuvent case activée pour l’état de l’abonnement après quelques minutes (lecture sur l’opération Get pour case activée’état de l’abonnement). Cela vous donne la réponse définitive si l’abonnement a été correctement mis à jour. L’échec de l’abonnement envoie automatiquement un webhook « Désabonnement ».

Il n’y a pas de corps de réponse pour cet appel.

Code : 400 Demande incorrecte : échec de la validation.

  • L’abonnement SaaS est à l’état suspendu .

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, a expiré ou n’a pas été fourni. La demande tente d’accéder à un abonnement SaaS pour une offre publiée avec un ID d’application Microsoft Entra différent de celui utilisé pour créer le jeton d’autorisation.

Cette erreur est souvent le symptôme de l’absence d’une inscription SaaS correcte.

Code : 404 Introuvable. L’abonnement SaaS est à l’état Unsubscribed.

Code : erreur de serveur interne 500. Renouvelez l’appel d’API. Si l’erreur persiste, contactez le support technique Microsoft.

Obtenir la liste de tous les abonnements

Cette API récupère une liste de tous les abonnements SaaS achetés pour toutes les offres publiées par l’éditeur sur la Place de marché commerciale. Les abonnements SaaS dans tous les états possibles sont retournés. Les abonnements SaaS annulés sont également retournés, car ces informations ne sont pas supprimées côté Microsoft.

L’API retourne des résultats paginés (100 par page).

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

Paramètres de requête :

Paramètre Valeur
ApiVersion Utilisez 2018-08-31.
continuationToken Paramètre facultatif. Pour récupérer la première page de résultats, laissez vide. Utilisez la valeur retournée dans le paramètre @nextLink pour récupérer la page suivante.

En-têtes de demande :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la requête du client, de préférence un GUID. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
x-ms-correlationid Valeur de chaîne unique pour l’opération sur le client. Ce paramètre sert à corréler tous les événements de l’opération client avec les événements côté serveur. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
authorization Jeton d’accès unique qui identifie l’éditeur effectuant cet appel d’API. Le format est "Bearer <access_token>" le moment où la valeur du jeton est récupérée par l’éditeur, comme expliqué dans Obtenir un jeton basé sur l’application Microsoft Entra.

Codes de réponse :

Code : 200 Retourne la liste de tous les abonnements existants pour toutes les offres effectuées par cet éditeur, en fonction du jeton d’autorisation de l’éditeur.

Exemple de corps de réponse :

{
  "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 aucun abonnement SaaS acheté n’est trouvé pour cet éditeur, un corps de réponse vide est retourné.

Code : 403 Interdit. Le jeton d'autorisation n'est pas disponible, n’est pas valide ou a expiré.

Cette erreur est souvent le symptôme de l’absence d’une inscription SaaS correcte.

Code : erreur de serveur interne 500. Renouvelez l’appel d’API. Si l’erreur persiste, contactez le support technique Microsoft.

Obtenir un abonnement

Cette API récupère un abonnement SaaS acheté spécifié pour une offre SaaS publiée par l’éditeur sur la Place de marché commerciale. Utilisez cet appel afin d’obtenir toutes les informations disponibles pour un abonnement SaaS spécifique par son ID, au lieu d’appeler l’API utilisée pour obtenir la liste de tous les abonnements.

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

Paramètres de requête :

Paramètre Valeur
ApiVersion Utilisez 2018-08-31.
subscriptionId Identificateur unique de l’abonnement SaaS acheté. Cet ID est obtenu après résolution du jeton d’autorisation de la Place de marché à l’aide de l’API Résolution.

En-têtes de demande :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la requête du client, de préférence un GUID. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
x-ms-correlationid Valeur de chaîne unique pour l’opération sur le client. Ce paramètre sert à corréler tous les événements de l’opération client avec les événements côté serveur. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
authorization Jeton d’accès unique qui identifie l’éditeur effectuant cet appel d’API. Le format est "Bearer <access_token>" le moment où la valeur du jeton est récupérée par l’éditeur, comme expliqué dans Obtenir un jeton basé sur l’application Microsoft Entra.

Codes de réponse :

Code : 200 Retourne les détails d’un abonnement SaaS en fonction de l’abonnement subscriptionId fourni.

Exemple de corps de réponse :

{
  "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.
  }
}

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, a expiré ou n’a pas été fourni. La demande tente d’accéder à un abonnement SaaS pour une offre publiée avec un ID d’application Microsoft Entra différent de celui utilisé pour créer le jeton d’autorisation.

Cette erreur est souvent le symptôme de l’absence d’une inscription SaaS correcte.

Code : 404 Introuvable. L’abonnement SaaS avec la valeur subscriptionId spécifiée est introuvable.

Code : erreur de serveur interne 500. Renouvelez l’appel d’API. Si l’erreur persiste, contactez le support technique Microsoft.

Liste des plans disponibles

Cette API récupère tous les plans pour une offre SaaS identifiée par la valeur subscriptionId d’un achat spécifique de cette offre. Utilisez cet appel pour obtenir une liste de tous les plans privés et publics que le bénéficiaire d’un abonnement SaaS peut mettre à jour pour l’abonnement. Les plans retournés sont disponibles dans la même zone géographique que le plan déjà acheté.

Cet appel renvoie une liste des plans disponibles pour ce client en plus de celui que vous avez déjà acheté. La liste peut être présentée à un utilisateur final sur le site de l’éditeur. Un utilisateur final peut modifier le plan d’abonnement au profit d’un des plans de la liste retournée. La modification du plan en plan non dans la liste ne fonctionne pas.

Cette API récupère également l’ID d’offre privée actif associé (si vous appelez l’API avec le filtre planId). L’API appelante avec le filtre planId affiche les GUID d’ID d’offre privée actifs dans le corps de la réponse sous le nœud sourceOffers. Le planId passé dans l’analyseur de filtre doit correspondre à l’id de plan acheté par le client.

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

Paramètres de requête :

Paramètre Valeur
ApiVersion Utilisez 2018-08-31.
subscriptionId Identificateur unique de l’abonnement SaaS acheté. Cet ID est obtenu après résolution du jeton d’autorisation de la Place de marché à l’aide de l’API Résolution.
planId (Optional) ID de plan d’un plan spécifique que vous souhaitez récupérer. Cette option est facultative et si elle est ignorée retourne tous les plans.

En-têtes de demande :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la requête du client, de préférence un GUID. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
x-ms-correlationid Valeur de chaîne unique pour l’opération sur le client. Ce paramètre sert à corréler tous les événements de l’opération client avec les événements côté serveur. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
authorization Jeton d’accès unique qui identifie l’éditeur effectuant cet appel d’API. Le format est "Bearer <access_token>" le moment où la valeur du jeton est récupérée par l’éditeur, comme expliqué dans Obtenir un jeton basé sur l’application Microsoft Entra.

Codes de réponse :

Code : 200 Retourne une liste de tous les plans disponibles pour un abonnement SaaS existant, y compris celui déjà acheté.

La transmission d’un planId non valide (facultatif) retourne la liste vide des plans.

Exemple de corps de réponse :

{
  "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.
        }
      ]
    }
  ]
}

Code : 404 Introuvable. subscriptionId est introuvable.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, a expiré ou n’a pas été fourni. La demande peut tenter d’accéder à un abonnement SaaS pour une offre qui est désinscription ou publiée avec un AUTRE ID d’application Microsoft Entra que celui utilisé pour créer le jeton d’autorisation.

Cette erreur est souvent le symptôme de l’absence d’une inscription SaaS correcte.

Code : erreur de serveur interne 500. Renouvelez l’appel d’API. Si l’erreur persiste, contactez le support technique Microsoft.

Modifier le plan de l’abonnement

Utilisez cette API pour mettre à jour le plan existant acheté pour un abonnement SaaS avec un nouveau plan (public ou privé). L’éditeur doit appeler cette API lorsqu’un plan est modifié côté éditeur pour un abonnement SaaS acheté sur la Place de marché commerciale.

Cette API peut être appelée uniquement pour des abonnements à l’état Active. Tout plan peut être remplacé par un autre plan existant (public ou privé), mais pas par lui-même. Pour les plans privés, le locataire du client doit être défini dans le cadre de l’audience du plan dans l’Espace partenaires.

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

Paramètres de requête :

Paramètre Valeur
ApiVersion Utilisez 2018-08-31.
subscriptionId Identificateur unique de l’abonnement SaaS acheté. Cet ID est obtenu après résolution du jeton d’autorisation de la Place de marché à l’aide de l’API Résolution.

En-têtes de demande :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la requête du client, de préférence un GUID. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
x-ms-correlationid Valeur de chaîne unique pour l’opération sur le client. Ce paramètre sert à corréler tous les événements de l’opération client avec les événements côté serveur. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
authorization Jeton d’accès unique qui identifie l’éditeur effectuant cet appel d’API. Le format est "Bearer <access_token>" le moment où la valeur du jeton est récupérée par l’éditeur, comme expliqué dans Obtenir un jeton basé sur l’application Microsoft Entra.

Exemple de demande de charge utile :

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

Codes de réponse :

Code : 202 La demande de modification du plan a été acceptée et gérée de manière asynchrone. Le partenaire doit interroger l’URL Operation-Location pour déterminer la réussite ou l’échec de la demande de changement de plan. L’interrogation doit être effectuée à intervalles réguliers (quelques secondes) jusqu’à ce que l’état final Failed, Succeed ou Conflict s’affiche pour l’opération. L’état final de l’opération doit être retourné rapidement, mais peut prendre plusieurs minutes dans certains cas.

Le partenaire reçoit également une notification de webhook lorsque l’action est prête à être effectuée avec succès côté place de marché commerciale. Ce n’est qu’après avoir reçu cette notification que l’éditeur devra modifier le plan côté éditeur.

En-têtes de réponse :

Paramètre Valeur
Operation-Location URL pour obtenir l’état de l’opération. Par exemple, https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31

Code : 400 Demande incorrecte : échecs de validation.

  • Le nouveau plan n’existe pas ou n’est pas disponible pour cet abonnement SaaS spécifique.
  • Le nouveau plan est identique au plan actuel.
  • L’état de l’abonnement SaaS n’est pas Subscribed.
  • L’opération de mise à jour pour un abonnement SaaS n’est pas incluse dans allowedCustomerOperations.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, a expiré ou n’a pas été fourni. La demande tente d’accéder à un abonnement SaaS pour une offre publiée avec un ID d’application Microsoft Entra différent de celui utilisé pour créer le jeton d’autorisation.

Cette erreur est souvent le symptôme de l’absence d’une inscription SaaS correcte.

Code : 404 Introuvable. L’abonnement SaaS avec subscriptionId est introuvable.

Code : erreur de serveur interne 500. Renouvelez l’appel d’API. Si l’erreur persiste, contactez le support technique Microsoft.

Remarque

Le plan ou la quantité de postes peut être modifié(e), mais pas simultanément.

Cette API peut être appelée uniquement après avoir obtenu l’approbation explicite de l’utilisateur final pour la modification.

Modifier la quantité de postes de l’abonnement SaaS

Utilisez cette API pour mettre à jour (augmenter ou diminuer) la quantité de postes achetés pour un abonnement SaaS. L’éditeur doit appeler cette API lorsque le nombre de postes est modifié côté éditeur pour un abonnement SaaS créé sur la Place de marché commerciale.

La quantité de sièges ne peut pas être supérieure à la quantité autorisée dans le plan actuel. Dans ce cas, l’éditeur doit changer le plan avant de modifier la quantité de postes.

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

Paramètres de requête :

Paramètre Valeur
ApiVersion Utilisez 2018-08-31.
subscriptionId Identificateur unique de l’abonnement SaaS acheté. Cet ID est obtenu après résolution du jeton d’autorisation de la Place de marché à l’aide de l’API Résolution.

En-têtes de demande :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la requête du client, de préférence un GUID. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
x-ms-correlationid Valeur de chaîne unique pour l’opération sur le client. Ce paramètre sert à corréler tous les événements de l’opération client avec les événements côté serveur. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
authorization Jeton d’accès unique qui identifie l’éditeur effectuant cet appel d’API. Le format est "Bearer <access_token>" le moment où la valeur du jeton est récupérée par l’éditeur, comme expliqué dans Obtenir un jeton basé sur l’application Microsoft Entra.

Exemple de demande de charge utile :

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

Codes de réponse :

Code : 202 La demande de modification de la quantité a été acceptée et gérée de manière asynchrone. Le partenaire doit interroger l’URL Operation-Location pour déterminer la réussite ou l’échec de la demande de changement de quantité. L’interrogation doit être effectuée à intervalles réguliers (quelques secondes) jusqu’à ce que l’état final Failed, Succeed ou Conflict s’affiche pour l’opération. L’état final de l’opération doit être retourné rapidement, mais peut prendre plusieurs minutes dans certains cas.

Le partenaire reçoit également une notification de webhook lorsque l’action est prête à être effectuée avec succès côté place de marché commerciale. Ce n’est qu’après avoir reçu cette notification que l’éditeur devra modifier la quantité côté éditeur.

En-têtes de réponse :

Paramètre Valeur
Operation-Location Lien vers une ressource pour obtenir le statut de l’opération. Par exemple : https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31.

Code : 400 Demande incorrecte : échecs de validation.

  • La nouvelle quantité est supérieure ou inférieure à la limite actuelle du plan.
  • La nouvelle quantité est manquante.
  • La nouvelle quantité est identique à la quantité actuelle.
  • L’état de l’abonnement SaaS n’est pas Abonné.
  • L’opération de mise à jour pour un abonnement SaaS n’est pas incluse dans allowedCustomerOperations.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, a expiré ou n’a pas été fourni. La demande tente d’accéder à un abonnement qui n’appartient pas à l’éditeur actuel.

Cette erreur est souvent le symptôme de l’absence d’une inscription SaaS correcte.

Code : 404 Introuvable. L’abonnement SaaS avec subscriptionId est introuvable.

Code : erreur de serveur interne 500. Renouvelez l’appel d’API. Si l’erreur persiste, contactez le support technique Microsoft.

Remarque

Un plan ou une quantité peut être modifié(e), mais pas les deux simultanément.

Cette API peut être appelée uniquement après avoir obtenu l’approbation explicite de l’utilisateur final pour la modification.

Annuler un abonnement

Utilisez cette API pour annuler un abonnement SaaS spécifié. L’éditeur n’a pas besoin d’utiliser cette API, et nous vous recommandons de diriger les clients vers la Place de marché commerciale afin d’annuler les abonnements SaaS.

Si l’éditeur décide d’implémenter l’annulation de l’abonnement SaaS acheté sur la Place de marché commerciale côté éditeur, il doit appeler cette API. Une fois cet appel terminé, l’état de l’abonnement devient Désinscription côté Microsoft.

Le client n’est pas facturé si un abonnement est annulé dans les 72 heures à partir de l’achat.

Le client est facturé si un abonnement est annulé après la période de grâce précédente. Le client perd l’accès à l’abonnement SaaS côté Microsoft immédiatement après l’annulation.

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

Paramètres de requête :

Paramètre Valeur
ApiVersion Utilisez 2018-08-31.
subscriptionId Identificateur unique de l’abonnement SaaS acheté. Cet ID est obtenu après résolution du jeton d’autorisation de la Place de marché à l’aide de l’API Résolution.

En-têtes de demande :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la requête du client, de préférence un GUID. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
x-ms-correlationid Valeur de chaîne unique pour l’opération sur le client. Ce paramètre sert à corréler tous les événements de l’opération client avec les événements côté serveur. Si cette valeur n’est pas fournie, une valeur est générée et fournie dans les en-têtes de réponse.
authorization Jeton d’accès unique qui identifie le serveur de publication qui effectue cet appel d’API. Le format est "Bearer <access_token>" le moment où la valeur du jeton est récupérée par l’éditeur, comme expliqué dans Obtenir un jeton basé sur l’application Microsoft Entra.

Codes de réponse :

Code : 202 La demande de désinscription a été acceptée et gérée de manière asynchrone. Le partenaire doit interroger l’URL Operation-Location pour déterminer la réussite ou l’échec de cette demande. L’interrogation doit être effectuée à intervalles réguliers (quelques secondes) jusqu’à ce que l’état final Failed, Succeed ou Conflict s’affiche pour l’opération. L’état final de l’opération doit être retourné rapidement, mais peut prendre plusieurs minutes dans certains cas.

Le partenaire reçoit également une notification de webhook lorsque l’action est effectuée avec succès côté place de marché commerciale. Ce n’est qu’après avoir reçu cette notification que l’éditeur devra annuler l’abonnement côté éditeur.

Code : 200 L’abonnement est déjà dans un état de désinscription.

En-têtes de réponse :

Paramètre Valeur
Operation-Location Lien vers une ressource pour obtenir le statut de l’opération. Par exemple : https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31.

Code : 400 Demande incorrecte. Le paramètre Delete ne fait pas partie de la liste allowedCustomerOperations pour cet abonnement SaaS.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, a expiré ou n’est pas disponible.

Cette erreur est souvent le symptôme de l’absence d’une inscription SaaS correcte.

Code : 404 Introuvable. L’abonnement SaaS avec subscriptionId est introuvable.

Code : 409

La suppression ne peut pas être terminée, car l’abonnement est verrouillé en raison d’opérations en attente.

Code : erreur de serveur interne 500. Renouvelez l’appel d’API. Si l’erreur persiste, contactez le support technique Microsoft.

Étapes suivantes