# เอกสาร Neo API แบบ Transfer (Two Wallet): create-user, transfer-in, transfer-out

# ภาพรวม

## 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

## Transfer Integration

การเชื่อมต่อแบบ Transfer เป็นระบบที่มี "ผู้เล่น (User)" และ "ยอดเงิน (Balance)" เพื่อให้ลูกค้า/พาร์ทเนอร์สามารถสร้างผู้เล่น เติมเงิน ถอนเงิน เช็คยอด และดูประวัติธุรกรรมได้

**หมายเหตุสำคัญ:**

- `username` ต้องเป็นค่า unique ต่อ agent (ห้ามซ้ำ)
- `amount` / `initialBalance` เป็นตัวเลข และ **ต้องไม่ติดลบ**
- เวลาในระบบใช้รูปแบบ ISO 8601 เช่น 2026-01-04T08:34:02.060Z

### Authentication

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

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

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

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

Authentication Errors:

**Missing Authorization Header / Invalid Private Key**

```json
{
  "error": "UNAUTHORIZED",
  "message": "INVALID_PRIVATE_KEY"
}
```

### 1. สร้างผู้ใช้ (Create User)

สร้างผู้เล่นใหม่ในระบบ พร้อมกำหนดยอดเริ่มต้นได้ (optional)

Request:

```json
POST /api/external-transfer/create-user
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "username": "string",
  "initialBalance": 0
}
```

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

- `username` (required): ชื่อผู้เล่น
- `initialBalance` (optional): ยอดเงินตั้งต้น (ถ้าไม่ส่งมาให้ถือว่า 0)

Response:

```json
{
  "id": "string",
  "username": "string",
  "agentId": "string",
  "balance": 0,
  "createdAt": "2026-01-04T08:34:02.060Z"
}
```

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

```bash
curl -X POST https://api.neoapihub.com/api/external-transfer/create-user \
  -H "Authorization: YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "string",
    "initialBalance": 0
  }'
```

```bash
curl -X POST https://api.neoapihub.com/api/external-transfer/create-user \
  -H "Authorization: YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "string",
    "initialBalance": 0
  }'
```

### 2. เติมเงิน (Transfer In)

เติมเงินให้ผู้เล่น (เพิ่มยอดเงิน)

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

เดิมผู้เล่นมีเงินในระบบ 100 บาท หากต้องการเพิ่มอีก 50 บาท สามารถส่งค่า 50 มา ระบบจะเพิ่มยอดจากเดิม 100 เป็น 150 บาท

Request:

```json
POST /api/external-transfer/transfer-in
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "username": "string",
  "amount": 0
}
```

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

- `username` (required): ชื่อผู้เล่น
- `amount` (required): จำนวนเงินที่ต้องการเติม (ต้องมากกว่า 0)

Response:

```json
{
  "id": "string",
  "agentId": "string",
  "agentUserId": "string",
  "transferAmount": 0,
  "transferType": "IN",
  "balanceBefore": 0,
  "balanceAfter": 0,
  "createdAt": "2026-01-04T08:34:27.438Z"
}
```

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

```bash
curl -X POST https://api.neoapihub.com/api/external-transfer/transfer-in \
  -H "Authorization: YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "string",
    "amount": 0
  }'
```

```bash
curl -X POST https://api.neoapihub.com/api/external-transfer/transfer-in \
  -H "Authorization: YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "string",
    "amount": 0
  }'
```

### 3. ถอนเงิน (Transfer Out)

ถอน/โยกเงินออกจากผู้เล่น (ลดยอดเงิน)

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

เดิมผู้เล่นมีเงินในระบบ 100 บาท หากต้องการโยกเงินออก 50 บาท สามารถส่งค่า 50 มา ระบบจะลดยอดจากเดิม 100 เหลือ 50 บาท

Request:

```json
POST /api/external-transfer/transfer-out
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "username": "string",
  "amount": 0
}
```

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

- `username` (required): ชื่อผู้เล่น
- `amount` (required): จำนวนเงินที่ต้องการถอน (ต้องมากกว่า 0)

Response:

```json
{
  "id": "string",
  "agentId": "string",
  "agentUserId": "string",
  "transferAmount": 0,
  "transferType": "OUT",
  "balanceBefore": 0,
  "balanceAfter": 0,
  "createdAt": "2026-01-04T08:34:27.438Z"
}
```

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

```bash
curl -X POST https://api.neoapihub.com/api/external-transfer/transfer-out \
  -H "Authorization: YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "string",
    "amount": 0
  }'
```

```bash
curl -X POST https://api.neoapihub.com/api/external-transfer/transfer-out \
  -H "Authorization: YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "string",
    "amount": 0
  }'
```

### 4. เช็คยอดเงิน (Get Balance)

ดึงยอดเงินปัจจุบันของผู้เล่น

Request:

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

{
  "username": "string"
}
```

Response:

```json
{
  "username": "string",
  "balance": 0
}
```

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

```bash
curl -X POST https://api.neoapihub.com/api/external-transfer/get-balance \
  -H "Authorization: YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "string"
  }'
```

```bash
curl -X POST https://api.neoapihub.com/api/external-transfer/get-balance \
  -H "Authorization: YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "string"
  }'
