Api:er för SaaS-uppfyllandeprenumeration v2 på Microsofts kommersiella marknadsplats

Artikel
04/30/2024

I den här artikeln beskrivs version 2 av API:erna för SaaS-uppfyllandeprenumeration.

Lösa en köpt prenumeration

Med slutpunkten lös kan utgivaren byta ut inköpsidentifieringstoken från den kommersiella marknadsplatsen (kallas token i Köpt men ännu inte aktiverat) till ett beständigt köpt SaaS-prenumerations-ID och dess information.

När en kund omdirigeras till partnerns url för landningssidan skickas kundidentifieringstoken som tokenparameter i det här URL-anropet. Partnern förväntas använda den här token och göra en begäran för att lösa det. Svar på Lös API innehåller SaaS-prenumerations-ID och annan information för att unikt identifiera köpet. Token som tillhandahålls med url-anropet för landningssidan är giltig i 24 timmar. Om den token som du får har upphört att gälla rekommenderar vi att du ger följande vägledning till slutanvändaren:

"Det gick inte att identifiera det här köpet. Öppna den här SaaS-prenumerationen igen i Azure-portalen eller i Administrationscenter för Microsoft 365 och välj "Konfigurera konto" eller "Hantera konto" igen.

Om du anropar Resolve API returneras prenumerationsinformation och status för SaaS-prenumerationer i alla statusar som stöds.

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

Frågeparametrar:

Parameter	Värde
`ApiVersion`	Använd 2018-08-31.

Begärandehuvuden:

Parameter	Värde
`content-type`	`application/json`
`x-ms-requestid`	Ett unikt strängvärde för att spåra begäran från klienten, helst ett GUID. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
`x-ms-correlationid`	Ett unikt strängvärde för åtgärden på klienten. Den här parametern korrelerar alla händelser från klientåtgärden med händelser på serversidan. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena
`authorization`	En unik åtkomsttoken som identifierar utgivaren som gör det här API-anropet. Formatet är `"Bearer <access_token>"` när tokenvärdet hämtas av utgivaren enligt beskrivningen i Hämta en token baserat på Microsoft Entra-appen.
`x-ms-marketplace-token`	Parametern för inköpsidentifieringstoken som ska matchas. Token skickas i url-anropet för landningssidan när kunden omdirigeras till SaaS-partnerns webbplats (till exempel: `https://contoso.com/signup?token=<token><authorization_token>`). Tokenvärdet som kodas är en del av målsidans URL, så det måste avkodas innan det används som en parameter i det här API-anropet. Här är ett exempel på en kodad sträng i URL:en: `contoso.com/signup?token=ab%2Bcd%2Fef`, där token är `ab%2Bcd%2Fef`. Samma token avkodade är: `Ab+cd/ef`

Svarskoder:

Kod: 200 Returnerar unika SaaS-prenumerationsidentifierare baserat på angivna x-ms-marketplace-token .

Exempel på svarstext:

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

Kod: 400 Felaktig begäran. x-ms-marketplace-token saknas, är felaktigt, ogiltigt eller har upphört att gälla.

Kod: 403 Förbjudet. Auktoriseringstoken är ogiltig, har upphört att gälla eller har inte angetts. Begäran försöker komma åt en SaaS-prenumeration för ett erbjudande som publicerades med ett annat Microsoft Entra-app-ID än det som användes för att skapa auktoriseringstoken.

Det här felet är ofta ett symptom på att SaaS-registreringen inte utförs korrekt.

Kod: 500 Internt serverfel. Försök igen med API-anropet. Kontakta Microsofts support om felet kvarstår.

Aktivera en prenumeration

När SaaS-kontot har konfigurerats för en slutanvändare måste utgivaren anropa API:et Aktivera prenumeration på Microsoft-sidan. Kunden debiteras inte om inte det här API-anropet lyckas.

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

Frågeparametrar:

Parameter	Värde
`ApiVersion`	Använd 2018-08-31.
`subscriptionId`	Den unika identifieraren för den köpta SaaS-prenumerationen. Det här ID:t hämtas efter att du har löst auktoriseringstoken för den kommersiella marknadsplatsen med hjälp av Resolve API.

