Partager via

API d’abonnement à l’exécution SaaS v2 sur la place de marché commerciale Microsoft

Cet article décrit la version 2 des API d’abonnement d’exécution SaaS.

Remarque

Pour pouvoir appeler les API d’abonnement d’exécution SaaS, vous devez créer un jeton d’autorisation d’éditeur à l’aide de l’ID de ressource correct. 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é jeton dans Acheté, mais pas encore activé) contre un ID d’abonnement SaaS acheté persistant et ses détails.

Lorsqu’un client est redirigé vers l’URL de la page de destination du partenaire, le jeton d’identification du client est transmis en tant que paramètre de jeton dans cet appel d’URL. Le partenaire est censé utiliser ce jeton et faire une demande pour le résoudre. La réponse de l’API Resolve contient l’ID de l’abonnement SaaS et d’autres détails permettant d’identifier de manière unique l’achat. Le jeton fourni avec l’appel d’URL de la page de destination est valable 24 heures. Si le jeton que vous recevez a expiré, nous vous recommandons de fournir les conseils suivants à l’utilisateur final :

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

L’appel de l’API Resolve renvoie les détails et l’état de l’abonnement SaaS dans tous les statuts pris en charge.

Publier 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 requête HTTP :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la demande 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 met en corrélation tous les événements de l’opération cliente 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 qui effectue cet appel d’API. Le format est "Bearer <access_token>" lorsque 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 de jeton d’identification d’achat à résoudre. Le jeton est transmis dans l’appel d’URL de la page de destination 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 de destination, 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 : Ab+cd/ef.

Codes de réponse :

Code : 200 Renvoie des identifiants d’abonnement SaaS uniques en fonction de ce qui x-ms-marketplace-token est fourni.

Exemple de contenu de la 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 Mauvaise demande. x-ms-marketplace-token est manquant, difforme, invalide ou expiré.

Code : 401 Non autorisé. Le jeton d’autorisation n’est pas valide ou a expiré. 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’authentification.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, n’a pas été fourni ou a été fourni avec des autorisations insuffisantes. Veillez à fournir un jeton d’autorisation valide.

Cette erreur est souvent le symptôme d’un défaut d’effectuer correctement l’enregistrement SaaS .

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

Activer un abonnement

Une fois le compte SaaS configuré pour un utilisateur final, l’éditeur doit appeler l’API Activate Subscription du côté de Microsoft. Le client n’est pas facturé tant que cet appel d’API n’est pas réussi.

Publier 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 L’identifiant unique de l’abonnement SaaS acheté. Cet ID est obtenu après la résolution du jeton d’autorisation de la place de marché commerciale à l’aide de l’API Resolve.

En-têtes de requête HTTP :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la demande 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 met en corrélation tous les événements de l’opération client avec les événements du 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 qui effectue cet appel d’API. Le format est "Bearer <access_token>" lorsque 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 La demande de mise à jour de l’abonnement et du marquage comme « Abonné » est reçue. Les éditeurs de logiciels indépendants (ISV) peuvent vérifier l’état de l’abonnement après quelques minutes (lisez la suite pour l’opération Obtenir pour vérifier l’état de l’abonnement). Cela vous donne la réponse définitive si l’abonnement a été mis à jour avec succès. L’échec de l’abonnement envoie automatiquement un webhook « Se désabonner ».

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

Code : 400 Mauvaise requête : échec de la validation.

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

Code : 401 Non autorisé. Le jeton d’autorisation n’est pas valide ou a expiré. 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’authentification.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, n’a pas été fourni ou a été fourni avec des autorisations insuffisantes. Veillez à fournir un jeton d’autorisation valide.

Cette erreur est souvent le symptôme d’un défaut d’effectuer correctement l’enregistrement SaaS .

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

Code : erreur de serveur interne 500. Réessayez l’appel d’API. Si l’erreur persiste, contactez le support 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 que l’éditeur publie sur la place de marché commerciale. Les abonnements SaaS dans tous les statuts possibles sont renvoyés. Les abonnements SaaS désabonnés sont également renvoyés, car ces informations ne sont pas supprimées du côté de Microsoft.

L’API renvoie des résultats paginés, vous devez passer le continuationToken pour obtenir les résultats suivants.

Avoir 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 renvoyée dans @nextLink le paramètre pour récupérer la page suivante.

En-têtes de requête HTTP :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la demande 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 met en corrélation tous les événements de l’opération cliente 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 qui effectue cet appel d’API. Le format est "Bearer <access_token>" lorsque 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 Renvoie la liste de tous les abonnements existants pour toutes les offres proposé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, le corps de la réponse vide est renvoyé.

Code : 401 Non autorisé. Le jeton d’autorisation n’est pas valide ou a expiré. 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’authentification.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, n’a pas été fourni ou a été fourni avec des autorisations insuffisantes. Veillez à fournir un jeton d’autorisation valide.

Cette erreur est souvent le symptôme d’un défaut d’effectuer correctement l’enregistrement SaaS .

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

Obtenir un abonnement

