API Langganan pemenuhan SaaS v2 di marketplace komersial Microsoft

Artikel ini menjelaskan versi 2 dari API langganan pemenuhan SaaS.

Menyelesaikan langganan yang telah dibeli

Titik akhir penyelesaian membuat penerbit dapat menukarkan token identifikasi pembelian dari pasar komersial (disebutsebagai tokendiDibeli namun belum diaktifkan) keID langganan SaaS yang dibeli terus-menerus dan rinciannya.

Ketika pelanggan dialihkan ke URL halaman arahan mitra, token identifikasi pelanggan diteruskan sebagai parameter token dalampanggilan URL ini. Mitra diharapkan menggunakan token ini dan membuat permintaan untuk menyelesaikannya. Respons Resolve API berisi ID langganan SaaS dan rincian lainnya untuk mengidentifikasi pembelian secara unik. Token yang disediakan dengan panggilan URL halaman arahan berlaku selama 24 jam. Jika token yang Anda terima kedaluwarsa, kami sarankan Anda memberikan panduan berikut kepada pengguna akhir:

"Kami tidak dapat mengidentifikasi pembelian ini. Buka kembali langganan SaaS ini di portal Azure atau di Pusat Admin Microsoft 365 dan pilih "Konfigurasi Akun" atau "Kelola Akun" lagi."

Memanggil Resolve API mengembalikan detail dan status langganan untuk langganan SaaS di semua status yang didukung.

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

Parameter kueri:

Parameter Nilai
ApiVersion Gunakan 2018-08-31.

Header permintaan:

Parameter Nilai
content-type application/json
x-ms-requestid Nilai karakter unik untuk melacak permintaan dari klien, sebaiknya GUID. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
x-ms-correlationid Nilai karakter unik untuk operasi pada klien. Parameter ini menghubungkan semua peristiwa dari operasi klien dengan peristiwa di sisi server. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons
authorization Token akses unik yang mengidentifikasi penerbit melakukan panggilan API ini. Formatnya adalah "Bearer <access_token>" ketika nilai token diambil oleh penerbit seperti yang dijelaskan dalam Mendapatkan token berdasarkan aplikasi Microsoft Entra.
x-ms-marketplace-token Parameter token identifikasi pembelianuntuk diselesaikan. Token diteruskan dalam panggilan URL halaman arahan ketika pelanggan diarahkan ke situs web mitra SaaS (misalnya:https://contoso.com/signup?token=<token><authorization_token>).

Nilai token yang dikodekan adalah bagian dari URL halaman arahan, sehingga perlu didekodekan sebelum digunakan sebagai parameter dalam panggilan API ini.

Berikut contoh karakter yang dikodekan di URL:contoso.com/signup?token=ab%2Bcd%2Fef, di mana token beradaab%2Bcd%2Fef. Token yang sama yang didekodekan adalah: Ab+cd/ef

Kode respons:

Kode: 200 Pengembalian pengidentifikasi langganan SaaS unik berdasarkan yangx-ms-marketplace-tokendisediakan.

Contoh badan respons:

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

Kode: 400 Permintaan Buruk. x-ms-marketplace-tokenhilang, cacat, tidak valid, atau kadaluwarsa.

Kode: 403 Terlarang. Token otorisasi tidak valid, kadaluwarsa, atau tidak tersedia. Permintaan ini mencoba mengakses langganan SaaS untuk penawaran yang diterbitkan dengan ID aplikasi Microsoft Entra yang berbeda dari yang digunakan untuk membuat token otorisasi.

Kesalahan ini sering merupakan gejala tidak melakukan pendaftaranSaaS denganbenar.

Kode: 500 Kesalahan server internal. Coba lagi panggilan API. Jika masalah berlanjut, hubungidukungan Microsoft.

Aktifkan langganan

Setelah akun SaaS dikonfigurasi untuk pengguna akhir, penerbit harus memanggil Aktifkan API Langganan di sisi Microsoft. Pelanggan tidak ditagih kecuali panggilan API ini berhasil.

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

Parameter kueri:

Parameter Nilai
ApiVersion Gunakan 2018-08-31.
subscriptionId Pengidentifikasi unik dari langganan SaaS yang dibeli. ID ini diperoleh setelah menyelesaikan token otorisasi pasar komersial dengan menggunakanResolve API.

Header permintaan:

Parameter Nilai
content-type application/json
x-ms-requestid Nilai karakter unik untuk melacak permintaan dari klien, sebaiknya GUID. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
x-ms-correlationid Nilai karakter unik untuk operasi pada klien. Parameter ini menghubungkan semua peristiwa dari operasi klien dengan peristiwa di sisi server. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
authorization Token akses unik yang mengidentifikasi penerbit melakukan panggilan API ini. Formatnya adalah "Bearer <access_token>" ketika nilai token diambil oleh penerbit seperti yang dijelaskan dalam Mendapatkan token berdasarkan aplikasi Microsoft Entra.

Kode respons:

Kode: 200 Permintaan untuk memperbarui langganan dan menandai sebagai "Berlangganan" diterima. Vendor Perangkat Lunak Independen (ISV) dapat memeriksa status langganan setelah beberapa menit (baca untuk operasi Dapatkan untuk memeriksa status langganan). Ini memberi Anda jawaban pasti apakah langganan berhasil diperbarui. Kegagalan untuk berlangganan secara otomatis mengirim webhook "Berhenti berlangganan".

Tidak ada isi respons untuk panggilan ini.

Kode: 400 Permintaan buruk: validasi gagal.

  • Langganan SaaS dalam status Ditangguhkan.

Kode: 403 Terlarang. Token otorisasi tidak valid, kadaluwarsa, atau tidak tersedia. Permintaan ini mencoba mengakses langganan SaaS untuk penawaran yang diterbitkan dengan ID aplikasi Microsoft Entra yang berbeda dari yang digunakan untuk membuat token otorisasi.

Kesalahan ini sering merupakan gejala tidak melakukan pendaftaranSaaS denganbenar.

Kode: 404 Tidak ditemukan. Langganan SaaS dalam kondisiTidak Berlangganan.

Kode: 500 Kesalahan server internal. Coba lagi panggilan API. Jika masalah berlanjut, hubungidukungan Microsoft.

Dapatkan daftar semua langganan

API ini mengambil daftar semua langganan SaaS yang dibeli untuk semua penawaran yang diterbitkan penerbit di pasar komersial. Langganan SaaS dalam semua status yang mungkin dikembalikan. Langganan SaaS yang tidak berlangganan juga dikembalikan karena informasi ini tidak dihapus di sisi Microsoft.

API mengembalikan hasil paginasi 100 per halaman.

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

Parameter kueri:

Parameter Nilai
ApiVersion Gunakan 2018-08-31.
continuationToken Parameter opsional. Untuk mengambil halaman pertama hasil, biarkan kosong. Gunakan nilai yang dikembalikan dalam @nextLinkparameter untuk mengambil halaman berikutnya.

Header permintaan:

Parameter Nilai
content-type application/json
x-ms-requestid Nilai karakter unik untuk melacak permintaan dari klien, sebaiknya GUID. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
x-ms-correlationid Nilai karakter unik untuk operasi pada klien. Parameter ini menghubungkan semua peristiwa dari operasi klien dengan peristiwa di sisi server. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
authorization Token akses unik yang mengidentifikasi penerbit melakukan panggilan API ini. Formatnya adalah "Bearer <access_token>" ketika nilai token diambil oleh penerbit seperti yang dijelaskan dalam Mendapatkan token berdasarkan aplikasi Microsoft Entra.

Kode respons:

Kode: 200 Mengembalikan daftar semua langganan yang ada untuk semua penawaran yang dibuat oleh penerbit ini, berdasarkan token otorisasi penerbit.

Contoh badan respons:

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

Jika tidak ada langganan SaaS yang dibeli ditemukan untuk penerbit ini, isi respons kosong akan dikembalikan.

Kode: 403 Terlarang. Token otorisasi tidak tersedia, tidak valid, atau kadaluwarsa.

Kesalahan ini sering merupakan gejala tidak melakukan pendaftaranSaaS denganbenar.

Kode: 500 Kesalahan server internal. Coba lagi panggilan API. Jika masalah berlanjut, hubungidukungan Microsoft.

Dapatkan langganan

API ini mengambil daftar semua langganan SaaS yang dibeli untuk semua penawaran yang diterbitkan penerbit di pasar komersial. Gunakan panggilan ini untuk mendapatkan semua informasi yang tersedia untuk langganan SaaS tertentu berdasarkan ID daripada memanggil API yang digunakan untuk mendapatkan daftar semua langganan.

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

Parameter kueri:

Parameter Nilai
ApiVersion Gunakan 2018-08-31.
subscriptionId Pengidentifikasi unik dari langganan SaaS yang dibeli. ID ini diperoleh setelah menyelesaikan token otorisasi pasar komersial dengan menggunakan Resolve API.

Header permintaan:

Parameter Nilai
content-type application/json
x-ms-requestid Nilai karakter unik untuk melacak permintaan dari klien, sebaiknya GUID. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
x-ms-correlationid Nilai karakter unik untuk operasi pada klien. Parameter ini menghubungkan semua peristiwa dari operasi klien dengan peristiwa di sisi server. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
authorization Token akses unik yang mengidentifikasi penerbit melakukan panggilan API ini. Formatnya adalah "Bearer <access_token>" ketika nilai token diambil oleh penerbit seperti yang dijelaskan dalam Mendapatkan token berdasarkan aplikasi Microsoft Entra.

Kode respons:

Kode: 200 Mengembalikan detail untuk langganan SaaS berdasarkan yang subscriptionIddisediakan.

Contoh badan respons:

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

Kode: 403 Terlarang. Token otorisasi tidak valid, kadaluwarsa, atau tidak tersedia. Permintaan ini mencoba mengakses langganan SaaS untuk penawaran yang diterbitkan dengan ID aplikasi Microsoft Entra yang berbeda dari yang digunakan untuk membuat token otorisasi.

Kesalahan ini sering merupakan gejala tidak melakukan pendaftaranSaaS denganbenar.

Kode: 404 Tidak ditemukan. Langganan SaaS dengan yang ditentukan subscriptionIdtidak dapat ditemukan.

Kode: 500 Kesalahan server internal. Coba lagi panggilan API. Jika masalah berlanjut, hubungidukungan Microsoft.

Muat paket yang tersedia

API ini mengambil semua paket untuk penawaran SaaS yang diidentifikasi subscriptionIdoleh pembelian tertentu dari penawaran ini. Gunakan panggilan ini untuk mendapatkan daftar semua paket pribadi dan publik yang dapat diperbarui oleh penerima langganan SaaS untuk langganan. Paket yang dikembalikan tersedia dalam geografi yang sama dengan paket yang sudah dibeli.

Panggilan ini mengembalikan daftar paket yang tersedia untuk pelanggan tersebut selain yang telah dibeli. Daftar dapat disajikan kepada pengguna akhir di situs penerbit. Pengguna akhir dapat mengubah paket langganan ke salah satu paket dalam daftar yang dikembalikan. Mengubah paket menjadi paket yang tidak ada dalam daftar tidak berfungsi.

API ini juga mengambil ID penawaran privat aktif yang terkait (jika Anda memanggil API dengan filter planId). API panggilan dengan filter planId menunjukkan GUID ID penawaran privat aktif di isi respons di bawah simpul sourceOffers. PlanId yang diteruskan dalam param filter harus cocok dengan planId yang dibeli pelanggan.

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

Parameter kueri:

Parameter Nilai
ApiVersion Gunakan 2018-08-31.
subscriptionId Pengidentifikasi unik dari langganan SaaS yang dibeli. ID ini diperoleh setelah menyelesaikan token otorisasi pasar komersial dengan menggunakan Resolve API.
planId (Optional) ID paket dari paket tertentu yang ingin Anda ambil. Ini opsional dan jika diabaikan mengembalikan semua paket.

Header permintaan:

Parameter Nilai
content-type application/json
x-ms-requestid Nilai karakter unik untuk melacak permintaan dari klien, sebaiknya GUID. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
x-ms-correlationid Nilai karakter unik untuk operasi pada klien. Parameter ini menghubungkan semua peristiwa dari operasi klien dengan peristiwa di sisi server. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
authorization Token akses unik yang mengidentifikasi penerbit melakukan panggilan API ini. Formatnya adalah "Bearer <access_token>" ketika nilai token diambil oleh penerbit seperti yang dijelaskan dalam Mendapatkan token berdasarkan aplikasi Microsoft Entra.

Kode respons:

Kode: 200 Mengembalikan daftar semua paket yang tersedia untuk langganan SaaS yang telah ada termasuk paket yang telah dibeli.

Meneruskan planId yang tidak valid (opsional) mengembalikan daftar paket kosong.

Contoh badan respons:

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

Kode: 404 Tidak Ditemukan. subscriptionId tidak ditemukan.

Kode: 403 Terlarang. Token otorisasi tidak valid, kadaluwarsa, atau tidak tersedia. Permintaan mungkin mencoba mengakses langganan SaaS untuk penawaran yang berhenti berlangganan atau diterbitkan dengan ID aplikasi Microsoft Entra yang berbeda dari yang digunakan untuk membuat token otorisasi.

Kesalahan ini sering merupakan gejala tidak melakukan pendaftaranSaaS denganbenar.

Kode: 500 Kesalahan server internal. Coba lagi panggilan API. Jika masalah berlanjut, hubungidukungan Microsoft.

Mengubah paket pada langganan

Gunakan API ini untuk memperbarui paket yang ada yang dibeli untuk langganan SaaS ke paket baru (publik atau pribadi). Penerbit harus memanggil API ini ketika paket diubah oleh penerbit untuk langganan SaaS yang dibeli di pasar komersial.

API ini hanya dapat dipanggil untuk Aktifkan langganan. Paket apa pun dapat diubah ke paket lain yang ada (publik atau pribadi) namun tidak untuk diri sendiri. Untuk paket pribadi, penyewa pelanggan harus didefinisikan sebagai bagian dari hadirin paket di Pusat Mitra.

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

Parameter kueri:

Parameter Nilai
ApiVersion Gunakan 2018-08-31.
subscriptionId Pengidentifikasi unik dari langganan SaaS yang dibeli. ID ini diperoleh setelah menyelesaikan token otorisasi pasar komersial dengan menggunakan Resolve API.

Header permintaan:

Parameter Nilai
content-type application/json
x-ms-requestid Nilai karakter unik untuk melacak permintaan dari klien, sebaiknya GUID. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
x-ms-correlationid Nilai karakter unik untuk operasi pada klien. Parameter ini menghubungkan semua peristiwa dari operasi klien dengan peristiwa di sisi server. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
authorization Token akses unik yang mengidentifikasi penerbit melakukan panggilan API ini. Formatnya adalah "Bearer <access_token>" ketika nilai token diambil oleh penerbit seperti yang dijelaskan dalam Mendapatkan token berdasarkan aplikasi Microsoft Entra.

Minta contoh payload:

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

Kode respons:

Kode: 202 Permintaan untuk mengubah paket telah diterima dan ditangani secara tidak sinkron. Mitra diharapkan untuk melakukan penjajakanURL Operation-Location untuk menentukan keberhasilan atau kegagalan permintaan rencana perubahan. Penjajakan harus dilakukan setiap beberapa detik sampai status akhir Gagal,Berhasil, atau Konflik diterima untuk operasi. Status operasi akhir harus dikembalikan dengan cepat, namun dapat menghabiskan waktu beberapa menit dalam beberapa kasus.

Mitra juga mendapatkan pemberitahuan webhook ketika tindakan siap untuk diselesaikan dengan sukses di sisi marketplace komersial. Hanya dengan begitu penerbit harus membuat perubahan rencana di sisi penerbit.

Header respons:

Parameter Nilai
Operation-Location URL untuk mendapatkan status operasi. Misalnya: https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31

Kode: 400 Permintaan buruk: validasi gagal.

  • Paket baru tidak ada atau tidak tersedia untuk langganan SaaS spesifik ini.
  • Paket baru ini sama dengan paket saat ini.
  • Status langganan SaaS tidak Berlangganan.
  • Operasi pembaruan untuk langganan SaaS tidak dimasukkan dalamallowedCustomerOperations.

Kode: 403 Terlarang. Token otorisasi tidak valid, kadaluwarsa, atau tidak disediakan. Permintaan ini mencoba mengakses langganan SaaS untuk penawaran yang diterbitkan dengan ID aplikasi Microsoft Entra yang berbeda dari yang digunakan untuk membuat token otorisasi.

Kesalahan ini sering merupakan gejala tidak melakukan pendaftaranSaaS denganbenar.

Kode: 404 Tidak ditemukan. Langganan SaaS dengansubscriptionIdtidak ditemukan.

Kode: 500 Kesalahan server internal. Coba lagi panggilan API. Jika masalah berlanjut, hubungidukungan Microsoft.

Catatan

Baik paket atau jumlah seat dapat diubah pada satu waktu, bukan keduanya.

API ini dapat dipanggil hanya setelah mendapatkan persetujuan eksplisit untuk perubahan dari pengguna akhir.

Ubah jumlah seat pada langganan SaaS

Gunakan API ini untuk memperbarui (menambah atau mengurangi) jumlah seat yang dibeli untuk langganan SaaS. Penerbit harus memanggil API ini ketika jumlah seat diubah oleh penerbit untuk langganan SaaS yang dibuat di pasar komersial.

Jumlah kursi tidak boleh lebih dari kuantitas yang diizinkan dalam paket saat ini. Dalam hal ini, penerbit harus mengubah paket sebelum mengubah jumlah seat.

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

Parameter kueri:

Parameter Nilai
ApiVersion Gunakan 2018-08-31.
subscriptionId Pengidentifikasi unik dari langganan SaaS yang dibeli. ID ini diperoleh setelah menyelesaikan token otorisasi pasar komersial dengan menggunakan Resolve API.

Header permintaan:

Parameter Nilai
content-type application/json
x-ms-requestid Nilai karakter unik untuk melacak permintaan dari klien, sebaiknya GUID. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
x-ms-correlationid Nilai karakter unik untuk operasi pada klien. Parameter ini menghubungkan semua peristiwa dari operasi klien dengan peristiwa di sisi server. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
authorization Token akses unik yang mengidentifikasi penerbit melakukan panggilan API ini. Formatnya adalah "Bearer <access_token>" ketika nilai token diambil oleh penerbit seperti yang dijelaskan dalam Mendapatkan token berdasarkan aplikasi Microsoft Entra.

Minta contoh payload:

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

Kode respons:

Kode: 202 Permintaan untuk mengubah paket telah diterima dan ditangani secara tidak sinkron. Mitra diharapkan melakukan penjajakanURL Operation-Location untuk menentukan keberhasilan atau kegagalan permintaan jumlah perubahan. Penjajakan harus dilakukan setiap beberapa detik sampai status akhir Gagal,Berhasil, atau Konflik diterima untuk operasi. Status operasi akhir harus dikembalikan dengan cepat, namun dapat menghabiskan waktu beberapa menit dalam beberapa kasus.

Mitra juga mendapatkan pemberitahuan webhook ketika tindakan siap untuk diselesaikan dengan sukses di sisi marketplace komersial. Hanya dengan begitu penerbit harus membuat perubahan jumlah di sisi penerbit.

Header respons:

Parameter Nilai
Operation-Location Tautkan ke sumber daya untuk mendapatkan status operasi. Contohnya,https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31.

Kode: 400 Permintaan buruk: validasi gagal.

  • Jumlah baru lebih besar atau lebih rendah dari batas paket saat ini.
  • Jumlah baru hilang.
  • Jumlah baru sama dengan jumlah saat ini.
  • Status langganan SaaS tidak Berlangganan.
  • Operasi pembaruan untuk langganan SaaS tidak dimasukkan dalamallowedCustomerOperations.

Kode: 403 Terlarang. Token otorisasi tidak valid, kadaluwarsa, atau tidak tersedia. Permintaan sedang mencoba mengakses langganan yang bukan milik penerbit saat ini.

Kesalahan ini sering merupakan gejala tidak melakukan pendaftaranSaaS denganbenar.

Kode: 404 Tidak ditemukan. Langganan SaaS dengansubscriptionIdtidak ditemukan.

Kode: 500 Kesalahan server internal. Coba lagi panggilan API. Jika masalah berlanjut, hubungidukungan Microsoft.

Catatan

Hanya paket atau jumlah yang dapat diubah pada satu waktu, bukan keduanya.

API ini dapat dipanggil hanya setelah mendapatkan persetujuan eksplisit untuk perubahan dari pengguna akhir.

Batalkan langganan

Gunakan API ini untuk berhenti berlangganan SaaS tertentu. Penerbit tidak harus menggunakan API ini dan kami menyarankan agar pelanggan diarahkan ke pasar komersial untuk membatalkan langganan SaaS.

Jika penerbit memutuskan untuk menerapkan pembatalan langganan SaaS yang dibeli di pasar komersial di sisi penerbit, mereka harus memanggil API ini. Setelah selesainya panggilan ini, status langganan menjadi Tidak Berlangganan di sisi Microsoft.

Pelanggan tidak ditagih jika langganan dibatalkan dalam waktu 72 jam sejak pembelian.

Pelanggan ditagih jika langganan dibatalkan setelah masa tenggang sebelumnya. Pelanggan kehilangan akses ke langganan SaaS di sisi Microsoft segera setelah pembatalan.

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

Parameter kueri:

Parameter Nilai
ApiVersion Gunakan 2018-08-31.
subscriptionId Pengidentifikasi unik dari langganan SaaS yang dibeli. ID ini diperoleh setelah menyelesaikan token otorisasi pasar komersial dengan menggunakan Resolve API.

Header permintaan:

Parameter Nilai
content-type application/json
x-ms-requestid Nilai karakter unik untuk melacak permintaan dari klien, sebaiknya GUID. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
x-ms-correlationid Nilai karakter unik untuk operasi pada klien. Parameter ini menghubungkan semua peristiwa dari operasi klien dengan peristiwa di sisi server. Jika nilai ini tidak disediakan, nilai dibuat dan disediakan di header respons.
authorization Token akses unik yang mengidentifikasi penerbit melakukan panggilan API ini. Formatnya adalah "Bearer <access_token>" ketika nilai token diambil oleh penerbit seperti yang dijelaskan dalam Mendapatkan token berdasarkan aplikasi Microsoft Entra.

Kode respons:

Kode: 202 Permintaan untuk mengubah paket telah diterima dan ditangani secara tidak sinkron. Mitra diharapkan melakukan penjajakanURL Operation-Location untuk menentukan keberhasilan atau kegagalan permintaan ini. Penjajakan harus dilakukan setiap beberapa detik sampai status akhir Gagal,Berhasil, atau Konflik diterima untuk operasi. Status operasi akhir harus dikembalikan dengan cepat, namun dapat menghabiskan waktu beberapa menit dalam beberapa kasus.

Mitra juga mendapatkan pemberitahuan webhook ketika tindakan berhasil diselesaikan di sisi marketplace komersial. Hanya dengan begitu penerbit harus membatalkan langganan di sisi penerbit.

Kode: 200 Langganan sudah dalam status Berhenti Berlangganan.

Header respons:

Parameter Nilai
Operation-Location Tautkan ke sumber daya untuk mendapatkan status operasi. Contohnya,https://marketplaceapi.microsoft.com/api/saas/subscriptions/<subscriptionId>/operations/<operationId>?api-version=2018-08-31.

Kode: 400 Permintaan Buruk. Hapus tidak ada dalamallowedCustomerOperations daftar untuk langganan SaaS ini.

Kode: 403 Terlarang. Token otorisasi tidak valid, kadaluwarsa, atau tidak tersedia.

Kesalahan ini sering merupakan gejala tidak melakukan pendaftaranSaaS denganbenar.

Kode: 404 Tidak ditemukan. Langganan SaaS dengansubscriptionIdtidak ditemukan.

Kode: 409

Penghapusan tidak dapat diselesaikan karena langganan dikunci karena operasi yang tertunda.

Kode: 500 Kesalahan server internal. Coba lagi panggilan API. Jika masalah berlanjut, hubungidukungan Microsoft.

Langkah berikutnya