Verifikasi kelayakan promosi

Artikel
03/21/2024

Berlaku untuk

Pusat Mitra

Peran yang sesuai

Admin global
Agen admin

Catatan

Pengalaman perdagangan baru untuk layanan berbasis lisensi mencakup banyak kemampuan baru dan tersedia untuk semua Penyedia Solusi Cloud (CSP). Untuk informasi selengkapnya, lihat gambaran umum pengalaman perdagangan baru.

Parter dapat memverifikasi apakah transaksi pelanggan memenuhi syarat untuk promosi tertentu. Metode ini mengembalikan True jika transaksi pelanggan memenuhi syarat untuk promosi tertentu. Mitra dapat memverifikasi kelayakan sebelum mengirimkan transaksi untuk memastikan promosi akan diterapkan.

Prasyarat

Kredensial seperti yang dijelaskan dalam autentikasi Pusat Mitra. Skenario ini mendukung autentikasi dengan kredensial Aplikasi mandiri dan Aplikasi+Pengguna.
Kelayakan mencakup ketersediaan sku produk yang dibeli, ID promosi yang dievaluasi, kuantitas, durasi jangka waktu, dan siklus penagihan transaksi.
Tingkat pembatasan untuk API ini maksimum 625 permintaan per menit (RPM) per penyewa mitra. Panggilan yang melebihi batas akan menghasilkan respons http 429. Lihat panduan pembatasan untuk informasi tentang pembatasan.

Permintaan REST

Minta sintaks

Metode	URI Permintaan
POST	{baseURL}/v1/customers/{customerId}/promotionEligibilities HTTP/1.1

Parameter URI

Gunakan parameter kueri berikut untuk mengembalikan promosi yang tersedia.

Nama	Tipe	Wajib	Deskripsi
customerId	tali	Y	Nilainya adalah id penyewa pelanggan berformat GUID, yang merupakan pengidentifikasi yang memungkinkan Anda menentukan pelanggan.

Header permintaan

Untuk informasi selengkapnya, lihat Header REST Pusat Mitra.

Isi permintaan

Isi mencakup kumpulan PromotionEligibilitiesRequestItems. Tabel ini menjelaskan properti untuk PromotionEligibilitiesRequestItem.

Properti	Tipe	Wajib	Deskripsi
catalogItemId	string	Ya	Pengidentifikasi item katalog.
kuantitas	int	Ya	Jumlah lisensi atau instans.
termDuration	DateTime	Ya	Representasi ISO 8601 dari durasi istilah. Nilai yang didukung saat ini adalah P1M (satu bulan), P1Y (satu tahun) dan P3Y (tiga tahun).
billingCycle	string	Ya	Nilai yang menunjukkan jenis siklus penagihan.
promotionId	string	No	Pengidentifikasi item promosi.

Contoh permintaan

POST https://api.partnercenter.microsoft.com/v1/customers/46632f71-f052-4384-8f84-4cdb6c12c2a1/promotionEligibilities HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70a
MS-CorrelationId: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e132
X-Locale: en-US

 // Request example with promotion ID input
{
    "items": [
        {
            "catalogItemId": "CFQ7TTC0LH2Z:0002:CFQ7TTC0HRVK",
            "quantity": 2400,
            "termDuration": "P1Y",
            "billingCycle": "Monthly",
            "promotionId": "39NFJQT1PM6C:0005:39NFJQT1Q5L7"
        }
    ]
}

POST https://api.partnercenter.microsoft.com/v1/customers/46632f71-f052-4384-8f84-4cdb6c12c2a1/promotionEligibilities HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70b
MS-CorrelationId: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e133
X-Locale: en-US

 // Request example with no promotion ID input
{
    "items": [
        {
            "id": "0",
            "catalogItemId": "CFQ7TTC0HBSJ:0001:CFQ7TTC0JQH3",
            "quantity": 300,
            "termDuration": "P1M",
            "billingCycle": "monthly"
        }
    ]
}

Respons REST