```

### 5. ตั้งยอดเงิน (Set Balance)

ตั้งยอดเงินของผู้เล่นเป็นค่าที่ต้องการโดยตรง (แทนการใช้ transfer-in/out) เหมาะสำหรับการ sync ยอดเงินให้ตรงกับระบบภายนอก

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

เดิมผู้เล่นมีเงินในระบบ 100 บาท หากต้องการตั้งยอดเงินในระบบเป็น 150 บาท สามารถส่งค่า 150 มา ระบบจะตั้งยอดเงินผู้เล่นเป็น 150 บาท

Request:

```json
POST /api/external-transfer/set-balance
Content-Type: application/json
Authorization: YOUR_PRIVATE_KEY

{
  "username": "string",
  "amount": 0
}
```

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

- `username` (required): ชื่อผู้เล่น
- `amount` (required): ยอดเงิน "สุดท้าย" ที่ต้องการให้เป็น

Response:

```json
{
  "id": "string",
  "agentId": "string",
  "agentUserId": "string",
  "transferAmount": 0,
  "transferType": "IN",
  "balanceBefore": 0,
  "balanceAfter": 0,
  "createdAt": "2026-01-04T08:34:27.438Z"
}
```

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

```bash
curl -X POST https://api.neoapihub.com/api/external-transfer/set-balance \
  -H "Authorization: YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "string",
    "amount": 0
  }'
```

```bash
curl -X POST https://api.neoapihub.com/api/external-transfer/set-balance \
  -H "Authorization: YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "string",
    "amount": 0
  }'
```

### 6. ดึงประวัติธุรกรรม (Get Transfer History)

ดึงประวัติธุรกรรมเติม/ถอน/ปรับยอด ของผู้เล่นแบบแบ่งหน้า (pagination)

Request:

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

{
  "username": "string",
  "startDate": "2026-01-04T08:36:37.138Z",
  "endDate": "2026-01-04T08:36:37.138Z",
  "page": 1,
  "limit": 20
}
```

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

- `username` (required): ชื่อผู้เล่น
- `startDate` (required): เวลาเริ่มต้น (ISO 8601)
- `endDate` (required): เวลาสิ้นสุด (ISO 8601)
- `page` (required): หน้าเริ่มที่ 1
- `limit` (required): จำนวนรายการต่อหน้า

Response:

```json
{
  "transactions": [
    {
      "id": "string",
      "agentId": "string",
      "agentUserId": "string",
      "transferAmount": 0,
      "transferType": "IN",
      "balanceBefore": 0,
      "balanceAfter": 0,
      "createdAt": "2026-01-04T08:36:37.138Z"
    }
  ],
  "total": 0,
  "page": 0,
  "limit": 0
}
```

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

```bash
curl -X POST https://api.neoapihub.com/api/external-transfer/get-transfer-history \
  -H "Authorization: YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "string",
    "startDate": "2026-01-04T08:36:37.138Z",
    "endDate": "2026-01-04T08:36:37.138Z",
    "page": 1,
    "limit": 20
  }'
```

```bash
curl -X POST https://api.neoapihub.com/api/external-transfer/get-transfer-history \
  -H "Authorization: YOUR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "string",
    "startDate": "2026-01-04T08:36:37.138Z",
    "endDate": "2026-01-04T08:36:37.138Z",
    "page": 1,
    "limit": 20
  }'
```

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

เป็น 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
        }
      ]
    }
  ]
}
```

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

```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"]
  }'
```

### 8. การสร้าง 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` เพื่อเปิดให้ผู้เล่น

### 9. การเช็คเครดิตของ 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 ภายใต้สาย

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

เป็น 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

อีกชั้น

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

เป็น 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 ไม่ใช่ชื่อค่าย

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

เป็น Endpoint สำหรับขอลิงก์หน้าประวัติของการเดิมพัน "หนึ่งตา" เพื่อให้เปิดดูย้อนหลังได้ว่า ตานั้นเกิดอะไรขึ้น เช่น หน้า replay ของสล็อต ผลไพ่ของคาสิโนสด หรือสลิปการแทงของกีฬา — ส่ง id ของรายการที่ได้จากข้อ 11 เข้ามา ระบบจะคืนลิงก์ที่เปิดดูได้ทันที เหมาะสำหรับทำปุ่ม "ดูผลย้อนหลัง" ในหน้าประวัติของผู้เล่น หรือใช้ตรวจสอบเมื่อผู้เล่นทักมาสอบถาม **ดูย้อนหลังได้ภายใน 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` ที่ได้จากข้อ 11
- `providerTransactionId` (optional): id ของรายการฝั่งค่ายเกม — คือค่า `providerTransactionId` ที่ได้จากข้อ 11 (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
- ค่ายส่วนใหญ่จำกัดความถี่ในการเรียก ไม่ควรยิงรัวเพื่อดึงหลายตาพร้อมกัน ให้เรียกตามที่ผู้เล่นกดดูจริง
- ลิงก์เปิดได้โดยไม่ต้องยืนยันตัวตน — ส่งให้ผู้เล่นเจ้าของรายการได้ แต่ไม่ควรนำไปวางในที่สาธารณะ เพราะเปิดดูตาของผู้เล่นคนนั้นได้จนกว่าจะหมดอายุ

### รูปแบบ Error

- `INVALID_PRIVATE_KEY` : แนบ private key ไม่ถูกต้อง
- `USERNAME_ALREADY_EXISTS` : username ซ้ำตอน create-user
- `USERNAME_NOT_FOUND` : ไม่พบผู้เล่น จาก username ที่ส่งมา
- `INSUFFICIENT_BALANCE` : ถอนเงินเกินยอด

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

Coming Soon
