# เอกสาร Neo API แบบ Seamless (Single Wallet): callback, get-games, init-session

# ภาพรวม

## Neo API คืออะไร ?

Neo API คือ Super API ที่รวมเส้น API จากกว่า **80+ ผู้ให้บริการเกม** ไว้ ทำให้คุณสามารถเชื่อมต่อค่ายเกมทั้งหมดเข้าระบบของคุณได้ด้วย API เพียงเส้นเดียว

## การเชื่อมต่อ

Neo API รองรับการเชื่อมต่อ 2 ประเภท: ดูรายละเอียดการเชื่อมต่อ API

#### 1. Seamless (Single Wallet)

ในรูปแบบ Seamless ผู้ให้บริการเกมจะไม่ถือเงินผู้เล่นไว้เอง (หรืออย่างมากมีการถือครองเพียงชั่วคราว) ทุกธุรกรรมเดิมพัน/ชนะจะมีการ callback ผ่าน API กับคุณโดยตรง ทุก callback ต้อง implement แบบ transactional และ idempotent (กันการหักเงินซ้ำ)

ข้อดี:

- UX ดีที่สุด: ผู้เล่นเห็นยอดเงินกลางเดียว ไม่มีขั้นตอนโยกเงินข้ามระบบ
- ลดปัญหาเงินค้าง/เงินสูญหาย

ข้อเสีย:

- ระบบของคุณต้องรองรับ API ที่ถูกเรียกถี่มาก (high QPS) และตอบกลับเร็ว
- ความผิดพลาดต้องมีการจัดการซับซ้อนกว่า (กัน duplicate และ replay)
- คุณเป็น "Source of Truth" ต้องมี audit log และ replay protection ที่ดี

เหมาะสำหรับ:

- ผู้ที่มีระบบเสถียรมั่นคง
- ต้องการให้ผู้เล่นเปลี่ยนเกม/ค่ายได้ทันทีไม่ต้องโยก
- พร้อม implement idempotency key, ledger, audit ครบถ้วน

#### 2. Transfer (Two Wallet)

ในรูปแบบ Transfer ฝั่งผู้ให้บริการเกมจะสร้าง "กระเป๋าเงินฝั่ง provider" ให้ผู้เล่นหนึ่งใบ เวลาจะเข้าไปเล่น ต้องโยกเงินไปยังมายังกระเป๋านี้ก่อน (transfer-in) และเมื่อจบ session หรือออกจากเกม ต้องโยกเงินกลับ (transfer-out) โดยระหว่างผู้เล่นกำลังเล่นเกม provider จะตัดสินใจดำเนินเกมและ settlement เอง ไม่มี callback กลับมาหาคุณทุกตาเหมือนการเชื่อมต่อแบบ seamless

ข้อดี:

- ระบบคุณรับ API load แค่ตอน transfer ไม่ต้องรองรับการถูกเรียกสูงในขณะที่ผู้เล่นกำลังเล่นเกมแบบ per-bet
- Provider รับผิดชอบการ settle bet ภายใน
- เริ่มต้นได้ง่ายกว่า seamless

ข้อเสีย:

- UX อาจแย่กว่า ผู้เล่นจะเห็นยอดแยก หรือเงินโยกช้า ติดค้างได้
- เงินอาจค้างอยู่หาก session ค้างหรือ error

เหมาะสำหรับ:

- ผู้เริ่มต้นพัฒนาระบบ
- ระบบที่ไม่ต้องการรับโหลด API การเล่นแบบ real-time

## เครดิต

Neo API ใช้ระบบเครดิตสำหรับควบคุมการใช้งาน เครดิตนับจากยอด Win/Loss (ผลรวมการชนะ/แพ้) ของผู้เล่นภายใต้การเชื่อมต่อกับยูสเซอร์ของคุณ

โปรดระวัง

เมื่อเครดิตหมดผู้เล่นจะไม่สามารถเล่นเกมได้ โปรดหมั่นตรวจสอบว่าบัญชีของคุณมีเครดิตเหลือเพียงพอ

กรุณาติดต่อหัวสายของคุณหากต้องการเครดิตเพิ่มเติม

## การตั้ง RTP

Neo API รองรับ **30+ ค่ายเกมปรับแตก** ที่สามารถตั้ง RTP (Return to Player) ได้ ซึ่งช่วยให้คุณสามารถควบคุมอัตราการจ่ายเงินรางวัลได้ตามต้องการ สามารถตั้ง RTP รวมทุกค่ายหรือแยกตามค่ายได้ผ่านหน้า UI และสามารถตั้ง RTP อย่างละเอียดตามผู้เล่นแบบ real-time ได้ผ่าน API

ฝั่ง API ตั้งได้ 2 แบบ: ส่งฟิลด์ `rtp` ไปกับ `init-session` เพื่อกำหนดเฉพาะ session นั้น หรือเรียก `set-rtp` เพื่อตั้งค่าค้างไว้ให้ทั้งค่าย ไม่ต้องส่งซ้ำทุกครั้งที่เปิดเกม (ดูรายละเอียดในหัวข้อ 5.2 ของการเชื่อมต่อ API)

# การเปิดสายต่อ

## สร้างลูกสาย

คุณสามารถสร้างบัญชี Subagent (ลูกสาย) ได้ ซึ่งลูกสายของคุณสามารถจัดการลูกสายชั้นต่อไปได้เช่นกัน โดยคุณในฐานะหัวสายจะสามารถจัดการดูแลลูกสายภายใต้คุณทั้งหมดได้

### ข้อมูลที่ต้องกรอกเมื่อสร้าง Subagent:

- **Username**: ชื่อผู้ใช้งานของ Subagent
- **Password**: รหัสผ่านสำหรับ Subagent
- **Callback Type**: เลือกประเภทการเชื่อมต่อ (Seamless หรือ Transfer)
- **Callback URL**: URL สำหรับรับ callback (กรณี Seamless) สามารถปล่อยว่างไว้ก่อนได้
- **เครดิต**: จำนวนเครดิตที่ต้องการกำหนดให้ Subagent
- **Provider Rates**: อัตราค่าคอมมิชชั่นสำหรับแต่ละค่ายเกม

## ดูการใช้งานภายใต้สายของคุณ

คุณสามารถดูการใช้งานของ Subagent ทั้งหมดได้ผ่าน Dashboard เพื่อติดตามสถิติและข้อมูลต่างๆ เช่น:

- **รายชื่อ Subagent**: ดูรายชื่อ Subagent ทั้งหมดที่คุณสร้างไว้
- **เครดิตคงเหลือ**: ดูเครดิตที่ใช้แล้วและคงเหลือของแต่ละ Subagent
- **ยอดการทำธุรกรรม**: ดูยอดเดิมพัน ยอดชนะ/แพ้ ของแต่ละ Subagent
- **สถิติตามช่วงเวลา**: ดูสถิติการใช้งานตามวันที่กำหนด
- **Hierarchy Level**: ดูระดับลำดับชั้นของ Subagent ในระบบ

คุณสามารถคลิกเข้าไปดูรายละเอียดของ Subagent แต่ละรายได้ เพื่อดูข้อมูลเพิ่มเติมและจัดการ Subagent ได้

# การเชื่อมต่อ API

## Seamless Integration

การเชื่อมต่อแบบ Seamless มี 6 ขั้นตอนหลักดังนี้:

1. การตั้ง Callback URL
2. การเตรียมรับ Callback
3. การดึงรายการเกม
4. การสร้าง Session ให้กับผู้เล่น
5. การเช็คเครดิตของ Subagent
6. ดูประวัติแทงหวยของผู้เล่น

**คำศัพท์:**

- **Agent** หมายถึงผู้ให้บริการเว็บคาสิโนหรือท่าน
- **Agent id** หมาย ID ของท่านซึ่งดูได้จากหน้า [บัญชีของฉัน](/settings)
- **Agent's server** หมายถึงเซิร์ฟเวอร์ของท่าน
- **Provider** หรือ ผู้ให้บริการ หมายถึงผู้ให้บริการเกมแต่ละค่าย เช่น PG Soft, Pragmatic Play, JOKER, Sexy, etc.

### Authentication

ในทุกการสื่อสารระหว่าง Agent และ Neo API ในทุก request จะต้องมีการแนบ Private Key มาใน Header ใน field `Authorization` เพื่อใช้ยืนยันตัวตน รวมไปถึงการรับ callback จาก Neo API จะมีการแนบ Private Key มาในรูปแบบเดียวกันด้วยเช่นกัน

เข้าไปที่หน้า [บัญชีของฉัน](/settings) เพื่อดูและคัดลอก Private Key ของคุณ

**หมายเหตุ:**

- Private Key จะใช้ในการยืนยันตัวตนเมื่อส่ง request ไปยัง Super API
- สำหรับการรับ callback จาก Neo API จะมีการแนบ Private Key มาในรูปแบบเดียวกันด้วยเช่นกัน อย่าลืมตรวจสอบความถูกต้องของ Private Key ก่อนประมวลผลข้อมูล
- โปรดเก็บ Private Key ไว้เป็นความลับและไม่ควรเปิดเผยให้ผู้อื่นทราบ
- หาก Private Key ถูกเปิดเผย กรุณา Reset Private Key ทันทีเพื่อความปลอดภัย

### 1. การตั้ง Callback URL

เข้ามาที่หน้า [บัญชีของฉัน](/settings) เลื่อนลงมาที่ จัดการ Callback URL แล้วระบุเซิร์ฟเวอร์ URL ของท่าน ที่จะให้ระบบส่ง Callback request มา

เงื่อนไขของ Callback URL

ระบบ Neo เป็นฝ่ายยิงเข้าไปหา URL นี้ทุกครั้งที่มีการเดิมพัน URL จึงต้องเป็นปลายทางที่เซิร์ฟเวอร์ของเราเรียกถึงได้จริง ระบบตรวจตั้งแต่ตอนกดบันทึก ถ้าไม่ผ่านจะได้ `CALLBACK_URL_NOT_ALLOWED`

- ต้องขึ้นต้นด้วย `http` หรือ `https`
- ต้องเป็นโฮสต์สาธารณะ — ใช้ `localhost` , `127.0.0.1` หรือ IP วงภายใน ( `10.x`, `172.16–31.x` , `192.168.x` , `169.254.x` ) ไม่ได้ เพราะเซิร์ฟเวอร์ของเรายิงไปไม่ถึงอยู่แล้ว
- ถ้าเป็นโดเมน ระบบจะ resolve แล้วดูปลายทางจริง — โดเมนที่ชี้กลับเข้า IP ภายในก็ไม่ผ่านเช่นกัน
- โดเมนที่ DNS ยังไม่ขึ้น **บันทึกได้ตามปกติ** แต่ Callback จะยังไม่ทำงานจนกว่า DNS จะชี้มาที่เซิร์ฟเวอร์ของท่าน
- ห้ามใส่ username/password ไว้ใน URL — การยืนยันว่าเป็น request จาก Neo จริง ให้ตรวจจาก `Authorization` header ที่เราแนบไปให้ (คือ Private Key ของท่าน)

เตรียมรับ Callback จาก Neo API โดยท่านต้องเตรียม Endpoint ไว้สองเส้นได้แก่:

- `/check-balance`
- `/update-balance`

### 2. การเตรียมรับ Callback

สำหรับ Callback ทั้งสองเส้นทาง Neo API จะแนบ Private Key มาใน Header ใน field `Authorization` เพื่อใช้ยืนยันตัวตน กรุณานำไปใช้ตรวจสอบยืนยันตัวตน

🔒 แนะนำเพื่อความปลอดภัย:

- กรุณาถาม agent ของท่านเพื่อขอรับ IP Whitelist เพื่อป้องกันการถูกสวมรอย
- โปรดหมั่น Reset Private Key เพื่อความปลอดภัย

#### 2.1 เส้นตรวจสอบยอดเงิน (Check Balance)

สำหรับเส้น `/check-balance` จะเป็นเส้นที่ Neo API ส่ง request ที่มี payload เป็น `agentId` และ `username` (โดย username นี้มาจากตอนที่ Agent init-session) เพื่อขอข้อมูลผู้เล่นจาก Agent โดย Agent ต้องตอบกลับหา Neo API ด้วยข้อมูลตามรูปแบบที่กำหนด

Request (จาก Neo API → Agent):

```json
POST /check-balance
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "username": "player123",
  "agentId": "agent_123"
}
```

Response (จาก Agent → Neo API):

```json
{
  "username": "player123",
  "balance": 1000.00,
  "status_code": 0
}
```

##### คำอธิบาย Response Body:

- `username`: ชื่อผู้ใช้งาน
- `balance`: ยอดคงเหลือของผู้ใช้งาน
- `status_code` : รหัสสถานะ

##### Status Code:

- `0`: SUCCESS
- `1`: USER_NOT_FOUND
- `2`: INSUFFICIENT_BALANCE
- `3`: INVALID_REQUEST
- `4`: UNAUTHORIZED
- `5`: FORBIDDEN
- `6`: INTERNAL_SERVER_ERROR
- `7`: TRANSACTION_ALREADY_EXISTS
- `8`: TO_CANCEL_TRANSACTION_NOT_FOUND

##### ตัวอย่างโค้ด:

```javascript
// Express.js example
const express = require('express');
const app = express();
app.use(express.json());

const PRIVATE_KEY = process.env.YOUR_PRIVATE_KEY;

app.post('/check-balance', async (req, res) => {
  try {
    // Verify Authorization header
    const authHeader = req.headers.authorization || '';
    if (authHeader !== PRIVATE_KEY) {
      return res.status(401).json({
        username: req.body.username || '',
        balance: 0,
        status_code: 4 // UNAUTHORIZED
      });
    }
    
    const { username, agentId } = req.body;
    
    // Get user balance from database
    // Replace this with your actual database query
    const userBalance = await getUserBalance(username, agentId);
    
    if (userBalance === null) {
      return res.json({
        username: username,
        balance: 0,
        status_code: 1 // USER_NOT_FOUND
      });
    }
    
    return res.json({
      username: username,
      balance: userBalance,
      status_code: 0 // SUCCESS
    });
  } catch (error) {
    console.error('Error:', error);
    return res.json({
      username: req.body.username || '',
      balance: 0,
      status_code: 6 // INTERNAL_SERVER_ERROR
    });
  }
});

async function getUserBalance(username, agentId) {
  // Implement your database query here
  // Return balance or null if user not found
}
```

#### 2.2 เส้นอัพเดทยอดเงิน (Update Balance)

สำหรับเส้น `/update-balance` จะเป็นเส้นที่ Neo API ส่ง request ที่มี payload เป็นข้อมูลการเล่นและผลลัพธ์ที่ได้ของผู้เล่นไปให้ เพื่อให้เซิร์ฟเวอร์ของ Agent ตรวจสอบและปรับข้อมูล โดยหลักๆจะใช้ค่า `transferIn` (player เอาเงินเข้ามาในระบบคล้ายๆ bet) และ `transferOut` (เราจ่ายเงินให้ player คล้ายๆ settle) เป็นหลัก

📢 ประกาศ (ก.ย. 2026): callback แนบ isBuyFeature / isFreeSpin ครบทุกค่ายที่มีข้อมูลแล้ว

- ตั้งแต่ 23 ก.ย. 2026 เส้นนี้แนบทั้ง isBuyFeature และ isFreeSpin มาให้ทุกค่ายที่มีข้อมูล จากเดิมที่มีแค่ isBuyFeature ของค่าย _plus บางค่าย และ isFreeSpin ไม่เคยส่งมาเลย
- ความหมายของสองฟิลด์ และตารางว่าค่ายไหนมีอันไหน อยู่ในกล่องด้านล่างของหัวข้อนี้
- **null หรือไม่มี field ไม่ได้แปลว่าผู้เล่นไม่ได้ซื้อ — แปลว่าค่ายนั้นไม่ได้ส่งข้อมูลนี้มาให้ อย่านับเป็น false ตอนทำรายงาน**

⚠️ สิ่งสำคัญที่ต้องตรวจสอบ:

- อย่าลืมตรวจสอบยอดเงินของผู้เล่นว่ามีเพียงพอที่จะ transfer in ไหม
- อย่าลืมเช็ค providerTransactionId ซ้ำ, ถ้าได้รับ provider transaction id ซ้ำต้องไม่นำไปคำนวณซ้ำ เกิดขึ้นในกรณีที่ agent ตอบกลับ Neo API ช้า Neo API จะส่งrequest ไปอีกครั้งด้วย provider transaction id เดิม
- ถ้า field `ableNegativeBalance` เป็น true ทาง Agent จะต้องอนุญาติให้เงินของ player ติดลบได้
- สำหรับ field `toCancelProviderTransactionId` เอาไว้ให้ค่ายเกมใช้อ้างอิง transaction ที่จะ cancel ซึ่ง agent จะต้องยกเลิก transaction นั้นออกจากระบบ
- field `isBuyFeature` และ `isFreeSpin` (optional) จะแนบมากับ request `เฉพาะเมื่อเป็น true` เท่านั้น ถ้าไม่มี field แปลว่ารอบนั้นไม่ใช่ หรือค่ายไม่ได้บอกเรามา — ดูรายชื่อค่ายที่ส่งได้ที่ตารางด้านล่าง

isBuyFeature กับ isFreeSpin ต่างกันยังไง

`isBuyFeature` = รอบนี้มาจากฟีเจอร์ที่ผู้เล่นจ่ายเงินก้อนซื้อเข้ามาเลย ไม่ได้รอหมุนให้ติดเอง ราคาซื้อมักอยู่ราว 100 เท่าของเงินเดิมพันปกติ รอบที่จ่ายเงินซื้อจึงมี betAmount สูงผิดปกติเมื่อเทียบกับรอบอื่นของผู้เล่นคนเดียวกัน

`isFreeSpin` = รอบที่ผู้เล่นไม่ได้จ่ายเงินเพิ่ม เป็นผลต่อเนื่องมาจากรอบก่อนหน้า ครอบคลุมทั้ง Free Spin ในเกม, Re-spin และรอบที่ต่อเนื่องกัน รอบแบบนี้จึงมักมี betAmount เป็น 0 แต่มียอดจ่ายออก

ทั้งสองอย่างมักมาคู่กัน — ผู้เล่นซื้อฟีเจอร์หนึ่งรอบ (isBuyFeature) แล้วได้รอบฟรีตามมาอีกหลายรอบ (isFreeSpin) เวลาคิด turnover หรือยอดเดิมพันจริง ให้ระวังอย่านับรอบฟรีเป็นเงินที่ผู้เล่นจ่ายเพิ่ม

บางค่าย (เช่น PG และ AMB) ติด isBuyFeature ให้รอบฟรีที่ตามมาจากการซื้อด้วย รอบพวกนั้นจึงเป็น true ทั้งสองฟิลด์และมี betAmount เป็น 0 — ถ้าจะนับจำนวนครั้งที่ผู้เล่นซื้อฟีเจอร์ ให้นับเฉพาะรอบที่ isBuyFeature เป็น true แต่ isFreeSpin ไม่ใช่ true ไม่งั้นตัวเลขของ PG จะสูงเกินจริงราว 20 เท่า

⚠️ null ไม่ได้แปลว่า "ไม่ได้ซื้อ" หรือ "ไม่ใช่ free spin"

- null แปลว่าค่ายนั้นไม่ได้ส่งข้อมูลนี้มาให้เรา — เราจึงไม่รู้ว่ารอบนั้นผู้เล่นซื้อฟีเจอร์หรือเป็น free spin หรือเปล่า มีแต่ false เท่านั้นที่แปลว่าค่ายบอกมาว่า "ไม่ใช่"
- ใน callback เราส่ง field มาให้เฉพาะตอนเป็น true — ถ้าไม่มี field มา ให้ดูตารางด้านล่าง: ค่ายที่เป็น ✅ แปลว่าไม่ใช่ ส่วนค่ายที่เป็น ⚠️ หรือ ❌ แปลว่าไม่รู้
- อย่านับ null เป็น false ตอนทำรายงาน ไม่งั้นตัวเลขจะออกมาว่าแทบไม่มีใครซื้อฟีเจอร์เลย ซึ่งไม่ตรงกับความจริง

ค่ายไหนมี isBuyFeature / isFreeSpin บ้าง

| ค่าย | `isBuyFeature` | `isFreeSpin` |
| --- | --- | --- |
| PG_plus, JILI_plus, JOKER_plus, NOLIMITCITY_plus, EVOPLAY_plus, FACHAI_plus | ✅ | ✅ |
| NEXTSPIN_plusค่ายใหม่ (ต.ค. 2026) ยังรอยืนยันจากรายการจริง | ⚠️ | ⚠️ |
| PG | ✅ | ✅ |
| AMB | ✅ | ✅ |
| 759GAMING, AFB1188_SLOT, AMBGAMING | ✅ | ✅ |
| JILI | ✅ | ❌ |
| PP | ✅ | ❌ |
| OCTOPLAYส่งมาเฉพาะรอบที่ซื้อฟีเจอร์ | ⚠️ | ❌ |
| CLOTPLAYส่งมาประมาณครึ่งหนึ่งของรายการ | ⚠️ | ❌ |
| BOOMING, YGR, I8 | ❌ | ✅ |
| JOKERส่งมาเฉพาะรอบที่ได้โบนัส | ❌ | ⚠️ |
| NEXTSPINส่งมาเฉพาะรอบที่เป็น free spin | ❌ | ⚠️ |
| BIGPOT, HOTDOG, FUNKYส่งมาประมาณครึ่งหนึ่งของรายการ | ❌ | ⚠️ |
| SA_plus, SEXY_plusคาสิโนสด ไม่มีฟีเจอร์นี้อยู่แล้ว | false เสมอ | false เสมอ |

✅ ส่งมาทุกรายการ · ⚠️ ส่งมาบางรายการ ถ้าไม่มีให้ถือว่าไม่รู้ ไม่ใช่ false · ❌ ไม่ส่ง เป็น null เสมอ

ค่ายอื่นทั้งหมดไม่มีทั้งสองอย่าง — เป็น null เสมอ

