Rozhraní API předplatného plnění SaaS v2 na komerčním marketplace Microsoftu

Článek
01/31/2025

Tento článek popisuje verzi 2 rozhraní API předplatného plnění SaaS.

Poznámka

Abyste mohli volat rozhraní API předplatného plnění SaaS, musíte vytvořit autorizační token vydavatele pomocí správného ID prostředku. Zjistěte, jak získat autorizační token vydavatele

Řešení potíží s zakoupeným předplatným

Koncový bod řešení umožňuje vydavateli vyměnit prodejní identifikační token z komerčního marketplace (označovaný jako token v Zakoupeno, ale ještě neaktivovaný) na trvalé zakoupené ID předplatného SaaS a jeho podrobnosti.

Když se zákazník přesměruje na adresu URL cílové stránky partnera, předá se identifikační token zákazníka jako parametr tokenu v tomto volání adresy URL. Očekává se, že partner tento token použije a požádá o jeho vyřešení. Odpověď rozhraní RESOLVE API obsahuje ID předplatného SaaS a další podrobnosti k jedinečné identifikaci nákupu. Token poskytnutý voláním adresy URL cílové stránky je platný po dobu 24 hodin. Pokud vypršela platnost tokenu, který obdržíte, doporučujeme koncovému uživateli poskytnout následující pokyny:

"Tento nákup se nám nepodařilo identifikovat. Znovu otevřete toto předplatné SaaS na webu Azure Portal nebo v Centru pro správu Microsoftu 365 a znovu vyberte Konfigurovat účet nebo Spravovat účet.

Volání rozhraní API pro řešení vrátí podrobnosti o předplatném a stav pro předplatná SaaS ve všech podporovaných stavech.

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

parametry dotazu :

Parametr	Hodnota
`ApiVersion`	Použijte 31. 8. 2018.

hlavičky požadavku :

Parametr	Hodnota
`content-type`	`application/json`
`x-ms-requestid`	Jedinečná řetězcová hodnota pro sledování požadavku od klienta, nejlépe identifikátor GUID. Pokud tato hodnota není zadaná, vygeneruje se a zadává se v hlavičce odpovědi.
`x-ms-correlationid`	Jedinečná řetězcová hodnota pro operaci v klientovi. Tento parametr koreluje všechny události z operace klienta s událostmi na straně serveru. Pokud tuto hodnotu nezadáte, vygeneruje se a zadává se v hlavičce odpovědi.
`authorization`	Jedinečný přístupový token, který identifikuje vydavatele, který provádí toto volání rozhraní API. Formát se `"Bearer <access_token>"` při načtení hodnoty tokenu vydavatelem, jak je vysvětleno v Získání tokenu na základě aplikace Microsoft Entra.
`x-ms-marketplace-token`	Identifikátor nákupu tokenu parametr k vyřešení. Token se předá při volání adresy URL cílové stránky, když se zákazník přesměruje na web partnera SaaS (například: `https://contoso.com/signup?token=<token><authorization_token>`). Hodnota tokenu , kódovaná, je součástí adresy URL cílové stránky, takže musí být dekódována před tím, než se použije jako parametr v tomto volání rozhraní API. Tady je příklad zakódovaného řetězce v adrese URL: `contoso.com/signup?token=ab%2Bcd%2Fef`, kde token je `ab%2Bcd%2Fef`. Stejný dekódovaný token je: `Ab+cd/ef`

kódy odpovědí :

Kód: 200 Vrátí jedinečné identifikátory předplatného SaaS na základě zadaného x-ms-marketplace-token.

Příklad textu odpovědi:

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

Kód: 400 Chybný požadavek. x-ms-marketplace-token chybí, je poškozený, neplatný nebo vypršela platnost.

Kód: 401 Neautorizováno. Autorizační token je neplatný nebo vypršela jeho platnost. Žádost se pokouší o přístup k předplatnému SaaS pro nabídku, která byla publikována s jiným ID aplikace Microsoft Entra, než které se použilo k vytvoření ověřovacího tokenu.

