วิธีการผนวกรวม YC365 Dapp

ภาพรวม

บทความนี้อธิบายวิธีที่แพลตฟอร์มของผู้ประกอบการ (Merchant) เชื่อมต่อกับ YC365 Dapp การสื่อสารรองรับ 2 โหมด ได้แก่ โหมดไม่ต้องโอนเงิน (v1) และโหมดโอนเงิน (v2)

• โหมดไม่ต้องโอนเงิน

ผู้ใช้ที่เข้าสู่ Dapp ผ่านแพลตฟอร์มของผู้ประกอบการไม่จำเป็นต้องเติมเงินล่วงหน้า ขณะทำคำสั่งซื้อ ระบบจะตัดยอดเงินจากบัญชีแพลตฟอร์มโดยตรง ฝั่ง Dapp จะสื่อสารแบบเรียลไทม์กับแพลตฟอร์ม

• โหมดโอนเงิน

เมื่อผู้ใช้เข้าสู่ Dapp จะต้องโอนสินทรัพย์บางส่วนจากบัญชีแพลตฟอร์มมายังบัญชี Dapp ฝั่ง Dapp จะทำงานค่อนข้างอิสระจากแพลตฟอร์มและไม่จำเป็นต้องสื่อสารแบบเรียลไทม์

🎯 ฟังก์ชันหลัก

1. ขอรหัสเชิญลงทะเบียน: รับแบบออฟไลน์ผ่านการติดต่อพนักงานธุรกิจของ YC365 หนึ่งรหัสต่อหนึ่งบัญชีสำหรับการลงทะเบียนของผู้ประกอบการ
2. ลงทะเบียนผู้ประกอบการ: API นี้ต้องยื่นคำขอเปิดใช้งานแบบออฟไลน์ ผู้ประกอบการหรือทีม YC365 จะกรอกพารามิเตอร์ที่จำเป็นเพื่อสร้างบัญชี เมื่อลงทะเบียนสำเร็จจะได้รับ app_id, api_key, wallet_address ซึ่งต้องเก็บเป็นความลับ
3. ก่อนลงทะเบียนต้องเตรียมอินเทอร์เฟซที่จำเป็นและตัดสินใจเลือกใช้โหมด v1 หรือ v2 เพราะแต่ละโหมดใช้ API ต่างกัน
4. สามารถจัดเก็บ app_id และ api_key ไว้ในระบบหลังบ้านของผู้ประกอบการ โดย api_key ใช้สำหรับเข้ารหัสการสื่อสารกับฝั่ง Dapp
5. wallet_address คือที่อยู่กระเป๋าเงินของผู้ประกอบการใน Dapp ต้องเติม USDT บนเครือข่าย BSC
6. ขอที่อยู่เข้าใช้งาน Dapp: เมื่อผู้ใช้คลิกลิงก์หรือไอคอนบนหน้าแพลตฟอร์ม ระบบหลังบ้านจะเรียก API นี้พร้อมพารามิเตอร์ที่จำเป็นเพื่อรับ URL ของ Dapp
7. รายละเอียดคำสั่งซื้อ: ผู้ประกอบการสามารถดูรายละเอียดธุรกรรมใน Dapp เพื่อใช้ตรวจสอบยอดกับฝั่งแพลตฟอร์ม
8. รายงานสำหรับผู้ประกอบการ: สามารถดูข้อมูลรายวัน รายสัปดาห์ และรายเดือน
9. การผลักดันข้อมูลสรุปรายวัน: ฝั่ง Dapp จะส่งข้อมูลสรุปของวันก่อนหน้าให้ผู้ประกอบการในเวลา 00:00 น. (UTC)

รูปแบบข้อมูลตัวอย่าง:

