ส่งข้อมูลการบริโภค
API นี้ส่งข้อมูลการบริโภคของผู้ใช้ไปยัง App Store เมื่อผู้ใช้แอปขอเงินคืน
API การส่งข้อมูลการบริโภคใช้การสื่อสารแบบเซิร์ฟเวอร์ต่อเซิร์ฟเวอร์ระหว่างเซิร์ฟเวอร์ Hive และเซิร์ฟเวอร์แอป เซิร์ฟเวอร์ Hive ส่งคำขอข้อมูลการใช้ไปยังเซิร์ฟเวอร์แอป และเซิร์ฟเวอร์แอปจะส่งคืนการตอบกลับไปยังเซิร์ฟเวอร์ Hive
Info
การส่งข้อมูลการบริโภครองรับ Apple App Store และ Google Play เนื่องจากแต่ละร้านค้ามีข้อกำหนดข้อมูลทริกเกอร์และการตอบสนองที่แตกต่างกัน ให้เลือกร้านค้าที่คุณต้องการรวมจากแท็บด้านล่าง
Apple App Store¶
ข้อมูลการบริโภคบางอย่างที่ส่งไปยังร้านค้ามีอยู่บนเซิร์ฟเวอร์แอปเท่านั้น หากต้องการส่งข้อมูลนี้ไปยัง Apple App Store เซิร์ฟเวอร์แอปจะต้องจัดเตรียมข้อมูลดังกล่าวให้กับเซิร์ฟเวอร์ Hive
URL เซิร์ฟเวอร์แอปเป็นจุดสิ้นสุด API ที่เปิดโดยเซิร์ฟเวอร์แอปเพื่อให้ข้อมูลแก่เซิร์ฟเวอร์ Hive กำหนดค่าตำแหน่งข้อมูลตามข้อกำหนดด้านล่าง และลงทะเบียนเป็น URL ของเซิร์ฟเวอร์แอป เมื่อใดก็ตามที่ผู้ใช้ขอเงินคืน เซิร์ฟเวอร์ Hive จะส่งคำขอ POST ไปยังตำแหน่งข้อมูลนี้ และรับข้อมูลที่จำเป็นจากเซิร์ฟเวอร์แอป เซิร์ฟเวอร์ Hive รวบรวมข้อมูลนี้และส่งข้อมูลการใช้งานไปยัง Apple App Store ในนามของนักพัฒนาแอป
กระบวนการโดยรวมมีดังนี้
- แอป: กำหนดค่าตำแหน่งข้อมูล API ตามข้อกำหนดด้านล่าง และเตรียม URL ของเซิร์ฟเวอร์
- แอพ: ใน การตั้งค่าบริการเพิ่มเติม > การส่งข้อมูลการบริโภค ในคอนโซล Hive ให้เปิดใช้งาน Apple App Store และลงทะเบียน URL ของเซิร์ฟเวอร์
- ไคลเอนต์แอป: ในขณะที่แอปกำลังทำงาน obtain ยินยอมที่จะส่งข้อมูลการใช้ผลิตภัณฑ์ที่ซื้อในแอป
- ผู้ใช้แอป: ขอเงินคืนในแอป
- Apple: ส่งคำขอข้อมูลการใช้ (
CONSUMPTION_REQUEST) ไปยังเซิร์ฟเวอร์ Hive - เซิร์ฟเวอร์ Hive: ส่งคำขอ POST API ไปยัง URL เซิร์ฟเวอร์ที่ลงทะเบียนโดยแอป และรับข้อมูลการบริโภคในการตอบกลับจากเซิร์ฟเวอร์แอป
- เซิร์ฟเวอร์ Hive: ส่งข้อมูลปริมาณการใช้ไปยัง Apple App Store Apple ตอบสนองด้วย HTTP 202 เมื่อสำเร็จ
Warning
หากผู้ใช้แอปไม่ยินยอมให้ส่งข้อมูลในป๊อปอัปขอความยินยอม เซิร์ฟเวอร์ Hive จะไม่ส่งข้อมูลไปยังร้านค้า แม้ว่าจะได้รับข้อมูลจากเซิร์ฟเวอร์แอปก็ตาม เซิร์ฟเวอร์แอปไม่ต้องส่งสถานะความยินยอมของผู้ใช้ (customerConsented) เนื่องจากเซิร์ฟเวอร์ Hive จะกำหนดค่านี้โดยตรง
ปิดการใช้งานกฎไฟร์วอลล์¶
ตำแหน่งข้อมูล API ที่ลงทะเบียนเป็น URL ของเซิร์ฟเวอร์จะต้องดึงข้อมูลการใช้งานโดยใช้ข้อมูลผู้ใช้ (player_id) และข้อมูลธุรกรรม (transaction_id) ในพารามิเตอร์คำขอ และส่งคืนข้อมูลที่สอดคล้องกับข้อกำหนดด้านล่าง
หากต้องการอนุญาตให้เซิร์ฟเวอร์ Hive ส่งคำขอไปยังจุดสิ้นสุด API ของเซิร์ฟเวอร์แอป ให้ปิดใช้งานกฎขาเข้าของไฟร์วอลล์สำหรับที่อยู่ IP ต่อไปนี้บนเซิร์ฟเวอร์แอป
| IP เซิร์ฟเวอร์ Hive |
|---|
| 15.165.223.210 |
| 3.34.158.195 |
| 43.202.20.33 |
| 13.209.91.38 |
| 3.34.235.15 |
| 15.165.134.120 |
กำหนดค่าคำขอ API (เซิร์ฟเวอร์ Hive ไปยังเซิร์ฟเวอร์แอป)¶
ต่อไปนี้คือคำขอ POST ที่ส่งจากเซิร์ฟเวอร์ Hive ไปยังเซิร์ฟเวอร์แอป
| ข้อมูลเอพีไอ | คำอธิบาย |
|---|---|
| วิธี | โพสต์ |
| รูปแบบการตอบกลับ | เจสัน |
| ประเภทเนื้อหา | แอปพลิเคชัน/json |
ขอเนื้อความ¶
เนื้อความคำขอมีดังนี้
| ชื่อ | ประเภท | จำเป็น (M: บังคับ, O: ไม่บังคับ) | คำอธิบาย |
|---|---|---|---|
| gameindex | จำนวนเต็ม | M | App Center Game Index |
| appid | สตริง | M | รหัสแอป App Center |
| server_id | สตริง | M | รหัสเซิร์ฟเวอร์แอป |
| player_id | สตริง | M | ตัวระบุผู้ใช้ในแอป (ค่าระบุตัวตนผู้ใช้ที่ใช้ในการยืนยันการซื้อ) สอดคล้องกับ user_seq ใน V1 |
| transaction_id | สตริง | M | ID ธุรกรรมดั้งเดิมของ Apple (originalTransactionId) |
| hiveiap_transaction_id | สตริง | M | รหัสธุรกรรมที่สร้างขึ้นสำหรับการรับที่ตรวจสอบสำเร็จแต่ละรายการ ค่า hiveiap_transaction_id ที่ส่งคืนจาก Hive IAP v4 การตรวจสอบการรับ |
ต่อไปนี้เป็นตัวอย่างเนื้อหาคำขอ
{
"gameindex": 539,
"appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
"server_id": "server_01",
"player_id": "222333",
"transaction_id": "2000000123456789",
"hiveiap_transaction_id": "AP_13"
}
กำหนดค่าการตอบสนอง API (เซิร์ฟเวอร์แอปไปยังเซิร์ฟเวอร์ Hive)¶
เซิร์ฟเวอร์แอปจะส่งโค้ดผลลัพธ์การประมวลผล (code) ข้อความผลลัพธ์ (message) และข้อมูลการใช้ (data) ไปยังเซิร์ฟเวอร์ Hive
เนื้อหาตอบกลับ¶
เซิร์ฟเวอร์ Hive พิจารณาความสำเร็จจากค่า code หากค่าเป็น 200 แสดงว่าคำร้องขอสำเร็จ และเซิร์ฟเวอร์ใช้ data สำหรับโค้ดอื่นๆ เซิร์ฟเวอร์จะไม่ส่งรายการและบันทึก message เป็นเหตุผล จำเป็นต้องมี code หากละเว้น คำขอจะถือเป็นข้อผิดพลาดและรายการจะไม่ถูกส่ง
| ชื่อ | ประเภท | จำเป็น (M: บังคับ, O: ไม่บังคับ) | คำอธิบาย |
|---|---|---|---|
| code | จำนวนเต็ม | M | กำลังประมวลผลรหัสผลลัพธ์ มีเพียง 200 เท่านั้นที่บ่งบอกถึงความสำเร็จ รหัสอื่นๆ ทั้งหมดจะถือเป็นข้อผิดพลาด |
| message | สตริง | O | กำลังประมวลผลข้อความผลลัพธ์ อธิบายสาเหตุของข้อผิดพลาด |
| data | อ็อบเจ็กต์ | M | ข้อมูลการตอบสนอง (จำเป็นเมื่อสำเร็จ) |
| ┕ delivery_status | สตริง | M | สถานะการจัดส่งสินค้าสิ้นเปลือง หนึ่งในค่าใน Delivery status ด้านล่าง |
| ┕ refund_preference | สตริง | O | สิทธิพิเศษในการคืนเงิน หนึ่งในค่าใน การกำหนดลักษณะการคืนเงิน ด้านล่าง |
| ┕ consumption_percentage | จำนวนเต็ม | O | เปอร์เซ็นต์การบริโภค 0-100000 เป็นมิลลิเปอร์เซ็นต์ (100000 = 100%) |
| ┕ sample_content_provided | จำนวนเต็ม | O | ไม่ว่าจะให้เนื้อหาตัวอย่างหรือไม่ 0 หรือ 1 |
รหัสตอบกลับ¶
| ค่า | คำอธิบาย |
|---|---|
| 200 | ความสำเร็จ |
| 400 | ค่าคำขอไม่ถูกต้อง |
| 500 | ข้อผิดพลาดของเซิร์ฟเวอร์ |
สถานะการจัดส่ง (delivery_status)¶
ระบุสถานะการจัดส่งของไอเทมสิ้นเปลือง โดยฟิลด์บังคับนี้ต้องเป็นหนึ่งในห้าค่าต่อไปนี้
| ค่า | ความหมาย |
|---|---|
| DELIVERED | รายการวัสดุสิ้นเปลืองได้รับการจัดส่งและทำงานได้อย่างถูกต้อง |
| UNDELIVERED_QUALITY_ISSUE | สินค้าไม่ได้ถูกจัดส่งเนื่องจากปัญหาด้านคุณภาพ |
| UNDELIVERED_WRONG_ITEM | มีการจัดส่งสินค้าอื่นหรือไม่ถูกต้อง |
| UNDELIVERED_SERVER_OUTAGE | ไม่ได้ส่งสินค้าเนื่องจากการหยุดทำงานของเซิร์ฟเวอร์ |
| UNDELIVERED_OTHER | สินค้าไม่ได้ถูกจัดส่งด้วยเหตุผลอื่น |
สิทธิพิเศษในการคืนเงิน (refund_preference)¶
ส่งผลการคืนเงิน ที่ต้องการของแอปไปยัง Apple หากมีการส่งช่องที่ไม่บังคับนี้ จะต้องมีค่าใดค่าหนึ่งจากสามค่าต่อไปนี้
| ค่า | ความหมาย |
|---|---|
| GRANT_FULL | ต้องการคืนเงินเต็มจำนวน |
| DECLINE | ต้องการปฏิเสธการคืนเงิน |
| GRANT_PRORATED | ต้องการคืนเงินบางส่วนหรือตามสัดส่วน ส่วนใหญ่สำหรับการสมัครสมาชิก |
Warning
หากค่าใดๆ ต่อไปนี้ไม่ถูกต้อง สินค้าจะถูกแยกออกและจะไม่ถูกส่งไปยังร้านค้า
- จำเป็นต้องมี
delivery_statusและต้องมีค่าใดค่าหนึ่งจากห้าค่าข้างต้น - หากส่งแล้ว
refund_preferenceจะต้องมีค่าใดค่าหนึ่งจากสามค่าข้างต้น - หากส่งแล้ว
consumption_percentageต้องเป็นจำนวนเต็มตั้งแต่ 0 ถึง 100000
Note
เซิร์ฟเวอร์ Hive จะปรับค่าต่อไปนี้โดยอัตโนมัติตามกฎของ Apple
- ถ้า
delivery_statusไม่ใช่DELIVERED,consumption_percentageจะถูกส่งเป็น 0 - หาก
refund_preferenceคือGRANT_PRORATED(สมัครสมาชิก) จะละเว้นconsumption_percentage
ต่อไปนี้เป็นตัวอย่างเนื้อหาการตอบสนองสำหรับคำขอที่ประสบความสำเร็จ
Google Play¶
ข้อมูลการบริโภคบางอย่างที่ส่งไปยังร้านค้ามีอยู่บนเซิร์ฟเวอร์แอปเท่านั้น หากต้องการส่งข้อมูลนี้ไปยัง Google Play เซิร์ฟเวอร์แอปจะต้องจัดเตรียมข้อมูลดังกล่าวให้กับเซิร์ฟเวอร์ Hive
URL เซิร์ฟเวอร์แอปเป็นจุดสิ้นสุด API ที่เปิดโดยเซิร์ฟเวอร์แอปเพื่อให้ข้อมูลแก่เซิร์ฟเวอร์ Hive กำหนดค่าตำแหน่งข้อมูลตามข้อกำหนดด้านล่าง และลงทะเบียนเป็น URL ของเซิร์ฟเวอร์แอป เมื่อใดก็ตามที่มีการแจ้งเตือนการตรวจสอบการคืนเงินเกิดขึ้น เซิร์ฟเวอร์ Hive จะส่งคำขอ POST ไปยังตำแหน่งข้อมูลนี้ และรับข้อมูลที่จำเป็นจากเซิร์ฟเวอร์แอป เซิร์ฟเวอร์ Hive รวบรวมข้อมูลนี้และส่งข้อมูลการตรวจสอบการคืนเงินไปยัง Google ในนามของนักพัฒนาแอป
กระบวนการโดยรวมมีดังนี้
- แอป: กำหนดค่าตำแหน่งข้อมูล API ตามข้อกำหนดด้านล่าง และเตรียม URL ของเซิร์ฟเวอร์
- แอพ: ใน การตั้งค่าบริการเพิ่มเติม > การส่งข้อมูลการบริโภค ในคอนโซล Hive ให้เปิดใช้งาน Google Play และลงทะเบียน URL ของเซิร์ฟเวอร์
- ผู้ใช้แอป: ขอเงินคืน (ปฏิเสธการชำระเงิน) สำหรับการทำธุรกรรมโดยตรงจากสถาบันการเงิน เช่น ผู้ออกบัตรเครดิต
- Google: ส่งการแจ้งเตือนการตรวจสอบการคืนเงิน (
pendingRefundReviewNotification) ไปยังเซิร์ฟเวอร์ Hive - เซิร์ฟเวอร์ Hive: ส่งคำขอ POST API ไปยัง URL เซิร์ฟเวอร์ที่ลงทะเบียนโดยแอปและรับข้อมูลในการตอบกลับ
- เซิร์ฟเวอร์ Hive: ส่งข้อมูลการตรวจสอบการคืนเงินไปยัง Google ด้วย
orders:reviewrefundGoogle ตอบสนองด้วยเนื้อหา HTTP 200 ที่ว่างเปล่าเมื่อสำเร็จ
Note
การตรวจสอบการคืนเงิน Google Play ไม่จำเป็นต้องมีกระบวนการยินยอมในแอป เมื่อผู้ใช้ขอเงินคืน (ปฏิเสธการชำระเงิน) โดยตรงจากสถาบันการเงิน Google จะส่งการแจ้งเตือนการตรวจสอบการคืนเงินไปยังเซิร์ฟเวอร์ Hive เพื่อดำเนินการ
ปิดการใช้งานกฎไฟร์วอลล์¶
ตำแหน่งข้อมูล API ที่ลงทะเบียนเป็น URL ของเซิร์ฟเวอร์จะต้องดึงข้อมูลการใช้งานโดยใช้ข้อมูลผู้ใช้ (player_id) และข้อมูลธุรกรรม (order_id) ในพารามิเตอร์คำขอ และส่งคืนข้อมูลที่สอดคล้องกับข้อกำหนดด้านล่าง
หากต้องการอนุญาตให้เซิร์ฟเวอร์ Hive ส่งคำขอไปยังจุดสิ้นสุด API ของเซิร์ฟเวอร์แอป ให้ปิดใช้งานกฎขาเข้าของไฟร์วอลล์สำหรับที่อยู่ IP ต่อไปนี้บนเซิร์ฟเวอร์แอป
| IP เซิร์ฟเวอร์ Hive |
|---|
| 15.165.223.210 |
| 3.34.158.195 |
| 43.202.20.33 |
| 13.209.91.38 |
| 3.34.235.15 |
| 15.165.134.120 |
กำหนดค่าคำขอ API (เซิร์ฟเวอร์ Hive ไปยังเซิร์ฟเวอร์แอป)¶
ต่อไปนี้คือคำขอ POST ที่ส่งจากเซิร์ฟเวอร์ Hive ไปยังเซิร์ฟเวอร์แอป
| ข้อมูลเอพีไอ | คำอธิบาย |
|---|---|
| วิธี | โพสต์ |
| รูปแบบการตอบกลับ | เจสัน |
| ประเภทเนื้อหา | แอปพลิเคชัน/json |
เนื้อความคำขอมีดังนี้
| ชื่อ | ประเภท | จำเป็น (M: บังคับ, O: ไม่บังคับ) | คำอธิบาย |
|---|---|---|---|
| gameindex | จำนวนเต็ม | M | App Center Game Index |
| appid | สตริง | M | รหัสแอป App Center |
| server_id | สตริง | M | รหัสเซิร์ฟเวอร์แอป |
| player_id | สตริง | M | ตัวระบุผู้ใช้ในแอป (ค่าระบุตัวตนผู้ใช้ที่ใช้ในการยืนยันการซื้อ) สอดคล้องกับ user_seq ใน V1 |
| order_id | สตริง | M | รหัสคำสั่งซื้อของ Google (orderId) |
| hiveiap_transaction_id | สตริง | M | ค่า hiveiap_transaction_id ที่ส่งคืนจาก Hive IAP v4 การตรวจสอบการรับ |
ต่อไปนี้เป็นตัวอย่างเนื้อหาคำขอ
{
"gameindex": 539,
"appid": "com.com2us.hivesdk.normal.freefull.google.global.android.universal",
"server_id": "server_01",
"player_id": "222333",
"order_id": "GPA.3300-1234-5678-90123",
"hiveiap_transaction_id": "GO_13"
}
กำหนดค่าการตอบสนอง API (เซิร์ฟเวอร์แอปไปยังเซิร์ฟเวอร์ Hive)¶
เซิร์ฟเวอร์แอปจะส่งโค้ดผลลัพธ์การประมวลผล (code) ข้อความผลลัพธ์ (message) และข้อมูลการใช้ (data) ไปยังเซิร์ฟเวอร์ Hive
เซิร์ฟเวอร์ Hive พิจารณาความสำเร็จจากค่า code หากค่าเป็น 200 แสดงว่าคำร้องขอสำเร็จ และเซิร์ฟเวอร์ใช้ data สำหรับโค้ดอื่นๆ เซิร์ฟเวอร์จะไม่ส่งรายการและบันทึก message เป็นเหตุผล จำเป็นต้องมี code หากละเว้น คำขอจะถือเป็นข้อผิดพลาดและรายการจะไม่ถูกส่ง
| ชื่อ | ประเภท | จำเป็น (M: บังคับ, O: ไม่บังคับ) | คำอธิบาย |
|---|---|---|---|
| code | จำนวนเต็ม | M | กำลังประมวลผลรหัสผลลัพธ์ มีเพียง 200 เท่านั้นที่บ่งบอกถึงความสำเร็จ รหัสอื่นๆ ทั้งหมดจะถือเป็นข้อผิดพลาด |
| message | สตริง | O | กำลังประมวลผลข้อความผลลัพธ์ อธิบายสาเหตุของข้อผิดพลาด |
| data | อ็อบเจ็กต์ | M | ข้อมูลการตอบสนอง (จำเป็นเมื่อสำเร็จ) |
| ┕ refund_preference | สตริง | M | สิทธิพิเศษในการคืนเงิน หนึ่งในค่าใน การกำหนดลักษณะการคืนเงิน ด้านล่าง |
| ┕ sample_content_provided | จำนวนเต็ม | M | มีการจัดหาเนื้อหาตัวอย่างหรือไม่ 0 หรือ 1 |
| ┕ consumption_percentage_milliunits | จำนวนเต็ม | M | เปอร์เซ็นต์การบริโภค 0-100000 เป็นมิลลิเปอร์เซ็นต์ (100000 = 100%) |
| ┕ consumption_usage_events | อาร์เรย์ | O | รายการเหตุการณ์การบริโภค (สูงสุด 1,000) ดูเหตุการณ์การบริโภค ด้านล่าง |
รหัสตอบกลับ¶
| ค่า | คำอธิบาย |
|---|---|
| 200 | ความสำเร็จ |
| 400 | ค่าคำขอไม่ถูกต้อง |
| 500 | ข้อผิดพลาดของเซิร์ฟเวอร์ |
สิทธิพิเศษในการคืนเงิน (refund_preference)¶
ส่งผลการคืนเงินที่ต้องการของแอปไปยัง Google ช่องที่ต้องกรอกนี้ต้องมีค่าใดค่าหนึ่งจากสี่ค่าต่อไปนี้
| ค่า | ความหมาย |
|---|---|
| APPROVE | ต้องการอนุมัติการคืนเงิน |
| DECLINE | ต้องการปฏิเสธการคืนเงิน |
| NEUTRAL | ไม่มีการตั้งค่า (เป็นกลาง) |
| REFUND_PREFERENCE_UNSPECIFIED | ไม่ได้ระบุการตั้งค่า |
เหตุการณ์การบริโภค (consumption_usage_events)¶
เหตุการณ์ปริมาณการใช้แต่ละรายการประกอบด้วยฟิลด์ต่อไปนี้ ฟิลด์ทั้งหมดเป็นทางเลือก แต่หากมีการส่ง location จะต้องระบุ location.region_code
| ชื่อ | ประเภท | ที่จำเป็น | คำอธิบาย |
|---|---|---|---|
| obfuscated_account_id | สตริง | O | ตัวระบุบัญชีที่สับสน |
| obfuscated_profile_id | สตริง | O | ตัวระบุโปรไฟล์ที่สับสน |
| consumption_time | สตริง | O | ระยะเวลาการใช้ (RFC 3339 เช่น 2026-07-20T00:00:00Z) |
| ip_address | สตริง | O | ที่อยู่ IP ณ เวลาที่บริโภค |
| consumption_item_description | สตริง | O | คำอธิบายของรายการที่ใช้ไป |
| location | อ็อบเจ็กต์ | O | ข้อมูลสถานที่บริโภค |
| ┕ region_code | สตริง | M เมื่อรวม location ด้วย | รหัสภูมิภาค (CLDR เช่น KR) |
| ┕ administrative_area | สตริง | O | เขตการปกครอง |
| ┕ locality | สตริง | O | เมือง |
| ┕ sublocality | สตริง | O | ตำบลย่อย |
Warning
หากค่าใดๆ ต่อไปนี้ไม่ถูกต้อง รายการดังกล่าวจะถูกแยกออกและจะไม่ถูกส่งไปยัง Google
- จำเป็นต้องมี
refund_preferenceและต้องมีค่าใดค่าหนึ่งจากสี่ค่าข้างต้น - จำเป็นต้องมี
sample_content_providedและต้องเป็น 0 หรือ 1 - ต้องระบุ
consumption_percentage_milliunitsและต้องเป็นจำนวนเต็มตั้งแต่ 0 ถึง 100000 - หากส่งแล้ว
consumption_usage_eventsสามารถมีเหตุการณ์ได้สูงสุด 1,000 เหตุการณ์ หากเหตุการณ์มีlocationจำเป็นต้องมีlocation.region_code
ต่อไปนี้เป็นตัวอย่างเนื้อหาการตอบสนองสำหรับคำขอที่ประสบความสำเร็จ
{
"code": 200,
"message": "OK",
"data": {
"refund_preference": "APPROVE",
"sample_content_provided": 0,
"consumption_percentage_milliunits": 100000,
"consumption_usage_events": [
{
"consumption_time": "2026-07-20T00:00:00Z",
"ip_address": "203.0.113.10",
"consumption_item_description": "Sample consumed item",
"location": {
"region_code": "KR"
}
}
]
}
}