Kód: 403 Zakázáno. Autorizační token je neplatný, nebyl poskytnut nebo byl poskytnut s nedostatečnými oprávněními. Nezapomeňte zadat platný autorizační token.

Tato chyba je často příznakem, že správně neprovádí registraci SaaS.

Kód: 500 Vnitřní chyba serveru. Zopakujte volání rozhraní API. Pokud chyba přetrvává, obraťte se na podporu Microsoftu.

Aktivace předplatného

Po nakonfigurování účtu SaaS pro koncového uživatele musí vydavatel volat rozhraní API pro aktivaci předplatného na straně Microsoftu. Zákazník se neúčtuje, pokud toto volání rozhraní API není úspěšné.

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

parametry dotazu :

Parametr	Hodnota
`ApiVersion`	Použijte 31. 8. 2018.
`subscriptionId`	Jedinečný identifikátor zakoupeného předplatného SaaS. Toto ID se získá po překladu autorizačního tokenu komerčního marketplace pomocí rozhraní Resolve API.

hlavičky požadavku :

Parametr	Hodnota
`content-type`	`application/json`
`x-ms-requestid`	Jedinečná řetězcová hodnota pro sledování požadavku od klienta, nejlépe identifikátor GUID. Pokud tato hodnota není zadaná, vygeneruje se a zadává se v hlavičce odpovědi.
`x-ms-correlationid`	Jedinečná řetězcová hodnota pro operaci v klientovi. Tento řetězec koreluje všechny události z operace klienta s událostmi na straně serveru. Pokud tato hodnota není zadaná, vygeneruje se a zadává se v hlavičce odpovědi.
`authorization`	Jedinečný přístupový token, který identifikuje vydavatele, který provádí toto volání rozhraní API. Formát se `"Bearer <access_token>"` při načtení hodnoty tokenu vydavatelem, jak je vysvětleno v Získání tokenu na základě aplikace Microsoft Entra.

kódy odpovědí :

Kód: 200 Žádost o aktualizaci předplatného a označení jako "Přihlášení k odběru" se přijímá. Nezávislí výrobci softwaru (ISV) můžou zkontrolovat stav předplatného po několika minutách (přečtěte si informace o operaci Get a zkontrolujte stav předplatného). Tím získáte konečnou odpověď, jestli se předplatné úspěšně aktualizovalo. Při přihlášení k odběru se automaticky odešle webhook "Odhlásit odběr".

Pro toto volání neexistuje žádný text odpovědi.

Kód: 400 Chybný požadavek: Ověření se nezdařilo.

Předplatné SaaS je ve stavu Pozastaveno.

Kód: 403 Zakázáno. Autorizační token je neplatný, nebyl poskytnut nebo byl poskytnut s nedostatečnými oprávněními. Nezapomeňte zadat platný autorizační token.

Tato chyba je často příznakem, že správně neprovádí registraci SaaS.

Kód: 404 Nenalezena. Předplatné SaaS je ve stavu odhlášené.

Kód: 500 Vnitřní chyba serveru. Zopakujte volání rozhraní API. Pokud chyba přetrvává, obraťte se na podporu Microsoftu.

Získání seznamu všech předplatných

Toto rozhraní API načte seznam všech zakoupených předplatných SaaS pro všechny nabídky, které vydavatel publikuje na komerčním marketplace. Vrátí se předplatná SaaS ve všech možných stavech. Odhlášené odběry předplatných SaaS se také vrátí, protože tyto informace se neodstraní na straně Microsoftu.

Rozhraní API vrátí stránkované výsledky. Pokud chcete získat další výsledky, musíte předat pokračováníToken.

Získání `https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>`

parametry dotazu :

Parametr	Hodnota
`ApiVersion`	Použijte 31. 8. 2018.
`continuationToken`	Volitelný parametr. Pokud chcete načíst první stránku výsledků, nechte prázdné. K načtení další stránky použijte hodnotu vrácenou v `@nextLink` parametru.

hlavičky požadavku :