Cette API récupère un abonnement SaaS acheté spécifié pour une offre SaaS que l’éditeur publie sur la place de marché commerciale. Utilisez cet appel pour obtenir toutes les informations disponibles pour un abonnement SaaS spécifique par son ID plutôt qu’en appelant l’API utilisée pour obtenir une liste de tous les abonnements.

Avoir 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 L’identifiant unique de l’abonnement SaaS acheté. Cet ID est obtenu après la résolution du jeton d’autorisation de la place de marché commerciale à l’aide de l’API Resolve.

En-têtes de requête HTTP :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la demande 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 met en corrélation tous les événements de l’opération cliente 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 qui effectue cet appel d’API. Le format est "Bearer <access_token>" lorsque 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 Renvoie les détails d’un abonnement SaaS en fonction des subscriptionId données fournies.

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 : 401 Non autorisé. Le jeton d’autorisation n’est pas valide ou a expiré. 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’authentification.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, n’a pas été fourni ou a été fourni avec des autorisations insuffisantes. Veillez à fournir un jeton d’autorisation valide.

Cette erreur est souvent le symptôme d’un défaut d’effectuer correctement l’enregistrement SaaS .

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

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

Énumérer les forfaits disponibles

Cette API récupère tous les plans d’une offre SaaS identifiés par le subscriptionId d’un achat spécifique de cette offre. Utilisez cet appel pour obtenir la 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 de plans disponibles pour ce client en plus de celui déjà acheté. La liste peut être présentée à un utilisateur final sur le site de l’éditeur. Un utilisateur final peut remplacer le plan d’abonnement par l’un des plans de la liste renvoyée. Changer le plan pour un plan qui ne figure pas dans la liste ne fonctionne pas.

Cette API récupère également l’ID d’offre privée active associé (si vous appelez l’API avec le filtre planId). L’appel de l’API 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 transmis dans le paramètre de filtre doit correspondre au planId que le client a acheté.

Avoir 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 L’identifiant unique de l’abonnement SaaS acheté. Cet ID est obtenu après la résolution du jeton d’autorisation de la place de marché commerciale à l’aide de l’API Resolve.
planId (Optional) ID de plan d’un plan spécifique que vous souhaitez récupérer. Ceci est facultatif et s’il est ignoré, renvoie tous les plans.

En-têtes de requête HTTP :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la demande 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 met en corrélation tous les événements de l’opération cliente 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 qui effectue cet appel d’API. Le format est "Bearer <access_token>" lorsque 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 Renvoie une liste de tous les plans disponibles pour un abonnement SaaS existant, y compris celui déjà acheté.

Le passage d’un planId non valide (facultatif) renvoie une liste vide de plans.

Exemple de contenu de la 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 n’est pas trouvé.

Code : 401 Non autorisé. Le jeton d’autorisation n’est pas valide ou a expiré. 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’authentification.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, n’a pas été fourni ou a été fourni avec des autorisations insuffisantes. Veillez à fournir un jeton d’autorisation valide.

Cette erreur est souvent le symptôme d’un défaut d’effectuer correctement l’enregistrement SaaS .

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

Modifier le plan de l’abonnement

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

Cette API ne peut être appelée que pour les abonnements actifs . Tout plan peut être remplacé par n’importe quel 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 comme faisant partie de l’audience du plan dans l’Espace partenaires.

Rapiécer 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 L’identifiant unique de l’abonnement SaaS acheté. Cet ID est obtenu après la résolution du jeton d’autorisation de la place de marché commerciale à l’aide de l’API Resolve.

En-têtes de requête HTTP :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la demande 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 met en corrélation tous les événements de l’opération cliente 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 qui effectue cet appel d’API. Le format est "Bearer <access_token>" lorsque 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 charge utile de demande :

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

Codes de réponse :

Code : 202 La demande de changement de forfait a été acceptée et traitée de manière asynchrone. Le partenaire doit interroger l’URL de laOperation-Location pour déterminer la réussite ou l’échec de la demande de plan de modification. L’interrogation doit être effectuée toutes les quelques secondes jusqu’à ce que l’état final Échec, Réussite ou Conflit soit reçu pour l’opération. L’état final de l’opération doit être renvoyé 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 menée à bien du côté de la place de marché commerciale. Ce n’est qu’à ce moment-là que l’éditeur doit effectuer le changement de plan du côté de l’é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 Requête incorrecte : échecs de validation.

  • Le plan demandé est introuvable ou le plan n’est pas disponible pour l’utilisateur.
  • Le plan demandé est le même que le plan souscrit.
  • L’état de l’abonnement SaaS n’est pas Abonné.
  • L’abonnement SaaS en cours de mise à jour est acheté par un fournisseur de solutions cloud (CSP). Vous devez travailler avec le fournisseur CSP pour effectuer cette action.

Code : 401 Non autorisé. Le jeton d’autorisation n’est pas valide ou a expiré. 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’authentification.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, n’a pas été fourni ou a été fourni avec des autorisations insuffisantes. Veillez à fournir un jeton d’autorisation valide.

Cette erreur est souvent le symptôme d’un défaut d’effectuer correctement l’enregistrement SaaS .

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

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

Remarque