- ค่าย _plus ตัวอื่นทั้งหมดที่ไม่อยู่ในตาราง เช่น PRAGMATIC_plus, CQ9_plus, HABANERO_plus, HACKSAW_plus, JDB_plus, KA_plus, PLAYSON_plus, SPRIBE_plus, TADA_plus, 3OAKS_plus — กลุ่มนี้วิ่งอยู่คนละระบบกับ _plus ในตาราง แม้ชื่อจะลงท้ายด้วย _plus เหมือนกัน
- PNG, HAB, RLX, NE, RTG, WAZ, YGG, PRG, NLC, EVP และ FCG
- ค่ายสล็อตอื่น เช่น ROYAL, LIVE22, SLOTXO, RICH88, PRETTY, SPADE, KINGMAKER
- คาสิโนสด กีฬา และหวย (SA, SEXY, DG, WM, SBO, BTI, UFAPLUS, HIPPO, HUAYDRAGON, LEKTHONG) — ไม่มีคอนเซปต์ free spin / buy feature ตั้งแต่ต้น

**ชื่อค่ายซ้ำกันได้** — JILI_plus กับ JILI, PG_plus กับ PG, NOLIMITCITY_plus กับ NLC, EVOPLAY_plus กับ EVP, NEXTSPIN_plus กับ NEXTSPIN เป็นคนละค่ายคนละระบบ และรองรับฟิลด์นี้ไม่เหมือนกัน เวลาทำรายงานให้ยึด providerId ไม่ใช่ชื่อค่าย

freeSpinIndex / freeSpinTotal — ฟรีสปินรอบที่เท่าไหร่ และเหลืออีกกี่รอบ

⚠️ มีเฉพาะ 2 ค่าย: PG_plus และ JOKER_plus

- ตอนนี้นับฟรีสปินได้แค่สองค่ายนี้ ค่ายอื่นทั้งหมดจะไม่มีสองฟิลด์นี้ รวมถึง PG, JOKER และค่าย _plus ตัวอื่น เช่น JILI_plus, NOLIMITCITY_plus, EVOPLAY_plus, FACHAI_plus, NEXTSPIN_plus
- PG_plus: บางเกมไม่มีสองฟิลด์นี้ เพราะไม่มีฟรีสปินให้นับเป็นตา เช่น Fortune Ox, Fortune Horse (ฟีเจอร์จบในสปินเดียว), Ninja Racoon Frenzy, Werewolf's Hunt (respin แบบ hold & win ไม่มีจำนวนตาตายตัว), The Great Icescape (ตัวอย่าง ไม่ใช่รายชื่อครบ)
- JOKER_plus: มีเฉพาะ 28 เกมที่จ่ายฟรีสปินทีละตา: Aladdin, Alice, Ancient Egypt, Arctic Treasure, Dragon Phoenix, Egypt Queen, Fei Long Zai Tian, Five Tiger Generals, Genie, Golden Dragon, Golden Island, Golden Rooster, Happy Buddha, Hercules, Jungle Island, Lucky Drum, Lucky God Progressive, Lucky Panda, MoneyBangBang, Mulan, Queen, Robin Hood, Safari Heat, Santa Surprise, Water Margin, White Snake, Wild Spirit, Zhao Cai Jin Bao
- เกม JOKER_plus อื่น เช่น Immortals, Horus Eye จ่ายทั้งฟีเจอร์ในรายการเดียว ทั้งตอนซื้อฟีเจอร์และตอนเข้าฟีเจอร์เอง จึงไม่มีสองฟิลด์นี้

`freeSpinIndex` = รอบฟรีสปินที่รายการนี้จ่าย นับจาก 1 ส่วน 0 คือรอบที่ผู้เล่นจ่ายเงินหมุนแล้วเข้าฟีเจอร์ หรือรอบที่ซื้อฟีเจอร์

`freeSpinTotal` = จำนวนฟรีสปินทั้งหมดของฟีเจอร์นี้ ณ ตอนนั้น ถ้าได้ฟรีสปินเพิ่มกลางทาง ตัวเลขนี้จะเพิ่มขึ้น เช่น 1/4 → 2/5 → 3/6

**ฟรีสปินที่เหลือ = freeSpinTotal − freeSpinIndex** — เราไม่ได้ส่งจำนวนที่เหลือมาให้ ให้คำนวณจากสองฟิลด์นี้

- สองฟิลด์มาคู่กันเสมอ และมาเฉพาะรายการที่อยู่ในฟีเจอร์ รายการปกติจะไม่มี field เลย ไม่มี field ไม่ได้แปลว่า 0
- ตาที่ผู้เล่นจ่ายเงินหมุนและคอมโบต่อเนื่องก่อนเข้าฟีเจอร์ อาจมี isFreeSpin แล้วแต่ยังไม่มีสองฟิลด์นี้ ค่าคู่นี้เริ่มที่ freeSpinIndex 0 ตอนเข้าฟีเจอร์
- PG_plus: ฟรีสปินตาเดียวอาจมีหลายรายการที่ freeSpinIndex เท่ากัน (คอมโบในตาเดียว) อย่านับจำนวนรายการเป็นจำนวนตา ส่วน JOKER_plus ส่งตาละรายการเดียว freeSpinIndex ไม่ซ้ำ
- ในฟีเจอร์ที่ผู้เล่นซื้อ รายการของ PG_plus จะไม่มี isFreeSpin แต่มีสองฟิลด์นี้ และบางรอบ freeSpinIndex 0 อยู่ที่รายการที่ 2–3 เพราะได้ฟรีสปินจากคอมโบถัดไป ถ้าจะแยกว่ารายการไหนอยู่ในฟีเจอร์ ให้ดูสองฟิลด์นี้แทน isFreeSpin
- ใช้แสดงผลหรือทำรายงานเท่านั้น ไม่มีผลกับยอดเงิน ให้คิดเงินจาก transferIn / transferOut เหมือนเดิม

Request (จาก Neo API → Agent):

```json
POST /update-balance
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "agent_123",
  "username": "player123",
  "providerTransactionId": "txn_123456",
  "transferIn": 0.00,
  "transferOut": 50.00,
  "ableNegativeBalance": false,
  "toCancelProviderTransactionId": null,
  "isBuyFeature": true,
  "isFreeSpin": true,
  "freeSpinIndex": 3,
  "freeSpinTotal": 10
}
```

Response (จาก Agent → Neo API):

```json
{
  "username": "player123",
  "balanceBefore": 1000.00,
  "balanceAfter": 1050.00,
  "status_code": 0
}
```

##### คำอธิบาย Response Body:

- `username`: ชื่อผู้ใช้งาน (เหมือนกับใน request)
- `balanceBefore` : ยอดคงเหลือก่อนทำรายการ
- `balanceAfter` : ยอดคงเหลือหลังทำรายการ
- `status_code` : รหัสสถานะ — Neo API ใช้ field นี้ (ต้องชื่อ `status_code` เท่านั้น) ในการตัดสินว่า transaction สำเร็จหรือไม่

##### Status Code ต่างๆตอน response:

- `0`: ในกรณีที่ transaction สำเร็จ
- `1`: ในกรณีที่ username หาไม่เจอ
- `2`: ในกรณีที่ เงินของ player ไม่พอให้ transferIn
- `3`: ในกรณีที่ request ส่งไปผิด format
- `4`: ในกรณีที่ agent id ส่งไปผิด
- `5`: ในกรณีที่ private key ส่งไปผิด
- `6`: ในกรณีที่ server ของทาง agent มีปัญหาอื่นๆ
- `7`: ในกรณีที่ providerTransactionId ซ้ำ
- `8`: ในกรณีที่หา providerTransactionId ที่จะ cancel ไม่เจอ

##### ตัวอย่างโค้ด:

```javascript
// Express.js example
const express = require('express');
const app = express();
app.use(express.json());

const PRIVATE_KEY = process.env.YOUR_PRIVATE_KEY;

app.post('/update-balance', async (req, res) => {
  try {
    // Verify Authorization header
    const authHeader = req.headers.authorization || '';
    if (authHeader !== PRIVATE_KEY) {
      return res.status(401).json({
        username: req.body.username || '',
        balanceBefore: 0,
        balanceAfter: 0,
        status_code: 5 // FORBIDDEN (wrong private key)
      });
    }

    const {
      username,
      agentId,
      providerTransactionId,
      transferIn = 0,
      transferOut = 0,
      ableNegativeBalance = false
    } = req.body;

    // Check if transaction already exists (idempotency check)
    const isProcessed = await isTransactionProcessed(providerTransactionId);
    if (isProcessed) {
      const currentBalance = await getUserBalance(username, agentId);
      return res.json({
        username: username,
        balanceBefore: currentBalance || 0,
        balanceAfter: currentBalance || 0,
        status_code: 7 // TRANSACTION_ALREADY_EXISTS
      });
    }

    // Get current balance
    const currentBalance = await getUserBalance(username, agentId);
    if (currentBalance === null) {
      return res.json({
        username: username,
        balanceBefore: 0,
        balanceAfter: 0,
        status_code: 1 // USER_NOT_FOUND
      });
    }

    // Check if user has enough balance for transfer in
    if (transferIn > 0 && currentBalance < transferIn && !ableNegativeBalance) {
      return res.json({
        username: username,
        balanceBefore: currentBalance,
        balanceAfter: currentBalance,
        status_code: 2 // INSUFFICIENT_BALANCE
      });
    }

    // Calculate new balance
    const newBalance = currentBalance - transferIn + transferOut;

    // Update balance in database
    await updateUserBalance(username, agentId, newBalance);

    // Mark transaction as processed
    await markTransactionProcessed(providerTransactionId);

    return res.json({
      username: username,
      balanceBefore: currentBalance,
      balanceAfter: newBalance,
      status_code: 0 // SUCCESS
    });
  } catch (error) {
    console.error('Error:', error);
    return res.json({
      username: req.body.username || '',
      balanceBefore: 0,
      balanceAfter: 0,
      status_code: 6 // INTERNAL_SERVER_ERROR
    });
  }
});

async function isTransactionProcessed(transactionId) {
  // Check if transaction already processed
  // Implement your idempotency check here
  return false;
}

async function getUserBalance(username, agentId) {
  // Get user balance from database
  // Return balance or null if user not found
  return null;
}

async function updateUserBalance(username, agentId, newBalance) {
  // Update user balance in database
}

async function markTransactionProcessed(transactionId) {
  // Mark transaction as processed
}
```

#### 2.3 การตรวจสอบ Callback

Neo API มีเครื่องมือสำหรับทดสอบ callback endpoints ของคุณที่หน้า [Callback Test](/callback-test) เพื่อให้คุณสามารถทดสอบว่า callback endpoints ของคุณทำงานถูกต้องหรือไม่

##### วิธีใช้งาน Callback Test Runner:

1. ไปที่หน้า [Callback Test](/callback-test)
2. กรอกข้อมูลที่จำเป็น:`Callback URL` : URL ของ callback server ของคุณ`Agent ID` : ID ของ Agent ของคุณ`Private Key` : Private Key ของคุณ`Username` : Username ของผู้เล่นที่ต้องการทดสอบ
3. คลิกปุ่ม `Run Tests` เพื่อเริ่มทดสอบ
4. ระบบจะทดสอบ callback endpoints ทั้ง `/check-balance` และ `/update-balance`
5. ดูผลลัพธ์การทดสอบและตรวจสอบว่า callback endpoints ของคุณตอบกลับตามรูปแบบที่ถูกต้อง

