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

Article
06/14/2024

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

Remarque

Pour pouvoir appeler des API d’abonnement de traitement SaaS, vous devez créer le jeton d’autorisation d’un éditeur à l’aide de l’ID de ressource approprié. Découvrez comment obtenir le jeton d’autorisation de l’éditeur

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 vérifier l’état de l’abonnement après quelques minutes (lecture sur l’opération Get pour vérifier l’é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 .

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

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 plan demandé est introuvable ou le plan n’est pas disponible pour l’utilisateur.
Le plan demandé est identique au plan abonné.
L’état de l’abonnement SaaS n’est pas Subscribed.
L’abonnement SaaS mis à jour est acheté par un fournisseur de solutions Cloud (CSP). Vous devez travailler avec le fournisseur CSP pour effectuer cette action.

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

Code : 404 Introuvable. L’abonnement SaaS avec le serveur spécifié 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.

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é n’est pas comprise dans la plage autorisée.
La nouvelle quantité est manquante ou 0.
La nouvelle quantité est identique à la quantité actuelle.
L’état de l’abonnement SaaS n’est pas Abonné.
L’abonnement SaaS mis à jour est acheté par un fournisseur de solutions Cloud (CSP). Vous devez travailler avec le fournisseur CSP pour effectuer cette action.

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

Code : 404 Introuvable. L’abonnement SaaS avec le serveur spécifié 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.

Pour plus d’options pour les offres SaaS sur la place de marché commerciale, consultez les API de service de contrôle de la Place de marché commerciale
Passer en revue et utiliser les clients pour différents langages et exemples de programmation
Pour obtenir des conseils sur les tests, consultez Implémentation d’un webhook sur le service SaaS

Partager via

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

Résoudre un abonnement acheté

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

Activer un abonnement

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

Obtenir la liste de tous les abonnements

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

Obtenir un abonnement

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

Liste des plans disponibles

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

Modifier le plan de l’abonnement

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

Modifier la quantité de postes de l’abonnement SaaS

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

Annuler un abonnement

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

Commentaires

Ressources supplémentaires

Partager via

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

Résoudre un abonnement acheté

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

Activer un abonnement

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

Obtenir la liste de tous les abonnements

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

Obtenir un abonnement

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

Liste des plans disponibles

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

Modifier le plan de l’abonnement

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

Modifier la quantité de postes de l’abonnement SaaS

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

Annuler un abonnement

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

Contenu connexe

Commentaires

Ressources supplémentaires

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

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

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

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

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

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

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

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