Begärandehuvuden:

Parameter	Värde
`content-type`	`application/json`
`x-ms-requestid`	Ett unikt strängvärde för att spåra begäran från klienten, helst ett GUID. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
`x-ms-correlationid`	Ett unikt strängvärde för åtgärden på klienten. Den här strängen korrelerar alla händelser från klientåtgärden med händelser på serversidan. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
`authorization`	En unik åtkomsttoken som identifierar utgivaren som gör det här API-anropet. Formatet är `"Bearer <access_token>"` när tokenvärdet hämtas av utgivaren enligt beskrivningen i Hämta en token baserat på Microsoft Entra-appen.

Svarskoder:

Kod: 200 Begäran om att uppdatera prenumerationen och markera som "Prenumererad" tas emot. Oberoende programvaruleverantörer (ISV:er) kan söka efter status för prenumerationen efter några minuter (läs vidare för get-åtgärden för att kontrollera prenumerationsstatusen). Detta ger dig det slutgiltiga svaret om prenumerationen har uppdaterats. Om det inte går att prenumerera skickar webhooken "Avbryt prenumeration".

Det finns ingen svarstext för det här anropet.

Kod: 400 Felaktig begäran: verifieringen misslyckades.

SaaS-prenumerationen är i inaktiverat tillstånd.

Det här felet är ofta ett symptom på att SaaS-registreringen inte utförs korrekt.

Kod: 404 Hittades inte. SaaS-prenumerationen är i tillståndet Avsluta prenumeration .

Kod: 500 Internt serverfel. Försök igen med API-anropet. Kontakta Microsofts support om felet kvarstår.

Hämta en lista över alla prenumerationer

Det här API:et hämtar en lista över alla köpta SaaS-prenumerationer för alla erbjudanden som utgivaren publicerar på den kommersiella marknadsplatsen. SaaS-prenumerationer i alla möjliga statusar returneras. SaaS-prenumerationer som inte har prenumerationer returneras också eftersom den här informationen inte tas bort på Microsoft-sidan.

API:et returnerar sidnumrerade resultat på 100 per sida.

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

Frågeparametrar:

Parameter	Värde
`ApiVersion`	Använd 2018-08-31.
`continuationToken`	Valfri parameter. Om du vill hämta den första sidan med resultat lämnar du tom. Använd värdet som returneras i `@nextLink` parametern för att hämta nästa sida.

Begärandehuvuden:

Parameter	Värde
`content-type`	`application/json`
`x-ms-requestid`	Ett unikt strängvärde för att spåra begäran från klienten, helst ett GUID. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
`x-ms-correlationid`	Ett unikt strängvärde för åtgärden på klienten. Den här parametern korrelerar alla händelser från klientåtgärden med händelser på serversidan. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
`authorization`	En unik åtkomsttoken som identifierar utgivaren som gör det här API-anropet. Formatet är `"Bearer <access_token>"` när tokenvärdet hämtas av utgivaren enligt beskrivningen i Hämta en token baserat på Microsoft Entra-appen.

Svarskoder:

Kod: 200 Returnerar listan över alla befintliga prenumerationer för alla erbjudanden som görs av den här utgivaren, baserat på utgivarens auktoriseringstoken.

Exempel på svarstext:

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

Om inga köpta SaaS-prenumerationer hittas för den här utgivaren returneras en tom svarstext.

Kod: 403 Förbjudet. Auktoriseringstoken är inte tillgänglig, ogiltig eller har upphört att gälla.

Det här felet är ofta ett symptom på att SaaS-registreringen inte utförs korrekt.

Kod: 500 Internt serverfel. Försök igen med API-anropet. Kontakta Microsofts support om felet kvarstår.

Hämta prenumeration

Det här API:et hämtar en angiven köpt SaaS-prenumeration för ett SaaS-erbjudande som utgivaren publicerar på den kommersiella marknadsplatsen. Använd det här anropet för att hämta all tillgänglig information för en specifik SaaS-prenumeration med sitt ID i stället för genom att anropa API:et som används för att hämta en lista över alla prenumerationer.

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

Frågeparametrar:

Parameter	Värde
`ApiVersion`	Använd 2018-08-31.
`subscriptionId`	Den unika identifieraren för den köpta SaaS-prenumerationen. Det här ID:t hämtas efter att du har löst auktoriseringstoken för den kommersiella marknadsplatsen med hjälp av Resolve API.

Begärandehuvuden:

Parameter	Värde
`content-type`	`application/json`
`x-ms-requestid`	Ett unikt strängvärde för att spåra begäran från klienten, helst ett GUID. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
`x-ms-correlationid`	Ett unikt strängvärde för åtgärden på klienten. Den här parametern korrelerar alla händelser från klientåtgärden med händelser på serversidan. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
`authorization`	En unik åtkomsttoken som identifierar utgivaren som gör det här API-anropet. Formatet är `"Bearer <access_token>"` när tokenvärdet hämtas av utgivaren enligt beskrivningen i Hämta en token baserat på Microsoft Entra-appen.

Svarskoder:

Kod: 200 Returnerar information för en SaaS-prenumeration baserat på angivet subscriptionId .

Exempel på svarstext:

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

Kod: 403 Förbjudet. Auktoriseringstoken är ogiltig, har upphört att gälla eller har inte angetts. Begäran försöker komma åt en SaaS-prenumeration för ett erbjudande som publiceras med ett annat Microsoft Entra-app-ID än det som användes för att skapa auktoriseringstoken.

Det här felet är ofta ett symptom på att SaaS-registreringen inte utförs korrekt.

Kod: 404 Hittades inte. Det går inte att hitta SaaS-prenumerationen med den angivna subscriptionId .

Kod: 500 Internt serverfel. Försök igen med API-anropet. Kontakta Microsofts support om felet kvarstår.

Lista tillgängliga planer

Det här API:et hämtar alla planer för ett SaaS-erbjudande som identifieras av subscriptionId ett specifikt köp av det här erbjudandet. Använd det här anropet för att hämta en lista över alla privata och offentliga planer som mottagaren av en SaaS-prenumeration kan uppdatera för prenumerationen. De returnerade planerna är tillgängliga i samma geografiska område som den redan köpta planen.

Det här anropet returnerar en lista över planer som är tillgängliga för kunden utöver den som redan har köpts. Listan kan visas för en slutanvändare på utgivarens webbplats. En slutanvändare kan ändra prenumerationsplanen till något av abonnemangen i den returnerade listan. Det fungerar inte att ändra planen till en plan som inte finns i listan.

Det här API:et hämtar också det aktiva privata erbjudande-ID som är associerat (om du anropar API:et med planId-filtret). Anrop av API med planId-filter visar aktiva privata erbjudande-ID-GUID i svarstexten under noden sourceOffers. PlanId som skickades i filterparamen ska matcha planId som kunden har köpt.

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

Frågeparametrar:

Parameter	Värde
`ApiVersion`	Använd 2018-08-31.
`subscriptionId`	Den unika identifieraren för den köpta SaaS-prenumerationen. Det här ID:t hämtas efter att du har löst auktoriseringstoken för den kommersiella marknadsplatsen med hjälp av Resolve API.
`planId (Optional)`	Planera ID för en specifik plan som du vill hämta. Detta är valfritt och om det ignoreras returneras alla planer.

Begärandehuvuden:

Parameter	Värde
`content-type`	`application/json`
`x-ms-requestid`	Ett unikt strängvärde för att spåra begäran från klienten, helst ett GUID. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
`x-ms-correlationid`	Ett unikt strängvärde för åtgärden på klienten. Den här parametern korrelerar alla händelser från klientåtgärden med händelser på serversidan. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
`authorization`	En unik åtkomsttoken som identifierar utgivaren som gör det här API-anropet. Formatet är `"Bearer <access_token>"` när tokenvärdet hämtas av utgivaren enligt beskrivningen i Hämta en token baserat på Microsoft Entra-appen.

Svarskoder:

Kod: 200 Returnerar en lista över alla tillgängliga planer för en befintlig SaaS-prenumeration, inklusive den som redan har köpts.

Om du skickar ogiltigt (valfritt) planId returneras en tom lista med planer.

Exempel på svarstext:

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

Kod: 404 hittades inte. subscriptionId hittades inte.