Parametr	Hodnota
`content-type`	`application/json`
`x-ms-requestid`	Jedinečná řetězcová hodnota pro sledování požadavku od klienta, nejlépe identifikátor GUID. Pokud tato hodnota není zadaná, vygeneruje se a zadává se v hlavičce odpovědi.
`x-ms-correlationid`	Jedinečná řetězcová hodnota pro operaci v klientovi. Tento parametr koreluje všechny události z operace klienta s událostmi na straně serveru. Pokud tato hodnota není zadaná, vygeneruje se a zadává se v hlavičce odpovědi.
`authorization`	Jedinečný přístupový token, který identifikuje vydavatele, který provádí toto volání rozhraní API. Formát se `"Bearer <access_token>"` při načtení hodnoty tokenu vydavatelem, jak je vysvětleno v Získání tokenu na základě aplikace Microsoft Entra.

kódy odpovědí :

Kód: 200 Vrátí seznam všech existujících předplatných pro všechny nabídky provedené tímto vydavatelem na základě autorizačního tokenu vydavatele.

Příklad textu odpovědi :

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

Pokud pro tohoto vydavatele nejsou nalezena žádná zakoupená předplatná SaaS, vrátí se prázdný text odpovědi.

Kód: 403 Zakázáno. Autorizační token je neplatný, nebyl poskytnut nebo byl poskytnut s nedostatečnými oprávněními. Nezapomeňte zadat platný autorizační token.

Tato chyba je často příznakem, že správně neprovádí registraci SaaS.

Kód: 500 Vnitřní chyba serveru. Zopakujte volání rozhraní API. Pokud chyba přetrvává, obraťte se na podporu Microsoftu.

Získání předplatného

Toto rozhraní API načte zadané zakoupené předplatné SaaS pro nabídku SaaS, kterou vydavatel publikuje na komerčním marketplace. Toto volání slouží k získání všech dostupných informací pro konkrétní předplatné SaaS podle ID, nikoli voláním rozhraní API, které se používá k získání seznamu všech předplatných.