{
  "event_type": "merchant_overview", // ประเภทเหตุการณ์ธุรกิจ: การผลักดันข้อมูลสรุปรายวัน
  "data": {
     "app_id":"string",            // รหัสผู้ประกอบการ
     "balance":0.000000,           // ยอด USDT ที่ใช้ได้
     "frozen":0.000000,            // ยอด USDT ที่ถูกระงับ
     "period_date":"string",       // วันแรกของรอบสรุป เช่น 2025-08-01
     "users":0,                    // จำนวนผู้ใช้ทั้งหมดของผู้ประกอบการใน Dapp
     "total_deposit":0.000000,     // ยอดฝากรวม (โหมด v1 จะเป็น 0)
     "total_deposit_count":0,      // จำนวนครั้งการฝาก (โหมด v1 จะเป็น 0)
     "total_withdraw":0.000000,    // ยอดถอนรวม (โหมด v1 จะเป็น 0)
     "total_withdraw_count":0,     // จำนวนครั้งการถอน (โหมด v1 จะเป็น 0)
     "total_buy_volume":0.000000,  // ปริมาณซื้อรวม
     "total_sell_volume":0.000000, // ปริมาณขายรวม
     "currency":"string"           // สกุลเงิน: USDT
  },
  "signature": "xxxxxxxx"
}

🛡️ คำอธิบายรหัสสถานะ

รหัสสถานะ	ความหมาย	รายละเอียด
0	OK	คำขอสำเร็จ
1	Canceled	ยกเลิกคำขอ
2	Unknown	ข้อผิดพลาดที่ไม่ทราบสาเหตุ
3	InvalidArgument	พารามิเตอร์ไม่ถูกต้อง
7	PermissionDenied	การยืนยันลายเซ็นล้มเหลว
8	ResourceExhausted	ถูกจำกัดอัตราการเรียกใช้งาน
13	Internal	ข้อผิดพลาดภายในระบบ

💡 API ที่ให้บริการ

YC365 Dapp เปิดให้ผู้ประกอบการเรียกใช้งาน API ดังต่อไปนี้

1. ขอรหัสเชิญ

GET /account/v1/app/invitecode

รหัสเชิญต้องรับแบบออฟไลน์ หนึ่งบัญชีต่อหนึ่งรหัส ส่วนหัวคำขอ (Header) ต้องมี Authorization

ตัวอย่างการตอบกลับ

{
   "code": 0,
   "message": "string",
   "data": "string"    // รหัสเชิญ
}

2. สร้างผู้ประกอบการ

POST /account/v1/app/create

ก่อนสร้างผู้ประกอบการให้ติดต่อพนักงานธุรกิจเพื่อขอรหัสเชิญ

เนื้อหาคำขอ (Request Body)

{
   "app_name": "string",         // ชื่อผู้ประกอบการ
   "app_desc": "string",         // คำอธิบายผู้ประกอบการ
   "api_version": "string",      // v1 = โหมดไม่ต้องโอนเงิน, v2 = โหมดโอนเงิน
   "signature_method": "string", // ปัจจุบันรองรับเฉพาะ hmac-sha256
   "assets_api": "string",
   "create_order_api": "string",
   "trade_order_api": "string",
   "cancel_order_api": "string",
   "settlement_api": "string",
   "webhook_api": "string",
   "invite_code": "string"       // รหัสเชิญ
}

ตัวอย่างการตอบกลับ

{
    "code": 0,
    "message": "string",
    "data": {
        "app_id": "string",        // รหัสผู้ประกอบการ
        "api_key": "string",       // คีย์ API
        "wallet_address": "string" // ที่อยู่กระเป๋าเงิน
    }
}

3. ขอ URL เข้าใช้งาน Dapp

POST /account/v1/app/access

แพลตฟอร์มเรียกใช้เพื่อสร้างลิงก์เข้าสู่ Dapp ให้ผู้ใช้ Authorization ต้องเป็น Base64 ของ app_id:signature (รายละเอียดการสร้างลายเซ็นอยู่ในส่วน “กฎการลงลายเซ็น”)

เนื้อหาคำขอ