Kod: 403 Förbjudet. Auktoriseringstoken är ogiltig, har upphört att gälla eller har inte angetts. Begäran kan försöka få åtkomst till en SaaS-prenumeration för ett erbjudande som har avregistrerats eller publicerats med ett annat Microsoft Entra-app-ID än det som användes för att skapa auktoriseringstoken.

Det här felet är ofta ett symptom på att SaaS-registreringen inte utförs korrekt.

Kod: 500 Internt serverfel. Försök igen med API-anropet. Kontakta Microsofts support om felet kvarstår.

Ändra prenumerationens plan

Använd det här API:et för att uppdatera den befintliga planen som köpts för en SaaS-prenumeration till en ny plan (offentlig eller privat). Utgivaren måste anropa detta API när en plan ändras på utgivarsidan för en SaaS-prenumeration som köpts på den kommersiella marknadsplatsen.

Det här API:et kan bara anropas för aktiva prenumerationer. Alla planer kan ändras till någon annan befintlig plan (offentlig eller privat) men inte till sig själv. För privata planer måste kundens klientorganisation definieras som en del av planens målgrupp i Partnercenter.

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

Frågeparametrar:

Parameter	Värde
`ApiVersion`	Använd 2018-08-31.
`subscriptionId`	Den unika identifieraren för den köpta SaaS-prenumerationen. Det här ID:t hämtas efter att du har löst auktoriseringstoken för den kommersiella marknadsplatsen med hjälp av Resolve API.

Begärandehuvuden:

Parameter	Värde
`content-type`	`application/json`
`x-ms-requestid`	Ett unikt strängvärde för att spåra begäran från klienten, helst ett GUID. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
`x-ms-correlationid`	Ett unikt strängvärde för åtgärden på klienten. Den här parametern korrelerar alla händelser från klientåtgärden med händelser på serversidan. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
`authorization`	En unik åtkomsttoken som identifierar utgivaren som gör det här API-anropet. Formatet är `"Bearer <access_token>"` när tokenvärdet hämtas av utgivaren enligt beskrivningen i Hämta en token baserat på Microsoft Entra-appen.

Exempel på begärandenyttolast:

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

Svarskoder:

Kod: 202 Begäran om ändringsplan har godkänts och hanterats asynkront. Partnern förväntas avsöka URL:en för åtgärdsplats för att fastställa om ändringsplanens begäran lyckades eller misslyckades. Avsökningen bör utföras varannat sekund tills den slutliga statusen Misslyckades, Lyckades eller Konflikt har tagits emot för åtgärden. Slutlig åtgärdsstatus bör returneras snabbt, men kan ta flera minuter i vissa fall.

Partnern får också webhook-meddelande när åtgärden är klar att slutföras på den kommersiella marknadsplatssidan. Först då ska utgivaren göra en ändring av planen på utgivarsidan.

Svarshuvuden:

Parameter	Värde
`Operation-Location`	URL för att hämta åtgärdens status. Till exempel: `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`

Kod: 400 Felaktig begäran: verifieringsfel.

Den nya planen finns inte eller är inte tillgänglig för den här specifika SaaS-prenumerationen.
Den nya planen är densamma som den aktuella planen.
SaaS-prenumerationsstatusen prenumererar inte.
Uppdateringsåtgärden för en SaaS-prenumeration ingår inte i allowedCustomerOperations.

Kod: 403 Förbjudet. Auktoriseringstoken är ogiltig, har upphört att gälla eller har inte angetts. Begäran försöker komma åt en SaaS-prenumeration för ett erbjudande som publiceras med ett annat Microsoft Entra-app-ID än det som användes för att skapa auktoriseringstoken.

Det här felet är ofta ett symptom på att SaaS-registreringen inte utförs korrekt.

Kod: 404 Hittades inte. Det går inte att hitta SaaS-prenumerationen med subscriptionId .

Kod: 500 Internt serverfel. Försök igen med API-anropet. Kontakta Microsofts support om felet kvarstår.

Kommentar

Antingen planen eller antalet platser kan ändras samtidigt, inte båda.

Det här API:et kan bara anropas när du har fått uttryckligt godkännande för ändringen från slutanvändaren.

Ändra antalet platser i SaaS-prenumerationen