💡 คำแนะนำ:

- ตรวจสอบให้แน่ใจว่า callback server ของคุณสามารถเข้าถึงได้จากอินเทอร์เน็ต
- ตรวจสอบว่า callback endpoints ของคุณรองรับ HTTPS (ถ้าใช้ production)
- ตรวจสอบว่า Authorization header และ response format ถูกต้องตามที่กำหนด
- ทดสอบกรณีต่างๆ เช่น username ที่ไม่มีอยู่, ยอดเงินไม่พอ, transaction id ซ้ำ เป็นต้น
- Test Runner ยิง request จาก browser โดยตรง ดังนั้น callback server ของคุณต้องเปิด CORS จึงจะใช้เครื่องมือนี้ได้ — เฉพาะตอนทดสอบเท่านั้น ของจริง Neo API ยิงแบบ server-to-server จึงไม่เกี่ยวกับ CORS

### 3. การดึงรายการเกม

เป็น Endpoint ที่ Agent จะยิงไปยัง Neo API เพื่อขอรายชื่อเกมทั้งหมดหรือตาม provider ที่ระบุเพื่อนำ `gameId` ไปใช้ต่อในการสร้าง Session ให้กับผู้เล่น

📢 ประกาศ (ก.ค. 2026): ค่าย Plus อัปเดต providerId / gameId ใหม่

- ค่าย JILI_plus, SA_plus, NOLIMITCITY_plus, EVOPLAY_plus และ FACHAI_plus ย้ายขึ้นระบบใหม่ — **ชื่อค่ายเหมือนเดิม แต่ providerId และ gameId เปลี่ยนใหม่ทั้งหมด** พร้อมค่ายใหม่ SEXY_plus
- กรุณายิง get-games เพื่อ sync รายการเกมรอบใหม่ แล้วอัปเดต gameId / providerId ที่บันทึกไว้ในระบบของคุณ
- gameId ชุดเดิมยังเปิดเกมได้ชั่วคราวในช่วงเปลี่ยนผ่านเท่านั้น และจะถูกปิดการใช้งานในลำดับถัดไป — แนะนำให้ sync ใหม่ทันที

Request:

```json
POST /api/external/get-games
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string",
  "providerList": ["string"] // optional
}
```

##### คำอธิบาย Request Body:

- `agentId`: ID ของ Agent
- `providerList` : รายชื่อ Provider ID ที่ต้องการ (optional, ถ้าไม่ระบุจะได้ทั้งหมด)

Response:

```json
{
  "providers": [
    {
      "provider": {
        "id": "string",
        "name": "string",
        "isRedirect": true,
        "logoUrl": "string" // optional
      },
      "games": [
        {
          "id": "string",
          "name": "string",
          "code": "string",
          "imageUrl": "string",
          "type": "slot" | "casino" | "table" | "fishing" | "lottery" | "virtual" | "sports",
          "tag": "string", // optional
          "order": 0, // optional
          "isRecommend": true,
          "isNew": false,
          "providerId": "string",
          "mappedGameCode": "string" // optional
        }
      ]
    }
  ]
}
```

##### คำอธิบาย Response Body:

- `providers`: รายชื่อ Provider พร้อมเกมที่เกี่ยวข้อง
- `provider.id`: ID ของ Provider
- `provider.name` : ชื่อ Provider
- `provider.isRedirect` : ระบุว่า Provider นี้ใช้ redirect หรือไม่
- `provider.logoUrl` : URL ของโลโก้ Provider (optional)
- `games`: รายชื่อเกมใน Provider นี้
- `game.type`: ประเภทของเกม (slot, casino, table, fishing, lottery, virtual, sports)
- `game.isRecommend` : ระบุว่าเป็นเกมแนะนำหรือไม่
- `game.isNew`: ระบุว่าเป็นเกมใหม่หรือไม่

##### ตัวอย่างโค้ด:

```bash
curl -X POST https://api.neoapihub.com/api/external/get-games \
  -H "Authorization: YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "string",
    "providerList": ["string"]
  }'
```

### 4. การสร้าง Session

เป็น Endpoint ที่ Agent จะยิงไปยัง Neo API เพื่อขอ URL สำหรับ redirect เริ่มเกมให้กับผู้เล่น

**หมายเหตุ:**

- สำหรับ Agent ที่มีหลายเว็บไซต์แนะนำให้ใช้ username ตามด้วยชื่อเว็บไซต์เพื่อป้องกันชื่อ username ซ้ำ
- ต้องแนบ Private Key มาใน Authorization ใน Header

Request:

```json
POST /api/external/init-session
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "gameId": "string",
  "username": "string",
  "hrefBackUrl": "string",
  "agentId": "string",
  "language": "en" | "cn" | "jp" | "th" | "vn" | "kr",
  "isDesktop": true, // optional, default: true
  "rtp": number, // optional, 30-99 (default: 97)
  "clientIp": "string", // required for PG games
}
```

##### คำอธิบาย Request Body:

- `gameId`: ID ของเกมที่ต้องการเล่น
- `username`: ชื่อผู้ใช้งาน
- `hrefBackUrl`: URL สำหรับกลับเมื่อออกจากเกม
- `agentId`: ID ของ Agent
- `language`: ภาษาที่ต้องการ (en, cn, jp, th, vn, kr) default: th
- `isDesktop`: ระบุว่าเป็น Desktop หรือไม่ (optional, default: true)
- `rtp`: ระบุค่า RTP ของเกม (optional, 30-99, default: 97)
- `clientIp`: IP ของผู้เล่น (จำเป็นสำหรับค่าย PG — ถ้าไม่ส่ง init-session จะตอบ 400 และเปิดเกมไม่ได้ ส่วนค่ายอื่นไม่ใช้ค่านี้)

Response:

```json
{
  "url": "string", // optional
  "html": "string", // optional
  "type": "url" | "html" | "redirect"
}
```

##### คำอธิบาย Response Body:

- `url`: URL สำหรับเปิดเกม (optional, จะมีเมื่อ type = "url" หรือ "redirect")
- `html`: HTML code สำหรับเปิดเกม (optional, จะมีเมื่อ type = "html")
- `type`: ประเภทของ response ("url", "html" หรือ "redirect")

##### ตัวอย่างโค้ด:

```bash
curl -X POST https://api.neoapihub.com/api/external/init-session \
  -H "Authorization: YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gameId": "string",
    "username": "string",
    "hrefBackUrl": "string",
    "agentId": "string",
    "language": "th",
    "isDesktop": true,
    "rtp": 97,
    "clientIp": "203.0.113.42"
  }'
```

การจัดการ Response:

- เมื่อยิง request `/api/external/init-session` มา จะได้ response กลับไปโดยเราจะต้องดูจาก `type` ก่อนว่าเป็น `url` หรือ `html`
- ถ้าเป็น **URL** (type = "url") หรือ **REDIRECT** (type = "redirect") ให้ใช้ `url` ที่ได้รับมาเพื่อเปิดหน้าเข้าเล่นเกมให้กับผู้เล่นใน Tab ใหม่ (โดยเฉพาะ type = "redirect" เช่น HuayDragon ที่ไม่รองรับ iframe — ต้องเปิดใน Tab ใหม่เท่านั้น ห้ามฝังใน iframe)
- ถ้าเป็น **HTML** (type = "html") ต้องเขียนให้เว็บปรับ HTML จาก `html` เพื่อเปิดให้ผู้เล่น

### 5. การเช็คเครดิตของ Subagent

เป็น Endpoint สำหรับตรวจสอบภาพรวมเครดิตของหัวสาย และดูรายละเอียดเครดิตของ Subagent ภายใต้สายทั้งหมดในครั้งเดียว เหมาะสำหรับใช้ทำหน้า Dashboard หรือหน้า Monitoring เครดิต

Request:

```json
POST /api/external/get-sub-agent-quota-summary
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string"
}
```

##### คำอธิบาย Request Body:

- `agentId` (required): Agent ID ของหัวสายที่ต้องการตรวจสอบเครดิต

Response:

```json
{
  "winningQuota": 100000,
  "winningQuotaUsed": 25000,
  "subagents": [
    {
      "username": "subagent01",
      "winningQuota": 30000,
      "winningQuotaUsed": 5000
    }
  ]
}
```

##### คำอธิบาย Response:

- `winningQuota` : เครดิตทั้งหมดของหัวสาย
- `winningQuotaUsed` : เครดิตที่ใช้งานไปแล้วของหัวสาย
- `subagents`: รายการเครดิตของ Subagent ภายใต้สาย

### 5.1 ดูค่าคอมและส่วนแบ่งของแต่ละค่าย (Subagent Providers)

เป็น Endpoint สำหรับดูรายการ Provider ของหัวสายและ Subagent โดยตรง (ชั้นเดียว) พร้อมเปอร์เซ็นต์ส่วนแบ่งบริษัท (Company Rate) และค่าคอมมิชชั่น (Commission Rate) ของแต่ละค่าย เหมาะสำหรับใช้ตรวจสอบและเปรียบเทียบส่วนแบ่งของแต่ละสาย

Request:

```json
POST /api/external/get-sub-agent-providers
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string"
}
```

##### คำอธิบาย Request Body:

- `agentId` (required): Agent ID ของหัวสายที่ต้องการดูรายการ Provider

Response:

```json
{
  "agentId": "agent-001",
  "username": "headagent",
  "providers": [
    {
      "providerId": "provider-uuid",
      "providerName": "PG",
      "providerFullName": "PG Soft",
      "isActive": true,
      "commissionRate": 5.00,
      "companyRate": 70.00,
      "canSetRtp": true,
      "canSetPreset": false,
      "gameTypes": ["slot"],
      "rtpMode": "rtp",
      "rtp": 96,
      "presetId": null
    }
  ],
  "subagents": [
    {
      "agentId": "subagent-uuid",
      "username": "subagent01",
      "providers": [
        {
          "providerId": "provider-uuid",
          "providerName": "PG",
          "providerFullName": "PG Soft",
          "isActive": true,
          "commissionRate": 3.00,
          "companyRate": 60.00,
          "canSetRtp": true,
          "canSetPreset": true,
          "gameTypes": ["slot"],
          "rtpMode": "preset",
          "rtp": null,
          "presetId": "preset-uuid"
        }
      ]
    }
  ]
}
```

##### คำอธิบาย Response:

- `agentId`: Agent ID ของหัวสายที่เรียก
- `username`: Username ของหัวสายที่เรียก
- `providers`: รายการ Provider ของหัวสายเอง พร้อม Company Rate และ Commission Rate
- `subagents`: รายการ Subagent ภายใต้สาย (ชั้นเดียว) แต่ละ Subagent มีรายการ Provider ของตนเอง
- `providerId` / `providerName` : ID และชื่อค่ายเกม
- `isActive`: สถานะการเปิดใช้งานของค่ายนั้นกับสายนี้
- `companyRate`: เปอร์เซ็นต์ส่วนแบ่งที่บริษัทถือกับค่ายนี้ (%)
- `commissionRate` : เปอร์เซ็นต์ค่าคอมมิชชั่นของสายนี้กับค่ายนี้ (%)
- `canSetRtp`: ค่ายนี้ตั้ง RTP ได้หรือไม่
- `canSetPreset` : ค่ายนี้ใช้ Preset ได้หรือไม่ ถ้าเป็น false แปลว่าตั้งได้แค่ตัวเลข ให้ซ่อน dropdown Preset สำหรับค่ายพวกนี้
- `gameTypes`: ประเภทเกมที่ค่ายนี้มี ใช้คัดว่าควรโชว์ปุ่มตั้ง RTP หรือไม่ (แนะนำให้โชว์เฉพาะค่ายที่มี slot)
- `rtpMode`: โหมดปัจจุบันของค่ายนี้ — rtp (ตัวเลข) หรือ preset
- `rtp` / `presetId`: ค่าที่ตั้งไว้ อันที่ไม่ได้ใช้จะเป็น null ใช้คู่กับ set-rtp (หัวข้อ 5.2) เพื่อทำหน้าตั้งค่าในระบบของท่านเอง

### 5.2 ตั้งค่า RTP (Set RTP)

เป็น Endpoint สำหรับตั้งค่า RTP ของค่ายเกม ให้กับหัวสายของท่านเองหรือ Subagent ชั้นถัดไป 1 ชั้น ค่าที่ตั้งไว้จะถูกเก็บค้างไว้ ไม่ต้องส่งซ้ำทุกครั้งที่เปิดเกม

ใช้ร่วมกับอีก 2 เส้นแล้วจะได้เท่ากับหน้า “ค่ายเกม” ในระบบหลังบ้านของเรา ทุกอย่าง สำหรับท่านที่ต้องการทำหน้าตั้งค่าเองในระบบของท่าน:

1. `get-sub-agent-providers` — ดึงรายการค่ายพร้อมค่า RTP ปัจจุบันของแต่ละค่าย
2. `get-presets` — ดึงลิสต์ Preset สำหรับทำเป็น dropdown
3. `set-rtp` — บันทึกค่า

แต่ละค่ายจะอยู่ในโหมดใดโหมดหนึ่งเท่านั้น

- **โหมดตัวเลข** — ส่ง `rtp` เป็นจำนวนเต็ม 30-99
- **โหมด Preset** — ส่ง `presetId` ที่ได้จาก get-presets

ส่งได้ทีละอย่าง **ส่งมาทั้งคู่หรือไม่ส่งเลยจะถูกปฏิเสธ** และส่งอันไหนมา อีกอันจะถูกล้างเป็น `null` ให้อัตโนมัติ — สลับโหมดได้ด้วยการส่งฟิลด์ของโหมดที่ต้องการมาเลย ไม่ต้องล้างเอง ดูโหมดปัจจุบันของแต่ละค่ายได้จากฟิลด์ `rtpMode` ใน get-sub-agent-providers

ลำดับการใช้ค่า RTP ตอนเปิดเกม:

1. ถ้า `init-session` ส่ง `rtp` มาด้วย จะใช้ค่านั้นสำหรับ session นั้น (ค่าที่ส่งมาชนะเสมอ)
2. ถ้าไม่ส่ง จะใช้ค่าที่ตั้งไว้ผ่าน `set-rtp`
3. ถ้ายังไม่เคยตั้งเลย จะใช้ค่าเริ่มต้นของค่ายนั้น

กล่าวคือ ถ้าระบบของท่านส่ง `rtp` ไปกับ init-session ทุกครั้งอยู่แล้ว ค่าที่ตั้งด้วย set-rtp จะไม่ถูกนำมาใช้

ค่ายที่ canSetPreset เป็น true: ตัวเลขที่ส่ง = ชื่อของ Preset ไม่ใช่ค่า RTP ลอยๆ

ค่ายที่ canSetPreset เป็น true (เช่น PG_plus และ JOKER_plus) ปลายทางรับเฉพาะ Preset เท่านั้น ตัวเลขที่ท่านส่งมาระบบจะเอาไปหา Preset ที่ชื่อตรงกับเลขนั้น แล้วส่ง Preset ตัวนั้นไปให้ค่าย — ตัวเลขไม่เคยถูกส่งออกไปตรงๆ

เพราะงั้นถ้าส่งเลขที่ไม่มี Preset ชื่อนั้นอยู่ เช่นส่ง `93` ทั้งที่มีแต่ Preset ชื่อ 94 กับ 96 จะได้ `RTP_HAS_NO_MATCHING_PRESET` กลับไป พร้อมฟิลด์ `availableRtp` ที่บอกว่าเลขไหนใช้ได้บ้าง เอาไปทำเป็นตัวเลือกในหน้าจอของท่านได้เลย

ส่วนค่ายที่ canSetPreset เป็น false รับเลขดิบจริงๆ ส่ง 30-99 อะไรก็ได้ ไม่ต้องมี Preset รองรับ

ค่ายที่ canSetPreset เป็น true: ตั้ง RTP เป็นตัวเลขจริง + ความผันผวน (โมเดลการจ่าย)

เรียก ensure-model-preset พร้อม RTP ที่ต้องการ (ทศนิยมได้ 2 ตำแหน่ง) ระบบจะคืน Preset หนึ่งตัวสำหรับค่านั้น เรียกซ้ำกี่ครั้งก็ได้ id เดิม แล้วเอา presetId ไปใช้กับ set-rtp หรือ init-session ได้เหมือน Preset ปกติ ทุกเกมจะจ่ายตาม RTP ที่ตั้ง เพราะระบบคำนวณจากตารางจ่ายของแต่ละเกม

- model "mixture" = RTP ที่กำหนด + ความผันผวน low / medium / high
- model "pgx_v2" = RTP จริงของแต่ละเกม (ไม่ต้องส่ง targetRtp หรือ volatility)
- model "rewardflow" = ปรับอัตโนมัติตามผู้เล่น (RewardFlow) ที่ RTP กำหนด ทุกรูปแบบจ่าย RTP เท่ากัน

หรือส่งกับ init-session ได้ตรงๆ (เฉพาะค่ายที่ canSetPreset เป็น true): model + targetRtp + volatility หรือ rewardFlow: true + rtp ห้ามส่งคู่กับ presetId, payoffSetting หรือ pool จะได้ MODEL_LAUNCH_CONFLICT

```json
POST /api/external/ensure-model-preset
Authorization: YOUR_PRIVATE_KEY
{ "agentId": "YOUR_AGENT_ID", "model": "mixture", "targetRtp": 95.5, "volatility": "medium" }

→ { "id": "PRESET_ID", "note": "95.5% ผันผวนกลาง", "rtpNormal": 0.955,
    "model": { "model": "mixture", "targetRtp": 95.5, "volatility": "medium" }, ... }

# per launch (canSetPreset providers only)
POST /api/external/init-session
{ ..., "model": "mixture", "targetRtp": 95.5, "volatility": "high" }
{ ..., "rewardFlow": true, "rtp": 96 }
```

ตั้งได้เฉพาะค่ายที่รองรับเท่านั้น ดูจากฟิลด์ `canSetRtp` ถ้าเป็น `false` จะถูกปฏิเสธด้วย `PROVIDER_CANNOT_SET_RTP` และแนะนำให้ซ่อนปุ่มตั้งค่าสำหรับค่ายที่ไม่มีเกมสล็อต (ดูจาก `gameTypes`) เพราะการปรับ RTP ไม่มีความหมายกับเกมคาสิโนสดหรือกีฬา — หน้าหลังบ้านของเราก็ใช้เกณฑ์นี้

Request:

```json
POST /api/external/set-rtp Content-Type: application/json Authorization: YOUR_PRIVATE_KEY { "agentId": "string", "providerId": "string", "rtp": number, // โหมดตัวเลข: 30-99 (จำนวนเต็ม) "presetId": "string", // โหมด Preset — ส่งอย่างใดอย่างหนึ่งกับ rtp "targetAgentId": "string" // optional }
```

##### คำอธิบาย Request Body:

- `agentId` (required): Agent ID ของหัวสายที่เรียก (เจ้าของ private key)
- `providerId` (required): ID ของค่ายเกมที่ต้องการตั้งค่า ใช้ค่าที่ได้จาก `get-sub-agent-providers` หรือ `get-games`
- `rtp`: ค่า RTP เป็นจำนวนเต็ม 30-99 (ทศนิยมจะถูกปฏิเสธ) ส่งอันนี้ = ตั้งเป็นโหมดตัวเลข และล้าง presetId
- `presetId`: ID ของ Preset จาก `get-presets` ส่งอันนี้ = ตั้งเป็นโหมด Preset และล้าง rtp — ใช้ได้เฉพาะค่ายที่ canSetPreset = true เท่านั้น
- `targetAgentId` (optional): Agent ID ที่ต้องการตั้งค่าให้ ถ้าไม่ส่งจะหมายถึงตัวเอง ใส่ได้เฉพาะตัวเอง หรือ Subagent ชั้นถัดไป 1 ชั้นเท่านั้น (หลานสายจะถูกปฏิเสธ) และค่ายนั้นต้องเป็นค่ายที่ท่านถืออยู่ด้วย

Response:

```json
{
  "agentId": "agent-001",
  "username": "headagent",
  "providerId": "provider-uuid",
  "providerName": "PG_plus",
  "rtpMode": "rtp",
  "rtp": 96,
  "presetId": null,
  "previousRtp": 90,
  "previousPresetId": null
}
```

##### คำอธิบาย Response:

- `agentId` / `username`: สายที่ถูกตั้งค่าจริง (ตัวเอง หรือ Subagent ที่ระบุใน targetAgentId)
- `rtpMode`: โหมดของค่ายนี้หลังบันทึก เป็น `rtp` หรือ `preset`
- `rtp` / `presetId`: ค่าที่มีผลอยู่ตอนนี้ อันที่ไม่ได้ใช้จะเป็น `null`
- `previousRtp` / `previousPresetId` : ค่าเดิมก่อนหน้านี้ ใช้ยืนยันว่าเปลี่ยนจากอะไรเป็นอะไร (ถ้าเดิมเป็นโหมด Preset แล้วส่ง rtp มา จะเห็น previousPresetId มีค่า และ presetId เป็น null)

##### Error ที่เป็นไปได้:

- `RTP_OR_PRESET_ID_REQUIRED` (400): ไม่ได้ส่ง rtp และ presetId เลย หรือส่งมาทั้งคู่
- `RTP_MUST_BE_BETWEEN_30_AND_99` (400): rtp ไม่ใช่จำนวนเต็มในช่วง 30-99
- `RTP_HAS_NO_MATCHING_PRESET` (400): ค่ายที่ canSetPreset เป็น true และไม่มี Preset ตัวไหนชื่อตรงกับเลขที่ส่งมา — ดูเลขที่ใช้ได้จริงจากฟิลด์ availableRtp ที่ติดมากับ error
- `PROVIDER_OPERATOR_NOT_CONFIGURED` (400): ค่ายที่ canSetPreset เป็น true ที่สายนี้ยังไม่ได้ผูก operator ไว้ ตั้งเป็นตัวเลขไม่ได้ (ใช้ Preset แทนได้) ติดต่อทีมงานถ้าเจอ
- `PROVIDER_CANNOT_SET_RTP` (400): ค่ายนี้ไม่รองรับการตั้ง RTP (canSetRtp = false)
- `PROVIDER_CANNOT_SET_PRESET` (400): ค่ายนี้ตั้งได้เฉพาะตัวเลข ใช้ Preset ไม่ได้ (canSetPreset = false)
- `INVALID_PRIVATE_KEY` (401): private key ไม่ตรงกับ agentId
- `AGENT_DO_NOT_HAVE_PERMISSION` (403): targetAgentId ไม่ใช่ตัวเองและไม่ใช่ Subagent ชั้นถัดไป หรือท่านไม่ได้ถือค่ายนี้อยู่
- `AGENT_PROVIDER_NOT_FOUND` (404): สายที่ระบุไม่มีค่ายนี้เปิดอยู่
- `PRESET_NOT_FOUND` (404): presetId ที่ส่งมาไม่มีอยู่ในลิสต์ Preset ของท่าน