Získání `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

parametry dotazu :

Parametr	Hodnota
`ApiVersion`	Použijte 31. 8. 2018.
`subscriptionId`	Jedinečný identifikátor zakoupeného předplatného SaaS. Toto ID se získá po překladu autorizačního tokenu komerčního marketplace pomocí rozhraní API pro překlad.

hlavičky požadavku :

Parametr	Hodnota
`content-type`	`application/json`
`x-ms-requestid`	Jedinečná řetězcová hodnota pro sledování požadavku od klienta, nejlépe identifikátor GUID. Pokud tato hodnota není zadaná, vygeneruje se a zadává se v hlavičce odpovědi.
`x-ms-correlationid`	Jedinečná řetězcová hodnota pro operaci v klientovi. Tento parametr koreluje všechny události z operace klienta s událostmi na straně serveru. Pokud tato hodnota není zadaná, vygeneruje se a zadává se v hlavičce odpovědi.
`authorization`	Jedinečný přístupový token, který identifikuje vydavatele, který provádí toto volání rozhraní API. Formát se `"Bearer <access_token>"` při načtení hodnoty tokenu vydavatelem, jak je vysvětleno v Získání tokenu na základě aplikace Microsoft Entra.

kódy odpovědí :

Kód: 200 Vrátí podrobnosti o předplatném SaaS na základě zadaného subscriptionId.

Příklad textu odpovědi :

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

Kód: 403 Zakázáno. Autorizační token je neplatný, nebyl poskytnut nebo byl poskytnut s nedostatečnými oprávněními. Nezapomeňte zadat platný autorizační token.

Tato chyba je často příznakem, že správně neprovádí registraci SaaS.

Kód: 404 Nenalezena. Předplatné SaaS se zadaným subscriptionId nelze najít.

Kód: 500 Vnitřní chyba serveru. Zopakujte volání rozhraní API. Pokud chyba přetrvává, obraťte se na podporu Microsoftu.

Seznam dostupných plánů

Toto rozhraní API načte všechny plány nabídky SaaS identifikované subscriptionId konkrétního nákupu této nabídky. Pomocí tohoto volání získáte seznam všech soukromých a veřejných plánů, které může příjemce předplatného SaaS aktualizovat pro toto předplatné. Vrácené plány jsou k dispozici ve stejné zeměpisné oblasti jako již zakoupený plán.

Toto volání vrátí seznam plánů, které jsou pro daného zákazníka k dispozici kromě už zakoupeného plánu. Seznam lze zobrazit koncovému uživateli na webu vydavatele. Koncový uživatel může plán předplatného změnit na libovolný z plánů ve vráceném seznamu. Změna plánu na plán, který není v seznamu, nefunguje.

Toto rozhraní API také načte aktivní ID privátní nabídky přidružené (pokud voláte rozhraní API s filtrem planId). Volání rozhraní API s filtrem planId zobrazuje identifikátory GUID ID aktivní privátní nabídky v těle odpovědi v uzlu sourceOffers. ID plánu předané v parametru filtru by se mělo shodovat s ID plánu zakoupeného zákazníkem.

Získání `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>`

parametry dotazu :

Parametr	Hodnota
`ApiVersion`	Použijte 31. 8. 2018.
`subscriptionId`	Jedinečný identifikátor zakoupeného předplatného SaaS. Toto ID se získá po překladu autorizačního tokenu komerčního marketplace pomocí rozhraní API pro překlad.
`planId (Optional)`	ID plánu konkrétního plánu, který chcete načíst. Tato možnost je nepovinná a pokud se ignoruje, vrátí všechny plány.

hlavičky požadavku :

Parametr	Hodnota
`content-type`	`application/json`
`x-ms-requestid`	Jedinečná řetězcová hodnota pro sledování požadavku od klienta, nejlépe identifikátor GUID. Pokud tato hodnota není zadaná, vygeneruje se a zadává se v hlavičce odpovědi.
`x-ms-correlationid`	Jedinečná řetězcová hodnota pro operaci v klientovi. Tento parametr koreluje všechny události z operace klienta s událostmi na straně serveru. Pokud tato hodnota není zadaná, vygeneruje se a zadává se v hlavičce odpovědi.
`authorization`	Jedinečný přístupový token, který identifikuje vydavatele, který provádí toto volání rozhraní API. Formát se `"Bearer <access_token>"` při načtení hodnoty tokenu vydavatelem, jak je vysvětleno v Získání tokenu na základě aplikace Microsoft Entra.

kódy odpovědí :

Kód: 200 Vrátí seznam všech dostupných plánů pro stávající předplatné SaaS, včetně už zakoupeného předplatného.

Předání neplatného (volitelného) id plánu vrátí prázdný seznam plánů.

Příklad textu odpovědi:

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

Kód: 404 Nenalezena. subscriptionId nebyl nalezen.

Kód: 403 Zakázáno. Autorizační token je neplatný, nebyl poskytnut nebo byl poskytnut s nedostatečnými oprávněními. Nezapomeňte zadat platný autorizační token.

Tato chyba je často příznakem, že správně neprovádí registraci SaaS.

Kód: 500 Vnitřní chyba serveru. Zopakujte volání rozhraní API. Pokud chyba přetrvává, obraťte se na podporu Microsoftu.

Změna plánu předplatného

Toto rozhraní API slouží k aktualizaci stávajícího plánu zakoupeného pro předplatné SaaS na nový plán (veřejný nebo soukromý). Vydavatel musí toto rozhraní API volat, když se plán změní na straně vydavatele předplatného SaaS zakoupeného na komerčním marketplace.

Toto rozhraní API lze volat pouze pro předplatná Active. Jakýkoliv plán lze změnit na jakýkoli jiný existující plán (veřejný nebo soukromý), ale ne na sebe. V případě privátních plánů musí být tenant zákazníka definován jako součást cílové skupiny plánu v Partnerském centru.

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

parametry dotazu :

Parametr	Hodnota
`ApiVersion`	Použijte 31. 8. 2018.
`subscriptionId`	Jedinečný identifikátor zakoupeného předplatného SaaS. Toto ID se získá po překladu autorizačního tokenu komerčního marketplace pomocí rozhraní API pro překlad.

hlavičky požadavku :

Parametr	Hodnota
`content-type`	`application/json`
`x-ms-requestid`	Jedinečná řetězcová hodnota pro sledování požadavku od klienta, nejlépe identifikátor GUID. Pokud tato hodnota není zadaná, vygeneruje se a zadává se v hlavičce odpovědi.
`x-ms-correlationid`	Jedinečná řetězcová hodnota pro operaci v klientovi. Tento parametr koreluje všechny události z operace klienta s událostmi na straně serveru. Pokud tato hodnota není zadaná, vygeneruje se a zadává se v hlavičce odpovědi.
`authorization`	Jedinečný přístupový token, který identifikuje vydavatele, který provádí toto volání rozhraní API. Formát se `"Bearer <access_token>"` při načtení hodnoty tokenu vydavatelem, jak je vysvětleno v Získání tokenu na základě aplikace Microsoft Entra.

Příklad datové části požadavku :

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

kódy odpovědí :

Kód: 202 Požadavek na změnu plánu byl přijat a zpracován asynchronně. Očekává se, že se partner dotazuje na adresu URL Operation-Location, aby určil úspěch nebo selhání žádosti o plán změn. Dotazování by se mělo provádět každých několik sekund, dokud se pro operaci neobdrží konečný stav neúspěšných, Úspěšnénebo konfliktní. Konečný stav operace by se měl rychle vrátit, ale v některých případech může trvat několik minut.

Partner dostane také oznámení webhooku, když je akce připravená k úspěšnému dokončení na straně komerčního marketplace. Teprve potom by měl vydavatel provést změnu plánu na straně vydavatele.

hlavičky odpovědi :

Parametr	Hodnota
`Operation-Location`	Adresa URL pro získání stavu operace Například `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`

Kód: 400 Chybný požadavek: selhání ověření.

Požadovaný plán nelze najít nebo pro uživatele není k dispozici.
Požadovaný plán je stejný jako předplacený plán.
Stav předplatného SaaS není přihlášení k odběru.
Aktualizované předplatné SaaS zakoupil poskytovatel cloudových řešení (CSP). Chcete-li provést tuto akci, musíte s poskytovatelem CSP pracovat.

Kód: 403 Zakázáno. Autorizační token je neplatný, nebyl poskytnut nebo byl poskytnut s nedostatečnými oprávněními. Nezapomeňte zadat platný autorizační token.

Tato chyba je často příznakem, že správně neprovádí registraci SaaS.

Kód: 404 Nenalezena. Předplatné SaaS se zadaným subscriptionId nelze najít.

Kód: 500 Vnitřní chyba serveru. Zopakujte volání rozhraní API. Pokud chyba přetrvává, obraťte se na podporu Microsoftu.

Poznámka

Plán nebo množství licencí je možné změnit najednou, nikoli obojí.

Toto rozhraní API se dá volat až po získání explicitního schválení změny od koncového uživatele.

Změna počtu licencí v předplatném SaaS

Pomocí tohoto rozhraní API můžete aktualizovat (zvýšit nebo snížit) množství licencí zakoupených pro předplatné SaaS. Vydavatel musí toto rozhraní API volat, když se počet licencí změní ze strany vydavatele pro předplatné SaaS vytvořené na komerčním marketplace.

Množství licencí nemůže být vyšší než množství povolené v aktuálním plánu. V takovém případě by měl vydavatel změnit plán před změnou počtu licencí.

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

parametry dotazu :

Parametr	Hodnota
`ApiVersion`	Použijte 31. 8. 2018.
`subscriptionId`	Jedinečný identifikátor zakoupeného předplatného SaaS. Toto ID se získá po překladu autorizačního tokenu komerčního marketplace pomocí rozhraní API pro překlad.

hlavičky požadavku :

Parametr	Hodnota
`content-type`	`application/json`
`x-ms-requestid`	Jedinečná řetězcová hodnota pro sledování požadavku od klienta, nejlépe identifikátor GUID. Pokud tato hodnota není zadaná, vygeneruje se a zadává se v hlavičce odpovědi.
`x-ms-correlationid`	Jedinečná řetězcová hodnota pro operaci v klientovi. Tento parametr koreluje všechny události z operace klienta s událostmi na straně serveru. Pokud tato hodnota není zadaná, vygeneruje se a zadává se v hlavičce odpovědi.
`authorization`	Jedinečný přístupový token, který identifikuje vydavatele, který provádí toto volání rozhraní API. Formát se `"Bearer <access_token>"` při načtení hodnoty tokenu vydavatelem, jak je vysvětleno v Získání tokenu na základě aplikace Microsoft Entra.

Příklad datové části požadavku :

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

kódy odpovědí :

Kód: 202 Požadavek na změnu množství byl přijat a zpracován asynchronně. Očekává se, že se partner dotazuje na adresu URL Operation-Location, aby určil úspěch nebo selhání žádosti o množství změn. Dotazování by se mělo provádět každých několik sekund, dokud se pro operaci neobdrží konečný stav neúspěšných, Úspěšnénebo konfliktní. Konečný stav operace by se měl rychle vrátit, ale v některých případech může trvat několik minut.

Partner dostane také oznámení webhooku, když je akce připravená k úspěšnému dokončení na straně komerčního marketplace. Teprve potom by měl vydavatel provést změnu množství na straně vydavatele.

hlavičky odpovědi :

Parametr	Hodnota
`Operation-Location`	Propojením s prostředkem získáte stav operace. Například `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`.

Kód: 400 Chybný požadavek: selhání ověření.

Nové množství není v povoleném rozsahu.
Nové množství chybí nebo 0.
Nové množství je stejné jako aktuální množství.
Stav předplatného SaaS není přihlášený k odběru.
Aktualizované předplatné SaaS zakoupil poskytovatel cloudových řešení (CSP). Chcete-li provést tuto akci, musíte s poskytovatelem CSP pracovat.

Kód: 403 Zakázáno. Autorizační token je neplatný, nebyl poskytnut nebo byl poskytnut s nedostatečnými oprávněními. Nezapomeňte zadat platný autorizační token.

Tato chyba je často příznakem, že správně neprovádí registraci SaaS.

Kód: 404 Nenalezena. Předplatné SaaS se zadaným subscriptionId nelze najít.

Kód: 500 Vnitřní chyba serveru. Zopakujte volání rozhraní API. Pokud chyba přetrvává, obraťte se na podporu Microsoftu.

Poznámka

Najednou se dá změnit jenom plán nebo množství, ne obojí.

Toto rozhraní API lze volat až po získání explicitního schválení koncového uživatele pro změnu.

Zrušení předplatného

Toto rozhraní API slouží k odhlášení odběru zadaného předplatného SaaS. Vydavatel nemusí používat toto rozhraní API a doporučujeme, aby zákazníci byli přesměrováni na komerční marketplace, aby zrušili předplatná SaaS.

Pokud se vydavatel rozhodne implementovat zrušení předplatného SaaS zakoupeného na komerčním marketplace na straně vydavatele, musí toto rozhraní API volat. Po dokončení tohoto hovoru se stav předplatného změní na Odhlásit odběr na straně Microsoftu.

Zákazník se neúčtuje, pokud se předplatné zruší do 72 hodin od nákupu.

Zákazník se fakturuje, pokud se předplatné zruší po předchozím období odkladu. Zákazník okamžitě po zrušení ztratí přístup k předplatnému SaaS na straně Microsoftu.

Odstranění `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

