Berikan produk gratis
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.com
URI 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. |