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

เรามี API สำหรับส่งข้อมูลการบริโภคของผู้ใช้ไปยัง App Store เมื่อผู้ใช้แอปขอคืนเงิน

API 'ส่งข้อมูลการบริโภค' ทำงานผ่านการสื่อสารแบบ Server-to-Server ระหว่างเซิร์ฟเวอร์ Hive และเซิร์ฟเวอร์แอป โดยเซิร์ฟเวอร์ Hive จะส่งคำขอส่งข้อมูลการบริโภคไปยังเซิร์ฟเวอร์แอป และเซิร์ฟเวอร์แอปจะส่งค่าตอบกลับกลับไปยังเซิร์ฟเวอร์ Hive

Note

ขณะนี้การส่งข้อมูลการบริโภครองรับเฉพาะ Apple App Store เท่านั้น

ขั้นตอนการทำงาน¶

สรุปขั้นตอนการทำงานทั้งหมดของการเรียกใช้และการตอบกลับ API 'ส่งข้อมูลการบริโภค' ได้ดังนี้

แอป: เตรียม URL เซิร์ฟเวอร์โดยกำหนดค่า API endpoint
แอป: เลือกเปิดใช้งานการส่งข้อมูลการบริโภคในคอนโซล Hive และลงทะเบียน URL เซิร์ฟเวอร์
ไคลเอนต์แอป: ยินยอมให้ส่งข้อมูลการบริโภคสินค้าในแอปขณะที่แอปกำลังทำงานอยู่
ผู้ใช้แอป: ขอคืนเงินในแอป
Apple: ส่งคำขอข้อมูลการบริโภค (CONSUMPTION_REQUEST) ไปยังเซิร์ฟเวอร์ Hive
เซิร์ฟเวอร์ Hive: ส่งคำขอ POST API ไปยัง URL เซิร์ฟเวอร์ที่แอปลงทะเบียนไว้ และรับข้อมูลการบริโภคเป็นค่าตอบกลับจากเซิร์ฟเวอร์แอป
เซิร์ฟเวอร์ Hive: ส่งข้อมูลการบริโภคไปยัง App Store (หากสำเร็จ Apple จะตอบกลับด้วย HTTP 202)

Warning

หากไคลเอนต์แอปไม่ยินยอมให้ส่งข้อมูลในหน้าต่างการยินยอม เซิร์ฟเวอร์ Hive จะไม่สามารถส่งข้อมูลไปยัง App Store ได้ แม้จะได้รับข้อมูลจากเซิร์ฟเวอร์แอปแล้วก็ตาม สถานะการยินยอมของผู้ใช้ (customerConsented) ไม่ได้ถูกส่งโดยเซิร์ฟเวอร์แอป แต่เซิร์ฟเวอร์ Hive จะเป็นผู้กำหนดค่านี้เอง

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

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

การกำหนดค่า API endpoint (URL เซิร์ฟเวอร์)¶

เมื่อเซิร์ฟเวอร์แอปได้รับคำขอผ่าน API endpoint ที่จะลงทะเบียนเป็น URL เซิร์ฟเวอร์ ต้องค้นหาข้อมูลการบริโภคด้วยข้อมูลผู้ใช้ (player_id) และข้อมูลธุรกรรม (transaction_id) ที่อยู่ในพารามิเตอร์คำขอ แล้วตอบกลับด้วยข้อมูลที่ตรงตามข้อกำหนดการตอบกลับ

ปิดกฎไฟร์วอลล์¶

เพื่อให้เซิร์ฟเวอร์ Hive สามารถส่งคำขอไปยัง API endpoint ของเซิร์ฟเวอร์แอปได้ คุณต้องปิดกฎไฟร์วอลล์ขาเข้าสำหรับที่อยู่ 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 endpoint

การกำหนดค่า API request (เซิร์ฟเวอร์ Hive → เซิร์ฟเวอร์แอป)¶

นี่คือข้อมูลคำขอ POST ที่ส่งจากเซิร์ฟเวอร์ Hive ไปยังเซิร์ฟเวอร์แอป

ข้อมูล API	คำอธิบาย
วิธีการ	POST
รูปแบบการตอบสนอง	JSON
ประเภทเนื้อหา	application/json

Request body¶

ข้อมูล Request body มีดังนี้

ชื่อ	ประเภท	จำเป็น (จำเป็น: M, ไม่จำเป็น: O)	คำอธิบาย
gameindex	Integer	M	Hive App Center Game Index
appid	String	M	Hive App Center AppID
server_id	String	M	รหัสเซิร์ฟเวอร์แอป
player_id	String	M	ตัวระบุผู้ใช้ในแอป (ค่าที่ใช้ระบุตัวผู้ใช้ในการตรวจสอบการซื้อ) ตรงกับ `user_seq` ใน V1
transaction_id	String	M	Original Transaction ID ของ Apple (originalTransactionId)

ตัวอย่าง Request body มีดังนี้

{
    "gameindex": 539,
    "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
    "server_id": "server_01",
    "player_id": "222333",
    "transaction_id": "2000000123456789"
}

การกำหนดค่า API response (เซิร์ฟเวอร์แอป → เซิร์ฟเวอร์ Hive)¶

เซิร์ฟเวอร์แอปจะส่งรหัสผลลัพธ์การประมวลผล (code) ข้อความผลลัพธ์ (message) และข้อมูลการบริโภค (data) ไปยังเซิร์ฟเวอร์ Hive

Response body¶

เซิร์ฟเวอร์ Hive จะพิจารณาความสำเร็จจากค่า code หากเป็น 200 จะถือว่าสำเร็จและใช้ data ส่วนรหัสอื่นจะไม่ส่งข้อมูลรายการนั้นและบันทึก message เป็นเหตุผล code เป็นค่าที่จำเป็น หากไม่ส่งมาจะถือเป็นข้อผิดพลาดและไม่ส่งข้อมูลรายการนั้น

ชื่อ	ประเภท	จำเป็น (จำเป็น: M, ไม่จำเป็น: O)	คำอธิบาย
code	Integer	M	รหัสผลลัพธ์การประมวลผล (ดูตารางด้านล่าง) มีเพียง 200 เท่านั้นที่ถือว่าสำเร็จ รหัสอื่นถือเป็นข้อผิดพลาด
message	String	O	ข้อความผลลัพธ์การประมวลผล ใช้อธิบายเหตุผลเมื่อเกิดข้อผิดพลาด
data	Object	M	ข้อมูลตอบกลับ (จำเป็นเมื่อสำเร็จ)
┕ delivery_status	String	M	สถานะการส่งมอบไอเทมสิ้นเปลือง เป็นหนึ่งในค่าสถานะการส่งมอบด้านล่าง
┕ refund_preference	String	O	ความชอบด้านการคืนเงิน เป็นหนึ่งในค่าความชอบด้านการคืนเงินด้านล่าง
┕ consumption_percentage	Integer	O	อัตราส่วนการบริโภค หน่วยเป็น millipercent ตั้งแต่ 0-100000 (100000 = 100%)
┕ sample_content_provided	Integer	O	การให้เนื้อหาตัวอย่างหรือไม่ 0 หรือ 1

ตัวอย่างการตอบกลับสำเร็จมีดังนี้

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

รหัสการตอบกลับ¶

ค่า	คำอธิบาย
200	สำเร็จ
400	ค่าคำขอไม่ถูกต้อง
500	ข้อผิดพลาดของเซิร์ฟเวอร์

สถานะการส่งมอบ (`delivery_status`)¶

ระบุสถานะการส่งมอบของไอเทมสิ้นเปลือง ต้องเป็นหนึ่งใน 5 ค่าด้านล่าง (จำเป็น)

ค่า	ความหมาย
DELIVERED	ส่งมอบไอเทมสิ้นเปลืองเรียบร้อยแล้วและทำงานได้ตามปกติ
UNDELIVERED_QUALITY_ISSUE	ไม่สามารถส่งมอบได้เนื่องจากปัญหาด้านคุณภาพ
UNDELIVERED_WRONG_ITEM	ส่งมอบไอเทมผิดรายการ (ไม่ตรงกับที่ซื้อ)
UNDELIVERED_SERVER_OUTAGE	ไม่สามารถส่งมอบได้เนื่องจากเซิร์ฟเวอร์ขัดข้อง
UNDELIVERED_OTHER	ไม่สามารถส่งมอบได้ด้วยเหตุผลอื่น

ความชอบด้านการคืนเงิน (`refund_preference`)¶

ส่งแนวทางการดำเนินการคืนเงินที่แอปต้องการไปยัง Apple (ไม่บังคับ) หากส่งค่านี้ ต้องเป็นหนึ่งใน 3 ค่าด้านล่าง

ค่า	ความหมาย
GRANT_FULL	ต้องการให้คืนเงินเต็มจำนวน
DECLINE	ต้องการไม่ให้คืนเงิน (ปฏิเสธ)
GRANT_PRORATED	ต้องการให้คืนเงินบางส่วน (ตามสัดส่วน) ใช้สำหรับการสมัครสมาชิกเป็นหลัก