Berikan produk gratis

  • Artikel

Gunakan metode ini dalam 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 memerlukan:

  • Token akses Azure AD 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
KIRIM https://purchase.mp.microsoft.com/v6.0/purchases/grant

Meminta header

Header Jenis Deskripsi
Authorization string Wajib diisi. Token akses Azure AD dalam bentuktoken>Pembawa<.
Host string Harus diatur ke nilai purchase.mp.microsoft.com.
Panjang-Konten nomor Panjang isi permintaan.
Jenis-Konten string Menentukan jenis permintaan dan respons. Saat ini, satu-satunya nilai yang didukung adalah aplikasi/json.

Isi permintaan

Parameter Jenis Deskripsi Diperlukan
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
orderId guid GUID yang dihasilkan untuk pesanan. Nilai ini unik untuk pengguna, tetapi tidak diharuskan unik di semua pesanan. Ya
productId string ID Bursa untuk produk di katalog Microsoft Store. Contoh ID Store untuk produk adalah 9NBLGGH42CFD. Ya
quantity int Kuantitas untuk dibeli. Saat ini, satu-satunya nilai yang didukung adalah 1. Jika tidak ditentukan, defaultnya adalah 1. Tidak
skuId string ID Toko untuk SKU produk di katalog Microsoft Store. Contoh ID Store 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 Diperlukan
clientContext ClientContextV6 Informasi kontekstual klien untuk pesanan ini. Ini akan ditetapkan ke nilai clientID dari token Azure AD. Ya
waktu pembuatan tanggalwaktulewat Waktu urutan 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, "AS"). Ya
orderId 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 Mengedit, CheckingOut, Tertunda, Dibeli, Dikembalikan,Ditagih Balik, dan Dibatalkan. 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 decimal Jumlah total pembelian semua item dalam pesanan termasuk pajak. Ya
totalAmountBeforeTax decimal Jumlah total pembelian semua item dalam pesanan sebelum pajak. Ya
totalChargedToCsvTopOffPI decimal Jika menggunakan alat pembayaran terpisah dan nilai tersimpan (CSV), jumlah yang dibebankan ke CSV. Ya
totalTaxAmount decimal Jumlah total pajak untuk semua item baris. Ya

Objek ClientContext berisi parameter berikut.

Parameter Jenis Deskripsi Diperlukan
Klien string ID klien yang membuat pesanan. Tidak

Objek OrderLineItemV6 berisi parameter berikut.

Parameter Jenis Deskripsi Diperlukan
agen IdentityV6 Agen yang terakhir mengedit item baris. Untuk informasi selengkapnya tentang objek ini, lihat tabel di bawah ini. Tidak
availabilityId string ID ketersediaan produk yang akan dibeli dari katalog Microsoft Store. Ya
penerima IdentityV6 Identitas penerima pesanan. Tidak
billingState string Status penagihan pesanan. Ini diatur ke Ditagih setelah selesai. Tidak
campaignId string ID kampanye untuk pesanan ini. Tidak
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. Tidak
fulfillmentDate tanggalwaktulewat Tanggal pemenuhan terjadi. Tidak
fulfillmentState string Status pemenuhan item ini. Ini diatur ke Terpenuhi setelah selesai. Tidak
isPIRequired boolean Menunjukkan apakah alat pembayaran diperlukan untuk item baris ini. Ya
isTaxIncluded boolean Ditunjukkan apakah pajak disertakan dalam detail harga item. Ya
legacyBillingOrderId string ID penagihan warisan. Tidak
lineItemId string ID item baris untuk item dalam urutan ini. Ya
listPrice decimal Harga daftar item dalam urutan ini. Ya
productId string ID Toko untuk produk yang mewakili item baris dalam katalog Microsoft Store. Contoh ID Penyimpanan untuk produk adalah 9NBLGGH42CFD. Ya
productType string Jenis produk. Nilai yang didukung adalah Durable, Application, dan UnmanagedConsumable. Ya
quantity int Kuantitas item yang diurutkan. Ya
retailPrice decimal Harga eceran barang yang dipesan. Ya
revenueRecognitionState string Status pengenalan pendapatan. Ya
skuId string ID Penyimpanan untuk SKU item baris di katalog Microsoft Store. Contoh ID Store untuk SKU adalah 0010. Ya
taxAmount decimal Jumlah pajak untuk item baris. Ya
taxType string Jenis pajak untuk pajak yang berlaku. Ya
Judul string Judul item baris yang dilokalkan. Ya
totalAmount decimal Jumlah total pembelian item baris termasuk pajak. Ya

Objek IdentityV6 berisi parameter berikut.

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

Contoh respons

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 galat

Kode Kesalahan Kode kesalahan dalam Deskripsi
401 Tidak diizinkan AuthenticationTokenInvalid Token akses Azure AD 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 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.