##### ตัวอย่างโค้ด:

```bash
# โหมดตัวเลข — ตั้ง RTP 96 ให้ค่ายหนึ่งของหัวสายตัวเอง curl -X POST https://api.neoapihub.com/api/external/set-rtp \ -H "Authorization: YOUR_PRIVATE_KEY" \ -H "Content-Type: application/json" \ -d '{ "agentId": "YOUR_AGENT_ID", "providerId": "PROVIDER_ID", "rtp": 96 }' # โหมด Preset — ใช้ presetId จาก get-presets (rtp จะถูกล้างให้อัตโนมัติ) curl -X POST https://api.neoapihub.com/api/external/set-rtp \ -H "Authorization: YOUR_PRIVATE_KEY" \ -H "Content-Type: application/json" \ -d '{ "agentId": "YOUR_AGENT_ID", "providerId": "PROVIDER_ID", "presetId": "PRESET_ID" }' # ตั้งให้ Subagent ชั้นถัดไป curl -X POST https://api.neoapihub.com/api/external/set-rtp \ -H "Authorization: YOUR_PRIVATE_KEY" \ -H "Content-Type: application/json" \ -d '{ "agentId": "YOUR_AGENT_ID", "providerId": "PROVIDER_ID", "targetAgentId": "SUBAGENT_ID", "rtp": 92 }'
```

### 6. ดูประวัติแทงหวยของผู้เล่น

เป็น Endpoint สำหรับดึงประวัติการแทงหวยของผู้เล่นรายคน โดยสามารถกำหนด Pagination และกรองตามสถานะรายการได้ เหมาะสำหรับทำหน้าประวัติย้อนหลังหรือ ตรวจสอบรายการชนะ/แพ้ของผู้เล่น

Request:

```json
POST /api/external/get-poy-group-history-by-user
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string",
  "userId": "string",
  "poyGroupStatusList": ["WIN", "LOSE"], // optional
  "skip": 0, // optional (default: 0)
  "take": 10 // optional (default: 10)
}
```

##### คำอธิบาย Request Body:

- `agentId` (required): Agent ID ของสายที่เป็นเจ้าของผู้เล่น
- `userId` (required): Username ของผู้เล่นฝั่ง Agent
- `poyGroupStatusList` (optional): กรองตามสถานะรายการ เช่น `WIN`, `LOSE`, `SETTLED`, `PENDING`, `FAILED`, `CANCELLED`, `REFUND`
- `skip` (optional): จำนวนรายการที่ข้าม
- `take` (optional): จำนวนรายการที่ต้องการต่อหน้า

##### ความหมายของสถานะ (PoyGroupStatus):

- `PENDING`: รับบิลแล้ว รอประมวลผล
- `SETTLED`: จ่ายเงินสำเร็จ
- `FAILED`: จ่ายเงินไม่สำเร็จ
- `WIN`: ปิดรอบแล้วผลเป็นชนะ
- `LOSE`: ปิดรอบแล้วผลเป็นแพ้
- `CANCELLED`: รายการถูกยกเลิก
- `REFUND`: ยกเลิกสำเร็จและคืนเงินสำเร็จ (callback cancel สำเร็จ)

Response:

```json
{ "total": 120, "take": 10, "skip": 0, "data": [ { "id": "string", "roundStartDate": "2026-03-12T08:00:00.000Z", "roundEndDate": "2026-03-12T09:00:00.000Z", "gameName": "หวยไทยรัฐบาล", "gameCode": "THAI_GOV", "totalAmount": 1000, "totalPayoff": 1500, "userId": "player123", "status": "WIN", "createdAt": "2026-03-12T08:10:00.000Z", "updatedAt": "2026-03-12T09:05:00.000Z", "poys": [ { "id": "string", "userId": "player123", "multiple": 1, "poyType": "THREE_UP", "poyNumber": "123", "amount": 100, "payoff": 900, "rate": 9, "status": "SUCCESS", "createdAt": "2026-03-12T08:11:00.000Z", "updatedAt": "2026-03-12T09:05:00.000Z", "subPoys": [ { "id": "string", "poyType": "TWO_UP", "poyNumber": "12", "amount": 50, "payoff": 0, "multiplier": 1, "status": "FAILED", "createdAt": "2026-03-12T08:11:00.000Z", "updatedAt": "2026-03-12T09:05:00.000Z" } ] } ] } ] }
```

##### คำอธิบาย Response:

###### ระดับ root ( `GetPoyGroupHistoryByUserResponse` )

- `data`: รายการชุดบิล ( `PoyGroupHistoryItem[]` ) ของ user ตาม filter และ pagination
- `total`: จำนวนชุดบิลทั้งหมดที่ตรงเงื่อนไข (ก่อน skip/take)
- `skip`: จำนวนที่ข้าม (offset ของ pagination)
- `take`: จำนวนที่ขอต่อหน้า (limit ของ pagination)

###### ระดับชุดบิล ( `PoyGroupHistoryItem` )

- `id`: รหัสธุรกรรมของชุดบิล (ใช้สำหรับอ้างอิง/ยืนยันกับ operator)
- `roundStartDate` : วันเวลาเริ่มรอบ
- `roundEndDate` : วันเวลาปิดรอบ
- `gameName`: ชื่อเกม (บางประเภทอาจต่อท้ายด้วย " ชุด")
- `gameCode`: รหัสเกม
- `totalAmount`: ยอดรวมที่ user เดิมพันในชุดบิลนี้
- `totalPayoff`: ยอดรวมที่จ่าย/คืนให้ user ในชุดบิลนี้
- `userId`: รหัส user ที่เดิมพัน
- `status`: สถานะชุดบิล (เช่น `PENDING`, `SETTLED`, `WIN`, `LOSE`, `FAILED`, `CANCELLED`, `REFUND`)
- `createdAt`: วันเวลาที่สร้างชุดบิล
- `updatedAt`: วันเวลาที่อัปเดตล่าสุด
- `poys`: รายการบิลย่อย ( `PoyHistoryItem[]` ) ในชุดบิลนี้

###### ระดับบิล ( `PoyHistoryItem` )

- `id`: รหัสบิลย่อย
- `userId`: รหัส user
- `multiple`: ตัวคูณ (จำนวนเท่าของเงินเดิมพันต่อชุด)
- `poyType`: ประเภทเลข/รูปแบบ (เช่น TWO_UP, THREE_DOWN, SET_FOUR)
- `poyNumber`: เลขที่แทง (string)
- `amount`: เงินเดิมพันของบิลนี้
- `payoff`: เงินที่จ่าย/คืนของบิลนี้
- `rate`: อัตราที่ใช้คำนวณ
- `status`: สถานะบิลย่อย
- `createdAt`: วันเวลาที่สร้างบิล
- `updatedAt`: วันเวลาที่อัปเดตล่าสุด
- `subPoys`: บิลย่อยระดับล่าง (มีในบางกรณี เช่น เกมแบบชุด)

###### ระดับ subPoy ( `SubPoyHistoryItem` )

- `id`: รหัส SubPoy
- `poyType`: ประเภทเลขของชุดย่อย
- `poyNumber`: เลขที่แทงของชุดย่อย
- `amount`: จำนวนเงินที่อ้างถึงของชุดย่อย
- `payoff`: เงินที่จ่ายของชุดย่อย
- `multiplier`: ตัวคูณรางวัลของชุดย่อย
- `status`: สถานะของชุดย่อย
- `createdAt`: วันเวลาที่สร้าง
- `updatedAt`: วันเวลาที่อัปเดตล่าสุด

สรุปโครงสร้าง:

Response = รายการชุดบิล (

data

) + pagination (

total

,

skip

,

take

) และในแต่ละชุดบิลจะมี

poys

โดยบางประเภทจะมี

subPoys

อีกชั้น

### 7. ดึงประวัติธุรกรรมรายผู้เล่น

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

Request:

```json
POST /api/external/get-transaction-by-username
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string",
  "username": "player123", // optional
  "startDate": "2026-06-01T00:00:00.000Z", // optional
  "endDate": "2026-06-19T23:59:59.999Z", // optional
  "skip": 0, // optional (default: 0)
  "take": 10 // optional (default: 10)
}
```

##### คำอธิบาย Request Body:

- `agentId` (required): Agent ID ของคุณ (เจ้าของ private key)
- `username` (optional): ชื่อผู้เล่นฝั่ง Agent — ถ้าไม่ส่ง จะดึงรายการของทุกผู้เล่นในสายของคุณ
- `startDate` (optional): เวลาเริ่มต้น (ISO 8601)
- `endDate` (optional): เวลาสิ้นสุด (ISO 8601)
- `skip` (optional): จำนวนรายการที่ข้าม (default: 0)
- `take` (optional): จำนวนรายการที่ต้องการต่อหน้า (default: 10)

หมายเหตุ:

ทุกรายการถูกจำกัดเฉพาะผู้เล่นภายใต้ Agent ของคุณเท่านั้น (scoped ด้วย private key) — ไม่สามารถดูข้อมูลของ Agent อื่นได้แม้จะระบุ username ที่ตรงกัน

Response:

```json
{
  "total": 2,
  "take": 10,
  "skip": 0,
  "data": [
    {
      "id": "string",
      "providerTransactionId": "string",
      "usernamePlayer": "player123",
      "betAmount": 100,
      "settleAmount": 0,
      "turnOver": 100,
      "transferIn": 0,
      "transferOut": 100,
      "gameType": "SLOT",
      "status": "SUCCESS",
      "gameId": "string",
      "agentId": "string",
      "createdAt": "2026-06-19T08:10:00.000Z",
      "updatedAt": "2026-06-19T08:10:05.000Z",
      "isBuyFeature": true,
      "isFreeSpin": false,
      "game": {
        "id": "string",
        "name": "Fortune Gems",
        "code": "JILI_FG",
        "providerId": "string",
        "providerName": "JILI_plus"
      }
    }
  ]
}
```

##### คำอธิบาย Response:

- `data` รายการธุรกรรมของผู้เล่นตาม filter และ pagination
- `total` จำนวนรายการในหน้านี้
- `skip` / `take`: ค่า pagination ที่ส่งมา (offset / limit)
- `betAmount` ยอดเดิมพัน
- `settleAmount` ยอดที่จ่ายคืน (ผลได้เสีย)
- `turnOver` ยอด Turnover ของรายการ
- `isBuyFeature` : เป็น `true` เมื่อรายการนั้นผู้เล่นกดซื้อฟีเจอร์ (Buy Feature)
- `isFreeSpin`: เป็น `true` เมื่อรายการนั้นเป็นการหมุนที่ผู้เล่นไม่ได้จ่ายเงินเพิ่ม — ครอบคลุมทั้ง Free Spin ในเกม, Re-spin และรอบที่ต่อเนื่องมาจากการเดิมพันครั้งก่อน ซึ่งเป็นเหตุผลที่รายการเหล่านี้มักมี `betAmount` เป็น 0 แต่มียอดจ่ายออก
- **ทั้งสองฟิลด์เป็น null เมื่อค่ายนั้นไม่ได้ส่งข้อมูลนี้มาให้** — ซึ่งไม่ได้แปลว่าผู้เล่นไม่ได้ซื้อฟีเจอร์หรือไม่ใช่ free spin แต่แปลว่าค่ายนั้นไม่ได้บอกเรามา จึงไม่ควรนับ `null` เป็น `false` ตอนทำรายงาน · ดูรายชื่อค่ายที่ส่งและไม่ส่งได้ที่ตารางด้านล่าง
- `status`: สถานะรายการ ( `PENDING`, `SUCCESS`, `FAILED`)
- `game`: ข้อมูลเกม เช่น `name`, `code`, `providerName` (ชื่อค่ายเกม)

isBuyFeature กับ isFreeSpin ต่างกันยังไง

`isBuyFeature` = รอบนี้มาจากฟีเจอร์ที่ผู้เล่นจ่ายเงินก้อนซื้อเข้ามาเลย ไม่ได้รอหมุนให้ติดเอง ราคาซื้อมักอยู่ราว 100 เท่าของเงินเดิมพันปกติ รอบที่จ่ายเงินซื้อจึงมี betAmount สูงผิดปกติเมื่อเทียบกับรอบอื่นของผู้เล่นคนเดียวกัน

`isFreeSpin` = รอบที่ผู้เล่นไม่ได้จ่ายเงินเพิ่ม เป็นผลต่อเนื่องมาจากรอบก่อนหน้า ครอบคลุมทั้ง Free Spin ในเกม, Re-spin และรอบที่ต่อเนื่องกัน รอบแบบนี้จึงมักมี betAmount เป็น 0 แต่มียอดจ่ายออก

ทั้งสองอย่างมักมาคู่กัน — ผู้เล่นซื้อฟีเจอร์หนึ่งรอบ (isBuyFeature) แล้วได้รอบฟรีตามมาอีกหลายรอบ (isFreeSpin) เวลาคิด turnover หรือยอดเดิมพันจริง ให้ระวังอย่านับรอบฟรีเป็นเงินที่ผู้เล่นจ่ายเพิ่ม

บางค่าย (เช่น PG และ AMB) ติด isBuyFeature ให้รอบฟรีที่ตามมาจากการซื้อด้วย รอบพวกนั้นจึงเป็น true ทั้งสองฟิลด์และมี betAmount เป็น 0 — ถ้าจะนับจำนวนครั้งที่ผู้เล่นซื้อฟีเจอร์ ให้นับเฉพาะรอบที่ isBuyFeature เป็น true แต่ isFreeSpin ไม่ใช่ true ไม่งั้นตัวเลขของ PG จะสูงเกินจริงราว 20 เท่า

⚠️ null ไม่ได้แปลว่า "ไม่ได้ซื้อ" หรือ "ไม่ใช่ free spin"

- null แปลว่าค่ายนั้นไม่ได้ส่งข้อมูลนี้มาให้เรา — เราจึงไม่รู้ว่ารอบนั้นผู้เล่นซื้อฟีเจอร์หรือเป็น free spin หรือเปล่า มีแต่ false เท่านั้นที่แปลว่าค่ายบอกมาว่า "ไม่ใช่"
- ใน callback เราส่ง field มาให้เฉพาะตอนเป็น true — ถ้าไม่มี field มา ให้ดูตารางด้านล่าง: ค่ายที่เป็น ✅ แปลว่าไม่ใช่ ส่วนค่ายที่เป็น ⚠️ หรือ ❌ แปลว่าไม่รู้
- อย่านับ null เป็น false ตอนทำรายงาน ไม่งั้นตัวเลขจะออกมาว่าแทบไม่มีใครซื้อฟีเจอร์เลย ซึ่งไม่ตรงกับความจริง

ค่ายไหนมี isBuyFeature / isFreeSpin บ้าง

| ค่าย | `isBuyFeature` | `isFreeSpin` |
| --- | --- | --- |
| PG_plus, JILI_plus, JOKER_plus, NOLIMITCITY_plus, EVOPLAY_plus, FACHAI_plus | ✅ | ✅ |
| NEXTSPIN_plusค่ายใหม่ (ต.ค. 2026) ยังรอยืนยันจากรายการจริง | ⚠️ | ⚠️ |
| PG | ✅ | ✅ |
| AMB | ✅ | ✅ |
| 759GAMING, AFB1188_SLOT, AMBGAMING | ✅ | ✅ |
| JILI | ✅ | ❌ |
| PP | ✅ | ❌ |
| OCTOPLAYส่งมาเฉพาะรอบที่ซื้อฟีเจอร์ | ⚠️ | ❌ |
| CLOTPLAYส่งมาประมาณครึ่งหนึ่งของรายการ | ⚠️ | ❌ |
| BOOMING, YGR, I8 | ❌ | ✅ |
| JOKERส่งมาเฉพาะรอบที่ได้โบนัส | ❌ | ⚠️ |
| NEXTSPINส่งมาเฉพาะรอบที่เป็น free spin | ❌ | ⚠️ |
| BIGPOT, HOTDOG, FUNKYส่งมาประมาณครึ่งหนึ่งของรายการ | ❌ | ⚠️ |
| SA_plus, SEXY_plusคาสิโนสด ไม่มีฟีเจอร์นี้อยู่แล้ว | false เสมอ | false เสมอ |

✅ ส่งมาทุกรายการ · ⚠️ ส่งมาบางรายการ ถ้าไม่มีให้ถือว่าไม่รู้ ไม่ใช่ false · ❌ ไม่ส่ง เป็น null เสมอ

ค่ายอื่นทั้งหมดไม่มีทั้งสองอย่าง — เป็น null เสมอ

- ค่าย _plus ตัวอื่นทั้งหมดที่ไม่อยู่ในตาราง เช่น PRAGMATIC_plus, CQ9_plus, HABANERO_plus, HACKSAW_plus, JDB_plus, KA_plus, PLAYSON_plus, SPRIBE_plus, TADA_plus, 3OAKS_plus — กลุ่มนี้วิ่งอยู่คนละระบบกับ _plus ในตาราง แม้ชื่อจะลงท้ายด้วย _plus เหมือนกัน
- PNG, HAB, RLX, NE, RTG, WAZ, YGG, PRG, NLC, EVP และ FCG
- ค่ายสล็อตอื่น เช่น ROYAL, LIVE22, SLOTXO, RICH88, PRETTY, SPADE, KINGMAKER
- คาสิโนสด กีฬา และหวย (SA, SEXY, DG, WM, SBO, BTI, UFAPLUS, HIPPO, HUAYDRAGON, LEKTHONG) — ไม่มีคอนเซปต์ free spin / buy feature ตั้งแต่ต้น

**ชื่อค่ายซ้ำกันได้** — JILI_plus กับ JILI, PG_plus กับ PG, NOLIMITCITY_plus กับ NLC, EVOPLAY_plus กับ EVP, NEXTSPIN_plus กับ NEXTSPIN เป็นคนละค่ายคนละระบบ และรองรับฟิลด์นี้ไม่เหมือนกัน เวลาทำรายงานให้ยึด providerId ไม่ใช่ชื่อค่าย

### 8. ดึงลิงก์ประวัติรายตา

เป็น Endpoint สำหรับขอลิงก์หน้าประวัติของการเดิมพัน "หนึ่งตา" เพื่อให้เปิดดูย้อนหลังได้ว่า ตานั้นเกิดอะไรขึ้น เช่น หน้า replay ของสล็อต ผลไพ่ของคาสิโนสด หรือสลิปการแทงของกีฬา — ส่ง id ของรายการที่ได้จากข้อ 7 เข้ามา ระบบจะคืนลิงก์ที่เปิดดูได้ทันที เหมาะสำหรับทำปุ่ม "ดูผลย้อนหลัง" ในหน้าประวัติของผู้เล่น หรือใช้ตรวจสอบเมื่อผู้เล่นทักมาสอบถาม **ดูย้อนหลังได้ภายใน 7 วันนับจากเวลาที่เดิมพัน** เกินจากนั้นค่ายไม่เก็บข้อมูลไว้ให้แล้ว

Request:

```json
POST /api/external/get-bet-detail-url
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string",
  "transactionId": "string", // optional
  "providerTransactionId": "string", // optional
  "lang": "th" // optional (default: en)
}
```

##### คำอธิบาย Request Body:

- `agentId` (required): Agent ID ของคุณ (เจ้าของ private key)
- `transactionId` (optional): id ของรายการฝั่งเรา — คือค่า `id` ที่ได้จากข้อ 7
- `providerTransactionId` (optional): id ของรายการฝั่งค่ายเกม — คือค่า `providerTransactionId` ที่ได้จากข้อ 7 (id เดียวกับที่เห็นในหลังบ้านของค่าย)
- `lang` (optional): ภาษาของหน้าประวัติ รองรับ `th` และ `en` (default: `en`) — ค่ายที่ไม่รองรับการเลือกภาษาจะใช้ค่าตั้งต้นของค่ายเอง

หมายเหตุ:

ต้องส่ง

transactionId

หรือ

providerTransactionId

อย่างน้อยหนึ่งตัว (ถ้าส่งมาทั้งคู่ ระบบจะใช้

transactionId

ก่อน)

Response:

```json
{
  "provider": "BTI",
  "type": "url",
  "url": "https://api.neoapihub.com/api/external/bet-detail-view?t=eyJhbGciOi...",
  "expiresInSeconds": 900
}
```

##### คำอธิบาย Response:

- `provider` ค่ายเกมที่รายการนี้เกิดขึ้น
- `type`: ปัจจุบันเป็น `url` เสมอ ไม่ว่าปลายทางจะเป็นหน้าของค่ายเองหรือหน้าที่เราเตรียมไว้ให้ — ฝั่งคุณเปิดลิงก์ได้เลยโดยไม่ต้องแยกเคส
- `url` ลิงก์หน้าประวัติของตานั้น เปิดได้โดยไม่ต้องแนบ header ใด ๆ ส่งต่อให้ผู้เล่นเปิดดูได้ทันที — ส่วนใหญ่เป็นหน้าของค่ายเอง (อยู่บนโดเมนของค่าย) ค่ายที่ไม่มีหน้าให้ เราจะประกอบหน้าสรุปขึ้นมา แล้วคืนเป็นลิงก์บนโดเมนของเราแทน
- `expiresInSeconds` อายุของลิงก์เป็นวินาที — มีมาเฉพาะลิงก์ที่เราประกอบหน้าให้เอง คือ `900` (15 นาที) ส่วนลิงก์ที่เป็นหน้าของค่ายจะไม่มีฟิลด์นี้ ให้ยึดตามกติกาของค่ายนั้น — ทั้งสองแบบขอลิงก์ใหม่ด้วย id เดิมได้ตลอด ไม่ต้องเก็บลิงก์เก่าไว้ใช้ซ้ำ

