Ringkasan API pengiriman penawaran pribadi

2025-06-21

Penawaran privat memungkinkan penerbit dan pelanggan untuk bertransaksi satu atau beberapa produk di Marketplace Azure dengan membuat harga terikat waktu dengan persyaratan yang disesuaikan. API pengiriman penawaran pribadi memungkinkan penayang membuat dan mengelola penawaran pribadi secara terprogram untuk pelanggan dan/atau partner CSP. API ini menggunakan ID Microsoft Entra untuk mengautentikasi panggilan dari aplikasi atau layanan Anda.

Ada tiga jenis utama penawaran privat yang tersedia di Pusat Mitra dan didukung oleh API pengiriman penawaran privat:

ISV ke penawaran pribadi pelanggan – Juga disebut penawaran pribadi Pelanggan di Pusat Mitra. Ini adalah kesepakatan kustom antara ISV dan pelanggan tertentu dengan persyaratan dan harga yang disesuaikan untuk produk tertentu di Azure Marketplace. Pelajari lebih lanjut tentang penawaran pribadi ISV ke pelanggan.
Penawaran pribadi ISV ke mitra CSP – Juga disebut penawaran pribadi Mitra CSP di Pusat Mitra. Jenis penawaran pribadi ini memungkinkan ISV menentukan margin terikat waktu untuk membuat harga grosir untuk mitra CSP mereka. Pelajari lebih lanjut tentang penawaran pribadi mitra ISV ke CSP.
Penawaran pribadi multipihak(MPO) – Kesepakatan kustom yang dikonfigurasi secara kolaboratif oleh ISV dan mitra saluran pilihan pelanggan tertentu dengan persyaratan dan harga yang disesuaikan untuk produk tertentu di Azure Marketplace. ISV menentukan harga grosir diskon yang tersedia untuk mitra, mitra saluran kemudian dapat menambahkan markup di atas harga grosir untuk mencapai harga pelanggan akhir dan menyajikan penawaran kepada pelanggan untuk diterima dan dibeli. Penerimaan dan pembelian MPO mengikuti aliran yang sama seperti ISV ke penawaran pribadi pelanggan. Pelajari penawaran pribadi multipihak lebih lanjut.

Terminologi

Originator MPO – MPO adalah kolaborasi antara ISV dan mitra saluran pada kesepakatan khusus yang sama untuk pelanggan tertentu, pihak yang pertama kali membuat MPO ditunjuk sebagai "pencetus" penawaran, biasanya ISV dari produk yang termasuk dalam MPO. Hanya ada satu pencetus untuk MPO tertentu.
Penjual MPO – Mitra saluran yang menyiapkan penawaran dengan harga pelanggan akhir dan menyajikan penawaran kepada pelanggan adalah penjual MPO. Hanya ada satu penjual untuk MPO tertentu.
Produk – Satu unit yang mewakili penawaran di Azure Marketplace. Ada satu produk per halaman daftar.
Paket – Versi tunggal dari produk tertentu. Mungkin ada beberapa paket untuk produk tertentu yang mewakili berbagai tingkat harga atau persyaratan.
Job – Tugas yang dibuat saat membuat permintaan di API ini. Saat menggunakan API ini untuk mengelola penawaran pribadi dan penawaran pribadi multipihak, pekerjaan dibuat untuk menyelesaikan permintaan. Setelah pekerjaan selesai, Anda bisa mendapatkan informasi lebih lanjut tentang penawaran pribadi (multipihak) yang relevan.

Skenario yang didukung

Bersiaplah untuk menggunakan API ini

Sebelum Anda menulis kode untuk memanggil API penawaran privat, pastikan Anda telah menyelesaikan prasyarat berikut. Prasyarat yang sama berlaku untuk semua mitra penerbitan.

Langkah 1: Lengkapi prasyarat untuk menggunakan API Penyerapan Produk Microsoft (satu kali)

Anda atau organisasi Anda harus memiliki direktori Microsoft Entra. Jika Anda sudah menggunakan Microsoft 365 atau layanan bisnis lainnya dari Microsoft, Anda sudah memiliki direktori Microsoft Entra. Jika tidak, Anda dapat membuat ID Microsoft Entra baru di Pusat Mitra secara gratis.

Anda harus mengaitkan aplikasi ID Microsoft Entra dengan akun Pusat Mitra Anda dan mendapatkan ID penyewa, ID klien, dan kunci Anda. Anda memerlukan nilai-nilai ini untuk mendapatkan token akses Microsoft Entra yang akan Anda gunakan dalam panggilan ke API penawaran pribadi.

Langkah 2: Dapatkan token akses Microsoft Entra (setiap saat)

