Reseller API · v1

API สำหรับตัวแทน

ให้ระบบ ร้าน หรือบอทของคุณดึงสินค้า ราคาตัวแทน และสต็อกของ KINGDOMX STORE แล้วสั่งซื้อจากยอดเงินในกระเป๋าได้อัตโนมัติ ได้คีย์กลับมาทันทีในคำตอบเดียว ใช้ได้เฉพาะบัญชีตัวแทน (Reseller)

Base URL

https://kingdomxstore.com/api/v1

รูปแบบ

JSON (UTF-8) · เงินเป็นบาท (THB)

ยืนยันตัวตน

header X-API-Key

ทุกคำตอบ

มี success เป็น true / false

เริ่มต้นใช้งาน

1เข้าสู่ระบบด้วยบัญชีตัวแทน ไปที่ บัญชี → API สำหรับตัวแทน แล้วกด สร้าง API Key คัดลอกเก็บไว้ (ระบบแสดงครั้งเดียว)
2เติมเงินเข้ากระเป๋าตามปกติที่หน้าเว็บ การสั่งซื้อผ่าน API จะหักจากยอดนี้ ในราคาตัวแทน
3เรียก GET /products เพื่อดู id ของแพ็กเกจ แล้วสั่งด้วย POST /order พร้อม reference ของคุณเอง

ลองเรียกครั้งแรก

curl https://kingdomxstore.com/api/v1/me \
  -H "X-API-Key: YOUR_API_KEY"

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

ส่ง Key ใน header X-API-Key ทุกครั้ง (หรือ Authorization: Bearer <key> ก็ได้) Key ขึ้นต้นด้วย kx_live_

เก็บเป็นความลับ

เรียกจากเซิร์ฟเวอร์หรือบอทเท่านั้น อย่าใส่ในหน้าเว็บ แอป หรือ GitHub

รีเซ็ตได้ทุกเมื่อ

สงสัยว่าหลุด กดรีเซ็ตที่หน้า API Key เดิมใช้ไม่ได้ทันที

จำกัด IP ได้

ใส่ IP เซิร์ฟเวอร์ของคุณไว้ คนอื่นได้ Key ไปก็ใช้ไม่ได้

ถ้าบัญชีไม่ได้เป็นตัวแทนแล้ว หรือถูกระงับ Key จะใช้ไม่ได้ทันที (403)

ขีดจำกัดการเรียก

60 ครั้ง/นาที ทุก endpoint รวมกัน

20 ครั้ง/นาที สำหรับ POST /order

ทุกคำตอบมี header X-RateLimit-Limit X-RateLimit-Remaining X-RateLimit-Reset (วินาทีจนรอบใหม่) เกินกำหนดจะได้ 429 rate_limited พร้อม Retry-After

GET/me

ข้อมูลบัญชีที่ใช้ Key นี้ และ IP ที่ระบบเห็น (เอาไปใส่ในรายการ IP ที่อนุญาตได้)

Response 200

{
  "success": true,
  "username": "myshop",
  "tier": "reseller",
  "balance": 1250.5,
  "currency": "THB",
  "ip": "203.0.113.10"
}

GET/balance

ยอดเงินคงเหลือในกระเป๋า (บาท)

Response 200

{ "success": true, "balance": 1250.5, "currency": "THB" }

GET/products

แพ็กเกจทั้งหมดที่เปิดขาย 1 รายการ = 1 แพ็กเกจ ราคาเป็นราคาตัวแทนของคุณแล้ว

ชื่อ	ต้องส่ง	คำอธิบาย
in_stock	ไม่บังคับ	ส่ง 1 = เอาเฉพาะที่มีของ
category	ไม่บังคับ	slug ของหมวด (category_slug) เช่น ios

ชื่อ	ต้องส่ง	คำอธิบาย
id	-	รหัสแพ็กเกจ ใช้เป็น package_id ตอนสั่งซื้อ
price	-	ราคาต่อชิ้นที่คุณจ่าย (ราคาตัวแทน)
list_price	-	ราคาปกติหน้าร้าน
stock / in_stock	-	จำนวนคงเหลือ ณ ตอนเรียก
duration_days	-	อายุการใช้งาน (วัน) null = ถาวร/ไม่ระบุ

Response 200

