● 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 |
ไม่มีสภาพแวดล้อม sandbox แยกต่างหาก ให้ทดสอบบน staging ปุ่ม Staging / Production มุมขวาบนจะเปลี่ยน URL ในตัวอย่างโค้ดทั้งหน้า
!
เรียกจาก backend เท่านั้น
hmac_secret ห้ามอยู่ในเว็บเบราว์เซอร์ แอปมือถือ หรือ repository สาธารณะ แนะนำให้รวมโค้ดที่เรียก HuayEngine ไว้ใน package เดียวของ backend จะได้ตรวจได้ง่ายว่าไม่มีที่อื่นเรียกตรง
⚡เริ่มใน 5 นาที
ขอคีย์ ยิง endpoint อ่านอย่างเดียวหนึ่งครั้ง ถ้าได้ 200 แปลว่าคีย์ ลายเซ็น และ IP ถูกต้องแล้ว
- ขอสิ่งเหล่านี้จากทีม 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 เอง
- ยิง
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"
- ได้รายการตลาดกลับมา
{
"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 ก่อน
ลำดับงานที่แนะนำ
🔒การยืนยันตัวตน
ทุกคำขอที่ไป /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-Type | application/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 บ่อยที่สุด
- เซ็นคนละไบต์กับที่ส่ง — แปลง body เป็น JSON ครั้งเดียว แล้วใช้สตริงนั้นทั้งตอนเซ็นและตอนส่ง อย่าให้ HTTP client แปลงซ้ำ
- 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')
import hashlib, hmac, json, os, uuid
from datetime import datetime, timezone
import requests
BASE = "https://huayapi-staging.huaysanook.online"
API_KEY = os.environ["HUAY_API_KEY"]
SECRET = os.environ["HUAY_HMAC_SECRET"].encode()
def sign(method, target, timestamp, request_id, idem_key, raw_body: bytes) -> str:
quoted = [json.dumps(v) for v in (method, target, timestamp, request_id, idem_key)]
digest = hashlib.sha256(raw_body).hexdigest()
canonical = "\n".join(["huayengine-provider-v2", *quoted, digest])
return hmac.new(SECRET, canonical.encode(), hashlib.sha256).hexdigest()
def call(method, target, body=None, idem_key=""):
# แปลงครั้งเดียว ใช้ทั้งเซ็นและส่ง
raw = b"" if body is None else json.dumps(body, ensure_ascii=False, separators=(",", ":")).encode()
request_id = str(uuid.uuid4())
timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
headers = {
"X-Api-Key": API_KEY,
"X-Request-Id": request_id,
"X-Timestamp": timestamp,
"X-Signature": sign(method, target, timestamp, request_id, idem_key, raw),
}
if raw:
headers["Content-Type"] = "application/json"
if idem_key:
headers["Idempotency-Key"] = idem_key
res = requests.request(method, BASE + target, data=raw or None, headers=headers,
timeout=8, allow_redirects=False)
env = res.json()
if res.status_code >= 400 or env.get("error"):
code = (env.get("error") or {}).get("code")
raise RuntimeError(f"HTTP {res.status_code} {code} [req {env.get('request_id')}]")
return env["data"]
games = call("GET", "/api/v1/provider/games")
<?php
const HUAY_BASE = 'https://huayapi-staging.huaysanook.online';
function huay_sign(string $secret, string $method, string $target, string $ts,
string $requestId, string $idemKey, string $rawBody): string
{
// ★ ต้องมี JSON_UNESCAPED_SLASHES ไม่งั้น "/" กลายเป็น "\/" แล้วลายเซ็นไม่ตรง
$q = fn(string $v): string => json_encode($v, JSON_UNESCAPED_SLASHES);
$canonical = implode("\n", [
'huayengine-provider-v2',
$q($method), $q($target), $q($ts), $q($requestId), $q($idemKey),
hash('sha256', $rawBody),
]);
return hash_hmac('sha256', $canonical, $secret);
}
function huay_call(string $method, string $target, ?array $body = null, string $idemKey = ''): array
{
$secret = getenv('HUAY_HMAC_SECRET');
$raw = $body === null ? '' : json_encode($body, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
$requestId = bin2hex(random_bytes(16));
$ts = gmdate('Y-m-d\TH:i:s\Z');
$headers = [
'X-Api-Key: ' . getenv('HUAY_API_KEY'),
'X-Request-Id: ' . $requestId,
'X-Timestamp: ' . $ts,
'X-Signature: ' . huay_sign($secret, $method, $target, $ts, $requestId, $idemKey, $raw),
];
if ($raw !== '') $headers[] = 'Content-Type: application/json';
if ($idemKey !== '') $headers[] = 'Idempotency-Key: ' . $idemKey;
$ch = curl_init(HUAY_BASE . $target);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 8,
CURLOPT_FOLLOWLOCATION => false,
]);
if ($raw !== '') curl_setopt($ch, CURLOPT_POSTFIELDS, $raw);
$res = curl_exec($ch);
if ($res === false) {
throw new RuntimeException('network: ' . curl_error($ch)); // ไม่รู้ผล ห้ามถือว่าล้มเหลว
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$env = json_decode($res, true) ?? [];
if ($status >= 400 || !empty($env['error'])) {
throw new RuntimeException(sprintf('HTTP %d %s [req %s]',
$status, $env['error']['code'] ?? 'unknown', $env['request_id'] ?? $requestId));
}
return $env['data'];
}
$games = huay_call('GET', '/api/v1/provider/games');
package huay
import (
"bytes"
"crypto/hmac"
"crypto/rand"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"fmt"
"net/http"
"time"
)
const Base = "https://huayapi-staging.huaysanook.online"
// Sign: %q ของ Go ให้ผลเดียวกับ JSON.stringify สำหรับค่า ASCII
func Sign(secret, method, target, ts, requestID, idemKey string, body []byte) string {
mac := hmac.New(sha256.New, []byte(secret))
fmt.Fprintf(mac, "huayengine-provider-v2\n%q\n%q\n%q\n%q\n%q\n%x",
method, target, ts, requestID, idemKey, sha256.Sum256(body))
return hex.EncodeToString(mac.Sum(nil))
}
var client = &http.Client{
Timeout: 8 * time.Second,
CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse },
}
func Call(apiKey, secret, method, target string, body []byte, idemKey string) (json.RawMessage, error) {
req, err := http.NewRequest(method, Base+target, bytes.NewReader(body))
if err != nil {
return nil, err
}
rid := make([]byte, 16)
if _, err := rand.Read(rid); err != nil {
return nil, err
}
requestID := hex.EncodeToString(rid) // ใหม่ทุกครั้ง แม้เป็นการ retry
ts := time.Now().UTC().Format(time.RFC3339)
req.Header.Set("X-Api-Key", apiKey)
req.Header.Set("X-Request-Id", requestID)
req.Header.Set("X-Timestamp", ts)
req.Header.Set("X-Signature", Sign(secret, method, req.URL.RequestURI(), ts, requestID, idemKey, body))
if len(body) > 0 {
req.Header.Set("Content-Type", "application/json")
}
if idemKey != "" {
req.Header.Set("Idempotency-Key", idemKey)
}
res, err := client.Do(req)
if err != nil {
return nil, err // ไม่รู้ผล ห้ามถือว่าล้มเหลว
}
defer res.Body.Close()
var env struct {
Data json.RawMessage `json:"data"`
Error *struct{ Code, Message string } `json:"error"`
RequestID string `json:"request_id"`
}
if err := json.NewDecoder(res.Body).Decode(&env); err != nil {
return nil, err
}
if res.StatusCode >= 400 || env.Error != nil {
code := ""
if env.Error != nil {
code = env.Error.Code
}
return nil, fmt.Errorf("HTTP %d %s [req %s]", res.StatusCode, code, env.RequestID)
}
return env.Data, nil
}
METHOD=POST
TARGET=/api/v1/provider/wallet/balance
BODY='{"member_id":501}'
IDEM='' # route ที่ย้ายเงินต้องใส่ เช่น IDEM=$(uuidgen)
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 -X "$METHOD" "https://huayapi-staging.huaysanook.online$TARGET" \
-H "X-Api-Key: $HUAY_API_KEY" -H "X-Request-Id: $RID" \
-H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
-H 'Content-Type: application/json' \
${IDEM:+-H "Idempotency-Key: $IDEM"} \
--data-raw "$BODY"
Test vector — ใช้ตรวจโค้ดของคุณ
ป้อนค่าด้านล่างเข้าฟังก์ชันเซ็นของคุณ ต้องได้ลายเซ็นตรงทุกตัวอักษร (ตรวจแล้วด้วย Node, Python, PHP และ Go) secret นี้ใช้ทดสอบเท่านั้น ใช้เรียก API จริงไม่ได้
| secret | test-secret-do-not-use |
| method / target | POST · /api/v1/provider/bet/place |
| X-Timestamp | 2026-11-17T08:00:00Z |
| X-Request-Id | 3f6c1d2e-8b7a-4c51-9e0d-2a1b3c4d5e6f |
| Idempotency-Key | ORDER-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-Signature | 20b2bf0c38d4331c91963e4fba6cb67c2325eca307f209f1d4d98f67534e9760 |
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 เดิมคือรายการใหม่
| HTTP | code | เกิดเมื่อ | ทำอย่างไร |
| 400 | idempotency_required | ไม่ได้ส่ง Idempotency-Key | ใส่ header |
| 409 | idempotency_in_progress | คำขอแรกด้วย key นี้ยังทำงานอยู่ | รอ 1–2 วินาที แล้วส่งซ้ำด้วย key เดิม |
| 409 | replay_detected | X-Request-Id เคยใช้กับ key อื่น หรือส่งลายเซ็นเดิมซ้ำ | สร้าง request id และลายเซ็นใหม่ คง key เดิม |
| 409 | idempotency_conflict | key เดิมแต่ body/ผู้เล่นต่างจากครั้งแรก (/bet/cancel, /bet/place แบบ external) | บั๊กฝั่งคุณ — รายการใหม่ต้องใช้ key ใหม่ |
| 422 | duplicate_bet | key นี้เคยรับบิลแล้ว (cache หมดอายุ) | ถือว่าอาจสำเร็จแล้ว ค้นตั๋วจาก /bet/history ด้วย reference |
ส่งคำขอซ้ำอย่างปลอดภัย
การแทงและการฝากถอนคือเงินที่ขยับ Idempotency-Key คือสิ่งเดียวที่บอก engine ว่าคำขอสองครั้งเป็นรายการเดียวกัน — key ใหม่คือรายการใหม่
- บันทึกก่อนยิง (commit-before-send)
สร้างแถวคำสั่งในฐานข้อมูลของคุณพร้อม idem_key (UUID) และไบต์ body ที่แปลงแล้ว → commit → จึงเรียก engine · ผูก key กับรายการ ไม่ใช่กับการเรียก HTTP แต่ละครั้ง
- ลองใหม่ด้วย key เดิม + ไบต์เดิม
แต่สร้าง X-Request-Id, X-Timestamp และลายเซ็นใหม่ทุกครั้ง
- หยุดลองใหม่เมื่อคำสั่งอายุเกินราว 20 ชั่วโมง
engine จำผลแค่ 24 ชม. เลยกว่านั้นจะกลายเป็นรายการใหม่ (= ตัดเงินซ้ำ) ให้เปลี่ยนเป็น needs_review ให้คนตรวจ
- แยกผลเป็น 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) |
| ยอดเงินผู้เล่นอยู่ที่ | กระเป๋าใน engine | ledger ของคุณ |
| ฝาก / ถอน | เรียก /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_idexternal | integer | เฉพาะคีย์ external_member · ต้องตรงกับค่าบนคีย์ |
| wallet_tenant_idexternal | integer | เฉพาะคีย์ external_member · ต้องตรงกับค่าบนคีย์ |
| member_idexternal | integer | เฉพาะคีย์ 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
| 400 | bad_request | member_code ผิดรูปแบบ |
| 403 | wallet_mode_not_allowed | คีย์ seamless ที่ไม่ใช่ external_member |
| 403 | binding_mismatch | wallet_* ไม่ตรงกับคีย์ หรือคีย์ไม่ใช่ external ส่งมา |
| 500 | member_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
| 400 | bad_request · idempotency_required |
| 409 | idempotency_in_progress · replay_detected |
| 422 | payment_failed |
POST
/api/v1/provider/wallet/withdraw
ถอนเงินออกจากกระเป๋าสมาชิก Idempotency-Key
Request และ response รูปเดียวกับ /wallet/deposit (direction: "withdrawal") · ยอดไม่พอได้ 422 payment_failed
- ตัดยอดที่ engine ก่อน ด้วย
/wallet/withdraw
- จึงโอนเงินจริงให้ผู้เล่น
- โอนไม่สำเร็จ ให้
/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 /games | 5 นาที |
GET /rounds | 15 วินาที |
GET /rounds/{id}/betconfig | 10 วินาที |
GET /results | 60 วินาที |
อย่าให้หน้าเว็บสาธารณะยิงตรงถึง 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บังคับ | integer | id ของงวดจาก /rounds |
| referenceแนะนำ | string ≤ 64 | รหัสบิลของคุณ ใช้ค้นตั๋วคืนจาก /bet/history และกระทบยอด |
| items[]บังคับ | array | รายการแทง อย่างน้อย 1 รายการ |
| items[].bet_type_code | string | ต้องมีอยู่ใน bet_types ของ betconfig งวดนั้น (ดูประเภทเลข) |
| items[].number | string | ตัวเลขล้วน จำนวนหลักตรงกับประเภทเลข · เป็นสตริงเสมอ |
| items[].stake_satang | integer | เงินแทง (สตางค์) อยู่ระหว่าง min_stake–max_stake |
| session_tokenไม่บังคับ | string | จาก /session/launch · ส่งแล้ว token ไม่ถูกต้องได้ 401 session_invalid |
| wallet_owner_id · wallet_tenant_idexternal | integer | เฉพาะคีย์ 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 — แสดงเงินรางวัลจากค่าในตั๋วเสมอ
สถานะ
ตั๋ว status | accepted → settled หรือ cancelled |
รายการ settlement_status | pending → won lost void |
Errors ที่พบบ่อย
| HTTP | code | ความหมาย |
| 422 | round_closed | งวดไม่รับแทงแล้ว แสดงผู้เล่น |
| 422 | number_held | เลขอั้น / เต็ม แสดงผู้เล่น |
| 422 | stake_out_of_range | เงินแทงนอกช่วง min–max แสดงผู้เล่น |
| 422 | unknown_bet_type · no_items | ประเภทเลขไม่เปิดในงวดนี้ / โพยว่าง แสดงผู้เล่น |
| 422 | place_bet_failed · wallet_rejected | อื่น ๆ เช่น เงินไม่พอ เกินเพดานต่อเลข / ปลายทาง seamless ปฏิเสธการตัดเงิน แสดงผู้เล่น |
| 422 | duplicate_bet | key นี้เคยรับตั๋วแล้ว — ถือว่าอาจสำเร็จ ค้นจาก /bet/history |
| 422 | unknown_member · rate_exceeds_ceiling | ไม่มีสมาชิกนี้ / อัตราที่แนบมาสูงกว่า snapshot |
| 403 | lottery_not_allowed · tenant_suspended · binding_mismatch | ไม่มีสิทธิ์ |
| 409 | idempotency_in_progress · replay_detected · idempotency_conflict | ดูIdempotency |
| 500 | member_lookup_failed | ลองใหม่ด้วย key เดิม |
| 503 | placement_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 |
| transfer | engine คืนเข้ากระเป๋าใน engine ทันที | confirmed |
| seamless | engine ยิง 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)
⛔ปิดรับ / ยกเลิกงวด
ปิดรับแทง หรือยกเลิกทั้งงวดพร้อมคืนเงินทุกบิล ของงวดในผู้เช่าของคุณเอง ด้วยคีย์ที่ใช้แทงอยู่ (จำกัดตามขอบเขตตลาดของคีย์)
!
สี่เรื่องที่พลาดแล้วเสียเงินจริง
void ต้องใช้ key เดิมทุกครั้งที่ retry — key ใหม่บนงวดที่ยกเลิกไปแล้วได้ 422 not_voidable ซึ่งบอกไม่ได้ว่าครั้งแรกสำเร็จหรือไม่
422 not_voidable หลัง timeout ไม่ได้แปลว่าล้มเหลว — อ่านสถานะงวดก่อน ห้ามคืนเงินผู้เล่นเองจนกว่าจะรู้ว่า engine ยังไม่ได้คืน
404 ไม่ได้แปลว่างวดไม่มีอยู่จริง — อาจเป็นงวดของผู้เช่าอื่น engine ตอบเหมือนกันโดยตั้งใจ
- คีย์ 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บังคับ | string | 1–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 | ความหมาย | ทำอะไรต่อ |
| cancelled | void สำเร็จแล้ว | อย่ายิงซ้ำ และอย่าคืนเงินเอง |
| closed | ปิดแล้ว · void ยังไม่เกิด | ถ้าจะ void ให้ยิงด้วย key เดิม |
| open | คำขอยังไม่สำเร็จ | ยิงซ้ำด้วย key เดิม |
| scheduled | งวดยังไม่เปิด | close ไม่ได้ · void ได้ ด้วย key เดิม |
| drawn ขึ้นไป | ออกผลหรือจ่ายเงินแล้ว | ติดต่อทีม HuayEngine |
Errors
| 400 | bad_request · idempotency_required | reason ผิดกติกา / ขาด key |
| 403 | lottery_not_allowed | ตลาดนี้ไม่ได้เปิดให้คีย์ |
| 404 | round_not_found | ไม่พบงวดในผู้เช่าของคีย์ (รวมงวดของผู้เช่าอื่น) |
| 422 | not_closable · not_voidable | สถานะงวดไม่อนุญาต — หลัง timeout อาจแปลว่าสำเร็จแล้ว |
| 422 | refund_failed | มีบิล seamless ที่คืนเงินไม่ได้ จึงไม่ยกเลิกอะไรเลย ติดต่อทีมพร้อม request_id |
| 500 | lookup_failed · scope_failed · close_failed · void_failed | ไม่มีอะไรเปลี่ยน — backoff แล้วใช้ key เดิม |
| 503 | void_unavailable | ท่อคืนเงิน seamless ยังไม่พร้อม (ฝั่ง engine) |
🏆ผลรางวัล
ผลมีผลกับตั๋วหลัง publish เท่านั้น จากนั้น worker จะ settle แบบ idempotent แล้วเปลี่ยนตั๋วเป็น settled — รู้ผลได้จาก webhook หรือดึงเอง
GET
/api/v1/provider/results
ผลรางวัลที่ประกาศแล้ว
| พารามิเตอร์ | ชนิด | คำอธิบาย |
| lottery_idไม่บังคับ | string | code ของตลาด เช่น 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ไม่บังคับ | string | https · ยาวไม่เกิน 512 · ปุ่ม "กลับเว็บผู้ให้บริการ" ในหน้า play |
| langไม่บังคับ | string | th · 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บังคับ | string | member_code ของผู้เล่นที่ล็อกอินอยู่ — อ่านจาก binding ในฐานของคุณ ห้ามรับจากเบราว์เซอร์ |
| wallet_tenant_id · wallet_owner_idบังคับ | integer ≥ 1 | ตรงกับค่าบนคีย์ |
| currencyบังคับ | string | "THB" |
| launch_grant_idบังคับ | uuid | สิทธิ์เล่นที่คุณสร้างและบันทึกไว้ก่อนขอลิงก์ (UUID สุ่มที่ไม่มี grant ฝั่งกระเป๋ารองรับใช้รับบิลไม่ได้) |
| return_urlบังคับ | uri | origin ต้องลงทะเบียนไว้ |
| lottery_round_id หรือ lottery_type_idไม่บังคับ | integer | ใส่ได้อย่างเดียว · ไม่ใส่ = lobby |
| langไม่บังคับ | string | th · 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_found | engine ไม่เคยได้รับ — ส่ง /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
| ฟิลด์ | ชนิด | คำอธิบาย |
| op | string | bet · getbalance · settle · rollback — ต้องตรงกับ {op} ใน path |
| member_ref | string | member_code ของผู้เล่น |
| currency | string | THB |
| reference | string | กุญแจกันทำซ้ำของธุรกรรมนี้ (เท่ากับ Idempotency-Key) |
| round_id | string | เลขงวด เป็นสตริง |
| ticket_ref | string | ความหมายต่างกันตาม op — ดูตารางด้านล่าง อย่าใช้จับคู่ข้าม op |
| amount_satang | integer | จำนวนเงิน (สตางค์) |
| wallet_owner_id · wallet_tenant_id | integer | ตัวตนกระเป๋าตามที่ผูกกับคีย์ |
| settlement_generation · settlement_item_ref | — | มีเมื่อเป็นรายการจ่ายรางวัล ใช้ถาม /bet/settlement-proof |
| op | ทำอะไร | reference | ticket_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"
}
}
| HTTP | code ที่ใช้ได้ |
| 422 | insufficient_funds · wallet_frozen · recovery_debt |
| 400 | bad_request · amount_overflow |
| 401 | unauthorized |
| 403 | binding_mismatch · forbidden |
| 409 | idempotency_conflict |
| 503 | dependency_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)
})
@app.post("/webhooks/huayengine")
def huayengine_webhook():
raw = request.get_data()
expected = hmac.new(WEBHOOK_SECRET, raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("X-HuayEngine-Signature", "")):
abort(401)
# กันซ้ำด้วย delivery id · เก็บ raw body · ตอบ 2xx ทันที
inbox.save_once(request.headers["X-HuayEngine-Delivery"], raw)
return "", 200
$raw = file_get_contents('php://input');
$expected = hash_hmac('sha256', $raw, getenv('HUAY_WEBHOOK_SECRET'));
if (!hash_equals($expected, $_SERVER['HTTP_X_HUAYENGINE_SIGNATURE'] ?? '')) {
http_response_code(401);
exit;
}
// กันซ้ำด้วย delivery id · เก็บ raw body · ตอบ 2xx ทันที
inbox_save_once($_SERVER['HTTP_X_HUAYENGINE_DELIVERY'] ?? '', $raw);
http_response_code(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 เดิม
| HTTP | code | ความหมาย | ลองใหม่? |
| 400 | bad_request | body/query ผิดรูปแบบหรือขาดฟิลด์ | ไม่ — แก้คำขอ |
| 400 | idempotency_required | ขาด Idempotency-Key | ไม่ — ใส่ header |
| 400 | amount_overflow | /bet/place (external): ยอดเงินผิด/ล้น | ไม่ |
| 401 | missing_api_key · invalid_api_key | ไม่มีคีย์ คีย์ผิด หรือคีย์ถูกปิด | ไม่ |
| 401 | missing_signature · invalid_signature | ลายเซ็นไม่ตรง (มักเพราะไม่ส่ง X-Request-Id หรือเซ็นคนละไบต์กับที่ส่ง) | ไม่ — ตรวจกับ test vector |
| 401 | signature_version_required | endpoint นี้รับเฉพาะลายเซ็น v2 | ไม่ |
| 401 | session_invalid | session_token ไม่ถูกต้องหรือหมดอายุ | launch ใหม่ |
| 403 | ip_not_allowed | IP ไม่อยู่ใน whitelist ของคีย์ | ไม่ |
| 403 | lottery_not_allowed | ตลาดนี้ไม่ได้เปิดให้คีย์ใบนี้ | ไม่ — ติดต่อผู้ดูแล |
| 403 | member_inactive · tenant_suspended | สมาชิก / ผู้เช่าถูกระงับ | ไม่ |
| 403 | wallet_mode_not_allowed | คีย์ seamless (ที่ไม่ใช่ external) เรียก /members | ไม่ |
| 403 | backend_only | คีย์ external_member เรียก /session/launch | ไม่ — ใช้ /play/launch |
| 403 | binding_mismatch | wallet_owner_id / wallet_tenant_id หรือสมาชิกไม่ตรงกับที่ผูกกับคีย์ | ไม่ — ตรวจค่าที่ส่ง |
| 403 | forbidden | endpoint นี้ไม่เปิดให้ชนิดคีย์ของคุณ | ไม่ |
| 403 | member_play_denied · launch_target_unavailable · member_not_allowed | ช่องทาง/งวด/ตัวตนที่ขอไม่อนุญาต | ไม่ |
| 404 | not_found | ไม่พบตั๋ว/งวดในผู้เช่านี้ หรือตั๋วนั้นวางด้วยคีย์ใบอื่น | ไม่ |
| 404 | round_not_found | /close, /void: ไม่พบงวดในผู้เช่าของคีย์ | ไม่ |
| 404 | attempt_not_found · proof_not_found | (external) engine ไม่มีบันทึกการวางบิล / หลักฐาน | attempt: ส่ง /bet/place ซ้ำด้วย key เดิม |
| 409 | idempotency_in_progress | คำขอที่ใช้ key เดียวกันยังทำงานอยู่ | ได้ — รอ 1–2 วิ ใช้ key เดิม |
| 409 | replay_detected | X-Request-Id เคยใช้กับ key อื่น หรือส่งลายเซ็นเดิมซ้ำ | ได้ — request id และลายเซ็นใหม่ คง key เดิม |
| 409 | idempotency_conflict | key เดิมกับ body/ผู้เล่นคนละชุด | ไม่ — รายการใหม่ใช้ key ใหม่ |
| 422 | round_closed | งวดไม่รับแทงแล้ว (ทั้งตอนแทงและยกเลิก) | ไม่ |
| 422 | number_held | เลขถูกสั่งหยุดรับ (เลขอั้น) | ไม่ |
| 422 | stake_out_of_range | เงินแทงนอกช่วง min_stake–max_stake | ไม่ |
| 422 | unknown_bet_type | ประเภทเลขไม่เปิดในงวดนี้ | ไม่ |
| 422 | no_items | โพยไม่มีรายการ | ไม่ |
| 422 | rate_exceeds_ceiling | อัตราที่แนบมาสูงกว่า snapshot | ไม่ |
| 422 | duplicate_bet | key นี้เคยรับตั๋วไปแล้ว | ไม่ — ค้นตั๋วจาก /bet/history |
| 422 | place_bet_failed | อื่น ๆ เช่น ยอดไม่พอ เกินเพดานต่อเลข เลขผิดหลัก | ไม่ |
| 422 | wallet_rejected | seamless: ปลายทาง callback ปฏิเสธการตัดเงิน หรือไม่ตอบ/ตอบผิดรูป | ไม่ — ถ้าไม่แน่ใจว่าตัดเงินไปแล้ว retry ด้วย key เดิม |
| 422 | placement_rejected · placement_compensated | (external) key นี้เคยถูกปฏิเสธ / ถูกคืนเงินแล้ว — ผลสุดท้าย ไม่มีตั๋ว | ไม่ — รายการใหม่ใช้ key ใหม่ |
| 422 | unknown_member | member_code ไม่มีในระบบ | ไม่ |
| 422 | seamless_identity_missing · seamless_member_mismatch | seamless: ตัวตนผู้เล่นขาดหรือขัดกัน | ไม่ |
| 422 | seamless_not_wired | คีย์ seamless แต่ engine ยังไม่เปิดท่อ seamless | ไม่ — ติดต่อทีม HuayEngine |
| 422 | cancel_failed | ยกเลิกไม่ได้ (เช่น ตั๋ว settle/ยกเลิกแล้ว) | ไม่ |
| 422 | payment_failed | ฝาก/ถอนไม่ได้ — ไม่รับประกันว่าเงินไม่ขยับ | ไม่ — เทียบยอดก่อนสรุป |
| 422 | not_closable · not_voidable | สถานะงวดไม่อนุญาต — หลัง timeout อาจแปลว่าสำเร็จแล้ว | ไม่ — อ่านสถานะงวดก่อน |
| 422 | refund_failed | /void: มีบิล seamless ที่คืนเงินไม่ได้ ไม่มีอะไรถูกยกเลิก | ไม่ — ติดต่อทีม |
| 422 | shooting_disabled · not_yeekee · round_not_open · shot_limit_reached · commitment_unavailable | ยิงเลขยี่กีไม่ได้ในตอนนี้ | ไม่ |
| 429 | rate_limited · shot_rate_limited | เกินโควตา | ได้ — รอตาม Retry-After |
| 503 | placement_pending | (external) ผลการวางบิลยังสรุปไม่ได้ | ได้ — key เดิม หรือถาม /bet/attempt |
| 503 | refund_status_unavailable | /bet/cancel: ยกเลิกสำเร็จแล้ว แต่อ่านสถานะคืนเงินไม่ได้ | ไม่ต้องยิงซ้ำ — อ่าน GET /bet/{id} |
| 503 | replay_unavailable · wallet_error · proof_unavailable · member_play_unavailable | ระบบที่เกี่ยวข้องยังไม่พร้อม | ได้ — backoff |
| 503 | void_unavailable | ท่อคืนเงิน seamless ของ engine ยังไม่พร้อม | ติดต่อทีม แล้วค่อยลองด้วย key เดิม |
| 5xx | internal_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_top | 3 ตัวบน | 3 | ตรงกับ 3 ตัวบนทุกตำแหน่ง |
| 3_toad | 3 ตัวโต๊ด | 3 | สลับตำแหน่งแล้วตรงกับ 3 ตัวบน |
| 2_top | 2 ตัวบน | 2 | ตรงกับ 2 หลักท้ายของเลขบน |
| 2_bottom | 2 ตัวล่าง | 2 | ตรงกับ 2 ตัวล่าง |
| run_top | วิ่งบน | 1 | เลขนั้นปรากฏใน 3 ตัวบน |
| run_bottom | วิ่งล่าง | 1 | เลขนั้นปรากฏใน 2 ตัวล่าง |
| 3_front | 3 ตัวหน้า | 3 | ตรงเลขหน้า 3 ตัวรางวัลใดรางวัลหนึ่ง (หวยรัฐบาลและสลากที่ประกาศชุดเต็ม) |
| 3_bottom | 3 ตัวหลัง | 3 | ตรงเลขท้าย 3 ตัวรางวัลใดรางวัลหนึ่ง (หวยรัฐบาลและสลากที่ประกาศชุดเต็ม) |
✅Checklist ก่อนขึ้น production
ติ๊กเก็บไว้ได้ — สถานะจำไว้ในเบราว์เซอร์นี้เท่านั้น
⬇️ดาวน์โหลด
ไฟล์สเปกและ Postman ชุดเดียวกับที่ใช้ทดสอบภายใน — environment ไม่มีคีย์หรือ secret ติดมา ใส่ของคุณเองในเครื่อง
✓
ต้องการความช่วยเหลือ ส่ง request_id ของคำขอที่มีปัญหา เวลาโดยประมาณ และ error.code ที่ได้ มาให้ทีม HuayEngine — ห้ามส่ง hmac_secret มาทุกกรณี