Använd det här API:et för att uppdatera (öka eller minska) antalet platser som köpts för en SaaS-prenumeration. Utgivaren måste anropa detta API när antalet platser ändras från utgivarsidan för en SaaS-prenumeration som skapats på den kommersiella marknadsplatsen.

Antalet platser får inte vara mer än den kvantitet som tillåts i den aktuella planen. I det här fallet bör utgivaren ändra planen innan antalet platser ändras.

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

Frågeparametrar:

Parameter	Värde
`ApiVersion`	Använd 2018-08-31.
`subscriptionId`	En unik identifierare för den köpta SaaS-prenumerationen. Det här ID:t hämtas efter att du har löst auktoriseringstoken för den kommersiella marknadsplatsen med hjälp av Resolve API.

Begärandehuvuden:

Parameter	Värde
`content-type`	`application/json`
`x-ms-requestid`	Ett unikt strängvärde för att spåra begäran från klienten, helst ett GUID. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
`x-ms-correlationid`	Ett unikt strängvärde för åtgärden på klienten. Den här parametern korrelerar alla händelser från klientåtgärden med händelser på serversidan. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
`authorization`	En unik åtkomsttoken som identifierar utgivaren som gör det här API-anropet. Formatet är `"Bearer <access_token>"` när tokenvärdet hämtas av utgivaren enligt beskrivningen i Hämta en token baserat på Microsoft Entra-appen.

Exempel på begärandenyttolast:

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

Svarskoder:

Kod: 202 Begäran om ändring av kvantitet har godkänts och hanterats asynkront. Partnern förväntas avsöka url:en för åtgärdsplatsen för att fastställa om begäran om ändringskvantitet lyckades eller misslyckades. Avsökningen bör utföras varannat sekund tills den slutliga statusen Misslyckades, Lyckades eller Konflikt har tagits emot för åtgärden. Den slutliga åtgärdsstatusen bör returneras snabbt men kan ta flera minuter i vissa fall.

Partnern får också webhook-meddelande när åtgärden är klar att slutföras på den kommersiella marknadsplatssidan. Först då ska utgivaren göra kvantitetsändringen på utgivarsidan.

Svarshuvuden:

Parameter	Värde
`Operation-Location`	Länka till en resurs för att hämta åtgärdens status. Exempel: `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`

Kod: 400 Felaktig begäran: verifieringsfel.

Den nya kvantiteten är större eller lägre än den aktuella plangränsen.
Den nya kvantiteten saknas.
Den nya kvantiteten är samma som den aktuella kvantiteten.
SaaS-prenumerationsstatusen är inte Prenumererad.
Uppdateringsåtgärden för en SaaS-prenumeration ingår inte i allowedCustomerOperations.

Kod: 403 Förbjudet. Auktoriseringstoken är ogiltig, har upphört att gälla eller har inte angetts. Begäran försöker komma åt en prenumeration som inte tillhör den aktuella utgivaren.

Det här felet är ofta ett symptom på att SaaS-registreringen inte utförs korrekt.

Kod: 404 Hittades inte. Det går inte att hitta SaaS-prenumerationen med subscriptionId .

Kod: 500 Internt serverfel. Försök igen med API-anropet. Kontakta Microsofts support om felet kvarstår.

Kommentar

Endast en plan eller kvantitet kan ändras samtidigt, inte båda.

Det här API:et kan bara anropas efter att slutanvändaren har fått uttryckligt godkännande för ändringen.

Avsluta en prenumeration

Använd det här API:et för att avbryta prenumerationen på en angiven SaaS-prenumeration. Utgivaren behöver inte använda det här API:et och vi rekommenderar att kunderna dirigeras till den kommersiella marknadsplatsen för att avbryta SaaS-prenumerationer.

Om utgivaren bestämmer sig för att genomföra annulleringen av en SaaS-prenumeration som köpts på den kommersiella marknadsplatsen på utgivarens sida måste de anropa detta API. När det här anropet har slutförts blir prenumerationens status avregistrerad på Microsoft-sidan.

Kunden debiteras inte om en prenumeration avbryts inom 72 timmar från köpet.

