Berikan produk gratis

Artikel
07/05/2024

Gunakan metode ini di API pembelian Microsoft Store untuk memberikan aplikasi atau add-on gratis (juga dikenal sebagai produk dalam aplikasi atau IAP) kepada pengguna tertentu.

Saat ini, Anda hanya dapat memberikan produk gratis. Jika layanan Anda mencoba menggunakan metode ini untuk memberikan produk yang tidak gratis, metode ini akan mengembalikan kesalahan.

Prasyarat

Untuk menggunakan metode ini, Anda akan memerlukan:

Token akses Azure ACTIVE Directory yang memiliki nilai https://onestore.microsoft.comURI audiens .
Kunci ID Microsoft Store yang mewakili identitas pengguna yang ingin Anda berikan produk gratis.

Untuk informasi selengkapnya, lihat Mengelola pemberian izin produk dari layanan.

Minta

Minta sintaks

Metode	URI Permintaan
POST	`https://purchase.mp.microsoft.com/v6.0/purchases/grant`

Header permintaan

Header	Tipe	Deskripsi
Authorization	string	Harus diisi. Token akses Microsoft Azure ACTIVE Directory dalam bentuk token> Pembawa<.
Host	string	Harus diatur ke nilai purchase.mp.microsoft.com.
Panjang-Konten	number	Panjang isi permintaan.
Content-Type	string	Menentukan jenis permintaan dan respons. Saat ini, satu-satunya nilai yang didukung adalah aplikasi/json.

Isi permintaan

Parameter	Jenis	Deskripsi	Wajib diisi
availabilityId	string	ID ketersediaan produk yang akan diberikan dari katalog Microsoft Store.	Ya
b2bKey	string	Kunci ID Microsoft Store yang mewakili identitas pengguna yang ingin Anda berikan produknya.	Ya
devOfferId	string	ID penawaran yang ditentukan pengembang yang akan muncul di item Koleksi setelah pembelian.
bahasa	string	Bahasa pengguna.	Ya
market	string	Pasar pengguna.	Ya
Id pemesanan	guid	GUID yang dihasilkan untuk pesanan. Nilai ini unik untuk pengguna, tetapi tidak diharuskan unik di semua pesanan.	Ya
productId	string	ID Toko untuk produk di katalog Microsoft Store. Contoh ID Penyimpanan untuk produk adalah 9NBLGGH42CFD.	Ya
kuantitas	int	Kuantitas untuk dibeli. Saat ini, satu-satunya nilai yang didukung adalah 1. Jika tidak ditentukan, defaultnya adalah 1.	No
skuId	string	ID Toko untuk SKU produk di katalog Microsoft Store. Contoh ID Penyimpanan untuk SKU adalah 0010.	Ya

Contoh permintaan

POST https://purchase.mp.microsoft.com/v6.0/purchases/grant HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJK……
Content-Length: 1863
Content-Type: application/json

{
    "b2bKey" : "eyJ0eXAiOiJK……",
    "availabilityId" : "9RT7C09D5J3W",
    "productId" : "9NBLGGH5WVP6",
    "skuId" : "0010",
    "language" : "en-us",
    "market" : "us",
    "orderId" : "3eea1529-611e-4aee-915c-345494e4ee76",
}

Respons

Isi respons