{
  "success": true,
  "count": 1,
  "currency": "THB",
  "products": [
    {
      "id": 28,
      "product_id": 11,
      "name": "3IN1 WINNER IOS - 1 วัน",
      "product_name": "3IN1 WINNER IOS",
      "package_name": "1 วัน",
      "category": "iOS",
      "category_slug": "ios",
      "platform": "IOS",
      "duration_days": 1,
      "price": 29.75,
      "list_price": 35,
      "in_stock": true,
      "stock": 18,
      "image_url": "https://…/image.png",
      "url": "https://kingdomxstore.com/product/3in1-winner-ios"
    }
  ]
}

GET/products/{id}

แพ็กเกจเดียว (รูปแบบเดียวกับแต่ละรายการใน /products) ใช้เช็กราคาและสต็อกก่อนสั่ง

curl https://kingdomxstore.com/api/v1/products/28 -H "X-API-Key: YOUR_API_KEY"

POST/order

ซื้อทันทีจากยอดเงินในกระเป๋า ได้คีย์กลับมาใน keys สั่งไม่สำเร็จจะไม่ตัดเงิน ส่งเป็น JSON หรือ form data

ชื่อ	ต้องส่ง	คำอธิบาย
package_id	จำเป็น	id จาก /products
quantity	ไม่บังคับ	จำนวน 1–20 (ค่าเริ่มต้น 1)
reference	แนะนำ	เลขออเดอร์ของคุณเอง a-z A-Z 0-9 . _ : - ไม่เกิน 64 ตัว ส่งซ้ำด้วยค่าเดิม = ได้ออเดอร์เดิม ไม่ซื้อซ้ำ
expected_price	ไม่บังคับ	ราคาต่อชิ้นที่คุณคาดไว้ ถ้าราคาเปลี่ยนจะปฏิเสธด้วย price_changed แทนการตัดเงินราคาใหม่

Request body

{
  "package_id": 28,
  "quantity": 1,
  "reference": "my-order-1001",
  "expected_price": 29.75
}

Response 201

{
  "success": true,
  "replay": false,
  "order_id": "3f6c2a91-8b4d-4e2a-9c1f-7d0e5b8a1c22",
  "reference": "my-order-1001",
  "channel": "api",
  "status": "completed",
  "package_id": 28,
  "product_id": 11,
  "product_name": "3IN1 WINNER IOS",
  "package_name": "1 วัน",
  "quantity": 1,
  "unit_price": 29.75,
  "total": 29.75,
  "currency": "THB",
  "keys": ["XXXX-XXXX-XXXX"],
  "created_at": "2026-10-26T09:41:12.000Z",
  "completed_at": "2026-10-26T09:41:12.000Z",
  "balance": 1220.75
}

ทำไมต้องส่ง reference: ถ้าเน็ตหลุดหรือ timeout ตอนสั่ง คุณจะไม่รู้ว่าซื้อสำเร็จไหม ส่งคำขอเดิมด้วย reference เดิมได้เลย ระบบจะคืนออเดอร์เดิม (replay: true) ไม่ตัดเงินซ้ำ

GET/order?reference=…

ดูผลออเดอร์ด้วย reference ของคุณ (หรือ ?id= เลขออเดอร์ของเรา) ใช้เมื่อการเชื่อมต่อหลุดระหว่างสั่งซื้อ

curl "https://kingdomxstore.com/api/v1/order?reference=my-order-1001" -H "X-API-Key: YOUR_API_KEY"

มีอีกแบบคือ GET /orders/{order_id} ไม่พบจะได้ 404 not_found แปลว่ายังไม่เคยสั่งสำเร็จ สั่งใหม่ด้วย reference เดิมได้

GET/orders

ออเดอร์ล่าสุดของบัญชี (ทั้งที่ซื้อผ่านเว็บและ API) เรียงใหม่ไปเก่า

ชื่อ	ต้องส่ง	คำอธิบาย
limit	ไม่บังคับ	1–100 (ค่าเริ่มต้น 20)
page	ไม่บังคับ	หน้าที่ (เริ่ม 1)
channel	ไม่บังคับ	api หรือ web

Response 200

{
  "success": true,
  "page": 1,
  "limit": 20,
  "total": 57,
  "orders": [ { "order_id": "…", "reference": "my-order-1001", "status": "completed", "keys": ["…"], … } ]
}

ตัวอย่างโค้ดครบชุด

ดึงสินค้า → สั่งซื้อพร้อม reference → ได้คีย์ (เก็บ Key ไว้ในตัวแปรสภาพแวดล้อม KX_API_KEY)

# 1. ดูยอดเงิน
curl https://kingdomxstore.com/api/v1/balance \
  -H "X-API-Key: $KX_API_KEY"