Kunden debiteras om en prenumeration avbryts efter föregående respitperiod. Kunden förlorar åtkomsten till SaaS-prenumerationen på Microsoft-sidan omedelbart efter annulleringen.

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

Frågeparametrar:

Parameter	Värde
`ApiVersion`	Använd 2018-08-31.
`subscriptionId`	Den unika identifieraren för den köpta SaaS-prenumerationen. Det här ID:t hämtas efter att du har löst auktoriseringstoken för den kommersiella marknadsplatsen med hjälp av Resolve API.

Begärandehuvuden:

Parameter	Värde
`content-type`	`application/json`
`x-ms-requestid`	Ett unikt strängvärde för att spåra begäran från klienten, helst ett GUID. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
`x-ms-correlationid`	Ett unikt strängvärde för åtgärden på klienten. Den här parametern korrelerar alla händelser från klientåtgärden med händelser på serversidan. Om det här värdet inte anges genereras ett värde och anges i svarshuvudena.
`authorization`	En unik åtkomsttoken som identifierar utgivaren som gör det här API-anropet. Formatet är `"Bearer <access_token>"` när tokenvärdet hämtas av utgivaren enligt beskrivningen i Hämta en token baserat på Microsoft Entra-appen.

Svarskoder:

Kod: 202 Begäran om att avbryta prenumerationen har godkänts och hanterats asynkront. Partnern förväntas avsöka URL:en för åtgärdsplats för att fastställa om begäran lyckades eller misslyckades. Avsökningen bör utföras varannat sekund tills den slutliga statusen Misslyckades, Lyckades eller Konflikt har tagits emot för åtgärden. Den slutliga åtgärdsstatusen bör returneras snabbt men kan ta flera minuter i vissa fall.

Partnern får också webhook-meddelande när åtgärden har slutförts på den kommersiella marknadsplatssidan. Först då ska utgivaren avbryta prenumerationen på utgivarsidan.

Kod: 200 Prenumerationen är redan i tillståndet Avsluta prenumeration.

Svarshuvuden:

Parameter	Värde
`Operation-Location`	Länka till en resurs för att hämta åtgärdens status. Exempel: `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`

Kod: 400 Felaktig begäran. Ta bort finns inte i allowedCustomerOperations listan för den här SaaS-prenumerationen.

Kod: 403 Förbjudet. Auktoriseringstoken är ogiltig, har upphört att gälla eller är inte tillgänglig.

Det här felet är ofta ett symptom på att SaaS-registreringen inte utförs korrekt.

Kod: 404 Hittades inte. Det går inte att hitta SaaS-prenumerationen med subscriptionId .

Kod: 409

Det går inte att slutföra borttagningen eftersom prenumerationen är låst på grund av väntande åtgärder.

Kod: 500 Internt serverfel. Försök igen med API-anropet. Kontakta Microsofts support om felet kvarstår.

Nästa steg

Fler alternativ för SaaS-erbjudanden på den kommersiella marknadsplatsen finns i API:erna för avläsningstjänsten för den kommersiella marknadsplatsen
Granska och använda klienterna för olika programmeringsspråk och exempel
Vägledning för testning finns i Implementera en webhook på SaaS-tjänsten

Api:er för SaaS-uppfyllandeprenumeration v2 på Microsofts kommersiella marknadsplats

Lösa en köpt prenumeration

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

Aktivera en prenumeration

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

Hämta en lista över alla prenumerationer

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

Hämta prenumeration

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

Lista tillgängliga planer

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

Ändra prenumerationens plan

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

Ändra antalet platser i SaaS-prenumerationen

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

Avsluta en prenumeration

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

Nästa steg

Feedback

Feedback

Ytterligare resurser

Api:er för SaaS-uppfyllandeprenumeration v2 på Microsofts kommersiella marknadsplats

Lösa en köpt prenumeration

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

Aktivera en prenumeration

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

Hämta en lista över alla prenumerationer

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

Hämta prenumeration

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

Lista tillgängliga planer

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

Ändra prenumerationens plan

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

Ändra antalet platser i SaaS-prenumerationen

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

Avsluta en prenumeration

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

Nästa steg

Feedback

Feedback

Ytterligare resurser

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

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

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

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

Få `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>`

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