Sebelum memanggil salah satu metode di API pengiriman Microsoft Store, Anda memerlukan token akses Microsoft Entra untuk diteruskan ke header otorisasi setiap metode di API. Anda memiliki waktu 60 menit untuk menggunakan token sebelum kedaluwarsa. Setelah kedaluwarsa, Anda dapat me-refresh token sehingga Anda dapat terus menggunakannya dalam panggilan lebih lanjut ke API.

Untuk mendapatkan token akses, lihat Panggilan Layanan ke Layanan Menggunakan Kredensial Klien untuk mengirim HTTP POST ke https://login.microsoftonline.com/<titik akhir tenant_id>/oauth2/token . Berikut adalah contoh permintaan:

POST https://login.microsoftonline.com/<tenant_id>/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8
grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&resource=https://graph.microsoft.com/

Untuk nilai tenant_id dalam URI POST dan parameter client_id dan client_secret, tentukan ID penyewa, ID klien, dan kunci untuk aplikasi Anda yang Anda ambil dari Pusat Mitra di bagian sebelumnya. Untuk parameter sumber daya, Anda harus menentukan https://graph.microsoft.com/.

Menemukan ID produk, paket, dan penawaran pribadi

ID	Di mana menemukannya
ID klien	Lihat Kaitkan aplikasi Microsoft Entra dengan akun Pusat Mitra Anda.
ID Penyewa	Lihat Kaitkan aplikasi Microsoft Entra dengan akun Pusat Mitra Anda.
client_secret (kunci rahasia klien)	Lihat Kaitkan aplikasi Microsoft Entra dengan akun Pusat Mitra Anda.
ID produk	Lihat Mengambil produk di artikel ini.
planId	Lihat Mengambil paket untuk produk tertentu di artikel ini.
privateofferId	Lihat Mengambil penawaran pribadi di artikel ini.

Ambil produk

Penawaran pribadi didasarkan pada produk yang ada di akun Pusat Mitra Anda. Untuk melihat daftar produk yang terkait dengan akun Pusat Mitra Anda, gunakan panggilan API ini:

GET https://graph.microsoft.com/rp/product-ingestion/product?$version=2022-07-01

Respons muncul dalam format sampel berikut:

{
  "value": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/product/2022-07-01",
      "id": "string",
      "identity": {
        "externalId": "string"
      },
      "type": "enum",
      "alias": "string"
    }
  ],
  "@nextLink": "opaque_uri"
}

Mengambil paket untuk produk tertentu

Untuk produk yang berisi lebih dari satu paket, Anda mungkin ingin membuat penawaran pribadi berdasarkan satu paket tertentu. Jika demikian, Anda memerlukan ID paket tersebut. Dapatkan daftar paket (seperti varian atau SKU) untuk produk menggunakan panggilan API berikut:

GET https://graph.microsoft.com/rp/product-ingestion/plan?product=<product-id>&$version=2022-07-01

Respons muncul dalam format sampel berikut:

{
  "value": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/plan/2022-07-01",
      "product": "string",
      "id": "string",
      "identity": {
        "externalId": "string"
      },
      "alias": "string"
    }
  ]
}

Ambil penawaran pribadi

Untuk melihat daftar semua penawaran pribadi, termasuk penawaran pribadi multipihak, yang terkait dengan akun Anda, gunakan panggilan API berikut:

GET https://graph.microsoft.com/rp/product-ingestion/private-offer/query?$version=2023-07-15

Cara menggunakan API

API penawaran pribadi memungkinkan Anda membuat dan mengelola penawaran pribadi yang terkait dengan produk dan paket dalam akun Pusat Mitra Anda. Berikut adalah ringkasan pola panggilan umum saat menggunakan API ini.

Langkah 1: Buat permintaan

Saat Anda melakukan panggilan API untuk membuat, menghapus, menarik, atau meningkatkan penawaran pribadi, pekerjaan baru dibuat untuk menyelesaikan tugas yang diminta. Respons API berisi jobId yang terkait dengan pekerjaan.

Langkah 2: Jajak pendapat untuk status pekerjaan

Menggunakan jobId dari respons API awal, polling untuk mendapatkan status pekerjaan. Status pekerjaan akan menjadi Berjalan atau Selesai. Setelah pekerjaan selesai, hasilnya akan berhasil atau gagal. Untuk menghindari masalah kinerja, jangan melakukan jajak pendapat lebih dari sekali per menit.

jobStatus	Deskripsi
Belum Mulai	Pekerjaan belum dimulai; Ini adalah bagian dari respons pada permintaan awal.
Berlari	Pekerjaan masih berjalan.
Selesai	Pekerjaan telah selesai. Lihat jobResult untuk detail selengkapnya.
jobResult	Deskripsi
Tertunda	Pekerjaan belum selesai.
Berhasil	Pekerjaan telah berhasil diselesaikan. Pekerjaan ini juga mengembalikan resourceURI yang mengacu pada penawaran pribadi yang terkait dengan pekerjaan. Gunakan resourceURI ini untuk mendapatkan detail lengkap penawaran pribadi.
Kegagalan	Pekerjaan telah gagal. Ini juga mengembalikan kesalahan yang relevan untuk membantu menentukan penyebab kegagalan.

Untuk informasi selengkapnya, lihat Mengkueri status pekerjaan yang ada.

Langkah 3: Dapatkan informasi dari pekerjaan yang telah selesai

Pekerjaan yang berhasil mengembalikan resourceUri yang mereferensikan penawaran pribadi yang relevan. Gunakan Uri sumber daya ini untuk mendapatkan detail selengkapnya tentang penawaran pribadi di masa mendatang, seperti privateofferId.

Pekerjaan yang gagal berisi kesalahan yang memberikan detail tentang mengapa pekerjaan gagal dan cara mengatasi masalah tersebut.

Untuk informasi selengkapnya, lihat Mendapatkan detail penawaran pribadi yang ada.

Bagaimana ISV dan partner saluran harus secara kolaboratif menggunakan API untuk penawaran pribadi multipihak

ISV dan mitra saluran dapat menggunakan API yang sama untuk pembuatan dan pengelolaan MPO tertentu. Namun, sumber daya dalam MPO yang dapat memengaruhi API bergantung pada apakah pemanggil API adalah ISV (originator) atau partner saluran (penjual) MPO. Alur penerbitan ISV/mitra saluran yang sama dan aturan bisnis yang mengatur Pusat Mitra dicerminkan dalam API. Berikut ikhtisarnya:

Operasi API	ISV (Pencetus)	Partner saluran (Penjual)
Buat	Audiens yang dituju adalah partnerpenjual (penjual) saat panggilan API diposting, pelanggan akhir tidak akan melihat penawaran pribadi hingga partner saluran mengirimkan Sumber daya yang dapat diedit: Tanggal berlaku Penerima manfaat yang dituju (pelanggan) Mitra saluran untuk berkolaborasi dalam penawaran, dibatasi hingga 1 per penawaran pribadi Kontak ISV tambahan untuk diberi tahu tentang status penawaran pribadi Syarat dan ketentuan kustom ISV Produk/paket termasuk dalam penawaran pribadi Durasi kontrak untuk setiap produk/paket Jumlah yang disertakan untuk setiap produk (jika ada) Atribut paket non-harga (jika ada) Harga grosir diskon tersedia untuk mitra saluran pada produk/paket yang disertakan Catatan penjualan ISV	Audiens yang dituju adalah pelanggan akhir saat panggilan API diposting Sumber daya yang dapat diedit: Syarat dan ketentuan khusus mitra saluran Disiapkan oleh Penyesuaian pelanggan (persentase markup) di atas harga grosir ISV untuk setiap produk/paket yang termasuk dalam penawaran pribadi, ini menentukan harga akhir pelanggan akhir Kontak partner saluran tambahan untuk diberi tahu tentang status penawaran pribadi Catatan penjualan mitra saluran
Menghapus	Didukung untuk penawaran pribadi dalam status draf	Tidak didukung
Menarik	Didukung untuk penawaran pribadi yang diterbitkan oleh ISV tetapi belum dipublikasikan oleh partner channel atau jika ditarik oleh partner channel	Didukung untuk penawaran pribadi yang dipublikasikan dan tersedia untuk pelanggan akhir tetapi belum diterima

Operasi API

ISV (Pencetus)

Partner saluran (Penjual)

Buat

Audiens yang dituju adalah partnerpenjual (penjual) saat panggilan API diposting, pelanggan akhir tidak akan melihat penawaran pribadi hingga partner saluran mengirimkan

Sumber daya yang dapat diedit:

Tanggal berlaku
Penerima manfaat yang dituju (pelanggan)
Mitra saluran untuk berkolaborasi dalam penawaran, dibatasi hingga 1 per penawaran pribadi
Kontak ISV tambahan untuk diberi tahu tentang status penawaran pribadi
Syarat dan ketentuan kustom ISV
Produk/paket termasuk dalam penawaran pribadi
Durasi kontrak untuk setiap produk/paket
Jumlah yang disertakan untuk setiap produk (jika ada)
Atribut paket non-harga (jika ada)
Harga grosir diskon tersedia untuk mitra saluran pada produk/paket yang disertakan
Catatan penjualan ISV

Audiens yang dituju adalah pelanggan akhir saat panggilan API diposting