● Provider API · v0.2 · HMAC v2

HuayEngine Provider API

เชื่อมเว็บหวยของคุณเข้ากับ HuayEngine เพื่อดึงตลาดและงวด รับแทง ออกผล และจ่ายรางวัล ผ่าน REST API แบบ server-to-server ที่เซ็นทุกคำขอด้วย HMAC-SHA256

BASE URL · Staging https://huayapi-staging.huaysanook.online
ยืนยันตัวตน
HMAC-SHA256
X-Api-Key + ลายเซ็น canonical v2 ทุกคำขอ
หน่วยเงิน
สตางค์ (จำนวนเต็ม)
100 = ฿1 · ห้ามส่งทศนิยม
Idempotency
จำผล 24 ชม.
บังคับในทุก route ที่ย้ายเงินหรือเปลี่ยนสถานะ
Rate limit
600 คำขอ/นาที
ต่อคีย์ · ขอปรับได้สูงสุด 6,000

ภาพรวมการเชื่อมต่อ

ผู้เล่น
เว็บ / แอปของคุณ
→HTTPS
Backend ของคุณ
ถือ hmac_secret · เก็บบิลและสมาชิก
⇄HMAC v2
HuayEngine
/api/v1/provider/* · ส่ง webhook และ callback กลับมา
เรื่องHuayEngineเว็บของคุณ
ตลาด งวด อัตราจ่าย ลิมิตเป็นเจ้าของอ่านมาแสดง (cache ได้)
รับแทง ตรวจเลขอั้นและลิมิตตัดสินส่งคำขอ และเก็บสถานะบิลของตัวเอง
ออกผล คำนวณรางวัล settleตัดสินsync ผลมา · ห้ามคำนวณรางวัลเอง
สมาชิก (ข้อมูลส่วนตัว การ login)รู้แค่ member_codeเป็นเจ้าของ
ฝากถอนกับผู้เล่น (ธนาคาร)—เป็นเจ้าของ
กระเป๋าเงินผู้เล่นโหมด transferโหมด seamless
สภาพแวดล้อมAPI base URLStudio (พอร์ทัลพาร์ทเนอร์)
Staging — ใช้ทดสอบhttps://huayapi-staging.huaysanook.onlinehuaystudio-staging.huaysanook.online
Productionhttps://huayapi.huaysanook.onlinehuaystudio.huaysanook.online

ไม่มีสภาพแวดล้อม sandbox แยกต่างหาก ให้ทดสอบบน staging ปุ่ม Staging / Production มุมขวาบนจะเปลี่ยน URL ในตัวอย่างโค้ดทั้งหน้า

!
เรียกจาก backend เท่านั้น hmac_secret ห้ามอยู่ในเว็บเบราว์เซอร์ แอปมือถือ หรือ repository สาธารณะ แนะนำให้รวมโค้ดที่เรียก HuayEngine ไว้ใน package เดียวของ backend จะได้ตรวจได้ง่ายว่าไม่มีที่อื่นเรียกตรง

⚡เริ่มใน 5 นาที

ขอคีย์ ยิง endpoint อ่านอย่างเดียวหนึ่งครั้ง ถ้าได้ 200 แปลว่าคีย์ ลายเซ็น และ IP ถูกต้องแล้ว

  1. ขอสิ่งเหล่านี้จากทีม HuayEngine
    • api_key + hmac_secret — secret แสดงครั้งเดียว ให้เก็บใน secret manager
    • โหมดกระเป๋า (transfer หรือ seamless — ดูโหมดกระเป๋าเงิน) และถ้าเป็น seamless ต้องแจ้ง URL ฐานของ callback ด้วย
    • รายการตลาดหวยที่คีย์เปิดใช้ได้ (ตลาดนอกขอบเขตจะได้ 403 lottery_not_allowed)
    • IP ขาออกของ backend สำหรับ whitelist (เทียบตรงตัว ไม่รองรับ CIDR · ว่างไว้ = รับทุก IP)
    • บัญชี Studio: ล็อกอินด้วย รหัสผู้เช่า (tenant code) + อีเมล + รหัสผ่าน (staging ใช้รหัสผู้เช่า default) ใช้ดู log/usage แก้ IP whitelist หมุน hmac_secret และสร้าง webhook endpoint เอง
  2. ยิง GET /api/v1/provider/games
    export HUAY_BASE=https://huayapi-staging.huaysanook.online
    export HUAY_API_KEY=...        # จาก Studio → API Keys
    export HUAY_HMAC_SECRET=...    # แสดงครั้งเดียวตอนสร้างหรือหมุนคีย์
    
    METHOD=GET
    TARGET=/api/v1/provider/games
    BODY=''
    IDEM=''
    RID=$(uuidgen)
    TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
    DIGEST=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')
    SIG=$(printf 'huayengine-provider-v2\n"%s"\n"%s"\n"%s"\n"%s"\n"%s"\n%s' \
      "$METHOD" "$TARGET" "$TS" "$RID" "$IDEM" "$DIGEST" \
      | openssl dgst -sha256 -hmac "$HUAY_HMAC_SECRET" -hex | awk '{print $NF}')
    
    curl -s "$HUAY_BASE$TARGET" \
      -H "X-Api-Key: $HUAY_API_KEY" -H "X-Request-Id: $RID" \
      -H "X-Timestamp: $TS" -H "X-Signature: $SIG"
  3. ได้รายการตลาดกลับมา
    {
      "data": [
        { "id": 3, "code": "th_gov", "name_th": "หวยรัฐบาลไทย", "name_en": "Thai Government", "category_id": 1, "sort_order": 1, "active": true }
      ],
      "request_id": "6f1c2a9e-4b7d-4f3a-9c2e-1a2b3c4d5e6f"
    }
    ได้ 401 invalid_signature? ตรวจตามสร้างลายเซ็น HMAC และเทียบกับ test vector ก่อน

ลำดับงานที่แนะนำ

ขั้นทำอะไรEndpoint
1สมัครสมาชิกแล้วลงทะเบียนกับ enginePOST /members
2อ่านตลาด งวด และอัตราจ่ายมาแสดง (cache ไว้)GET /games · /rounds · /betconfig
3(transfer) โอนเงินเข้ากระเป๋าใน enginePOST /wallet/deposit
4รับโพยจากผู้เล่นแล้วส่งแทงPOST /bet/place
5รับผลและยอดจ่าย — webhook เป็นตัวกระตุ้น + worker sync สำรองWebhook · GET /bets/detail
6(transfer) ถอนเงินออกเมื่อผู้เล่นขอถอนPOST /wallet/withdraw

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

ทุกคำขอที่ไป /api/v1/provider/* ต้องมี header ชุดนี้

Headerค่า
X-Api-Keyบังคับapi_key ที่ได้รับ
X-Request-Idบังคับไม่ว่าง ไม่ซ้ำต่อคำขอ ยาวไม่เกิน 64 ตัว (แนะนำ UUID) · สร้างใหม่ทุกครั้ง แม้เป็นการ retry · ถ้าไม่ส่ง engine จะสร้างให้เอง แล้วลายเซ็นจะไม่ตรง
X-Timestampบังคับเวลา UTC แบบ RFC3339 เช่น 2026-11-17T08:00:00Z ต้องห่างจากเวลาเซิร์ฟเวอร์ไม่เกิน 5 นาที
X-Signatureบังคับhex ตัวพิมพ์เล็กของ HMAC-SHA256 ตาม canonical v2
Content-Typeapplication/json เมื่อมี body
Idempotency-Keyบังคับใน route ที่ย้ายเงินหรือเปลี่ยนสถานะ (ดูIdempotency) · ยาวไม่เกิน 80 ตัว · คนละค่ากับ X-Request-Id

กันการส่งซ้ำ (replay)

ลายเซ็นที่เวลาเหลื่อมเกิน 5 นาทีจะถูกปฏิเสธ เซิร์ฟเวอร์จองลายเซ็นต่อคีย์ไว้ 10 นาที ส่งคำขอเดิมซ้ำทั้งก้อนจะได้ 409 replay_detected · ถ้าระบบจองใช้ไม่ได้จะได้ 503 replay_unavailable

IP whitelist

ถ้าตั้ง IP ไว้บนคีย์ เซิร์ฟเวอร์จะเทียบ IP ต้นทางแบบตรงตัว (ไม่รองรับ CIDR) ไม่ตรงได้ 403 ip_not_allowed แก้รายการ IP เองได้ใน Studio

i
ลายเซ็นแบบเก่า (v1: request_id + "." + body ไม่มี X-Timestamp) ยังรับอยู่ชั่วคราวระหว่างย้ายระบบ และจะถูกปิดในอนาคต integration ใหม่ให้ใช้ v2 เท่านั้น คำขอที่มี X-Timestamp จะถูกตรวจแบบ v2 เสมอ
!
เก็บ hmac_secret และ webhook secret ใน secret manager ถ้าใช้ไฟล์ .env อย่าเขียน comment ท้ายบรรทัดของค่า secret เพราะบาง loader อ่าน comment เป็นส่วนหนึ่งของค่า แล้วลายเซ็นจะผิดแบบหาสาเหตุยาก

🔑สร้างลายเซ็น HMAC (v2)

เซ็น HMAC-SHA256 ของ canonical string ด้วย hmac_secret แล้วส่งผลเป็น hex ตัวพิมพ์เล็กใน X-Signature

huayengine-provider-v2
"<HTTP method>"
"<request target: path + query>"
"<X-Timestamp>"
"<X-Request-Id>"
"<Idempotency-Key หรือค่าว่าง>"
<SHA-256 hex ตัวพิมพ์เล็กของ body ที่ส่งจริง>
  • บรรทัดที่ 2–6 ครอบด้วย JSON string (JSON.stringify · Go %q · Python json.dumps) สำหรับค่า ASCII ทั้งสามแบบให้ผลเดียวกัน
  • request target คือ path + query ตามที่ส่งจริงทุกไบต์ รวม percent-encoding และลำดับของ query
  • ไม่มี Idempotency-Key ให้เซ็นเป็นสตริงว่าง ""
  • GET หรือคำขอที่ไม่มี body ใช้ SHA-256 ของสตริงว่าง e3b0c442…b855
  • ทุกครั้งที่ retry ให้สร้าง X-Timestamp, X-Request-Id และลายเซ็นใหม่ โดยใช้ Idempotency-Key และ body ของธุรกรรมเดิม
!
สองจุดที่ทำให้ได้ 401 invalid_signature บ่อยที่สุด
  1. เซ็นคนละไบต์กับที่ส่ง — แปลง body เป็น JSON ครั้งเดียว แล้วใช้สตริงนั้นทั้งตอนเซ็นและตอนส่ง อย่าให้ HTTP client แปลงซ้ำ
  2. PHP json_encode แปลง / เป็น \/ ต้องใส่ JSON_UNESCAPED_SLASHES ตอน quote path ไม่งั้น canonical string ไม่ตรงกับเซิร์ฟเวอร์
import { createHash, createHmac, randomUUID } from 'node:crypto'

const BASE = 'https://huayapi-staging.huaysanook.online'
const API_KEY = process.env.HUAY_API_KEY
const SECRET = process.env.HUAY_HMAC_SECRET

// canonical v2 → HMAC-SHA256 → hex ตัวพิมพ์เล็ก
export function sign(method, target, timestamp, requestId, idempotencyKey, rawBody) {
  const quoted = [method, target, timestamp, requestId, idempotencyKey].map(v => JSON.stringify(v))
  const digest = createHash('sha256').update(rawBody).digest('hex')
  const canonical = ['huayengine-provider-v2', ...quoted, digest].join('\n')
  return createHmac('sha256', SECRET).update(canonical).digest('hex')
}

export async function call(method, target, { body, idempotencyKey = '' } = {}) {
  const rawBody = body === undefined ? '' : JSON.stringify(body) // แปลงครั้งเดียว ใช้ทั้งเซ็นและส่ง
  const requestId = randomUUID()             // ใหม่ทุกครั้ง แม้เป็นการ retry
  const timestamp = new Date().toISOString() // RFC3339 UTC
  const headers = {
    'X-Api-Key': API_KEY,
    'X-Request-Id': requestId,
    'X-Timestamp': timestamp,
    'X-Signature': sign(method, target, timestamp, requestId, idempotencyKey, rawBody),
  }
  if (rawBody) headers['Content-Type'] = 'application/json'
  if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey

  const res = await fetch(BASE + target, {
    method, headers, body: rawBody || undefined, redirect: 'manual', signal: AbortSignal.timeout(8000),
  })
  const env = await res.json().catch(() => ({}))
  if (!res.ok || env.error) {
    const err = new Error(`HTTP ${res.status} ${env.error?.code ?? 'unknown'}`)
    Object.assign(err, { status: res.status, code: env.error?.code, requestId: env.request_id ?? requestId })
    throw err
  }
  return env.data
}

const games = await call('GET', '/api/v1/provider/games')

Test vector — ใช้ตรวจโค้ดของคุณ

ป้อนค่าด้านล่างเข้าฟังก์ชันเซ็นของคุณ ต้องได้ลายเซ็นตรงทุกตัวอักษร (ตรวจแล้วด้วย Node, Python, PHP และ Go) secret นี้ใช้ทดสอบเท่านั้น ใช้เรียก API จริงไม่ได้

secrettest-secret-do-not-use
method / targetPOST · /api/v1/provider/bet/place
X-Timestamp2026-11-17T08:00:00Z
X-Request-Id3f6c1d2e-8b7a-4c51-9e0d-2a1b3c4d5e6f
Idempotency-KeyORDER-1001-bet
body (ไบต์ตรงตัว){"member_code":"HP000123","round_id":4821,"reference":"ORDER-1001","items":[{"bet_type_code":"3_top","number":"123","stake_satang":1000}]}
SHA-256(body)6bb6d09b6aeadd62936f48924fbaf10c17d8b285b215d0fa5018e79d0bca689c
X-Signature20b2bf0c38d4331c91963e4fba6cb67c2325eca307f209f1d4d98f67534e9760
huayengine-provider-v2
"POST"
"/api/v1/provider/bet/place"
"2026-11-17T08:00:00Z"
"3f6c1d2e-8b7a-4c51-9e0d-2a1b3c4d5e6f"
"ORDER-1001-bet"
6bb6d09b6aeadd62936f48924fbaf10c17d8b285b215d0fa5018e79d0bca689c

ตัวอย่าง GET ที่มี query และไม่มี body: GET · /api/v1/provider/rounds?lottery_type_id=3 · เวลาเดียวกัน · X-Request-Id = 9b2e4f60-1c3d-4e5f-8a7b-6c5d4e3f2a10 · ไม่มี Idempotency-Key → X-Signature = e19bd6caa084b6e5ecb036d736017049c063298d98cb350569ca704462107618

🔁Idempotency และการลองใหม่

ส่วนที่สำคัญที่สุดของการเชื่อมต่อ เพราะทุกจุดที่ผิดตรงนี้คือเงินที่ตัดซ้ำหรือคืนซ้ำ

!
Idempotency-Key — บังคับใน route เหล่านี้ POST /wallet/deposit · /wallet/withdraw · /bet/place · /bet/cancel · /rounds/{id}/close · /rounds/{id}/void · /rounds/{id}/yeekee/shots
ไม่ส่งจะได้ 400 idempotency_required · 1 ธุรกรรม = 1 key · ยาวไม่เกิน 80 ตัว

พฤติกรรมของ engine

  • เก็บคำตอบที่สำเร็จ (2xx) ไว้ 24 ชั่วโมง ต่อ (ผู้เช่า, path, key) — ส่งซ้ำด้วย key เดิมจะได้คำตอบเดิมพร้อม header Idempotency-Replayed: true โดยไม่ทำรายการซ้ำ
  • คำตอบ 4xx/5xx ไม่ถูกเก็บ ส่งซ้ำด้วย key เดิมจะประมวลผลใหม่
  • คำขอซ้อนกันด้วย key เดียวกันได้ 409 idempotency_in_progress ให้รอแล้วลองใหม่ด้วย key เดิม
  • X-Request-Id ผูกกับ key แรกที่ใช้ — เอา request id เดิมไปใช้กับ key ใหม่ได้ 409 replay_detected
  • คำตอบที่ replay คือคำตอบตอนที่สร้างครั้งแรก ไม่ใช่สถานะปัจจุบัน — สถานะล่าสุดของตั๋วให้อ่านจาก GET /bet/{ticket_id}
!
route ส่วนใหญ่ไม่ตรวจว่า body ตรงกับครั้งแรก ใช้ key เดิมกับรายการใหม่จะได้คำตอบของรายการเก่ากลับมาเงียบ ๆ ยกเว้น /bet/cancel (body ต่าง = 409 idempotency_conflict) และ /bet/place ของคีย์ external_member
/bet/place มีด่านในฐานข้อมูลอีกชั้น: key ที่เคยรับบิลแล้วได้ 422 duplicate_bet แม้พ้น 24 ชม. แต่ /wallet/deposit และ /wallet/withdraw ไม่มีด่านนี้ — พ้น 24 ชม. แล้วส่ง key เดิมคือรายการใหม่
HTTPcodeเกิดเมื่อทำอย่างไร
400idempotency_requiredไม่ได้ส่ง Idempotency-Keyใส่ header
409idempotency_in_progressคำขอแรกด้วย key นี้ยังทำงานอยู่รอ 1–2 วินาที แล้วส่งซ้ำด้วย key เดิม
409replay_detectedX-Request-Id เคยใช้กับ key อื่น หรือส่งลายเซ็นเดิมซ้ำสร้าง request id และลายเซ็นใหม่ คง key เดิม
409idempotency_conflictkey เดิมแต่ body/ผู้เล่นต่างจากครั้งแรก (/bet/cancel, /bet/place แบบ external)บั๊กฝั่งคุณ — รายการใหม่ต้องใช้ key ใหม่
422duplicate_betkey นี้เคยรับบิลแล้ว (cache หมดอายุ)ถือว่าอาจสำเร็จแล้ว ค้นตั๋วจาก /bet/history ด้วย reference

ส่งคำขอซ้ำอย่างปลอดภัย

การแทงและการฝากถอนคือเงินที่ขยับ Idempotency-Key คือสิ่งเดียวที่บอก engine ว่าคำขอสองครั้งเป็นรายการเดียวกัน — key ใหม่คือรายการใหม่

  1. บันทึกก่อนยิง (commit-before-send)
    สร้างแถวคำสั่งในฐานข้อมูลของคุณพร้อม idem_key (UUID) และไบต์ body ที่แปลงแล้ว → commit → จึงเรียก engine · ผูก key กับรายการ ไม่ใช่กับการเรียก HTTP แต่ละครั้ง
  2. ลองใหม่ด้วย key เดิม + ไบต์เดิม
    แต่สร้าง X-Request-Id, X-Timestamp และลายเซ็นใหม่ทุกครั้ง
  3. หยุดลองใหม่เมื่อคำสั่งอายุเกินราว 20 ชั่วโมง
    engine จำผลแค่ 24 ชม. เลยกว่านั้นจะกลายเป็นรายการใหม่ (= ตัดเงินซ้ำ) ให้เปลี่ยนเป็น needs_review ให้คนตรวจ
  4. แยกผลเป็น 5 แบบ แล้วจัดการตามตาราง
ผลจาก engineความหมายทำอย่างไร
2xxสำเร็จบันทึกผล
422 duplicate_betอาจรับไปแล้วค้น /bet/history หา reference ของคุณ · ไม่เจอ ⇒ needs_review
400 · 404 · 422 อื่น · 403 lottery_not_allowed / member_inactive / tenant_suspendedถูกปฏิเสธปิดเป็น rejected (ถ้าเป็นการลองซ้ำ ให้เช็ค history ก่อนปิด)
409 idempotency_in_progress · 429ยังไม่รู้ ให้รอลองใหม่ภายหลังด้วย key เดิม
5xx · timeout · ต่อไม่ได้ · 3xx · 401/403 อื่น · 409 replay_detected · body อ่านไม่ออกไม่รู้ผลสถานะ unknown → worker ไล่ตาม ห้ามถือว่าล้มเหลว
!
"ไม่รู้" ไม่เท่ากับ "ไม่สำเร็จ" คืนเงินให้ผู้เล่นได้ก็ต่อเมื่อยืนยันแล้วว่า engine ไม่ได้รับรายการ คำขอสองครั้งของรายการเดียวที่ใช้ key ต่างกันคือสองรายการ และ engine จะทำทั้งสองรายการ
✓
ค่าที่เว็บพาร์ทเนอร์ที่ใช้งานจริงตั้งไว้: timeout 8 วินาที/ครั้ง · ลองใหม่ในคำขอเดียว 2 ครั้ง (หน่วง 1s, 2s) · ไม่ตาม redirect · circuit breaker (20 คำขอล่าสุด ล้มเกินครึ่ง ⇒ หยุด 30 วินาที นับเฉพาะ timeout/ต่อไม่ได้/5xx)

📦รูปแบบคำตอบและข้อตกลง

ทุกคำตอบห่อด้วย envelope เดียวกัน สำเร็จมี data ล้มเหลวมี error — ไม่มีฟิลด์ success หรือ ok ให้ดูที่ HTTP status และการมี error

{
  "data": { "...": "..." },
  "request_id": "6f1c2a9e-4b7d-4f3a-9c2e-1a2b3c4d5e6f"
}
{
  "error": {
    "code": "round_closed",
    "message": "betting: round is not accepting bets"
  },
  "request_id": "6f1c2a9e-4b7d-4f3a-9c2e-1a2b3c4d5e6f"
}
เรื่องข้อตกลง
เงินจำนวนเต็มสตางค์ (100 = ฿1) เช่น stake_satang: 1000 = ฿10 · ห้ามใช้ float
สกุลเงินTHB เท่านั้น
อัตราจ่ายเศษส่วนแม่นยำ rate_num / rate_den เช่น 900/1 = จ่าย 900 เท่า ปัดเศษแบบ half-up
เวลาISO 8601 เขต UTC (ลงท้าย Z) แปลงเป็นเวลาไทย (+07:00) ที่ฝั่งคุณ · ยกเว้น draw_date ที่เป็น YYYY-MM-DD ตามวันเวลาไทย
เลขที่แทงสตริงเสมอ เช่น "05" ห้ามส่งเป็นตัวเลข ไม่งั้นเลข 0 นำหน้าหาย
Rate limitค่าเริ่มต้น 600 คำขอ/นาทีต่อคีย์ เกินได้ 429 rate_limited · ดู header X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After
Paginationไม่มี cursor ทั่วไป แต่ละ endpoint คืนจำนวนจำกัดตามที่ระบุ
ผู้เช่า (tenant)มาจากคีย์เท่านั้น ส่ง tenant_id ใน body จะถูกเพิกเฉย
ข้อผิดพลาดตัดสินใจจาก error.code เท่านั้น · error.message เป็นภาษาอังกฤษสำหรับ log ห้ามแสดงให้ผู้เล่นเห็น · 5xx มีข้อความคงที่ ไม่มีรายละเอียดภายใน
i
เก็บ request_id ของทุกคำขอไว้ใน log ฝั่งคุณ เวลาแจ้งปัญหาให้ส่งค่านี้มาด้วย ทีม HuayEngine ใช้ไล่ log ฝั่งเซิร์ฟเวอร์ได้ทันที

💼โหมดกระเป๋าเงิน

คีย์หนึ่งใบมีโหมดกระเป๋าตายตัว ทีม HuayEngine ตั้งให้ตอนออกคีย์ — ถ้าไม่จำเป็นต้องถือเงินเอง ให้เริ่มที่ transfer

transfer แนะนำseamless (external_member)
ยอดเงินผู้เล่นอยู่ที่กระเป๋าใน engineledger ของคุณ
ฝาก / ถอนเรียก /wallet/deposit · /wallet/withdrawบันทึกใน ledger ตัวเอง ไม่เรียก engine
ตอนแทงengine ตัดเงินจากกระเป๋าในธุรกรรมเดียวกับตั๋วengine callback bet มาตัดเงินที่คุณก่อนรับตั๋ว
ถูกรางวัลเข้ากระเป๋าใน engine อัตโนมัติengine callback settle มาเครดิตที่คุณ
ยกเลิกบิล / ยกเลิกงวดengine คืนเข้ากระเป๋าทันทีengine callback rollback มาคืน — ห้ามคืนซ้ำเอง
ระบุผู้เล่นmember_id (กระเป๋า) · member_code (แทง)member_code + wallet_owner_id + wallet_tenant_id
ความยากต่ำสูง — ต้องเปิด callback endpoint ทำ idempotency และ reconcile

ค่าที่ตั้งบนคีย์: wallet_mode, wallet_identity_mode, seamless_callback_url, wallet_owner_id, wallet_tenant_id, ip_whitelist, rate_limit_per_min — เปลี่ยน identity mode ภายหลังไม่ได้

!
external_member ยังเป็นความสามารถใหม่ ต้องให้ทีม HuayEngine อนุมัติก่อนใช้กับเงินจริงบน production · คีย์ seamless แบบ legacy_agent เป็นเส้นทางภายในแพลตฟอร์ม HuayZ ไม่อยู่ในเอกสารนี้

👤สมาชิก

ลงทะเบียนผู้เล่นด้วย member_code ที่ฝั่งคุณออก แล้วเก็บ member_id ที่ได้ไว้ใช้ตลอดชีวิตของผู้เล่นคนนั้น

POST /api/v1/provider/members สร้างหรือคืนสมาชิก idempotent ในตัว · ไม่ต้องใช้ Idempotency-Key

Request

ฟิลด์ชนิดคำอธิบาย
member_codeบังคับstring^[A-Za-z0-9_-]{1,64}$ · แนะนำ รหัสแบรนด์ 2–4 ตัว + เลขรัน ≥ 6 หลัก เช่น AB000123 (ขอ prefix ที่ไม่ชนกับพาร์ทเนอร์อื่นจากทีม engine)
wallet_owner_idexternalintegerเฉพาะคีย์ external_member · ต้องตรงกับค่าบนคีย์
wallet_tenant_idexternalintegerเฉพาะคีย์ external_member · ต้องตรงกับค่าบนคีย์
member_idexternalintegerเฉพาะคีย์ external_member · ผูกกับ member_id ที่มีอยู่แล้ว (ไม่บังคับ)
{ "member_code": "AB000123" }
{
  "data": {
    "member_id": 812,
    "member_code": "AB000123",
    "status": "active",
    "created": true
  },
  "request_id": "..."
}
  • member_code ไม่สนตัวพิมพ์เล็ก/ใหญ่ — abC1 กับ ABc1 คือสมาชิกคนเดียวกัน (กระเป๋าเดียวกัน) ฝั่งคุณต้องออกรหัสที่ไม่ซ้ำแม้ไม่สนตัวพิมพ์ · member_code ในคำตอบคือค่าที่ส่งมา ไม่ใช่ตัวสะกดที่บันทึกไว้ — ใช้ member_id เป็นตัวระบุที่แน่นอน
  • ห้ามส่งข้อมูลส่วนตัว (ชื่อ เบอร์โทร ฯลฯ) — เก็บไว้ที่ฝั่งคุณ
  • สมาชิกที่ถูกระงับไว้แล้วคืน status ตามจริง (suspended, banned) endpoint นี้ไม่ปลุกให้กลับเป็น active
  • แนวทางที่ใช้ได้ดี: สมัครแล้วตั้งสถานะ pending_engine → เรียก /members ทันที + worker ไล่ซ้ำทุกนาที → active · หลังกู้ฐานข้อมูลให้เลื่อนเลขรันเลยรหัสที่ engine มีแล้ว

Errors

400bad_requestmember_code ผิดรูปแบบ
403wallet_mode_not_allowedคีย์ seamless ที่ไม่ใช่ external_member
403binding_mismatchwallet_* ไม่ตรงกับคีย์ หรือคีย์ไม่ใช่ external ส่งมา
500member_provision_failedลองใหม่ได้

💰กระเป๋าเงิน (transfer)

ทุก endpoint เป็น POST และระบุสมาชิกด้วย member_id (ตัวเลข) — ต่างจาก /bet/place ที่ใช้ member_code · บัญชีกระเป๋าถูกสร้างอัตโนมัติครั้งแรกที่เห็น member_id นั้น

!
ใช้ตัวระบุแบบเดียวกันทั้งระบบ member_id ที่ engine ไม่รู้จักจะได้กระเป๋าว่างเงียบ ๆ แล้วเงินที่ฝากกับบิลที่แทงจะอยู่คนละกระเป๋า
POST /api/v1/provider/wallet/balance ดูยอดเงินของสมาชิก
{ "member_id": 501 }
{
  "data": {
    "member_id": 501,
    "balance_satang": 125000,
    "balance": "1250.00",
    "currency": "THB"
  },
  "request_id": "..."
}

คีย์ external_member ส่ง { member_code, wallet_owner_id, wallet_tenant_id } แทน engine จะยิง callback getbalance ไปถามระบบคุณแล้วคืนยอดกลับมา · Errors: 400 bad_request · 403 binding_mismatch · 500/503 wallet_error (ลองใหม่ได้)

POST /api/v1/provider/wallet/deposit โอนเงินเข้ากระเป๋าสมาชิก Idempotency-Key

Request

ฟิลด์ชนิดคำอธิบาย
member_idบังคับintegerจาก POST /members
amount_satangบังคับintegerจำนวนเงิน (สตางค์) มากกว่า 0
referenceบังคับstringรหัสรายการของคุณ เช่น AB-D-981
{
  "member_id": 501,
  "amount_satang": 50000,
  "reference": "AB-D-981"
}
{
  "data": {
    "id": 70412,
    "member_id": 501,
    "direction": "deposit",
    "amount": 50000,
    "status": "completed",
    "reference": "AB-D-981",
    "request_id": "..."
  },
  "request_id": "..."
}
!
422 payment_failed ไม่รับประกันว่าเงินไม่ขยับ — เทียบยอดก่อน/หลังด้วย /wallet/balance ก่อนสรุป · timeout = ไม่รู้ผล ส่งซ้ำด้วย key และ body เดิม

แนะนำรูปแบบ reference ที่แยกประเภทได้ เช่น ฝาก XXD-{id} · ถอน XXW-{id} · คืนเงินถอน XXW-{id}-R · ปรับยอด XXA- · โบนัส XXB-

Errors

400bad_request · idempotency_required
409idempotency_in_progress · replay_detected
422payment_failed
POST /api/v1/provider/wallet/withdraw ถอนเงินออกจากกระเป๋าสมาชิก Idempotency-Key

Request และ response รูปเดียวกับ /wallet/deposit (direction: "withdrawal") · ยอดไม่พอได้ 422 payment_failed

  1. ตัดยอดที่ engine ก่อน ด้วย /wallet/withdraw
  2. จึงโอนเงินจริงให้ผู้เล่น
  3. โอนไม่สำเร็จ ให้ /wallet/deposit คืนด้วย reference ต่อท้าย -R (key ใหม่ เพราะเป็นรายการใหม่)

🎯ตลาดและงวด

อ่านอย่างเดียว ไม่ต้องใช้ Idempotency-Key · อัตราจ่ายและเพดานถูก freeze ลง snapshot ตอนสร้างงวด จึงใช้ betconfig ของงวดนั้นเป็นความจริงเสมอ

i
ขอบเขตตลาดของคีย์ ค่าเริ่มต้นคือเปิดทุกตลาด ถ้าคีย์ถูกจำกัด /games และ /rounds จะคืนเฉพาะตลาดที่เปิดให้ และทุก endpoint ที่ลงมือทำ (แทง ยกเลิก ปิด/ยกเลิกงวด betconfig) จะตรวจขอบเขตเองด้วย ตลาดนอกขอบเขตได้ 403 lottery_not_allowed อย่าแคชรายการตลาดข้ามวันแล้วเดาว่ายังทำได้ · /results และ /results/status ไม่กรองตามขอบเขตของคีย์

สถานะงวด

scheduled→open→closed→drawn→settled→reconciled→archived

แทงได้เมื่อ status = open และยังไม่ถึง close_at เท่านั้น · scheduled / open / closed ถูกยกเลิกเป็น cancelled ได้ด้วย /void

cache ที่แนะนำ

ข้อมูลcache
GET /games5 นาที
GET /rounds15 วินาที
GET /rounds/{id}/betconfig10 วินาที
GET /results60 วินาที

อย่าให้หน้าเว็บสาธารณะยิงตรงถึง engine ทุกครั้ง โควตา 600/นาทีใช้ร่วมกับการแทง · engine ล่มให้เสิร์ฟของใน cache พร้อมป้าย stale แทนหน้าว่าง

GET /api/v1/provider/games รายการตลาดหวยที่คีย์นี้เปิดใช้
{
  "data": [
    { "id": 3, "code": "th_gov", "name_th": "หวยรัฐบาลไทย", "name_en": "Thai Government", "category_id": 1, "sort_order": 1, "active": true },
    { "id": 12, "code": "yeekee_5", "name_th": "ยี่กี 5 นาที", "name_en": "Yeekee 5 min", "category_id": 4, "sort_order": 20, "active": true }
  ],
  "request_id": "..."
}

code ของตลาดใช้เป็น lottery_id ตอนดึงผลจาก /results

GET /api/v1/provider/rounds รายการงวด

Query

พารามิเตอร์ชนิดคำอธิบาย
lottery_type_idไม่บังคับintegerไม่ใส่ = งวดตัวแทน 1 งวดต่อตลาด (งวดที่เปิดและใกล้ปิดที่สุด ถ้าไม่มีคืองวดล่าสุด) ใช้ทำหน้า lobby · ใส่ = งวดของตลาดนั้น สูงสุด 300 งวด · ตลาดนอกขอบเขตได้ 403 lottery_not_allowed (ไม่ใช่รายการว่าง)
{
  "data": [
    {
      "id": 4821,
      "lottery_type_id": 3,
      "lottery_code": "th_gov",
      "name": "หวยรัฐบาล 16/12/69",
      "round_date": "2026-12-16T00:00:00Z",
      "open_at": "2026-12-01T09:00:00Z",
      "close_at": "2026-12-16T08:30:00Z",
      "draw_at": "2026-12-16T09:00:00Z",
      "status": "open"
    }
  ],
  "request_id": "..."
}
GET /api/v1/provider/rounds/{roundID}/betconfig ประเภทเลข อัตราจ่าย และเพดานของงวด
{
  "data": {
    "round_id": 4821,
    "lottery_type_id": 3,
    "lottery_code": "th_gov",
    "name": "หวยรัฐบาล 16/12/69",
    "status": "open",
    "accepts_bets": true,
    "bet_types": {
      "3_top": {
        "id": 11, "code": "3_top", "name": "3 ตัวบน",
        "rate": { "num": 900, "den": 1 },
        "min_stake": 100, "max_stake": 500000,
        "number_limit": 2000000, "member_limit": 100000,
        "ladder": [ { "exposure_from": 1000000, "rate": { "num": 700, "den": 1 } } ]
      }
    }
  },
  "request_id": "..."
}
ฟิลด์ใน bet_types.*ความหมาย
rateอัตราจ่าย เงินรางวัล = เงินแทง × num ÷ den
min_stake · max_stakeเงินแทงต่ำสุด/สูงสุดต่อรายการ (สตางค์)
number_limitยอดแทงรวมทุกคนสูงสุดต่อเลข (สตางค์)
member_limitยอดแทงสะสมต่อสมาชิกต่อเลข · ไม่มีฟิลด์ = ไม่จำกัด
payout_risk_limitเพดานยอดต้องจ่ายรวมต่อเลข · ไม่มีฟิลด์ = ไม่จำกัด
ladderอัตราจ่ายขั้นบันได เมื่อยอดแทงรวมของเลขถึง exposure_from จะจ่ายตาม rate ขั้นนั้น
!
bet_types เป็น object ที่คีย์คือรหัสประเภทเลข ไม่ใช่ array · ห้ามส่ง number_limit, member_limit, payout_risk_limit, ladder ให้ผู้เล่น (ข้อมูลความเสี่ยงภายใน)

Errors: 400 bad_request (roundID ไม่ใช่ตัวเลข) · 403 lottery_not_allowed · 404 not_found — ตอบรหัสเดียวกันแม้อ่านงวดไม่สำเร็จชั่วคราว อย่าสรุปจาก 404 ครั้งเดียวว่างวดไม่มีจริง

GET /api/v1/provider/rounds/{roundID}/yeekee-commitment ตรวจความโปร่งใสของงวดยี่กี (commit-reveal)

ก่อนออกผลคืน seed_hash ส่วน seed เปิดเผยหลังออกผล ให้ผู้เล่นตรวจได้ว่าผลไม่ถูกเปลี่ยน

{
  "data": {
    "round_id": 9120,
    "algorithm": "...",
    "seed_hash": "4f1e…",
    "committed_at": "2026-11-17T07:55:00Z",
    "seed": "…",          // หลังออกผลเท่านั้น
    "bet_total": 1520000, // หลังออกผลเท่านั้น
    "revealed_at": "2026-11-17T08:05:02Z"
  },
  "request_id": "..."
}

Errors: 400 bad_request · 403 lottery_not_allowed · 404 not_found (งวดนี้ไม่มี commitment) · 500 read_failed (ลองใหม่ได้)

🎫แทงหวย

โพยหนึ่งใบ = ตั๋ว (ticket) หนึ่งใบที่มีได้หลายรายการ การวางเป็น atomic ทั้งใบ — รายการใดผิด ทั้งใบถูกปฏิเสธและไม่ตัดเงิน

i
ตั๋วผูกกับคีย์ที่วาง: GET /bet/{ticket_id}, /bets/detail, /bet/history และ /bet/cancel เห็นเฉพาะตั๋วที่วางด้วยคีย์ใบเดียวกัน ตั๋วของคีย์อื่นได้ 404 not_found
POST /api/v1/provider/bet/place วางโพย Idempotency-Key

Request

ฟิลด์ชนิดคำอธิบาย
member_codeบังคับstringตัวผู้เล่น · ส่ง member_code ไม่ใช่ member_id (member_id ที่ engine ไม่รู้จักได้กระเป๋าว่างเงียบ ๆ) · ไม่มีในระบบได้ 422 unknown_member
round_idบังคับintegerid ของงวดจาก /rounds
referenceแนะนำstring ≤ 64รหัสบิลของคุณ ใช้ค้นตั๋วคืนจาก /bet/history และกระทบยอด
items[]บังคับarrayรายการแทง อย่างน้อย 1 รายการ
items[].bet_type_codestringต้องมีอยู่ใน bet_types ของ betconfig งวดนั้น (ดูประเภทเลข)
items[].numberstringตัวเลขล้วน จำนวนหลักตรงกับประเภทเลข · เป็นสตริงเสมอ
items[].stake_satangintegerเงินแทง (สตางค์) อยู่ระหว่าง min_stake–max_stake
session_tokenไม่บังคับstringจาก /session/launch · ส่งแล้ว token ไม่ถูกต้องได้ 401 session_invalid
wallet_owner_id · wallet_tenant_idexternalintegerเฉพาะคีย์ external_member ต้องตรงกับค่าบนคีย์ · currency ถ้าส่งต้องเป็น "THB"
!
ห้ามส่ง rate_num / rate_den — อัตราจ่ายถูกล็อกโดย engine ตอนรับตั๋ว
{
  "member_code": "AB000123",
  "round_id": 4821,
  "reference": "AB-1001",
  "items": [
    { "bet_type_code": "3_top",    "number": "123", "stake_satang": 10000 },
    { "bet_type_code": "2_bottom", "number": "45",  "stake_satang": 5000 }
  ]
}
{
  "data": {
    "id": 9042,
    "member_id": 501,
    "member_code": "AB000123",
    "lottery_round_id": 4821,
    "lottery_code": "th_gov",
    "reference": "AB-1001",
    "total_stake": 15000,
    "potential_win": 9450000,
    "status": "accepted",
    "currency": "",
    "request_id": "6f1c2a9e-...",
    "idempotency_key": "0f1c8a2e-...",
    "ledger_entry_id": 33107,
    "created_at": "2026-12-10T06:12:04Z"
  },
  "request_id": "..."
}

คำตอบไม่มีรายการ ให้อ่านจาก GET /bet/{ticket_id} · อัตราจ่ายจริงของแต่ละรายการ (rate_num/rate_den) อาจต่ำกว่า rate ใน betconfig เมื่อเลขนั้นถึงขั้น ladder — แสดงเงินรางวัลจากค่าในตั๋วเสมอ

สถานะ

ตั๋ว statusaccepted → settled หรือ cancelled
รายการ settlement_statuspending → won lost void

Errors ที่พบบ่อย

HTTPcodeความหมาย
422round_closedงวดไม่รับแทงแล้ว แสดงผู้เล่น
422number_heldเลขอั้น / เต็ม แสดงผู้เล่น
422stake_out_of_rangeเงินแทงนอกช่วง min–max แสดงผู้เล่น
422unknown_bet_type · no_itemsประเภทเลขไม่เปิดในงวดนี้ / โพยว่าง แสดงผู้เล่น
422place_bet_failed · wallet_rejectedอื่น ๆ เช่น เงินไม่พอ เกินเพดานต่อเลข / ปลายทาง seamless ปฏิเสธการตัดเงิน แสดงผู้เล่น
422duplicate_betkey นี้เคยรับตั๋วแล้ว — ถือว่าอาจสำเร็จ ค้นจาก /bet/history
422unknown_member · rate_exceeds_ceilingไม่มีสมาชิกนี้ / อัตราที่แนบมาสูงกว่า snapshot
403lottery_not_allowed · tenant_suspended · binding_mismatchไม่มีสิทธิ์
409idempotency_in_progress · replay_detected · idempotency_conflictดูIdempotency
500member_lookup_failedลองใหม่ด้วย key เดิม
503placement_pending(external) ยังไม่รู้ผล — ถาม /bet/attempt

สถานะบิลฝั่งคุณที่ใช้ได้ดี: pending → accepted → settled | cancelled และ rejected, unknown (+ needs_review) — settled / cancelled เป็นสถานะสุดท้าย ห้ามถอยกลับ

POST /api/v1/provider/bet/cancel ยกเลิกตั๋ว Idempotency-Key

ทำได้เฉพาะตั๋ว accepted ที่งวดยังรับแทงอยู่ หลังปิดรับได้ 422 round_closed · key ผูกกับ body — key เดิมแต่ body ต่างได้ 409 idempotency_conflict · บันทึก cancel key ลงฐานก่อนยิงเช่นกัน

{ "ticket_id": 9042 }
{
  "data": {
    "ticket_id": 9042,
    "status": "cancelled",
    "cancellation_action": "cancel",
    "refund_status": "confirmed",
    "refund_reference": "..."
  },
  "request_id": "..."
}
ชนิดคีย์ใครคืนเงินrefund_status
transferengine คืนเข้ากระเป๋าใน engine ทันทีconfirmed
seamlessengine ยิง callback rollback ผ่าน outbox (refund_reference = rollback:void:{tenant_id}:{ticket_id}) — ห้ามคืนซ้ำในระบบคุณpending → อ่านซ้ำได้ confirmed หรือ needs_review

ยืนยันการคืนเงินของคีย์ seamless จาก receipt ของ callback เท่านั้น refund_status ในคำตอบบอกได้แค่ว่าเข้าคิวแล้ว

!
503 refund_status_unavailable = ยกเลิกสำเร็จแล้ว แต่อ่านสถานะคืนเงินไม่ได้ชั่วคราว อย่ายิงซ้ำ ให้อ่าน GET /bet/{ticket_id} แทน · 422 cancel_failed เป็นรหัสรวมของเหตุอื่น ๆ (เช่นตั๋ว settle แล้ว) ไม่ได้แปลว่างวดปิด
GET /api/v1/provider/bet/{ticket_id} ตั๋ว 1 ใบพร้อมรายการ
{
  "data": {
    "ticket": { "id": 9042, "lottery_round_id": 4821, "reference": "AB-1001", "total_stake": 15000, "status": "settled", "...": "..." },
    "items": [
      {
        "id": 77101, "bet_ticket_id": 9042, "bet_type_code": "3_top", "number": "123",
        "stake": 10000, "rate_num": 900, "rate_den": 1,
        "potential_payout": 9000000, "payout": 9000000, "settlement_status": "won"
      },
      {
        "id": 77102, "bet_ticket_id": 9042, "bet_type_code": "2_bottom", "number": "45",
        "stake": 5000, "rate_num": 90, "rate_den": 1,
        "potential_payout": 450000, "payout": 0, "settlement_status": "lost"
      }
    ]
  },
  "request_id": "..."
}

ตั๋ว status = settled แปลว่าทุกรายการได้ผลแล้ว · ยอดถูกรางวัล = ผลรวม payout ของ items ห้ามคำนวณเอง · ทางเดียวที่จะเห็นการยกเลิก/void/rollback จากฝั่ง engine คืออ่านตั๋วซ้ำ · Errors: 400 bad_request · 404 not_found

GET /api/v1/provider/bets/detail?ids=9042,9043 รายการของหลายตั๋วในครั้งเดียว (สูงสุด 200 ใบ)
{
  "data": {
    "bills": [
      { "ticket_id": 9042, "items": [ { "id": 77101, "settlement_status": "won", "payout": 9000000, "...": "..." } ] },
      { "ticket_id": 9043, "items": [] }
    ]
  },
  "request_id": "..."
}

คืน 1 แถวต่อ id ที่ขอ · id ที่ไม่พบหรือเป็นของคีย์อื่นได้ items: [] · id ที่ไม่ใช่ตัวเลขถูกข้าม · ใช้ทำ worker sync ทุก 5 นาที: บิล settled เมื่อไม่มี item ที่เป็น pending · Errors: 500 batch_failed (ลองใหม่ได้)

GET /api/v1/provider/bet/history?member_id=501 ตั๋วล่าสุด 100 ใบของสมาชิก

เรียงใหม่สุดก่อน สูงสุด 100 ใบ · ใช้ค้น reference ของคุณเมื่อได้ 422 duplicate_bet หรือไม่รู้ผลการแทง · Errors: 400 bad_request (ไม่มี member_id)

⛔ปิดรับ / ยกเลิกงวด

ปิดรับแทง หรือยกเลิกทั้งงวดพร้อมคืนเงินทุกบิล ของงวดในผู้เช่าของคุณเอง ด้วยคีย์ที่ใช้แทงอยู่ (จำกัดตามขอบเขตตลาดของคีย์)

!
สี่เรื่องที่พลาดแล้วเสียเงินจริง
  1. void ต้องใช้ key เดิมทุกครั้งที่ retry — key ใหม่บนงวดที่ยกเลิกไปแล้วได้ 422 not_voidable ซึ่งบอกไม่ได้ว่าครั้งแรกสำเร็จหรือไม่
  2. 422 not_voidable หลัง timeout ไม่ได้แปลว่าล้มเหลว — อ่านสถานะงวดก่อน ห้ามคืนเงินผู้เล่นเองจนกว่าจะรู้ว่า engine ยังไม่ได้คืน
  3. 404 ไม่ได้แปลว่างวดไม่มีอยู่จริง — อาจเป็นงวดของผู้เช่าอื่น engine ตอบเหมือนกันโดยตั้งใจ
  4. คีย์ seamless: void คืนเงินให้เอง ผ่าน callback rollback ต่อบิล ห้ามคืนซ้ำในระบบคุณ
POST /api/v1/provider/rounds/{roundID}/close ปิดรับแทง Idempotency-Key ย้อนกลับไม่ได้

ไม่มี body (เซ็นด้วย SHA-256 ของ body ว่าง) · ใช้ได้เฉพาะงวด open ปิดก่อนถึง close_at ได้ · ตั๋วที่รับไว้แล้วยัง accepted และรอผลตามปกติ · หลังปิด /bet/place ได้ 422 round_closed · ไม่มี endpoint เปิดรับกลับ

{ "data": { "round_id": 4821, "status": "closed" }, "request_id": "..." }
POST /api/v1/provider/rounds/{roundID}/void ยกเลิกทั้งงวดและคืนเงินทุกบิล Idempotency-Key ย้อนกลับไม่ได้
ฟิลด์ชนิดคำอธิบาย
reasonบังคับstring1–200 อักขระ นับเป็น Unicode code point (สระและวรรณยุกต์ไทยนับตัวละหนึ่ง เช่น "ที่" = 3) · ห้ามมีขึ้นบรรทัด tab หรืออักขระควบคุม
{ "reason": "ตลาดต้นทางประกาศงดออกผลงวดนี้" }
{
  "data": { "round_id": 4821, "status": "cancelled", "refunded": 12 },
  "request_id": "..."
}
  • ใช้กับงวดที่ยังไม่ออกผล: scheduled, open, closed · ออกผลแล้วหรือยกเลิกไปแล้วได้ 422 not_voidable
  • ทำในธุรกรรมเดียว: บิล accepted ทุกใบเป็น cancelled รายการเป็น void คืนเงินตามรางของบิล และงวดเป็น cancelled — ผลกระทบระดับงวด รวมบิลที่วางผ่านคีย์อื่นในผู้เช่าเดียวกัน
  • refunded = จำนวนบิล ไม่ใช่จำนวนเงิน · งวดที่มีบิลมากใช้เวลานาน ให้ตั้ง timeout ยาวกว่าปกติ
  • engine ส่ง webhook round.closed เมื่อปิด และ bet.cancelled ต่อบิลเมื่อ void

ไม่แน่ใจว่าสำเร็จหรือยัง

อ่าน GET /rounds/{roundID}/betconfig แล้วดู data.status

statusความหมายทำอะไรต่อ
cancelledvoid สำเร็จแล้วอย่ายิงซ้ำ และอย่าคืนเงินเอง
closedปิดแล้ว · void ยังไม่เกิดถ้าจะ void ให้ยิงด้วย key เดิม
openคำขอยังไม่สำเร็จยิงซ้ำด้วย key เดิม
scheduledงวดยังไม่เปิดclose ไม่ได้ · void ได้ ด้วย key เดิม
drawn ขึ้นไปออกผลหรือจ่ายเงินแล้วติดต่อทีม HuayEngine

Errors

400bad_request · idempotency_requiredreason ผิดกติกา / ขาด key
403lottery_not_allowedตลาดนี้ไม่ได้เปิดให้คีย์
404round_not_foundไม่พบงวดในผู้เช่าของคีย์ (รวมงวดของผู้เช่าอื่น)
422not_closable · not_voidableสถานะงวดไม่อนุญาต — หลัง timeout อาจแปลว่าสำเร็จแล้ว
422refund_failedมีบิล seamless ที่คืนเงินไม่ได้ จึงไม่ยกเลิกอะไรเลย ติดต่อทีมพร้อม request_id
500lookup_failed · scope_failed · close_failed · void_failedไม่มีอะไรเปลี่ยน — backoff แล้วใช้ key เดิม
503void_unavailableท่อคืนเงิน seamless ยังไม่พร้อม (ฝั่ง engine)

🏆ผลรางวัล

ผลมีผลกับตั๋วหลัง publish เท่านั้น จากนั้น worker จะ settle แบบ idempotent แล้วเปลี่ยนตั๋วเป็น settled — รู้ผลได้จาก webhook หรือดึงเอง

GET /api/v1/provider/results ผลรางวัลที่ประกาศแล้ว
พารามิเตอร์ชนิดคำอธิบาย
lottery_idไม่บังคับstringcode ของตลาด เช่น th_gov
draw_dateไม่บังคับYYYY-MM-DDวันออกผลตามเวลาไทย
limitไม่บังคับintegerระบุตลาด: ค่าเริ่มต้น 400 สูงสุด 500 · ไม่ระบุตลาด: ไม่เกิน 60 งวดล่าสุดต่อตลาด รวมไม่เกิน 500 แถว (ไม่สน limit)
{
  "data": [
    {
      "lottery_id": "th_gov",
      "lottery_name": "หวยรัฐบาล 16/12/69",
      "round_id": 4821,
      "draw_date": "2026-12-16",
      "numbers": { "top3": "739", "bottom2": "12" }
    }
  ],
  "request_id": "..."
}

numbers เป็น map ชื่อรางวัล → เลข คีย์ขึ้นกับตลาด อย่าฮาร์ดโค้ดชุดคีย์

GET /api/v1/provider/results/status?round_id=4821 ผลงวดนี้ออกหรือยัง
{
  "data": { "round_id": 4821, "published": true, "top3": "739", "top2": "39", "bottom2": "12" },
  "request_id": "..."
}

Errors: 400 bad_request (ไม่มี round_id) · 500 status_failed (ลองใหม่ได้)

🚀Session และลิงก์เข้าเล่น

พาผู้เล่นไปแทงที่หน้า play ของ HuayEngine แทนการสร้างหน้าแทงเอง — ไม่บังคับ ถ้าคุณมีหน้าแทงของตัวเองและเรียก /bet/place เอง ข้ามหัวข้อนี้ได้

POST /api/v1/provider/session/launch ขอ session และลิงก์เข้าเล่น transfer
ฟิลด์ชนิดคำอธิบาย
member_codeบังคับstring^[A-Za-z0-9_-]{1,64}$ · ยังไม่มีสมาชิก engine สร้างให้ (member_ref = ชื่อเดิมของฟิลด์นี้)
return_urlไม่บังคับstringhttps · ยาวไม่เกิน 512 · ปุ่ม "กลับเว็บผู้ให้บริการ" ในหน้า play
langไม่บังคับstringth · en · lo
lottery_round_id หรือ lottery_type_idไม่บังคับintegerเปิดเข้าหน้าแทงของงวด/ตลาดนั้นตรง ๆ (ใส่ได้อย่างเดียว) · ไม่ใส่ = หน้า lobby
{
  "member_code": "AB000123",
  "return_url": "https://partner.example/lobby",
  "lang": "th"
}
{
  "data": {
    "session_token": "…",
    "member_ref": "AB000123",
    "expires_at": "2026-11-17T09:00:00Z",
    "member_id": 812,
    "launch_url": "https://…/launch#code=…",
    "launch_expires_at": "2026-11-17T08:02:00Z"
  },
  "request_id": "..."
}
  • launch_url ใช้ได้ ครั้งเดียว ภายใน 120 วินาที — สร้างตอนผู้เล่นกด "เล่น" แล้ว redirect ทันที ห้ามสร้างล่วงหน้า ห้ามส่งทางแชตหรืออีเมล และอย่าเขียนลง log
  • เปิดแบบ redirect เต็มหน้าหรือแท็บใหม่ (ไม่รองรับ iframe) · ถ้าเปิดแท็บใหม่ให้เปิดหน้าต่างก่อน await ไม่งั้นเบราว์เซอร์บล็อก popup
  • session ในหน้า play อยู่ได้ 2 ชั่วโมง ไม่ต่ออายุ · session_token อายุ 1 ชั่วโมง
  • โอนเงินเข้า /wallet/deposit ด้วย member_id ที่ได้ ก่อนพาผู้เล่นไป

Errors: 400 bad_request · 403 member_inactive · tenant_suspended · launch_target_unavailable · backend_only (คีย์ external_member ใช้ /play/launch แทน) · 500 session_failed / launch_failed (เรียกใหม่ได้ลิงก์ใหม่)

POST /api/v1/provider/session/validate ตรวจ session token
{ "session_token": "…" }
{
  "data": { "valid": true, "member_ref": "AB000123", "expires_at": "2026-11-17T09:00:00Z" },
  "request_id": "..."
}

หมดอายุหรือไม่ถูกต้องได้ 401 session_invalid · ไม่ส่ง token ได้ 400 bad_request

POST /api/v1/provider/play/launch ลิงก์เข้าเล่นของสมาชิกกระเป๋าภายนอก (Member Play) external_member

ต้องเป็นคีย์ external_member ที่เปิดช่องทาง Member Play แล้ว และลงทะเบียน origin ของ return_url ไว้ · ลายเซ็น v2 เท่านั้น · การสร้างลิงก์ไม่ตัดเงิน · body เป็น strict JSON (ฟิลด์แปลกปลอมหรือซ้ำถูกปฏิเสธ)

ฟิลด์ชนิดคำอธิบาย
member_refบังคับstringmember_code ของผู้เล่นที่ล็อกอินอยู่ — อ่านจาก binding ในฐานของคุณ ห้ามรับจากเบราว์เซอร์
wallet_tenant_id · wallet_owner_idบังคับinteger ≥ 1ตรงกับค่าบนคีย์
currencyบังคับstring"THB"
launch_grant_idบังคับuuidสิทธิ์เล่นที่คุณสร้างและบันทึกไว้ก่อนขอลิงก์ (UUID สุ่มที่ไม่มี grant ฝั่งกระเป๋ารองรับใช้รับบิลไม่ได้)
return_urlบังคับuriorigin ต้องลงทะเบียนไว้
lottery_round_id หรือ lottery_type_idไม่บังคับintegerใส่ได้อย่างเดียว · ไม่ใส่ = lobby
langไม่บังคับstringth · en · lo
{
  "member_ref": "AB000123",
  "wallet_tenant_id": 3,
  "wallet_owner_id": 7,
  "currency": "THB",
  "launch_grant_id": "0b6f1e9a-2c4d-4f8e-9a1b-3c5d7e9f1a2b",
  "return_url": "https://partner.example/lobby",
  "lang": "th"
}
{
  "data": {
    "launch_url": "https://…/launch#code=…",
    "expires_at": "2026-11-17T08:02:00Z"
  }
}

เปิด launch_url ทั้งเส้นทางและ fragment ทันที (ใช้ครั้งเดียว) อย่าประกอบ URL เอง · ยอดในหน้า play อ่านสดจาก callback getbalance และต้องเป็นยอดใช้ได้ ไม่ใช่ยอดรวมก่อนหักยอดที่กันไว้

Errors: 400 bad_request · 401 signature_version_required / invalid_signature · 403 member_play_denied / launch_target_unavailable · 409 replay_detected · 429 rate_limited · 503 member_play_unavailable

🎲ยิงเลขยี่กี

ให้ผู้เล่นยิงเลข 5 หลักร่วมกำหนดผลยี่กี — การยิงไม่ใช่การแทงและไม่ขยับเงิน · ปิดไว้เป็นค่าเริ่มต้น ต้องขอทีม HuayEngine เปิดให้ตลาดของคุณ

!
GET ของ state / shots / proof ต้องส่ง JSON body ระบุตัวผู้เล่น และเซ็นไบต์นั้น เช่น {"member_ref":"AB000123"} (สมาชิกต้องลงทะเบียนผ่าน /members ก่อน) · ห้ามย้ายตัวตนไปไว้ใน query · proxy ระหว่างทางต้องคง GET body ไว้ · คำตอบมี Cache-Control: private, no-store · ฟิลด์นอกสัญญา member_id หรือ tenant_id ถูกปฏิเสธ
GET /api/v1/provider/rounds/{roundID}/yeekee/state สถานะการยิงของงวดและของผู้เล่น

คืน round_id, lottery_type_id, lottery_code, algorithm, shooting_enabled, accepts_shots, open_at, close_at, server_time, shot_count, shot_sum, cadence_ms, member_round_cap, my_count, next_shot_at (ถ้ามี), seed_hash · accepts_shots คำนวณฝั่งเซิร์ฟเวอร์ ใช้ค่านี้ตัดสินว่าเปิดปุ่มยิงได้หรือไม่

GET /api/v1/provider/rounds/{roundID}/yeekee/shots?after_sequence=0&limit=20&mine=false ฟีดเลขที่ยิงแล้ว (เรียงตาม sequence)

limit 1–50 · after_sequence เป็น cursor · mine = true/false · คืน items[{sequence, number, accepted_at, is_mine}], next_sequence, has_more — ไม่มีชื่อหรือข้อมูลส่วนตัวของผู้ยิงคนอื่น

POST /api/v1/provider/rounds/{roundID}/yeekee/shots ยิงเลข 5 หลัก Idempotency-Key
{ "member_ref": "AB000123", "number": "00001" }
{
  "data": {
    "round_id": 9120, "shot_id": 551, "sequence": 37,
    "number": "00001", "accepted_at": "2026-11-17T07:58:12Z"
  },
  "request_id": "..."
}

number เป็นสตริง ASCII 5 หลัก (รักษา 00000) · key: ASCII ที่มองเห็นได้ 1–128 ไบต์ · key เดิม + เลขเดิมคืน receipt เดิมแม้ปิดรอบแล้ว · เลขต่างได้ 409 idempotency_conflict

Errors: 400 invalid_shot_request / idempotency_required · 403 lottery_not_allowed / member_not_allowed · 409 idempotency_conflict · 422 shooting_disabled / not_yeekee / round_not_open / round_closed / shot_limit_reached / commitment_unavailable · 429 shot_rate_limited · 500 shooting_failed

GET /api/v1/provider/rounds/{roundID}/yeekee/proof หลักฐานการคำนวณผล

คืน tenant_id, round_id, version, algorithm, seed_hash, committed_at · หลังเปิดเผยเพิ่ม revealed_at, seed, bet_total, top3/bottom2 และ (v3) frozen_count, frozen_sum, frozen_digest, subtracted_sequence, subtracted_number, frozen_at · ก่อนปิดรอบไม่มี seed

🔄โหมด seamless (external_member)

เมื่อต้องถือเงินผู้เล่นใน ledger ของคุณเอง — ทำขั้นตอนเหมือน transfer ทุกอย่าง ยกเว้นไม่เรียก /wallet/deposit และ /wallet/withdraw และต้องเปิด callback endpoint

คำขอที่เปลี่ยนไป

  • /members และ /bet/place ต้องส่ง wallet_owner_id, wallet_tenant_id (ตามค่าบนคีย์) · currency ใน /bet/place ถ้าส่งต้องเป็น "THB"
  • /wallet/balance ส่ง {member_code, wallet_owner_id, wallet_tenant_id} → engine ยิง getbalance มาถามคุณ
  • /session/launch ใช้ไม่ได้ (403 backend_only) — ใช้ /play/launch
  • /bet/place ที่ผลไม่ชัด (timeout, 503 placement_pending) ให้ถาม /bet/attempt ก่อน · มีรหัสเพิ่ม: 422 placement_rejected / placement_compensated (ปิดเป็น rejected ได้) · 403 binding_mismatch
  • /bet/place ของคีย์นี้ตรวจตัวตนของคำขอ: key เดิมกับผู้เล่น/รายการต่างได้ 409 idempotency_conflict
POST /api/v1/provider/bet/attempt ถามผลการวางบิลจาก Idempotency-Key external_member
{
  "member_id": 812,
  "idempotency_key": "0f1c8a2e-…",
  "wallet_owner_id": 7,
  "wallet_tenant_id": 3
}
{
  "data": {
    "state": "accepted",
    "ticket": { "id": 9042, "...": "..." },
    "refund_pending": false
  },
  "request_id": "..."
}
ผลทำอย่างไร
state: acceptedใช้ ticket ที่ได้
404 attempt_not_foundengine ไม่เคยได้รับ — ส่ง /bet/place ซ้ำด้วย key เดิม
state: rejectedไม่รับ ไม่มีเงินค้าง
state: compensatedไม่รับ และคืนเงินแล้ว
สถานะอื่น (persisting, compensation_pending, needs_review) · 503 placement_pendingยังไม่รู้ผล ถามใหม่ภายหลัง

member_id คือของ engine (จาก /members) · idempotency_key ยาวไม่เกิน 80 · คีย์ที่ไม่ใช่ external ได้ 403 forbidden

POST /api/v1/provider/bet/settlement-proof หลักฐานการจ่ายรางวัลฝั่ง engine external_member
{
  "ticket_id": 9042,
  "member_id": 812,
  "wallet_owner_id": 7,
  "wallet_tenant_id": 3,
  "generation": 1,
  "item_ref": "settle:3:118:77101"
}
{
  "data": {
    "ticket": { "id": 9042, "...": "..." },
    "item": { "...": "..." },
    "generation_status": "...",
    "credit_status": "...",
    "reversal_status": "..."
  },
  "request_id": "..."
}

ใส่ generation + item_ref คู่กันเมื่อถามรายการรางวัลรายตัว (ตรงกับ settlement_generation / settlement_item_ref ใน callback) · Errors: 400 bad_request · 403 forbidden / binding_mismatch · 404 proof_not_found · 503 proof_unavailable

Reconcile

ตรวจยอดรายวันเทียบกับ engine (แนะนำหลัง 05:00 เวลาไทย) และเว้นระยะคำขอเพื่อไม่กินโควตาแทง

📞Callback ที่คุณต้องเปิด (seamless)

engine ยิงทุกการเคลื่อนไหวของเงินมาที่ระบบคุณ ระบบคุณเป็นผู้ตัดสินว่าตัด/จ่ายได้หรือไม่

POST {seamless_callback_url}/seamless/lotto/HUAY/{op}
Content-Type: application/json
X-Api-Key: <api_key ของคุณ>
X-Request-Id: c0ffee00-1111-4222-8333-444455556666
X-Signature: hex(HMAC-SHA256(hmac_secret, X-Request-Id + "." + raw_body))
Idempotency-Key: <reference>

{"op":"bet","member_ref":"HP000123","currency":"THB","reference":"ORDER-1001-bet","round_id":"4821","ticket_ref":"","amount_satang":1000,"wallet_owner_id":7,"wallet_tenant_id":3}
!
ลายเซ็นของ callback ไม่ใช่ v2 engine เซ็น callback ด้วยสูตร hex(HMAC-SHA256(hmac_secret, X-Request-Id + "." + raw_body)) โดยใช้คู่คีย์เดียวกับที่เราออกให้คุณ (ไม่มี X-Timestamp) — ตรวจลายเซ็นด้วย constant-time compare ก่อนอ่าน JSON · test vector: secret test-secret-do-not-use, request id และ body ตามตัวอย่างข้างบน → 7a599b1dc57db4ffb17b0e25de6cd579de2409be73d6a4ee0f5c808f20558939

Body

ฟิลด์ชนิดคำอธิบาย
opstringbet · getbalance · settle · rollback — ต้องตรงกับ {op} ใน path
member_refstringmember_code ของผู้เล่น
currencystringTHB
referencestringกุญแจกันทำซ้ำของธุรกรรมนี้ (เท่ากับ Idempotency-Key)
round_idstringเลขงวด เป็นสตริง
ticket_refstringความหมายต่างกันตาม op — ดูตารางด้านล่าง อย่าใช้จับคู่ข้าม op
amount_satangintegerจำนวนเงิน (สตางค์)
wallet_owner_id · wallet_tenant_idintegerตัวตนกระเป๋าตามที่ผูกกับคีย์
settlement_generation · settlement_item_ref—มีเมื่อเป็นรายการจ่ายรางวัล ใช้ถาม /bet/settlement-proof
opทำอะไรreferenceticket_ref
betตัดเงิน (ก่อนรับตั๋ว)Idempotency-Key ของ /bet/placeว่าง
settleเครดิตรางวัล ต่อรายการที่ถูก 1 ครั้ง ไม่ใช่ต่อตั๋วsettle:{tenant}:{batch}:{item}ticket id
rollback — ยกเลิกบิล / void งวดคืนเงินเดิมพันrollback:void:{tenant}:{ticket}Idempotency-Key ของ /bet/place
rollback — วางบิลไม่สำเร็จหลังตัดเงินคืนเงินที่ตัดไปrollback:{tenant}:{Idempotency-Key}Idempotency-Key ของ /bet/place
rollback — กลับรายการรางวัลดึงรางวัลคืนrollback:{tenant}:{batch}:{item}settle:{tenant}:{batch}:{item}
getbalanceคืนยอดใช้ได้ ไม่ย้ายเงินว่างว่าง

engine ไม่ส่ง cancelbet หรือ void — การคืนเงินทุกแบบมาเป็น rollback

คำตอบที่ต้องส่งกลับ

{
  "data": {
    "ok": true,
    "code": "ok",
    "balance_satang": 123400,
    "provider_ref": "รหัสรายการของคุณ"
  }
}
{
  "data": {
    "ok": false,
    "code": "insufficient_funds"
  }
}
HTTPcode ที่ใช้ได้
422insufficient_funds · wallet_frozen · recovery_debt
400bad_request · amount_overflow
401unauthorized
403binding_mismatch · forbidden
409idempotency_conflict
503dependency_pending — ยังไม่พร้อม engine จะลองใหม่

balance_satang ต้อง ≥ 0 และบังคับสำหรับ getbalance · คำตอบอื่นทั้งหมด (ไม่มี data.ok, รหัสกับ HTTP ไม่ตรงคู่, body เกิน 1 MB, redirect, timeout) engine ถือว่าไม่รู้ผล

กติกาฝั่งคุณ

  • ตรวจลายเซ็นก่อนอ่าน JSON · จำกัดขนาด body · op ใน path ต้องตรงกับ body · รายการย้ายเงิน Idempotency-Key ต้องเท่ากับ reference
  • บันทึก receipt กับ ledger ในธุรกรรมเดียวกัน — reference ซ้ำให้ตอบผลเดิม (ตรวจก่อนอย่างอื่น)
  • ตอบ ok: true เฉพาะเมื่อตัด/จ่ายเงินสำเร็จจริงแล้ว — engine เชื่อค่านี้และรับตั๋วทันที
  • ตอบภายใน 5 วินาที · ยังไม่พร้อมหรือตรวจไม่ได้ให้ตอบ 503 ห้ามตอบ 2xx หรือ 4xx ที่เป็นผลสุดท้าย
  • settle / rollback ผ่าน outbox ลองรวมสูงสุด 10 ครั้ง (เว้น 5 วิ · 15 วิ · 1 นาที · 5 นาที แล้ว 15 นาทีซ้ำ ราว 80 นาที) หลังจากนั้นเงินค้างจนกว่าทีม HuayEngine จะตามให้
  • หมุน hmac_secret แล้วยังต้องรับ secret เก่าอีกอย่างน้อย 1–2 นาที (engine cache คีย์ราว 30 วินาที) แต่ขาที่คุณเรียก engine ต้องเปลี่ยนเป็น secret ใหม่ทันที
import express from 'express'
import { createHmac, timingSafeEqual } from 'node:crypto'

const app = express()
app.post('/seamless/lotto/HUAY/:op', express.raw({ type: 'application/json', limit: '1mb' }), async (req, res) => {
  const requestId = req.get('X-Request-Id') || ''
  const expected = createHmac('sha256', process.env.HUAY_HMAC_SECRET).update(requestId + '.').update(req.body).digest()
  const given = Buffer.from(req.get('X-Signature') || '', 'hex')
  if (req.get('X-Api-Key') !== process.env.HUAY_API_KEY || given.length !== expected.length || !timingSafeEqual(given, expected)) {
    return res.status(401).json({ data: { ok: false, code: 'unauthorized' } })
  }
  const body = JSON.parse(req.body)
  if (body.op !== req.params.op) return res.status(400).json({ data: { ok: false, code: 'bad_request' } })

  // บันทึก receipt + ledger ในธุรกรรมเดียว · reference ซ้ำ = คืนผลเดิม
  const result = await wallet.applyOnce(body) // ← ของคุณ
  res.status(result.httpStatus).json({ data: result.payload })
})

🔔Webhook

engine แจ้งเหตุการณ์ไปที่ URL ของคุณ — ใช้เป็นตัวกระตุ้น และมี worker ไล่เก็บสำรองเสมอ เพราะ webhook อาจมาช้า ซ้ำ สลับลำดับ หรือหาย

สร้าง endpoint เองได้ที่ Studio หน้า Webhooks เลือก event ได้ (ว่าง = ทุก event) แต่ละ endpoint มี secret ของตัวเอง แยกจาก hmac_secret และแสดงครั้งเดียวตอนสร้าง

Eventส่งเมื่อdataส่งไปที่
bet.placedรับตั๋วสำเร็จตั๋วเต็มใบ (รูปเดียวกับคำตอบ /bet/place)คีย์ที่วางบิล
bet.cancelledบิลถูกยกเลิก (/bet/cancel หรือ void ทั้งงวด — ส่งต่อบิล)ตั๋วหลังยกเลิก (status, cancellation_action, refund_status)คีย์ที่วางบิล
round.closedงวดปิดรับ (สั่ง /close หรือถึง close_at · ไม่รวมยี่กี){round_id, lottery_type_id, status: "closed", reason: "manual" | "close_at"}คีย์ที่ตลาดเปิดให้
result.publishedผลงวดถูกประกาศ{result_id, round_id} — ล้าง cache ผลคีย์ที่ตลาดเปิดให้
settlement.doneจ่ายเงินทั้งงวดเสร็จ{id, lottery_round_id, status, total_items, total_payout} หรือ {round_id, undecidable_items, reason: "incomplete_result"} เมื่อยังจ่ายไม่ครบคีย์ที่ตลาดเปิดให้
POST https://partner.example/webhooks/huayengine
Content-Type: application/json
X-HuayEngine-Event: settlement.done
X-HuayEngine-Delivery: 58213
X-HuayEngine-Signature: 3f9a…

{"event":"settlement.done","data":{"id":118,"lottery_round_id":4821,"status":"done","total_items":240,"total_payout":9000000},"ts":1797494400}
i
ลายเซ็น = hex(HMAC-SHA256(webhook_secret, raw_body)) — เซ็นเฉพาะ body ไม่มี request id นำหน้า (ต่างจาก callback)
app.post('/webhooks/huayengine', express.raw({ type: 'application/json' }), async (req, res) => {
  const expected = createHmac('sha256', process.env.HUAY_WEBHOOK_SECRET).update(req.body).digest()
  const given = Buffer.from(req.get('X-HuayEngine-Signature') || '', 'hex')
  if (given.length !== expected.length || !timingSafeEqual(given, expected)) return res.sendStatus(401)

  // กันซ้ำด้วย delivery id · เก็บ raw body ลงฐาน · ตอบ 2xx ทันที แล้วไปประมวลผลใน worker
  await inbox.saveOnce(req.get('X-HuayEngine-Delivery'), req.body) // ← ของคุณ
  res.sendStatus(200)
})
  • ตอบ 2xx ภายใน 8 วินาที แล้วค่อยประมวลผลแบบ async · ไม่ใช่ 2xx หรือ timeout = ล้มเหลว
  • ส่งรวมสูงสุด 6 ครั้ง (เว้น 15 วิ · 1 นาที · 2¼ นาที · 4 นาที · 6¼ นาที ⇒ จบในราว 14 นาที) แล้วเลิก — ดูประวัติการส่งได้ใน Studio · ตั้งเตือนถ้าไม่มี webhook เข้าเกินราว 2 ชั่วโมง
  • worker สำรองที่แนะนำ: ทุก 5 นาที GET /bets/detail?ids= (≤ 200 ใบ) · ทุก 15 นาที GET /bet/{ticket_id} ของบิลที่ยังเปิด

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

ตัดสินใจจาก error.code เท่านั้น · 5xx และ timeout ทุกแบบ = ไม่รู้ผล ให้ไล่ตามด้วย key เดิม

HTTPcodeความหมายลองใหม่?
400bad_requestbody/query ผิดรูปแบบหรือขาดฟิลด์ไม่ — แก้คำขอ
400idempotency_requiredขาด Idempotency-Keyไม่ — ใส่ header
400amount_overflow/bet/place (external): ยอดเงินผิด/ล้นไม่
401missing_api_key · invalid_api_keyไม่มีคีย์ คีย์ผิด หรือคีย์ถูกปิดไม่
401missing_signature · invalid_signatureลายเซ็นไม่ตรง (มักเพราะไม่ส่ง X-Request-Id หรือเซ็นคนละไบต์กับที่ส่ง)ไม่ — ตรวจกับ test vector
401signature_version_requiredendpoint นี้รับเฉพาะลายเซ็น v2ไม่
401session_invalidsession_token ไม่ถูกต้องหรือหมดอายุlaunch ใหม่
403ip_not_allowedIP ไม่อยู่ใน whitelist ของคีย์ไม่
403lottery_not_allowedตลาดนี้ไม่ได้เปิดให้คีย์ใบนี้ไม่ — ติดต่อผู้ดูแล
403member_inactive · tenant_suspendedสมาชิก / ผู้เช่าถูกระงับไม่
403wallet_mode_not_allowedคีย์ seamless (ที่ไม่ใช่ external) เรียก /membersไม่
403backend_onlyคีย์ external_member เรียก /session/launchไม่ — ใช้ /play/launch
403binding_mismatchwallet_owner_id / wallet_tenant_id หรือสมาชิกไม่ตรงกับที่ผูกกับคีย์ไม่ — ตรวจค่าที่ส่ง
403forbiddenendpoint นี้ไม่เปิดให้ชนิดคีย์ของคุณไม่
403member_play_denied · launch_target_unavailable · member_not_allowedช่องทาง/งวด/ตัวตนที่ขอไม่อนุญาตไม่
404not_foundไม่พบตั๋ว/งวดในผู้เช่านี้ หรือตั๋วนั้นวางด้วยคีย์ใบอื่นไม่
404round_not_found/close, /void: ไม่พบงวดในผู้เช่าของคีย์ไม่
404attempt_not_found · proof_not_found(external) engine ไม่มีบันทึกการวางบิล / หลักฐานattempt: ส่ง /bet/place ซ้ำด้วย key เดิม
409idempotency_in_progressคำขอที่ใช้ key เดียวกันยังทำงานอยู่ได้ — รอ 1–2 วิ ใช้ key เดิม
409replay_detectedX-Request-Id เคยใช้กับ key อื่น หรือส่งลายเซ็นเดิมซ้ำได้ — request id และลายเซ็นใหม่ คง key เดิม
409idempotency_conflictkey เดิมกับ body/ผู้เล่นคนละชุดไม่ — รายการใหม่ใช้ key ใหม่
422round_closedงวดไม่รับแทงแล้ว (ทั้งตอนแทงและยกเลิก)ไม่
422number_heldเลขถูกสั่งหยุดรับ (เลขอั้น)ไม่
422stake_out_of_rangeเงินแทงนอกช่วง min_stake–max_stakeไม่
422unknown_bet_typeประเภทเลขไม่เปิดในงวดนี้ไม่
422no_itemsโพยไม่มีรายการไม่
422rate_exceeds_ceilingอัตราที่แนบมาสูงกว่า snapshotไม่
422duplicate_betkey นี้เคยรับตั๋วไปแล้วไม่ — ค้นตั๋วจาก /bet/history
422place_bet_failedอื่น ๆ เช่น ยอดไม่พอ เกินเพดานต่อเลข เลขผิดหลักไม่
422wallet_rejectedseamless: ปลายทาง callback ปฏิเสธการตัดเงิน หรือไม่ตอบ/ตอบผิดรูปไม่ — ถ้าไม่แน่ใจว่าตัดเงินไปแล้ว retry ด้วย key เดิม
422placement_rejected · placement_compensated(external) key นี้เคยถูกปฏิเสธ / ถูกคืนเงินแล้ว — ผลสุดท้าย ไม่มีตั๋วไม่ — รายการใหม่ใช้ key ใหม่
422unknown_membermember_code ไม่มีในระบบไม่
422seamless_identity_missing · seamless_member_mismatchseamless: ตัวตนผู้เล่นขาดหรือขัดกันไม่
422seamless_not_wiredคีย์ seamless แต่ engine ยังไม่เปิดท่อ seamlessไม่ — ติดต่อทีม HuayEngine
422cancel_failedยกเลิกไม่ได้ (เช่น ตั๋ว settle/ยกเลิกแล้ว)ไม่
422payment_failedฝาก/ถอนไม่ได้ — ไม่รับประกันว่าเงินไม่ขยับไม่ — เทียบยอดก่อนสรุป
422not_closable · not_voidableสถานะงวดไม่อนุญาต — หลัง timeout อาจแปลว่าสำเร็จแล้วไม่ — อ่านสถานะงวดก่อน
422refund_failed/void: มีบิล seamless ที่คืนเงินไม่ได้ ไม่มีอะไรถูกยกเลิกไม่ — ติดต่อทีม
422shooting_disabled · not_yeekee · round_not_open · shot_limit_reached · commitment_unavailableยิงเลขยี่กีไม่ได้ในตอนนี้ไม่
429rate_limited · shot_rate_limitedเกินโควตาได้ — รอตาม Retry-After
503placement_pending(external) ผลการวางบิลยังสรุปไม่ได้ได้ — key เดิม หรือถาม /bet/attempt
503refund_status_unavailable/bet/cancel: ยกเลิกสำเร็จแล้ว แต่อ่านสถานะคืนเงินไม่ได้ไม่ต้องยิงซ้ำ — อ่าน GET /bet/{id}
503replay_unavailable · wallet_error · proof_unavailable · member_play_unavailableระบบที่เกี่ยวข้องยังไม่พร้อมได้ — backoff
503void_unavailableท่อคืนเงิน seamless ของ engine ยังไม่พร้อมติดต่อทีม แล้วค่อยลองด้วย key เดิม
5xxinternal_error · session_failed · launch_failed · member_lookup_failed · member_provision_failed · batch_failed · lookup_failed · scope_failed · status_failed · read_failed · close_failed · void_failed · shooting_failedเซิร์ฟเวอร์ผิดพลาด — ไม่รู้ผลได้ — backoff ใช้ key เดิม

🔢ประเภทเลข

รหัสที่ระบบรู้จัก แต่ละงวดเปิดขายเฉพาะรหัสที่อยู่ใน bet_types ของ betconfig งวดนั้น

bet_type_codeชื่อหลักถูกรางวัลเมื่อ
3_top3 ตัวบน3ตรงกับ 3 ตัวบนทุกตำแหน่ง
3_toad3 ตัวโต๊ด3สลับตำแหน่งแล้วตรงกับ 3 ตัวบน
2_top2 ตัวบน2ตรงกับ 2 หลักท้ายของเลขบน
2_bottom2 ตัวล่าง2ตรงกับ 2 ตัวล่าง
run_topวิ่งบน1เลขนั้นปรากฏใน 3 ตัวบน
run_bottomวิ่งล่าง1เลขนั้นปรากฏใน 2 ตัวล่าง
3_front3 ตัวหน้า3ตรงเลขหน้า 3 ตัวรางวัลใดรางวัลหนึ่ง (หวยรัฐบาลและสลากที่ประกาศชุดเต็ม)
3_bottom3 ตัวหลัง3ตรงเลขท้าย 3 ตัวรางวัลใดรางวัลหนึ่ง (หวยรัฐบาลและสลากที่ประกาศชุดเต็ม)

✅Checklist ก่อนขึ้น production

ติ๊กเก็บไว้ได้ — สถานะจำไว้ในเบราว์เซอร์นี้เท่านั้น

⬇️ดาวน์โหลด

ไฟล์สเปกและ Postman ชุดเดียวกับที่ใช้ทดสอบภายใน — environment ไม่มีคีย์หรือ secret ติดมา ใส่ของคุณเองในเครื่อง

✓
ต้องการความช่วยเหลือ ส่ง request_id ของคำขอที่มีปัญหา เวลาโดยประมาณ และ error.code ที่ได้ มาให้ทีม HuayEngine — ห้ามส่ง hmac_secret มาทุกกรณี