parametry dotazu :

Parametr	Hodnota
`ApiVersion`	Použijte 31. 8. 2018.
`subscriptionId`	Jedinečný identifikátor zakoupeného předplatného SaaS. Toto ID se získá po překladu autorizačního tokenu komerčního marketplace pomocí rozhraní API pro překlad.

hlavičky požadavku :

Parametr	Hodnota
`content-type`	`application/json`
`x-ms-requestid`	Jedinečná řetězcová hodnota pro sledování požadavku od klienta, nejlépe identifikátor GUID. Pokud tato hodnota není zadaná, vygeneruje se a zadává se v hlavičce odpovědi.
`x-ms-correlationid`	Jedinečná řetězcová hodnota pro operaci v klientovi. Tento parametr koreluje všechny události z operace klienta s událostmi na straně serveru. Pokud tato hodnota není zadaná, vygeneruje se a zadává se v hlavičce odpovědi.
`authorization`	Jedinečný přístupový token, který identifikuje vydavatele, který provádí toto volání rozhraní API. Formát se `"Bearer <access_token>"` při načtení hodnoty tokenu vydavatelem, jak je vysvětleno v Získání tokenu na základě aplikace Microsoft Entra.

kódy odpovědí :

Kód: 202 Žádost o odhlášení odběru byla přijata a zpracována asynchronně. Očekává se, že se partner dotazuje na adresu URL Operation-Location, aby určil úspěch nebo selhání tohoto požadavku. Dotazování by se mělo provádět každých několik sekund, dokud se pro operaci neobdrží konečný stav neúspěšných, Úspěšnénebo konfliktní. Konečný stav operace by se měl rychle vrátit, ale v některých případech může trvat několik minut.