{
   "user_id": "string",   // รหัสผู้ใช้ในแพลตฟอร์ม
   "user_name": "string", // ชื่อเล่นผู้ใช้
   "lang": "string",      // ภาษา: en, zh
   "email": "string",     // อีเมล (ไม่บังคับ)
   "phone": "string",     // เบอร์โทร (ไม่บังคับ) รูปแบบ +66 xxxxxxxx
   "avatar": "string",    // URL รูปโปรไฟล์
   "timestamp": 0,        // เวลาเรียกใช้งาน (มิลลิวินาที)
   "signature": "string"  // ลายเซ็นข้อมูล
}

ตัวอย่างการตอบกลับ

{
    "code": 0,
    "message": "string",
    "data": {
        "url": "string" // ลิงก์เข้าสู่ Dapp
    }
}

4. ซิงก์สินทรัพย์ (เฉพาะ v1)

POST /account/v1/app/account/assets

ใช้ซิงก์ยอดสินทรัพย์ของผู้ใช้ในโหมดไม่ต้องโอนเงิน Authorization เช่นเดียวกับข้อก่อนหน้า

เนื้อหาคำขอ

{
   "user_id": "string", // รหัสผู้ใช้ในแพลตฟอร์ม
   "assets": [
     {
       "asset": "string",   // ประเภทสินทรัพย์: USDT
       "balance": 0.000000, // ยอดคงเหลือที่ใช้ได้
       "frozen": 0.000000   // ยอดที่ถูกระงับ
     }
   ],
   "timestamp": 0,
   "signature": "string"
}

ตัวอย่างการตอบกลับ

{
    "code": 0,
    "message": "string",
    "data": {}
}

5. สร้างคำสั่งซื้อ (เฉพาะ v1)

POST /account/v1/app/order/create

ผู้ประกอบการเรียกใช้ก่อนผู้ใช้จะส่งคำสั่งซื้อ เมื่อการชำระเงินสำเร็จจะส่งสถานะคำสั่งกลับมา Authorization เช่นเดียวกัน

เนื้อหาคำขอ

{
   "user_id": "string",          // รหัสผู้ใช้ในแพลตฟอร์ม
   "order_id": "string",         // รหัสคำสั่งของแพลตฟอร์ม
   "side": "buy/sell",           // ฝั่งซื้อหรือขาย
   "outcome": "yes/no",          // yes = ทายว่าจะเกิด, no = ทายว่าจะไม่เกิด
   "market_id": "string",        // รหัสตลาด
   "price": 0.000000,            // ราคา
   "quantity": 0.000000,         // ปริมาณ
   "amount": 0.000000,           // มูลค่าคำสั่ง
   "fee": 0.000000,              // ค่าธรรมเนียม
   "timestamp": 0,
   "signature": "string"
}

ตัวอย่างการตอบกลับ

{
    "code": 0,
    "message": "string",
    "data": {
        "status": "success",  // success = สำเร็จ, failed = ล้มเหลว
        "fail_reason": ""     // สาเหตุที่ล้มเหลว (ถ้ามี)
    }
}

6. การแจ้งผลจับคู่คำสั่ง (เฉพาะ v1)

POST /account/v1/app/order/trade

เมื่อคำสั่งซื้อถูกจับคู่บนฝั่ง Dapp จะเรียก API นี้เพื่อแจ้งรายละเอียด ผู้ประกอบการต้องตอบกลับผลการประมวลผล

เนื้อหาคำขอ

{
   "order_id": "string",          // รหัสคำสั่งของแพลตฟอร์ม
   "trade_id": "string",          // รหัสการจับคู่
   "side": "buy/sell",            // ฝั่งซื้อหรือขาย
   "outcome": "yes/no",           // yes = ทายว่าจะเกิด, no = ทายว่าจะไม่เกิด
   "price": 0.000000,             // ราคาที่จับคู่
   "quantity": 0.000000,          // ปริมาณที่จับคู่
   "amount": 0.000000,            // มูลค่าที่จับคู่
   "fee": 0.000000,               // ค่าธรรมเนียม
   "timestamp": 0,
   "signature": "string"
}

ตัวอย่างการตอบกลับ

{
    "code": 0,
    "message": "string",
    "data": {}
}

7. การแจ้งยกเลิกคำสั่ง (เฉพาะ v1)

POST /account/v1/app/order/cancel

