Share via

Interfejsy API subskrypcji realizacji SaaS w wersji 2 na komercyjnej platformie handlowej firmy Microsoft

  • Artykuł

W tym artykule opisano wersję 2 interfejsów API subskrypcji realizacji SaaS.

Rozwiązywanie problemu z kupioną subskrypcją

Punkt końcowy rozpoznawania umożliwia wydawcy wymianę tokenu identyfikacji zakupu z komercyjnej platformy handlowej (określanej jako token w zakupionej, ale jeszcze nieaktywnej) do trwałego zakupionego identyfikatora subskrypcji SaaS i jego szczegółów.

Gdy klient jest przekierowywany do adresu URL strony docelowej partnera, token identyfikacji klienta jest przekazywany jako parametr tokenu w tym wywołaniu adresu URL. Oczekuje się, że partner użyje tego tokenu i poprosi o jego rozwiązanie. Odpowiedź interfejsu API Rozpoznawanie zawiera identyfikator subskrypcji SaaS i inne szczegóły umożliwiające unikatowe zidentyfikowanie zakupu. Token dostarczony z wywołaniem adresu URL strony docelowej jest ważny przez 24 godziny. Jeśli otrzymany token wygasł, zalecamy udostępnienie użytkownikowi końcowemu następujących wskazówek:

"Nie można zidentyfikować tego zakupu. Otwórz ponownie tę subskrypcję SaaS w witrynie Azure Portal lub w centrum Administracja Microsoft 365 i ponownie wybierz pozycję "Konfiguruj konto" lub "Zarządzaj kontem".

Wywołanie interfejsu API Rozpoznawanie zwraca szczegóły subskrypcji i stan subskrypcji SaaS we wszystkich obsługiwanych stanach.

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

Parametry zapytania:

Parametr Wartość
ApiVersion Użyj 2018-08-31.

Nagłówki żądań:

Parametr Wartość
content-type application/json
x-ms-requestid Unikatowa wartość ciągu do śledzenia żądania od klienta, najlepiej identyfikator GUID. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
x-ms-correlationid Unikatowa wartość ciągu dla operacji na kliencie. Ten parametr koreluje wszystkie zdarzenia z operacji klienta ze zdarzeniami po stronie serwera. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi
authorization Unikatowy token dostępu identyfikujący wydawcę wykonującego to wywołanie interfejsu API. Format jest "Bearer <access_token>" taki, gdy wartość tokenu jest pobierana przez wydawcę, jak wyjaśniono w artykule Uzyskiwanie tokenu na podstawie aplikacji Microsoft Entra.
x-ms-marketplace-token Parametr tokenu identyfikacji zakupu do rozwiązania. Token jest przekazywany w wywołaniu adresu URL strony docelowej, gdy klient jest przekierowywany do witryny internetowej partnera SaaS (na przykład: https://contoso.com/signup?token=<token><authorization_token>).

Wartość tokenu kodowana jest częścią adresu URL strony docelowej, dlatego należy ją zdekodować przed użyciem go jako parametru w tym wywołaniu interfejsu API.

Oto przykład zakodowanego ciągu w adresie URL: contoso.com/signup?token=ab%2Bcd%2Fef, gdzie token to ab%2Bcd%2Fef. Ten sam token jest zdekodowany: Ab+cd/ef

Kody odpowiedzi:

Kod: 200 Zwraca unikatowe identyfikatory subskrypcji SaaS na podstawie podanej x-ms-marketplace-token wartości.

Przykład treści odpowiedzi:

{
  "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 Nieprawidłowe żądanie. x-ms-marketplace-token brak, źle sformułowany, nieprawidłowy lub wygasł.

Kod: 403 Zabronione. Token autoryzacji jest nieprawidłowy, wygasł lub nie został podany. Żądanie próbuje uzyskać dostęp do subskrypcji SaaS dla oferty opublikowanej przy użyciu innego identyfikatora aplikacji Microsoft Entra z tej, która została użyta do utworzenia tokenu autoryzacji.

Ten błąd jest często objawem nieprawidłowego wykonania rejestracji SaaS.

Kod: 500 Wewnętrzny błąd serwera. Ponów próbę wywołania interfejsu API. Jeśli błąd będzie się powtarzać, skontaktuj się z pomocą techniczną firmy Microsoft.

Aktywowanie subskrypcji

Po skonfigurowaniu konta SaaS dla użytkownika końcowego wydawca musi wywołać interfejs API aktywacji subskrypcji po stronie firmy Microsoft. Klient nie jest rozliczany, chyba że to wywołanie interfejsu API zakończy się pomyślnie.

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

Parametry zapytania:

Parametr Wartość
ApiVersion Użyj 2018-08-31.
subscriptionId Unikatowy identyfikator zakupionej subskrypcji SaaS. Ten identyfikator jest uzyskiwany po rozpoznaniu tokenu autoryzacji komercyjnej platformy handlowej przy użyciu interfejsu API rozpoznawania.

Nagłówki żądań:

Parametr Wartość
content-type application/json
x-ms-requestid Unikatowa wartość ciągu do śledzenia żądania od klienta, najlepiej identyfikator GUID. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
x-ms-correlationid Unikatowa wartość ciągu dla operacji na kliencie. Ten ciąg koreluje wszystkie zdarzenia z operacji klienta ze zdarzeniami po stronie serwera. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
authorization Unikatowy token dostępu identyfikujący wydawcę wykonującego to wywołanie interfejsu API. Format jest "Bearer <access_token>" taki, gdy wartość tokenu jest pobierana przez wydawcę, jak wyjaśniono w artykule Uzyskiwanie tokenu na podstawie aplikacji Microsoft Entra.

Kody odpowiedzi:

Kod: 200 Żądanie zaktualizowania subskrypcji i oznaczenie jako "Subskrybowane" jest odbierane. Niezależni dostawcy oprogramowania (ISV) mogą sprawdzić stan subskrypcji po kilku minutach (przeczytaj operację Pobierz, aby sprawdzić stan subskrypcji). Daje to ostateczną odpowiedź, czy subskrypcja została pomyślnie zaktualizowana. Niesubskrybowanie automatycznie wysyła element webhook "Anuluj subskrypcję".

Nie ma treści odpowiedzi dla tego wywołania.

Kod: 400 Nieprawidłowe żądanie: weryfikacja nie powiodła się.

  • Subskrypcja SaaS jest w stanie Wstrzymanie .

Kod: 403 Zabronione. Token autoryzacji jest nieprawidłowy, wygasł lub nie został podany. Żądanie próbuje uzyskać dostęp do subskrypcji SaaS dla oferty opublikowanej przy użyciu innego identyfikatora aplikacji Microsoft Entra z tej, która została użyta do utworzenia tokenu autoryzacji.

Ten błąd jest często objawem nieprawidłowego wykonania rejestracji SaaS.

Kod: 404 Nie znaleziono. Subskrypcja SaaS jest w stanie Anulowana subskrypcja .

Kod: 500 Wewnętrzny błąd serwera. Ponów próbę wywołania interfejsu API. Jeśli błąd będzie się powtarzać, skontaktuj się z pomocą techniczną firmy Microsoft.

Pobieranie listy wszystkich subskrypcji

Ten interfejs API pobiera listę wszystkich zakupionych subskrypcji SaaS dla wszystkich ofert publikowanych przez wydawcę na platformie handlowej. Zwracane są subskrypcje SaaS we wszystkich możliwych stanach. Anulowane subskrypcje SaaS są również zwracane, ponieważ te informacje nie są usuwane po stronie firmy Microsoft.

Interfejs API zwraca wyniki podzielone na strony o wartości 100 na stronę.

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

Parametry zapytania:

Parametr Wartość
ApiVersion Użyj 2018-08-31.
continuationToken Opcjonalny parametr. Aby pobrać pierwszą stronę wyników, pozostaw wartość pustą. Użyj wartości zwróconej w parametrze , @nextLink aby pobrać następną stronę.

Nagłówki żądań:

Parametr Wartość
content-type application/json
x-ms-requestid Unikatowa wartość ciągu do śledzenia żądania od klienta, najlepiej identyfikator GUID. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
x-ms-correlationid Unikatowa wartość ciągu dla operacji na kliencie. Ten parametr koreluje wszystkie zdarzenia z operacji klienta ze zdarzeniami po stronie serwera. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
authorization Unikatowy token dostępu identyfikujący wydawcę, który wykonuje to wywołanie interfejsu API. Format jest "Bearer <access_token>" taki, gdy wartość tokenu jest pobierana przez wydawcę, jak wyjaśniono w artykule Uzyskiwanie tokenu na podstawie aplikacji Microsoft Entra.

Kody odpowiedzi:

Kod: 200 Zwraca listę wszystkich istniejących subskrypcji dla wszystkich ofert dokonanych przez tego wydawcę na podstawie tokenu autoryzacji wydawcy.

Przykład treści odpowiedzi:

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

Jeśli nie znaleziono zakupionych subskrypcji SaaS dla tego wydawcy, zwracana jest pusta treść odpowiedzi.

Kod: 403 Zabronione. Token autoryzacji jest niedostępny, nieprawidłowy lub wygasł.

Ten błąd jest często objawem nieprawidłowego wykonania rejestracji SaaS.

Kod: 500 Wewnętrzny błąd serwera. Ponów próbę wywołania interfejsu API. Jeśli błąd będzie się powtarzać, skontaktuj się z pomocą techniczną firmy Microsoft.

Pobierz subskrypcję

Ten interfejs API pobiera określoną kupioną subskrypcję SaaS dla oferty SaaS, którą wydawca publikuje na platformie handlowej. Użyj tego wywołania, aby uzyskać wszystkie dostępne informacje dla określonej subskrypcji SaaS według jego identyfikatora, a nie przez wywołanie interfejsu API używanego do uzyskania listy wszystkich subskrypcji.

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

Parametry zapytania:

Parametr Wartość
ApiVersion Użyj 2018-08-31.
subscriptionId Unikatowy identyfikator zakupionej subskrypcji SaaS. Ten identyfikator jest uzyskiwany po rozpoznaniu tokenu autoryzacji komercyjnej platformy handlowej przy użyciu interfejsu API rozpoznawania.

Nagłówki żądań:

Parametr Wartość
content-type application/json
x-ms-requestid Unikatowa wartość ciągu do śledzenia żądania od klienta, najlepiej identyfikator GUID. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
x-ms-correlationid Unikatowa wartość ciągu dla operacji na kliencie. Ten parametr koreluje wszystkie zdarzenia z operacji klienta ze zdarzeniami po stronie serwera. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
authorization Unikatowy token dostępu identyfikujący wydawcę, który wykonuje to wywołanie interfejsu API. Format jest "Bearer <access_token>" taki, gdy wartość tokenu jest pobierana przez wydawcę, jak wyjaśniono w artykule Uzyskiwanie tokenu na podstawie aplikacji Microsoft Entra.

Kody odpowiedzi:

Kod: 200 Zwraca szczegóły dla subskrypcji SaaS na podstawie podanej subscriptionId wersji.

Przykład treści odpowiedzi:

{
  "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 Zabronione. Token autoryzacji jest nieprawidłowy, wygasł lub nie został podany. Żądanie próbuje uzyskać dostęp do subskrypcji SaaS dla oferty opublikowanej przy użyciu innego identyfikatora aplikacji Microsoft Entra z tej, która została użyta do utworzenia tokenu autoryzacji.

Ten błąd jest często objawem nieprawidłowego wykonania rejestracji SaaS.

Kod: 404 Nie znaleziono. Nie można odnaleźć subskrypcji SaaS z określonymi subscriptionId elementami.

Kod: 500 Wewnętrzny błąd serwera. Ponów próbę wywołania interfejsu API. Jeśli błąd będzie się powtarzać, skontaktuj się z pomocą techniczną firmy Microsoft.

Wyświetlanie listy dostępnych planów

Ten interfejs API pobiera wszystkie plany oferty SaaS zidentyfikowane przez subscriptionId konkretny zakup tej oferty. Użyj tego wywołania, aby uzyskać listę wszystkich planów prywatnych i publicznych, które mogą być aktualizowane przez beneficjenta subskrypcji SaaS. Zwrócone plany są dostępne w tej samej lokalizacji geograficznej co już zakupiony plan.

To wywołanie zwraca listę planów dostępnych dla tego klienta oprócz tego, który został już zakupiony. Listę można wyświetlić użytkownikowi końcowemu w witrynie wydawcy. Użytkownik końcowy może zmienić plan subskrypcji na dowolną z planów na zwróconej liście. Zmiana planu na plan, który nie znajduje się na liście, nie działa.

Ten interfejs API pobiera również skojarzony aktywny prywatny identyfikator oferty (jeśli wywołasz interfejs API z filtrem planId). Wywoływanie interfejsu API za pomocą filtru planId pokazuje aktywne identyfikatory GUID identyfikatora oferty prywatnej w treści odpowiedzi w węźle sourceOffers. Identyfikator planu przekazany w parametrze filtru powinien być zgodny z identyfikatorem planId zakupionym przez klienta.

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

Parametry zapytania:

Parametr Wartość
ApiVersion Użyj 2018-08-31.
subscriptionId Unikatowy identyfikator zakupionej subskrypcji SaaS. Ten identyfikator jest uzyskiwany po rozpoznaniu tokenu autoryzacji komercyjnej platformy handlowej przy użyciu interfejsu API rozpoznawania.
planId (Optional) Identyfikator planu określonego planu, który chcesz pobrać. Jest to opcjonalne i jeśli ignorowane zwraca wszystkie plany.

Nagłówki żądań:

Parametr Wartość
content-type application/json
x-ms-requestid Unikatowa wartość ciągu do śledzenia żądania od klienta, najlepiej identyfikator GUID. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
x-ms-correlationid Unikatowa wartość ciągu dla operacji na kliencie. Ten parametr koreluje wszystkie zdarzenia z operacji klienta ze zdarzeniami po stronie serwera. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
authorization Unikatowy token dostępu identyfikujący wydawcę, który wykonuje to wywołanie interfejsu API. Format jest "Bearer <access_token>" taki, gdy wartość tokenu jest pobierana przez wydawcę, jak wyjaśniono w artykule Uzyskiwanie tokenu na podstawie aplikacji Microsoft Entra.

Kody odpowiedzi:

Kod: 200 Zwraca listę wszystkich dostępnych planów dla istniejącej subskrypcji SaaS, w tym tej, która została już zakupiona.

Przekazanie nieprawidłowego (opcjonalnego) identyfikatora planu zwraca pustą listę planów.

Przykład treści odpowiedzi:

{
  "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 Nie znaleziono. subscriptionId nie można odnaleźć.

Kod: 403 Zabronione. Token autoryzacji jest nieprawidłowy, wygasł lub nie został podany. Żądanie może próbować uzyskać dostęp do subskrypcji SaaS dla oferty, która została anulowana lub opublikowana przy użyciu innego identyfikatora aplikacji Microsoft Entra z tego, który został użyty do utworzenia tokenu autoryzacji.

Ten błąd jest często objawem nieprawidłowego wykonania rejestracji SaaS.

Kod: 500 Wewnętrzny błąd serwera. Ponów próbę wywołania interfejsu API. Jeśli błąd będzie się powtarzać, skontaktuj się z pomocą techniczną firmy Microsoft.

Zmienianie planu subskrypcji

Użyj tego interfejsu API, aby zaktualizować istniejący plan zakupiony dla subskrypcji SaaS do nowego planu (publicznego lub prywatnego). Wydawca musi wywołać ten interfejs API, gdy plan zostanie zmieniony po stronie wydawcy subskrypcji SaaS zakupionej na platformie handlowej.

Ten interfejs API może być wywoływany tylko dla aktywnych subskrypcji. Każdy plan można zmienić na inny istniejący plan (publiczny lub prywatny), ale nie na sam. W przypadku planów prywatnych dzierżawa klienta musi być zdefiniowana jako część odbiorców planu w Centrum partnerskim.

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

Parametry zapytania:

Parametr Wartość
ApiVersion Użyj 2018-08-31.
subscriptionId Unikatowy identyfikator zakupionej subskrypcji SaaS. Ten identyfikator jest uzyskiwany po rozpoznaniu tokenu autoryzacji komercyjnej platformy handlowej przy użyciu interfejsu API rozpoznawania.

Nagłówki żądań:

Parametr Wartość
content-type application/json
x-ms-requestid Unikatowa wartość ciągu do śledzenia żądania od klienta, najlepiej identyfikator GUID. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
x-ms-correlationid Unikatowa wartość ciągu dla operacji na kliencie. Ten parametr koreluje wszystkie zdarzenia z operacji klienta ze zdarzeniami po stronie serwera. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
authorization Unikatowy token dostępu identyfikujący wydawcę, który wykonuje to wywołanie interfejsu API. Format jest "Bearer <access_token>" taki, gdy wartość tokenu jest pobierana przez wydawcę, jak wyjaśniono w artykule Uzyskiwanie tokenu na podstawie aplikacji Microsoft Entra.

Przykład ładunku żądania:

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

Kody odpowiedzi:

Kod: 202 Żądanie zmiany planu zostało zaakceptowane i obsłużone asynchronicznie. Oczekuje się, że partner sonduje adres URL lokalizacji operacji, aby określić powodzenie lub niepowodzenie żądania planu zmian. Sondowanie powinno odbywać się co kilka sekund do momentu odebrania końcowego stanu Niepowodzenie, Powodzenie lub Konflikt dla operacji. Stan ostatecznej operacji powinien być zwracany szybko, ale w niektórych przypadkach może upłynąć kilka minut.

Partner otrzymuje również powiadomienie elementu webhook, gdy akcja jest gotowa do pomyślnego ukończenia po stronie komercyjnej platformy handlowej. Dopiero wtedy wydawca powinien wprowadzić zmianę planu po stronie wydawcy.

Nagłówki odpowiedzi:

Parametr Wartość
Operation-Location Adres URL, aby uzyskać stan operacji. Na przykład https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31

Kod: 400 Nieprawidłowe żądanie: niepowodzenia walidacji.

  • Nowy plan nie istnieje lub nie jest dostępny dla tej konkretnej subskrypcji SaaS.
  • Nowy plan jest taki sam jak bieżący plan.
  • Stan subskrypcji SaaS nie jest subskrybowany.
  • Operacja aktualizacji subskrypcji SaaS nie jest uwzględniona w programie allowedCustomerOperations.

Kod: 403 Zabronione. Token autoryzacji jest nieprawidłowy, wygasł lub nie został podany. Żądanie próbuje uzyskać dostęp do subskrypcji SaaS dla oferty opublikowanej przy użyciu innego identyfikatora aplikacji Microsoft Entra z tej, która została użyta do utworzenia tokenu autoryzacji.

Ten błąd jest często objawem nieprawidłowego wykonania rejestracji SaaS.

Kod: 404 Nie znaleziono. Nie można odnaleźć subskrypcji SaaS z subscriptionId programem .

Kod: 500 Wewnętrzny błąd serwera. Ponów próbę wywołania interfejsu API. Jeśli błąd będzie się powtarzać, skontaktuj się z pomocą techniczną firmy Microsoft.

Uwaga

Plan lub ilość miejsc można zmienić jednocześnie, a nie obie.

Ten interfejs API może być wywoływany tylko po otrzymaniu jawnego zatwierdzenia zmiany od użytkownika końcowego.

Zmienianie ilości miejsc w subskrypcji SaaS

Użyj tego interfejsu API, aby zaktualizować (zwiększyć lub zmniejszyć) ilość miejsc zakupionych dla subskrypcji SaaS. Wydawca musi wywołać ten interfejs API, gdy liczba miejsc zostanie zmieniona ze strony wydawcy dla subskrypcji SaaS utworzonej na platformie handlowej.

Ilość miejsc nie może być większa niż ilość dozwolona w bieżącym planie. W takim przypadku wydawca powinien zmienić plan przed zmianą ilości miejsc.

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

Parametry zapytania:

Parametr Wartość
ApiVersion Użyj 2018-08-31.
subscriptionId Unikatowy identyfikator zakupionej subskrypcji SaaS. Ten identyfikator jest uzyskiwany po rozpoznaniu tokenu autoryzacji komercyjnej platformy handlowej przy użyciu interfejsu API rozpoznawania.

Nagłówki żądań:

Parametr Wartość
content-type application/json
x-ms-requestid Unikatowa wartość ciągu do śledzenia żądania od klienta, najlepiej identyfikator GUID. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
x-ms-correlationid Unikatowa wartość ciągu dla operacji na kliencie. Ten parametr koreluje wszystkie zdarzenia z operacji klienta ze zdarzeniami po stronie serwera. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
authorization Unikatowy token dostępu identyfikujący wydawcę, który wykonuje to wywołanie interfejsu API. Format jest "Bearer <access_token>" taki, gdy wartość tokenu jest pobierana przez wydawcę, jak wyjaśniono w artykule Uzyskiwanie tokenu na podstawie aplikacji Microsoft Entra.

Przykład ładunku żądania:

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

Kody odpowiedzi:

Kod: 202 Żądanie zmiany ilości zostało zaakceptowane i obsłużone asynchronicznie. Oczekuje się, że partner sonduje adres URL lokalizacji operacji, aby określić powodzenie lub niepowodzenie żądania zmiany ilości. Sondowanie powinno odbywać się co kilka sekund do momentu odebrania końcowego stanu Niepowodzenie, Powodzenie lub Konflikt dla operacji. Stan ostatecznej operacji powinien zostać zwrócony szybko, ale w niektórych przypadkach może upłynąć kilka minut.

Partner otrzymuje również powiadomienie elementu webhook, gdy akcja jest gotowa do pomyślnego ukończenia po stronie komercyjnej platformy handlowej. Tylko wtedy wydawca powinien wprowadzić zmianę ilości po stronie wydawcy.

Nagłówki odpowiedzi:

Parametr Wartość
Operation-Location Połącz z zasobem, aby uzyskać stan operacji. Na przykład https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31.

Kod: 400 Nieprawidłowe żądanie: niepowodzenia walidacji.

  • Nowa ilość jest większa lub niższa niż bieżący limit planu.
  • Brak nowej ilości.
  • Nowa ilość jest taka sama jak bieżąca ilość.
  • Stan subskrypcji SaaS nie jest subskrybowany.
  • Operacja aktualizacji subskrypcji SaaS nie jest uwzględniona w pliku allowedCustomerOperations.

Kod: 403 Zabronione. Token autoryzacji jest nieprawidłowy, wygasł lub nie został podany. Żądanie próbuje uzyskać dostęp do subskrypcji, która nie należy do bieżącego wydawcy.

Ten błąd jest często objawem nieprawidłowego wykonania rejestracji SaaS.

Kod: 404 Nie znaleziono. Nie można odnaleźć subskrypcji SaaS z subscriptionId programem .

Kod: 500 Wewnętrzny błąd serwera. Ponów próbę wywołania interfejsu API. Jeśli błąd będzie się powtarzać, skontaktuj się z pomocą techniczną firmy Microsoft.

Uwaga

Jednocześnie można zmienić tylko plan lub ilość, a nie obie.

Ten interfejs API może być wywoływany tylko po uzyskaniu jawnego zatwierdzenia od użytkownika końcowego w celu zmiany.

Anulowanie subskrypcji

Użyj tego interfejsu API, aby anulować subskrypcję usługi SaaS. Wydawca nie musi używać tego interfejsu API i zalecamy, aby klienci zostali przekierowani do komercyjnej platformy handlowej, aby anulować subskrypcje SaaS.

Jeśli wydawca zdecyduje się wdrożyć anulowanie subskrypcji SaaS zakupionej na platformie handlowej po stronie wydawcy, musi wywołać ten interfejs API. Po zakończeniu tego wywołania stan subskrypcji zostanie anulowany po stronie firmy Microsoft.

Klient nie jest rozliczany, jeśli subskrypcja zostanie anulowana w ciągu 72 godzin od zakupu.

Klient jest rozliczany, jeśli subskrypcja zostanie anulowana po poprzednim okresie prolongaty. Klient traci dostęp do subskrypcji SaaS po stronie firmy Microsoft natychmiast po anulowaniu.

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

Parametry zapytania:

Parametr Wartość
ApiVersion Użyj 2018-08-31.
subscriptionId Unikatowy identyfikator zakupionej subskrypcji SaaS. Ten identyfikator jest uzyskiwany po rozpoznaniu tokenu autoryzacji komercyjnej platformy handlowej przy użyciu interfejsu API rozpoznawania.

Nagłówki żądań:

Parametr Wartość
content-type application/json
x-ms-requestid Unikatowa wartość ciągu do śledzenia żądania od klienta, najlepiej identyfikator GUID. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
x-ms-correlationid Unikatowa wartość ciągu dla operacji na kliencie. Ten parametr koreluje wszystkie zdarzenia z operacji klienta ze zdarzeniami po stronie serwera. Jeśli ta wartość nie zostanie podana, zostanie wygenerowana i podana w nagłówkach odpowiedzi.
authorization Unikatowy token dostępu identyfikujący wydawcę wykonującego to wywołanie interfejsu API. Format jest "Bearer <access_token>" taki, gdy wartość tokenu jest pobierana przez wydawcę, jak wyjaśniono w artykule Uzyskiwanie tokenu na podstawie aplikacji Microsoft Entra.

Kody odpowiedzi:

Kod: 202 Żądanie anulowania subskrypcji zostało zaakceptowane i obsłużone asynchronicznie. Oczekuje się, że partner sonduje adres URL lokalizacji operacji, aby określić powodzenie lub niepowodzenie tego żądania. Sondowanie powinno odbywać się co kilka sekund do momentu odebrania końcowego stanu Niepowodzenie, Powodzenie lub Konflikt dla operacji. Stan ostatecznej operacji powinien zostać zwrócony szybko, ale w niektórych przypadkach może upłynąć kilka minut.

Partner otrzymuje również powiadomienie elementu webhook po pomyślnym zakończeniu akcji po stronie komercyjnej platformy handlowej. Dopiero wtedy wydawca powinien anulować subskrypcję po stronie wydawcy.

Kod: 200 Subskrypcja jest już w stanie Subskrypcja anulowana.

Nagłówki odpowiedzi:

Parametr Wartość
Operation-Location Połącz z zasobem, aby uzyskać stan operacji. Na przykład https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31.

Kod: 400 Nieprawidłowe żądanie. Usuwanie nie znajduje się na allowedCustomerOperations liście dla tej subskrypcji SaaS.

Kod: 403 Zabronione. Token autoryzacji jest nieprawidłowy, wygasł lub jest niedostępny.

Ten błąd jest często objawem nieprawidłowego wykonania rejestracji SaaS.

Kod: 404 Nie znaleziono. Nie można odnaleźć subskrypcji SaaS z subscriptionId programem .

Kod: 409

Nie można ukończyć usuwania, ponieważ subskrypcja jest zablokowana z powodu oczekujących operacji.

Kod: 500 Wewnętrzny błąd serwera. Ponów próbę wywołania interfejsu API. Jeśli błąd będzie się powtarzać, skontaktuj się z pomocą techniczną firmy Microsoft.

Następne kroki