Jika promotionId disediakan dan permintaan berhasil, metode ini mengembalikan kumpulan hasil kelayakan. Jika promotionId tidak disediakan dan permintaan berhasil, metode ini mengembalikan semua promosi yang tersedia untuk penawaran yang ditentukan dan kelayakan pelanggan yang sesuai untuk setiap promosi.

Kode kesalahan dan keberhasilan respons

Setiap respons dilengkapi dengan kode status HTTP yang menunjukkan keberhasilan atau kegagalan dan informasi penelusuran kesalahan lainnya. Gunakan alat pelacakan jaringan untuk membaca kode ini, jenis kesalahan, dan lebih banyak parameter. Untuk daftar lengkapnya, lihat Kode Kesalahan.

Jenis dan deskripsi kesalahan kelayakan

Kelayakan akan mengembalikan false jika pemeriksaan kelayakan menentukan SKU produk yang dievaluasi terhadap ID promosi tidak selaras. Berbagai kondisi dan batasan dievaluasi dan mengembalikan jenis kesalahan untuk menjelaskan kondisi yang tidak terpenuhi untuk kelayakan.

Jenis kesalahan kelayakan	Deskripsi kesalahan kelayakan
InvalidCatalogItemId	CatalogItemId yang disediakan tidak valid.
InvalidPromotion	Promosi yang disediakan tidak valid.
PrerequisiteProductOwnership	Pelanggan tidak memenuhi persyaratan kepemilikan produk prasyarat agar memenuhi syarat untuk promosi ini.
RedemptionLimit	Batas penukaran untuk promosi ini telah terpenuhi.
SeatCount	Jumlah yang disediakan tidak memenuhi persyaratan kursi minimum atau maksimum untuk promosi.
OfferPurchasedPreviously	Penawaran ini telah dibeli sebelumnya untuk pelanggan ini.
Term	Istilah yang disediakan tidak berlaku untuk promosi.
NoPromotionsAvailable	Saat ini tidak ada promosi yang tersedia.

Contoh tanggapan

HTTP/1.1 200 OK
Content-Length: 138
Content-Type: application/json
MS-CorrelationId: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e132
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70a
Date: Fri, 26 Feb 2021 20:42:26 GMT

// Response example with promotion ID provided in the request
{
    "totalCount": 1,
    "items": [
        {
            "id": 0,
            "catalogItemId": "CFQ7TTC0LH2Z:0002:CFQ7TTC0HRVK",
            "quantity": 2400,
            "billingCycle": "monthly",
            "termDuration": "P1Y",
            "eligibilities": [
                {
                    "promotionId": "39NFJQT1PM6C:0005:39NFJQT1Q5L7",
                    "isEligible": false,
                    "errors": [
                        {
                            "minimumRequiredSeats": 1,
                            "maximumRequiredSeats": 2400,
                            "availableSeats": 500,
                            "type": "SeatCount",
                            "description": "The provided quantity does not satisfy the minimum or maximum seat requirements for the promotion."
                        }
                    ]
                }
            ],
            "attributes": {
                "objectType": "PromotionEligibilities"
            }
        }
    ],
    "attributes": {
        "objectType": "Collection"
    }
}

HTTP/1.1 200 OK
Content-Length: 138
Content-Type: application/json
MS-CorrelationId: 81b08ffe-4cf8-49cd-82db-5c2fb0a8e133
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70b
Date: Fri, 26 Feb 2021 20:42:26 GMT

// Response example with no promotion ID provided in the request
{
    "totalCount": 1,
    "items": [
        {
            "id": 0,
            "catalogItemId": "CFQ7TTC0HBSJ:0001:CFQ7TTC0JQH3",
            "quantity": 300,
            "billingCycle": "monthly",
            "termDuration": "P1M",
            "eligibilities": [
                {
                    "promotionId": "39NFJQT1XK5L:000J:39NFJQT1Q5D8",
                    "isEligible": true
                },
                {
                    "promotionId": "39NFJQT1XG89:0002:39NFJQT1Q5L2",
                    "isEligible": true
                }
            ],
            "attributes": {
                "objectType": "PromotionEligibilities"
            }
        }
    ],
    "attributes": {
        "objectType": "Collection"
    }
}

Bagikan melalui