เมื่อคำสั่งถูกยกเลิกบนฝั่ง Dapp จะเรียก API นี้

เนื้อหาคำขอ

{
   "order_id": "string",  // รหัสคำสั่งของแพลตฟอร์ม
   "timestamp": 0,
   "signature": "string"
}

ตัวอย่างการตอบกลับ

{
    "code": 0,
    "message": "string",
    "data": {}
}

8. การแจ้งผลชำระบัญชี (เฉพาะ v1)

POST /account/v1/app/order/settlement

ใช้แจ้งผลกำไร/ขาดทุนหลังตลาดปิดและชำระบัญชี

เนื้อหาคำขอ

{
   "market_id": "string",       // รหัสตลาด
   "user_id": "string",         // รหัสผู้ใช้บนแพลตฟอร์ม
   "outcome": "yes/no",         // ผลลัพธ์ที่ผู้ใช้ถืออยู่
   "quantity": 0.000000,        // ปริมาณที่ถือ
   "payout": 0.000000,          // จำนวนเงินที่ได้รับ
   "timestamp": 0,
   "signature": "string"
}

ตัวอย่างการตอบกลับ

{
    "code": 0,
    "message": "string",
    "data": {}
}

9. เรียกดูรายละเอียดคำสั่ง

GET /account/v1/app/order/detail

ผู้ประกอบการสามารถตรวจสอบสถานะและรายละเอียดคำสั่งได้

พารามิเตอร์คำขอ

order_id=string

ตัวอย่างการตอบกลับ

{
    "code": 0,
    "message": "string",
    "data": {
        "order_id": "string",
        "user_id": "string",
        "status": "string",   // สถานะคำสั่ง
        "trades": [
           {
              "trade_id": "string",
              "price": 0.000000,
              "quantity": 0.000000,
              "amount": 0.000000,
              "fee": 0.000000,
              "created_at": "string"
           }
        ]
    }
}

10. รายงานของผู้ประกอบการ

GET /account/v1/app/report

รองรับการดึงข้อมูลตามช่วงวันที่ต้องการ

พารามิเตอร์คำขอ

start_date=string   // รูปแบบ yyyy-MM-dd
end_date=string     // รูปแบบ yyyy-MM-dd

ตัวอย่างการตอบกลับ

{
    "code": 0,
    "message": "string",
    "data": [
       {
          "period_date": "string",       // วันที่ของรายงาน
          "users": 0,                    // จำนวนผู้ใช้ที่มีกิจกรรม
          "total_deposit": 0.000000,     // ยอดฝาก
          "total_withdraw": 0.000000,    // ยอดถอน
          "total_buy_volume": 0.000000,  // ปริมาณซื้อ
          "total_sell_volume": 0.000000, // ปริมาณขาย
          "currency": "string"           // สกุลเงิน
       }
    ]
}

🔐 กฎการลงลายเซ็น

ทุก API ที่ต้องมีลายเซ็นจะใช้ HMAC-SHA256 ขั้นตอนดังนี้

1. แปลงเนื้อหาคำขอ (สตริง JSON) เป็น UTF-8
2. ใช้ api_key ของผู้ประกอบการเป็น secret key แล้วคำนวณ HMAC-SHA256
3. แปลงผลลัพธ์เป็นสตริงฐานสิบหก (hex) เพื่อใช้เป็น signature

ตัวอย่างโค้ดภาษา Python:

import hmac
import hashlib

def sign(payload: str, api_key: str) -> str:
    return hmac.new(api_key.encode('utf-8'),
                    payload.encode('utf-8'),
                    hashlib.sha256).hexdigest()

📄 ภาคผนวก

• ทุกการตอบกลับจะมีโครงสร้าง code, message, data
• รูปแบบข้อมูลเป็น JSON และตัวเลขเก็บ 6 ตำแหน่งทศนิยม
• เวลาอ้างอิงทั้งหมดเป็น UTC
• แนะนำให้ผู้ประกอบการบันทึก Log ของการเรียก API เพื่อให้ง่ายต่อการตรวจสอบปัญหา