Partner dostane také oznámení webhooku, když se akce úspěšně dokončí na straně komerčního marketplace. Teprve potom by vydavatel měl předplatné zrušit na straně vydavatele.

Kód: 200 Předplatné je již ve stavu Odhlášení odběru.

hlavičky odpovědi :

Parametr	Hodnota
`Operation-Location`	Propojením s prostředkem získáte stav operace. Například `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31`.

Kód: 400 Chybný požadavek. Odstranění není v seznamu allowedCustomerOperations pro toto předplatné SaaS.

Kód: 403 Zakázáno. Autorizační token je neplatný, nebyl poskytnut nebo byl poskytnut s nedostatečnými oprávněními. Nezapomeňte zadat platný autorizační token.

Tato chyba je často příznakem, že správně neprovádí registraci SaaS.

Kód: 404 Nenalezena. Předplatné SaaS s subscriptionId se nenašlo.

Kód: 409

Odstranění nelze dokončit, protože předplatné je uzamčené kvůli čekajícími operacím.

Kód: 500 Vnitřní chyba serveru. Zopakujte volání rozhraní API. Pokud chyba přetrvává, obraťte se na podporu Microsoftu.

Další možnosti nabídek SaaS na komerčním marketplace najdete v rozhraní API služby měření komerčního marketplace
Kontrola a použití klientů pro různé programovací jazyky a ukázky
Pokyny k testování najdete v tématu Implementace webhooku ve službě SaaS