Le plan ou le nombre de sièges peuvent être modifiés en une seule fois, mais pas les deux.

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

Modifier le nombre de postes sur l’abonnement SaaS

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

Le nombre de places ne peut pas être supérieur au nombre autorisé dans le plan actuel. Dans ce cas, l’éditeur doit modifier le plan avant de modifier le nombre de sièges.

Rapiécer 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 Un identifiant unique de l’abonnement SaaS acheté. Cet ID est obtenu après la résolution du jeton d’autorisation de la place de marché commerciale à l’aide de l’API Resolve.

En-têtes de requête HTTP :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la demande 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 met en corrélation tous les événements de l’opération cliente 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 qui effectue cet appel d’API. Le format est "Bearer <access_token>" lorsque 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 charge utile de demande :

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

Codes de réponse :

Code : 202 La demande de modification de quantité a été acceptée et traitée de manière asynchrone. Le partenaire est censé interroger l’URLOperation-Location pour déterminer la réussite ou l’échec de la demande de modification de quantité. L’interrogation doit être effectuée toutes les quelques secondes jusqu’à ce que l’état final Échec, Réussite ou Conflit soit reçu pour l’opération. L’état final de l’opération doit être renvoyé 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 menée à bien du côté de la place de marché commerciale. Ce n’est qu’à ce moment-là que l’éditeur doit effectuer la modification de la quantité du côté de l’éditeur.

En-têtes de réponse :

Paramètre Valeur
Operation-Location Lien vers une ressource 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 Requête incorrecte : échecs de validation.

  • La nouvelle quantité n’est pas dans la plage autorisée.
  • La nouvelle quantité est manquante ou 0.
  • La nouvelle quantité est la même que la quantité actuelle.
  • Le statut de l’abonnement SaaS n’est pas Abonné.
  • L’abonnement SaaS en cours de mise à jour est acheté par un fournisseur de solutions cloud (CSP). Vous devez travailler avec le fournisseur CSP pour effectuer cette action.

Code : 401 Non autorisé. Le jeton d’autorisation n’est pas valide ou a expiré. 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’authentification.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, n’a pas été fourni ou a été fourni avec des autorisations insuffisantes. Veillez à fournir un jeton d’autorisation valide.

Cette erreur est souvent le symptôme d’un défaut d’effectuer correctement l’enregistrement SaaS .

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

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

Remarque

Seul un plan ou une quantité peut être modifié en une seule fois, pas les deux.

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

Annuler un abonnement

Utilisez cette API pour désabonner un abonnement SaaS spécifié. L’éditeur n’a pas besoin d’utiliser cette API et nous recommandons aux clients d’être redirigés vers la place de marché commerciale pour annuler leurs abonnements SaaS.

Si l’éditeur décide de mettre en œuvre l’annulation d’un abonnement SaaS acheté sur la place de marché commerciale du côté de l’éditeur, il doit appeler cette API. Une fois cet appel terminé, l’état de l’abonnement devient Désabonné du côté Microsoft.

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

Le client est facturé si un abonnement est résilié après le délai de grâce précédent. Le client perd l’accès à l’abonnement SaaS du côté de Microsoft immédiatement après l’annulation.

Supprimer 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 L’identifiant unique de l’abonnement SaaS acheté. Cet ID est obtenu après la résolution du jeton d’autorisation de la place de marché commerciale à l’aide de l’API Resolve.

En-têtes de requête HTTP :

Paramètre Valeur
content-type application/json
x-ms-requestid Valeur de chaîne unique pour le suivi de la demande 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 met en corrélation tous les événements de l’opération cliente 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 qui effectue cet appel d’API. Le format est "Bearer <access_token>" lorsque 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ésabonnement a été acceptée et traitée de manière asynchrone. Le partenaire est censé interroger l’URLOperation-Location pour déterminer la réussite ou l’échec de cette demande. L’interrogation doit être effectuée toutes les quelques secondes jusqu’à ce que l’état final Échec, Réussite ou Conflit soit reçu pour l’opération. L’état final de l’opération doit être renvoyé rapidement, mais peut prendre plusieurs minutes dans certains cas.

Le partenaire reçoit également une notification de webhook lorsque l’action est menée à bien du côté de la place de marché commerciale. Ce n’est qu’à ce moment-là que l’éditeur doit annuler l’abonnement du côté de l’éditeur.

Code : 200 L’abonnement est déjà à l’état Désabonné.

En-têtes de réponse :

Paramètre Valeur
Operation-Location Lien vers une ressource 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 Mauvaise demande. La suppression n’est pas dans la allowedCustomerOperations liste de cet abonnement SaaS.

Code : 401 Non autorisé. Le jeton d’autorisation n’est pas valide ou a expiré. 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’authentification.

Code : 403 Interdit. Le jeton d’autorisation n’est pas valide, n’a pas été fourni ou a été fourni avec des autorisations insuffisantes. Veillez à fournir un jeton d’autorisation valide.

Cette erreur est souvent le symptôme d’un défaut d’effectuer correctement l’enregistrement SaaS .

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. Réessayez l’appel d’API. Si l’erreur persiste, contactez le support Microsoft.

Contenu connexe