# 2. ดึงสินค้า (เฉพาะที่มีของ)
curl "https://kingdomxstore.com/api/v1/products?in_stock=1" \
  -H "X-API-Key: $KX_API_KEY"

# 3. สั่งซื้อ (reference = เลขออเดอร์ของคุณเอง ส่งซ้ำได้ ไม่ซื้อซ้ำ)
curl -X POST https://kingdomxstore.com/api/v1/order \
  -H "X-API-Key: $KX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"package_id": 28, "quantity": 1, "reference": "my-order-1001"}'

# 4. เน็ตหลุดระหว่างสั่ง? ดูผลด้วย reference เดิม
curl "https://kingdomxstore.com/api/v1/order?reference=my-order-1001" \
  -H "X-API-Key: $KX_API_KEY"

รหัสข้อผิดพลาด

ทุกข้อผิดพลาดตอบรูปแบบเดียวกัน ใช้ค่า error ในโค้ด ส่วน message เป็นภาษาไทยไว้แสดงผล

{
  "success": false,
  "error": "insufficient_balance",
  "message": "ยอดเงินในกระเป๋าไม่พอ"
}

error	HTTP	ความหมาย	ควรทำ
missing_key	401	ไม่ได้ส่ง API Key	ใส่ header X-API-Key
invalid_key	401	Key ผิด หรือถูกรีเซ็ต/ยกเลิกแล้ว	สร้างหรือคัดลอก Key ใหม่ที่หน้า API ในบัญชี
not_reseller	403	บัญชีไม่ได้เป็นตัวแทนแล้ว	ติดต่อร้าน
account_suspended	403	บัญชีถูกระงับ	ติดต่อร้าน
ip_not_allowed	403	เรียกจาก IP ที่ไม่ได้อนุญาตไว้ (คำตอบมี ip ที่ระบบเห็น)	เพิ่ม IP นั้นในหน้า API หรือล้างรายการ IP
rate_limited	429	เรียกเกินกำหนดต่อนาที	รอตาม retry_after (วินาที) แล้วค่อยเรียกใหม่
bad_request	400	ข้อมูลที่ส่งมาไม่ถูกต้อง (ดู issues)	ตรวจชื่อและชนิดของฟิลด์
not_found	404	ไม่พบสินค้า/ออเดอร์ หรือ endpoint	ตรวจ id / reference / path
method_not_allowed	405	ใช้ GET/POST ผิดกับ endpoint	ดู method ของแต่ละ endpoint
product_unavailable	422	สินค้าปิดการขายชั่วคราว	ดึง /products ใหม่
out_of_stock	422	สินค้าหมด หรือเหลือไม่พอตามจำนวน	ลดจำนวน หรือรอสต็อก
insufficient_balance	422	ยอดเงินในกระเป๋าไม่พอ	เติมเงินที่หน้าเว็บ
price_changed	409	ราคาไม่ตรงกับ expected_price (คำตอบมี unit_price ปัจจุบัน)	ตรวจราคาใหม่แล้วสั่งอีกครั้ง
in_progress	409	reference เดียวกันกำลังถูกสั่งพร้อมกัน	เรียก GET /order?reference= เพื่อดูผล
unavailable	503	ระบบไม่พร้อมชั่วคราว	ลองใหม่ด้วย reference เดิม

แนวทางที่แนะนำ

ส่ง reference ทุกครั้งที่สั่งซื้อ และใช้ค่าที่ไม่ซ้ำต่อออเดอร์ของคุณ (เช่น เลขออเดอร์ในระบบคุณ)
เจอ timeout หรือ 503 ให้ส่งคำขอเดิมซ้ำด้วย reference เดิม หรือเรียก GET /order?reference= ก่อน อย่าสร้าง reference ใหม่
ส่ง expected_price ไปด้วย จะไม่โดนตัดเงินในราคาที่เปลี่ยนไปโดยไม่รู้ตัว
เก็บคีย์ที่ได้ลงฐานข้อมูลของคุณทันที (ดูย้อนหลังได้ด้วย GET /order และในประวัติการซื้อบนเว็บ)
ดึง /products ไม่ต้องถี่ ทุก 1–5 นาทีพอ สต็อกเปลี่ยนได้ตลอด ระบบเช็กสต็อกจริงอีกครั้งตอนสั่ง
สินค้าที่มีไฟล์ให้ดาวน์โหลด ดาวน์โหลดได้จากประวัติการซื้อบนเว็บ (API ส่งเฉพาะคีย์)

พร้อมเริ่มแล้ว? สร้าง API Key ได้ที่หน้าบัญชีของคุณ

ไปที่หน้า API Key