Parameter	Jenis	Deskripsi	Wajib diisi
clientContext	ClientContextV6	Informasi kontekstual klien untuk pesanan ini. Ini akan ditetapkan ke nilai clientID dari token Microsoft Azure AD.	Ya
waktu pembuatan	tanggalwaktulewat	Waktu pesanan dibuat.	Ya
currencyCode	string	Kode mata uang untuk totalAmount dan totalTaxAmount. N/A untuk item gratis.	Ya
friendlyName	string	Nama yang mudah diingat untuk pesanan. N/A untuk pesanan yang dibuat menggunakan API pembelian Microsoft Store.	Ya
isPIRequired	Boolean	Menunjukkan apakah instrumen pembayaran (PI) diperlukan sebagai bagian dari pesanan pembelian.	Ya
bahasa	string	ID bahasa untuk pesanan (misalnya, "en").	Ya
market	string	ID pasar untuk pesanan (misalnya, "US").	Ya
Id pemesanan	string	ID yang mengidentifikasi pesanan untuk pengguna tertentu.	Ya
orderLineItems	daftar<OrderLineItemV6>	Daftar item baris untuk pesanan. Biasanya ada 1 item baris per pesanan.	Ya
orderState	string	Status pesanan. Status yang valid adalah Editing, CheckingOut, Pending, Purchased, Refunded, ChargedBack, dan Cancelled.	Ya
orderValidityEndTime	string	Terakhir kali harga pesanan valid sebelum dikirimkan. N/A untuk aplikasi gratis.	Ya
orderValidityStartTime	string	Pertama kali harga pesanan valid sebelum dikirimkan. N/A untuk aplikasi gratis.	Ya
pembeli	IdentityV6	Objek yang menjelaskan identitas pembeli.	Ya
totalAmount	desimal	Jumlah total pembelian semua item dalam pesanan termasuk pajak.	Ya
totalAmountBeforeTax	desimal	Jumlah total pembelian semua item dalam pesanan sebelum pajak.	Ya
totalChargedToCsvTopOffPI	desimal	Jika menggunakan instrumen pembayaran terpisah dan nilai tersimpan (CSV), jumlah yang dibebankan ke CSV.	Ya
totalTaxAmount	desimal	Jumlah total pajak untuk semua item baris.	Ya

Objek ClientContext berisi parameter berikut.

Parameter	Jenis	Deskripsi	Wajib diisi
klien	string	ID klien yang membuat pesanan.	No

Objek OrderLineItemV6 berisi parameter berikut.

Parameter	Jenis	Deskripsi	Wajib diisi
agen	IdentityV6	Agen yang terakhir mengedit item baris. Untuk informasi selengkapnya tentang objek ini, lihat tabel di bawah ini.	No
availabilityId	string	ID ketersediaan produk yang akan dibeli dari katalog Microsoft Store.	Ya
penerima	IdentityV6	Identitas penerima pesanan.	No
billingState	string	Status penagihan pesanan. Ini diatur ke Ditagih setelah selesai.	No
campaignId	string	ID kampanye untuk pesanan ini.	No
currencyCode	string	Kode mata uang yang digunakan untuk detail harga.	Ya
description	string	Deskripsi item baris yang dilokalkan.	Ya
devofferId	string	ID penawaran untuk pesanan tertentu, jika ada.	No
fulfillmentDate	tanggalwaktulewat	Tanggal pemenuhan terjadi.	No
fulfillmentState	string	Status pemenuhan item ini. Ini diatur ke Terpenuhi setelah selesai.	No
isPIRequired	Boolean	Menunjukkan apakah instrumen pembayaran diperlukan untuk item baris ini.	Ya
isTaxIncluded	Boolean	Ditunjukkan apakah pajak disertakan dalam detail harga item.	Ya
legacyBillingOrderId	string	ID penagihan warisan.	No
lineItemId	string	ID item baris untuk item dalam urutan ini.	Ya
listPrice	desimal	Harga daftar item dalam urutan ini.	Ya
productId	string	ID Penyimpanan untuk produk yang mewakili item baris di katalog Microsoft Store. Contoh ID Penyimpanan untuk produk adalah 9NBLGGH42CFD.	Ya
productType	string	Jenis produk. Nilai yang didukung adalah Durable, Application, dan UnmanagedConsumable.	Ya
kuantitas	int	Kuantitas item yang diurutkan.	Ya
retailPrice	desimal	Harga eceran item yang dipesan.	Ya
revenueRecognitionState	string	Status pengenalan pendapatan.	Ya
skuId	string	ID Penyimpanan untuk SKU item baris di katalog Microsoft Store. Contoh ID Penyimpanan untuk SKU adalah 0010.	Ya
taxAmount	desimal	Jumlah pajak untuk item baris.	Ya
taxType	string	Jenis pajak untuk pajak yang berlaku.	Ya
Judul	string	Judul item baris yang dilokalkan.	Ya
totalAmount	desimal	Jumlah total pembelian item baris termasuk pajak.	Ya

