ข้ามไปที่เนื้อหา

ส่งข้อมูลการบริโภค

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 ในนามของนักพัฒนาแอป

กระบวนการโดยรวมมีดังนี้

  1. แอป: กำหนดค่าตำแหน่งข้อมูล API ตามข้อกำหนดด้านล่าง และเตรียม URL ของเซิร์ฟเวอร์
  2. แอพ: ใน การตั้งค่าบริการเพิ่มเติม > การส่งข้อมูลการบริโภค ในคอนโซล Hive ให้เปิดใช้งาน Apple App Store และลงทะเบียน URL ของเซิร์ฟเวอร์
  3. ไคลเอนต์แอป: ในขณะที่แอปกำลังทำงาน obtain ยินยอมที่จะส่งข้อมูลการใช้ผลิตภัณฑ์ที่ซื้อในแอป
  4. ผู้ใช้แอป: ขอเงินคืนในแอป
  5. Apple: ส่งคำขอข้อมูลการใช้ (CONSUMPTION_REQUEST) ไปยังเซิร์ฟเวอร์ Hive
  6. เซิร์ฟเวอร์ Hive: ส่งคำขอ POST API ไปยัง URL เซิร์ฟเวอร์ที่ลงทะเบียนโดยแอป และรับข้อมูลการบริโภคในการตอบกลับจากเซิร์ฟเวอร์แอป
  7. เซิร์ฟเวอร์ 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

ต่อไปนี้เป็นตัวอย่างเนื้อหาการตอบสนองสำหรับคำขอที่ประสบความสำเร็จ

{
        "code": 200,
        "message": "OK",
        "data": {
                "delivery_status": "DELIVERED",
                "refund_preference": "GRANT_FULL",
                "consumption_percentage": 100000,
                "sample_content_provided": 0
        }
}

Google Play

ข้อมูลการบริโภคบางอย่างที่ส่งไปยังร้านค้ามีอยู่บนเซิร์ฟเวอร์แอปเท่านั้น หากต้องการส่งข้อมูลนี้ไปยัง Google Play เซิร์ฟเวอร์แอปจะต้องจัดเตรียมข้อมูลดังกล่าวให้กับเซิร์ฟเวอร์ Hive

URL เซิร์ฟเวอร์แอปเป็นจุดสิ้นสุด API ที่เปิดโดยเซิร์ฟเวอร์แอปเพื่อให้ข้อมูลแก่เซิร์ฟเวอร์ Hive กำหนดค่าตำแหน่งข้อมูลตามข้อกำหนดด้านล่าง และลงทะเบียนเป็น URL ของเซิร์ฟเวอร์แอป เมื่อใดก็ตามที่มีการแจ้งเตือนการตรวจสอบการคืนเงินเกิดขึ้น เซิร์ฟเวอร์ Hive จะส่งคำขอ POST ไปยังตำแหน่งข้อมูลนี้ และรับข้อมูลที่จำเป็นจากเซิร์ฟเวอร์แอป เซิร์ฟเวอร์ Hive รวบรวมข้อมูลนี้และส่งข้อมูลการตรวจสอบการคืนเงินไปยัง Google ในนามของนักพัฒนาแอป

กระบวนการโดยรวมมีดังนี้

  1. แอป: กำหนดค่าตำแหน่งข้อมูล API ตามข้อกำหนดด้านล่าง และเตรียม URL ของเซิร์ฟเวอร์
  2. แอพ: ใน การตั้งค่าบริการเพิ่มเติม > การส่งข้อมูลการบริโภค ในคอนโซล Hive ให้เปิดใช้งาน Google Play และลงทะเบียน URL ของเซิร์ฟเวอร์
  3. ผู้ใช้แอป: ขอเงินคืน (ปฏิเสธการชำระเงิน) สำหรับการทำธุรกรรมโดยตรงจากสถาบันการเงิน เช่น ผู้ออกบัตรเครดิต
  4. Google: ส่งการแจ้งเตือนการตรวจสอบการคืนเงิน (pendingRefundReviewNotification) ไปยังเซิร์ฟเวอร์ Hive
  5. เซิร์ฟเวอร์ Hive: ส่งคำขอ POST API ไปยัง URL เซิร์ฟเวอร์ที่ลงทะเบียนโดยแอปและรับข้อมูลในการตอบกลับ
  6. เซิร์ฟเวอร์ Hive: ส่งข้อมูลการตรวจสอบการคืนเงินไปยัง Google ด้วย orders:reviewrefund Google ตอบสนองด้วยเนื้อหา 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"
                                }
                        }
                ]
        }
}