##### Error ที่อาจได้รับ:

- `BET_DETAIL_ID_REQUIRED` (400): ไม่ได้ส่ง id มาสักตัว
- `TRANSACTION_NOT_FOUND` (404): ไม่พบรายการนี้
- `BET_DETAIL_TOO_OLD` (410): รายการเก่าเกินกว่าที่ค่ายเก็บไว้ (ตอบ `retentionDays` และ `roundAgeDays` มาด้วย)
- `BET_DETAIL_NOT_SUPPORTED` (400): ค่ายนี้ไม่มีหน้าประวัติรายตาให้ (ตอบ `reason` เป็นคำชี้แจงของค่ายมาด้วย)
- `BET_DETAIL_UNAVAILABLE` (503): ค่ายตอบไม่ได้ในขณะนั้น ลองใหม่อีกครั้งได้

**ข้อจำกัดที่ควรทราบ:**

- **ย้อนหลังได้ 7 วัน** — เป็นระยะเวลาที่เรารองรับตามค่ายที่เก็บข้อมูลสั้นที่สุด รายการที่เก่ากว่านั้นจะได้ `BET_DETAIL_TOO_OLD` (บางค่ายเก็บนานกว่านี้ แต่ไม่ควรออกแบบระบบโดยพึ่งพา)
- **ลิงก์มีอายุจำกัด** ตามค่า `expiresInSeconds` — ควรขอลิงก์ตอนที่ผู้เล่นกดดู ไม่ควรขอล่วงหน้าแล้วเก็บไว้
- **ตาที่ยังไม่เคลียร์ผล** จะได้หน้าสรุปที่มีสถานะ `IN_PLAY` พร้อมยอดเดิมพันแทนหน้าประวัติเต็ม เพราะรายงานฝั่งค่ายจะเขียนเมื่อจบรอบ — เรียกใหม่อีกครั้งหลังรายการ settle
- ค่ายส่วนใหญ่จำกัดความถี่ในการเรียก ไม่ควรยิงรัวเพื่อดึงหลายตาพร้อมกัน ให้เรียกตามที่ผู้เล่นกดดูจริง
- ลิงก์เปิดได้โดยไม่ต้องยืนยันตัวตน — ส่งให้ผู้เล่นเจ้าของรายการได้ แต่ไม่ควรนำไปวางในที่สาธารณะ เพราะเปิดดูตาของผู้เล่นคนนั้นได้จนกว่าจะหมดอายุ

### 9. จัดการสายงาน (Downline API)

ชุด Endpoint สำหรับดึงกระดานแพ้ชนะของลูกสาย และจัดการลูกสายจากระบบของท่านเอง โดยไม่ต้องเข้าหน้าเว็บ เหมาะกับผู้ที่ทำเว็บแบบสายงานและต้องการให้ลูกสาย ดูยอดของตัวเองภายในเว็บของท่าน

กติกาที่ใช้กับทุกเส้นในหมวดนี้

- `agentId` ต้องเป็น Agent ID ของท่านเอง (ตรงกับ Private Key ที่แนบมา) ใส่ของคนอื่นจะได้ `401`
- **เส้นอ่าน** ดูได้ทั้งสายงาน (ลูก หลาน เหลน) ผ่าน `targetAgentId` ไม่ใส่ = ของตัวเอง
- **เส้นเขียนทำได้เฉพาะลูกสายชั้นถัดไป** ยิงใส่หลานจะได้ `403` ให้หัวสายโดยตรงของเขาเป็นคนทำ
- ส่ง field ที่ตั้งไม่ได้ (เช่น `canBuyQuota` , `hierarchyLevelLimit` , `privateKey` , `password` ) จะได้ `400 FIELD_NOT_ALLOWED` พร้อมบอกชื่อ field ที่ไม่ผ่าน

#### 9.1 กระดานแพ้ชนะรายลูกสาย

สรุปยอดรายลูกสาย ตรงกับแท็บ "แบ่งตามลูกสาย" ในหน้าเว็บ รวมยอดที่เก็บได้จากลูกสาย

```json
POST /api/external/get-downline-summary
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string",
  "targetAgentId": "string (optional)",
  "startDate": "2026-09-01T00:00:00Z",
  "endDate": "2026-09-20T23:59:59Z",
  "searchString": "optional",
  "skip": 0,
  "take": 50
}
```

Response:

```json
{
  "total": 4,
  "data": [
    {
      "subAgent": { "username": "ufa88g", "winningQuota": 30000 },
      "summary": { "totalBetAmount": 924.5, "totalWinLose": -308.29 }
    }
  ]
}
```

#### 9.2 กระดานแยกตามค่ายเกม

สรุปยอดแยกรายค่าย ตรงกับแท็บ "แบ่งตามค่ายเกม" รวมยอดที่ต้องจ่ายขึ้นและยอดเทิร์น

```json
POST /api/external/get-downline-provider-summary
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string",
  "targetAgentId": "string (optional)",
  "startDate": "2026-09-01T00:00:00Z",
  "endDate": "2026-09-20T23:59:59Z",
  "providerId": "optional",
  "skip": 0,
  "take": 50
}
```

Response:

```json
{
  "summaryByProvider": [
    {
      "providerName": "PG_plus",
      "allTotalBetAmount": 323,
      "allTotalCompany": 16.11
    }
  ]
}
```

#### 9.3 รายชื่อลูกสาย

ดึงรายชื่อลูกสายพร้อมเครดิตคงเหลือ สำหรับทำหน้ารายการในระบบของท่าน

```json
POST /api/external/get-sub-agents
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string",
  "targetAgentId": "string (optional)",
  "searchString": "optional",
  "skip": 0,
  "take": 50
}
```

Response:

```json
{
  "total": 62,
  "data": [
    {
      "id": "uuid",
      "username": "subagent01",
      "isActive": true,
      "winningQuota": 30000,
      "winningQuotaUsed": 5000,
      "currentHierarchyLevel": 2
    }
  ]
}
```

หมายเหตุ: รายการนี้ **ไม่คืน Private Key ของลูกสาย** Private Key จะคืนให้ครั้งเดียวตอนสร้างลูกสายเท่านั้น

#### 9.4 สร้างลูกสาย

สร้างลูกสายใต้ท่าน เครดิตที่ให้จะถูกหักจากเครดิตคงเหลือของท่าน และระบบคืน Private Key ของลูกสายให้ครั้งเดียว

```json
POST /api/external/create-sub-agent Content-Type: application/json Authorization: YOUR_PRIVATE_KEY { "agentId": "string", "username": "subagent02", "password": "อย่างน้อย 8 ตัวอักษร", "callbackType": "SEAMLESS | TRANSFER", "callbackUrl": "https://... (จำเป็นเมื่อเป็น SEAMLESS)", "winningQuota": 10000, "providerConfigs": [ { "providerId": "uuid", "companyRate": 0.06 } ] }
```

Response:

```json
{ "id": "uuid", "username": "subagent02", "privateKey": "คืนครั้งเดียว เก็บให้ดี", "winningQuota": 10000 }
```

- `companyRate` = (100 − %ถือ) / 100 · ถือเกินของท่านไม่ได้ จะได้ `SUBAGENT_RATE_EXCEEDS_PARENT`
- เครดิตไม่พอ → `NOT_ENOUGH_WINNING_QUOTA`
- ชื่อซ้ำ → `USERNAME_ALREADY_EXISTS` (ยิงซ้ำจึงไม่สร้างซ้ำ)

#### 9.5 แก้ไขลูกสาย

แก้ Callback หรือเปิด/ปิดการใช้งานของลูกสายชั้นถัดไป · เปลี่ยนรหัสผ่านผ่าน API ไม่ได้ ต้องทำในหน้าเว็บ

```json
POST /api/external/update-sub-agent
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string",
  "subAgentId": "uuid",
  "callbackType": "SEAMLESS | TRANSFER",
  "callbackUrl": "https://...",
  "isActive": true
}
```

Response:

```json
{
  "id": "uuid",
  "username": "subagent02",
  "isActive": true
}
```

#### 9.6 ตั้ง % ถือ ให้ลูกสาย

ตั้งส่วนแบ่ง % ถือ ของลูกสายรายค่าย — คนละเรื่องกับ set-rtp ซึ่งเป็นการปรับ RTP ของเกม

```json
POST /api/external/set-sub-agent-rate
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "agentId": "string",
  "subAgentId": "uuid",
  "providerId": "uuid",
  "companyRate": 0.06,
  "commissionRate": 0
}
```

Response:

```json
{
  "id": "uuid",
  "companyRate": 0.06
}
```

- ลูกสายถือเกินท่านไม่ได้ → `SUBAGENT_RATE_EXCEEDS_PARENT`
- ลดจนต่ำกว่าที่ลูกสายของเขาถืออยู่ไม่ได้ → `RATE_BELOW_SUBAGENT_HOLD` ต้องปรับชั้นล่างลงก่อน

#### 9.7 เพิ่มเครดิตให้ลูกสาย

โอนเครดิตจากท่านไปให้ลูกสายชั้นถัดไป ต้องส่ง header Idempotency-Key ทุกครั้ง

```json
POST /api/external/add-sub-agent-quota Content-Type: application/json Authorization: YOUR_PRIVATE_KEY Idempotency-Key: ค่าที่ไม่ซ้ำต่อ 1 รายการ { "agentId": "string", "subAgentId": "uuid", "winningAmount": 1000, "note": "optional" }
```

Response:

```json
{
  "success": true,
  "message": "Quota added successfully",
  "log": { "id": "uuid", "winningAmount": 1000 }
}
```

**Idempotency-Key จำเป็น** — ไม่ส่งจะได้ `400 IDEMPOTENCY_KEY_REQUIRED` ถ้าไม่ได้รับ response (เน็ตหลุด / timeout) ให้ **ยิงซ้ำด้วย Key เดิม** ระบบจะคืนผลของรายการเดิมพร้อม `"replayed": true` และ**ไม่โอนเครดิตซ้ำ** · ถ้าเปลี่ยน Key ระบบจะถือว่าเป็นรายการใหม่และโอนอีกครั้ง

#### 9.8 เรียกคืนเครดิตจากลูกสาย

ดึงเครดิตกลับจากลูกสายชั้นถัดไป ใช้ Idempotency-Key เหมือนกับการเพิ่มเครดิต

```json
POST /api/external/retrieve-sub-agent-quota Content-Type: application/json Authorization: YOUR_PRIVATE_KEY Idempotency-Key: ค่าที่ไม่ซ้ำต่อ 1 รายการ { "agentId": "string", "subAgentId": "uuid", "winningAmount": 1000, "note": "optional" }
```

Response:

```json
{
  "success": true,
  "message": "Quota retrieved successfully",
  "log": { "id": "uuid", "winningAmount": 1000 }
}
```

เรียกคืนเกินกว่าที่ลูกสายเหลืออยู่ไม่ได้

### API เพิ่มเติม

Coming Soon