Objek IdentityV6 berisi parameter berikut.

Parameter	Jenis	Deskripsi	Wajib diisi
identityType	string	Berisi nilai "pub".	Ya
identityValue	string	Nilai string publisherUserId dari kunci ID Microsoft Store yang ditentukan.	Ya

Contoh tanggapan

Content-Length: 1203
Content-Type: application/json
MS-CorrelationId: fb2e69bc-f26a-4aab-a823-7586c19f5762
MS-RequestId: c1bc832c-f742-47e4-a76c-cf061402f698
MS-CV: XjfuNWLQlEuxj6Mt.8
MS-ServerId: 030032362
Date: Tue, 13 Oct 2015 21:21:51 GMT

{
    "clientContext": {
        "client": "86b78998-d05a-487b-b380-6c738f6553ea"
    },
    "createdTime": "2015-10-13T21:21:51.1863494+00:00",
    "currencyCode": "USD",
    "isPIRequired": false,
    "language": "en-us",
    "market": "us",
    "orderId": "3eea1529-611e-4aee-915c-345494e4ee76",
    "orderLineItems": [{
        "availabilityId": "9RT7C09D5J3W",
        "beneficiary": {
            "identityType": "pub",
            "identityValue": "user1"
        },
        "billingState": "Charged",
        "currencyCode": "USD",
        "description": "Jewels, Jewels, Jewels - Consumable 2",
        "fulfillmentDate": "2015-10-13T21:21:51.639478+00:00",
        "fulfillmentState": "Fulfilled",
        "isPIRequired": false,
        "isTaxIncluded": true,
        "lineItemId": "2814d758-3ee3-46b3-9671-4fb3bdae9ffe",
        "listPrice": 0.0,
        "payments": [],
        "productId": "9NBLGGH5WVP6",
        "productType": "UnmanagedConsumable",
        "quantity": 1,
        "retailPrice": 0.0,
        "revenueRecognitionState": "None",
        "skuId": "0010",
        "taxAmount": 0.0,
        "taxType": "NoApplicableTaxes",
        "title": "Jewels, Jewels, Jewels - Consumable 2",
        "totalAmount": 0.0
    }],
    "orderState": "Purchased",
    "orderValidityEndTime": "2015-10-14T21:21:51.1863494+00:00",
    "orderValidityStartTime": "2015-10-13T21:21:51.1863494+00:00",
    "purchaser": {
        "identityType": "pub",
        "identityValue": "user1"
    },
    "testScenarios": "None",
    "totalAmount": 0.0,
    "totalTaxAmount": 0.0
}

Kode kesalahan

Kode	Kesalahan	Kode kesalahan dalam	Deskripsi
401	Tidak diizinkan	AuthenticationTokenInvalid	Token akses Azure ACTIVE Directory tidak valid. Dalam beberapa kasus, detail ServiceError akan berisi informasi lebih lanjut, seperti ketika token kedaluwarsa atau klaim appid hilang.
401	Tidak diizinkan	PartnerAadTicketRequired	Token akses Azure AD tidak diteruskan ke layanan di header otorisasi.
401	Tidak diizinkan	InconsistentClientId	Klaim clientId di kunci ID Microsoft Store di isi permintaan dan klaim appid di token akses Microsoft Azure AD di header otorisasi tidak cocok.
400	BadRequest	InvalidParameter	Detail berisi informasi mengenai isi permintaan dan bidang mana yang memiliki nilai yang tidak valid.

Bagikan melalui

Berikan produk gratis

Prasyarat

Minta

Minta sintaks

Header permintaan

Isi permintaan

Contoh permintaan

Respons

Isi respons

Contoh tanggapan

Kode kesalahan

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Berikan produk gratis

Prasyarat

Minta

Minta sintaks

Header permintaan

Isi permintaan

Contoh permintaan

Respons

Isi respons

Contoh tanggapan

Kode kesalahan

Topik terkait

Saran dan Komentar

Sumber Daya Tambahan: