เอกสาร API สำหรับตัวแทนจำหน่าย

API ตัวแทนจำหน่ายของ SHOP2TOPUP เป็น JSON REST API สำหรับขายแพ็กเติมเกม การเติมเงินในเกม และโค้ดบัตรเติมเงิน ผ่านร้านค้า หน้าร้าน หรือบอทของคุณเอง เอกสารนี้อธิบายทุก endpoint สาธารณะ พร้อมพารามิเตอร์และการตอบกลับ

Base URL และการรับส่งข้อมูล

ทุก path ในเอกสารนี้อ้างอิงจาก Base URL ด้านล่าง คำขอและการตอบกลับเป็น JSON ผ่าน HTTPS จำนวนเงินส่งเป็นสตริงเพื่อไม่ให้เกิดการปัดเศษแบบ float และเวลาทุกค่าเป็น UTC ในรูปแบบ ISO 8601

https://shop2topup.com/api/endpoints/v1

การยืนยันตัวตน

ทุกคำขอต้องแนบ header หนึ่งตัว คู่คีย์ออกให้จากหน้า API Access ในแผงควบคุมตัวแทนจำหน่าย และตั้งให้ใช้ได้เฉพาะ IP ที่อนุญาตได้ หากเรียกจากที่อยู่อื่น ระบบจะปฏิเสธด้วย IP_NOT_ALLOWED ก่อนเข้าสู่การประมวลผลใดๆ

เฮดเดอร์ของคำขอ

Authorization: Bearer <keyId>.<secret>

เรียกใช้ครั้งแรก

ไม่ต้องติดตั้งอะไรเพิ่ม เปลี่ยนเป็นคีย์ของคุณ แล้วคำขอนี้จะส่งข้อมูลแค็ตตาล็อกจริงกลับมา

ตัวอย่างคำขอผ่าน cURL

curl -s "https://shop2topup.com/api/endpoints/v1/catalog/categories?bigCategoryId=1" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

รูปแบบการตอบกลับ

ทุกการตอบกลับมีฟิลด์ success แบบ boolean จึงแยกกรณีสำเร็จออกจากความผิดพลาดทุกแบบได้ด้วยเงื่อนไขเดียว
กรณีผิดพลาดจะได้ออบเจ็กต์ error ที่มีรหัสคงที่ ข้อความสำหรับคนอ่าน และรายละเอียดเพิ่มเติม (ถ้ามี) ให้แยกเงื่อนไขจากรหัสเสมอ ไม่ใช่จากข้อความ
จำนวนเงินเป็นสตริงทศนิยมเสมอ เช่น "0.950000" หน่วยเป็น USD อย่าแปลงเป็น float แบบไบนารีก่อนนำไปเปรียบเทียบหรือรวมยอด
เอนด์พอยต์ที่ส่งข้อมูลกลับมาเป็นรายการจะแนบข้อมูลการแบ่งหน้ามาด้วย ซึ่งมีฟิลด์ page, limit, total และ total_pages
การสร้างคำสั่งซื้อเป็นแบบ idempotent ตาม UUID ใน order_id ที่คุณส่งมา การลองใหม่จึงไม่มีทางเรียกเก็บเงินซ้ำ

การตอบกลับเมื่อเกิดข้อผิดพลาด

{
  "success": false,
  "error": {
    "code": "PRICE_INCREASED",
    "message": "Price has increased beyond expected",
    "action": "FIX_INPUT",
    "retryable": false,
    "retry_after": null,
    "details": {
      "expected_unit_price": "0.950000",
      "current_unit_price": "0.980000"
    }
  }
}

หัวข้อในเอกสารอ้างอิง

แค็ตตาล็อกแค็ตตาล็อกเป็นโครงสร้างสามชั้น หมวดหมู่ใหญ่มีหมวดหมู่อยู่ภายใน หมวดหมู่มีหมวดหมู่ย่อย และหมวดหมู่ย่อยคือสินค้าที่ซื้อจริง ใช้ endpoint เหล่านี้คัดลอกโครงสร้างไปไว้ในฐานข้อมูลของคุณเอง และเช็กราคาสินค้าทันทีก่อนสั่งซื้อ ตรวจสอบผู้เล่นการตรวจสอบผู้เล่นช่วยระบุบัญชีในเกมก่อนมีการโอนเงิน ระบบจะยืนยันว่า ID มีอยู่จริงสำหรับสินค้านั้น พร้อมส่งชื่อในเกมกลับมาให้ลูกค้าตรวจสอบ และระบุโซนของบัญชี เพื่อปฏิเสธคำสั่งซื้อข้ามโซนตั้งแต่ต้น ป้องกันคำสั่งซื้อไม่สำเร็จหลังการชำระเงิน คำสั่งซื้อคำสั่งซื้อทุกรายการสร้างด้วย UUID ที่ฝั่งคุณสร้างขึ้นเอง UUID นี้คือ idempotency key หากส่งซ้ำ ระบบจะคืนคำสั่งซื้อเดิมให้แทนการเรียกเก็บเงินสองครั้ง จากนั้นอ่านสถานะได้ทีละคำสั่งซื้อ ครั้งละไม่เกิน 50 รายการ หรือดึงเป็นลิสต์แบบแบ่งหน้า บัญชีและการยืนยันตัวตนทุกคำขอแนบ header เพียงตัวเดียว ส่วน GET /account ใช้ทดสอบว่าคีย์ใช้งานได้ ดูยอดคงเหลือในกระเป๋าเงินที่คำสั่งซื้อจะตัดไป และเช็กว่าบัญชียังเปิดใช้งานอยู่ก่อนเริ่มรันแบบชุด รหัสข้อผิดพลาดเมื่อคำขอล้มเหลว ระบบจะส่งรหัสที่โปรแกรมอ่านได้และคงที่มาพร้อมสถานะ HTTP ทุกครั้ง ให้เขียนเงื่อนไขโดยอิงรหัส อย่าอิงข้อความ เพราะข้อความเขียนไว้ให้คนอ่านและอาจปรับถ้อยคำได้ ส่วนรหัสเป็นส่วนหนึ่งของข้อกำหนด API

ขีดจำกัดการเรียกใช้

ขีดจำกัดคิดแยกตามบัญชีและนับแบบ rolling window endpoint ของแคตตาล็อก คำสั่งซื้อ และบัญชีจะแนบ header X-RateLimit-Limit X-RateLimit-Remaining และ X-RateLimit-Reset มาในคำตอบ หากเรียกเกินกำหนด ระบบจะตอบกลับด้วย 429 พร้อม header Retry-After ส่วนการตรวจสอบผู้เล่นจะนับจากโควตาตรวจสอบผู้เล่นรายวันแทน โดยไม่ส่ง header X-RateLimit และจะแจ้งโควตาไว้ใน body ของคำตอบ 429

เส้นทาง	จำนวนคำขอ	ช่วงเวลา	นับต่อ
GET /catalog/* (ทั้ง 5 รายการ)	5000	60 วินาที	ต่อบัญชี
POST /orders/create	5000	60 วินาที	ต่อบัญชี
GET /orders/:orderId	3	60 วินาที	ต่อบัญชี + ID คำสั่งซื้อ
POST /orders/batch	2	60 วินาที	ต่อบัญชี
GET /orders	2	60 วินาที	ต่อบัญชี
GET /account	60	60 วินาที	ต่อบัญชี
POST /player/validate	โควตาตรวจสอบผู้เล่นรายวัน	24 ชั่วโมง	นับแยกตามบัญชี (ไม่มีเฮดเดอร์ X-RateLimit ในการตอบกลับ)

การแจ้งผลผ่าน Webhook

ระบบส่งผลของคำสั่งซื้อไปยัง endpoint HTTPS ที่คุณลงทะเบียนไว้ พร้อมลายเซ็น HMAC-SHA256 ที่คำนวณจาก body ดิบ รายการ event, รายการ header, โครงสร้าง payload และตัวอย่างโค้ดตรวจลายเซ็นอยู่ในหน้าภาพรวม API

อ่านเอกสาร payload และลายเซ็นของ Webhook

หากเพิ่งเริ่มใช้แพลตฟอร์ม เริ่มที่หน้าภาพรวม API เติมเกมสำหรับตัวแทนจำหน่าย หรืออ่านภาพรวมโปรแกรมตัวแทนจำหน่ายของ SHOP2TOPUP เพื่อดูว่าบัญชีพาร์ทเนอร์ใช้งานอย่างไร