Sdílet prostřednictvím

Rozhraní API předplatného plnění SaaS v2 na komerčním marketplace Microsoftu

Řešení potíží s zakoupeným předplatným

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

Aktivace předplatného

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

Získání seznamu všech předplatných

Získání `https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>`

Získání předplatného

Získání `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Seznam dostupných plánů

Získání `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>`

Změna plánu předplatného

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

Změna počtu licencí v předplatném SaaS

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

Zrušení předplatného

Odstranění `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Váš názor

Další materiály

Sdílet prostřednictvím

Rozhraní API předplatného plnění SaaS v2 na komerčním marketplace Microsoftu

Řešení potíží s zakoupeným předplatným

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

Aktivace předplatného

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

Získání seznamu všech předplatných

Získání https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>

Získání předplatného

Získání https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Seznam dostupných plánů

Získání https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>

Změna plánu předplatného

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

Změna počtu licencí v předplatném SaaS

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

Zrušení předplatného

Odstranění https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>

Související obsah

Váš názor

Další materiály

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

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

Získání `https://marketplaceapi.microsoft.com/api/saas/subscriptions?api-version=<ApiVersion>`

Získání `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`

Získání `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/listAvailablePlans?api-version=<ApiVersion>&planId=<planId>`

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

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

Odstranění `https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>?api-version=<ApiVersion>`