🔌 RESTful API Design Specification (การออกแบบ APIs)

🇹🇭 ภาษาไทย (For User)

📌 1. โครงสร้างทั่วไปและรูปแบบผลลัพธ์ (General Info & Response Envelope)

Base URL: /api/v1/
รูปแบบการยืนยันตัวตน (Authentication): ใช้ Header: Authorization: Bearer <JWT_TOKEN>

โครงสร้างผลลัพธ์มาตรฐาน (Response Structure):

{
  "success": true,
  "data": {},
  "error": null
}

กรณีเกิดข้อผิดพลาด (Error Response):

{
  "success": false,
  "data": null,
  "error": {
    "code": "ERROR_CODE",
    "message": "ข้อความอธิบายความผิดพลาดสำหรับผู้ใช้"
  }
}

🛣️ 2. รายการช่องทางเชื่อมต่อ (API Endpoints List)

2.1 ระบบยืนยันตัวตนและบัญชีผู้ใช้ (Authentication & Users)

POST /api/v1/auth/signup
- รายละเอียด: สมัครสมาชิกใหม่
- Request Body: {"email", "password", "display_name", "phone_number"}
- Response Data: ข้อมูลโปรไฟล์ผู้ใช้พร้อมกับ JWT Token
POST /api/v1/auth/login
- รายละเอียด: เข้าสู่ระบบเพื่อรับ Token
- Request Body: {"email", "password"}
- Response Data: {"token": "string", "user": {user_details}}
GET /api/v1/users/me
- รายละเอียด: ดึงข้อมูลโปรไฟล์ของตนเอง
- Response Data: {id, email, display_name, phone_number, avatar_url}
PUT /api/v1/users/me
- รายละเอียด: แก้ไขเบอร์โทรศัพท์ (สำหรับรับเงิน PromptPay) หรือชื่อแสดง
- Request Body: {"display_name", "phone_number", "avatar_url"}

2.2 ระบบจัดการกลุ่ม (Group Management)

POST /api/v1/groups
- รายละเอียด: สร้างกลุ่มใหม่ (เช่น กลุ่มรูมเมท หรือ ทริปพัทยา)
- Request Body: {"name", "description"}
- Response Data: รายละเอียดกลุ่มรวมถึง invite_code ที่ระะบบสร้างให้
GET /api/v1/groups
- รายละเอียด: ดึงรายการกลุ่มทั้งหมดที่ผู้ใช้นี้เป็นสมาชิกอยู่
POST /api/v1/groups/join
- รายละเอียด: เข้าร่วมกลุ่มแชร์ค่าใช้จ่ายด้วยรหัสเชิญชวน (Invite Code)
- Request Body: {"invite_code"}

2.3 ระบบลงบิลค่าใช้จ่ายและหารเงิน (Bills & Expense Splits)

POST /api/v1/groups/{group_id}/bills

รายละเอียด: บันทึกบิลใหม่และกระจายยอดหนี้ให้กับสมาชิกตามเงื่อนไขที่กำหนด

Request Body:

{
  "title": "ค่าอาหารค่ำ",
  "total_amount": 1200.00,
  "category": "food",
  "split_method": "equal", // options: equal, exact, percentage
  "shares": [
    { "user_id": "uuid-1", "amount": 400.00 },
    { "user_id": "uuid-2", "amount": 400.00 },
    { "user_id": "uuid-3", "amount": 400.00 }
  ]
}

GET /api/v1/groups/{group_id}/bills
- รายละเอียด: รายการประวัติบิลทั้งหมดของกลุ่มนี้
GET /api/v1/bills/{bill_id}
- รายละเอียด: ดึงรายละเอียดบิลและสัดส่วนหนี้ค้างชำระรายบุคคลของบิลนั้นๆ

2.4 ระบบชำระเงินและตรวจสอบสลิป (Payments & Verification)

GET /api/v1/bills/{bill_id}/payment-qr
- รายละเอียด: เจนเนอเรตและแสดงภาพ PromptPay QR Code ที่ฝังยอดหนี้ตามจริงของผู้ใช้รายนั้น
- Response Data: ภาพ QR ในรูปแบบ Base64 หรือ String Payload สำหรับสแกน
POST /api/v1/bills/{bill_id}/payments
- รายละเอียด: ส่งภาพถ่ายสลิปเงินโอนเข้าสู่ระบบ AI เพื่อสแกนและยืนยันการเคลียร์บิลทันที
- Request Body (Multipart/form-data): รูปภาพสลิปโอนเงิน (File)
- Response Data: รายละเอียดการโอนเงินที่สกัดได้จากสลิป และผลลัพธ์การตรวจสอบ ("status": "verified" หรือ "failed")

2.5 ระบบแชทกลุ่มและการแจ้งเตือน (Chat & Notification)

GET /api/v1/groups/{group_id}/messages
- รายละเอียด: ดึงประวัติการสนทนาและประวัติกิจกรรมระบบย้อนหลัง
- Query parameters: limit=50, before_timestamp
POST /api/v1/groups/{group_id}/messages
- รายละเอียด: ส่งข้อความแชทใหม่เข้าไปในกลุ่ม
- Request Body: {"message_type": "text", "message": "ทวงหนี้หน่อยเพื่อน"}

2.6 ระบบสัตว์เลี้ยงกลุ่ม (Gamification Pet - Mochi)

GET /api/v1/groups/{group_id}/pet
- รายละเอียด: ดูระดับความสุข พลังชีวิต (HP) และของเล่นตกแต่งของน้องโมจิประจำกลุ่ม
POST /api/v1/groups/{group_id}/pet/interact
- รายละเอียด: ใช้แต้ม XP กลุ่มเพื่อป้อนอาหารหรือลูบหัวเพื่อเพิ่มค่าความสุขของน้อง

🇬🇧 English (For AI Agents)

📝 Pydantic Data Schemas (Mockup Schema for Request/Response validation)

Below is the data schema declaration for key endpoints using OpenAPI Pydantic model equivalents:

# Auth Login Request Schema
class LoginRequest(BaseModel):
    email: EmailStr
    password: str
 
# Create Bill Request Schema
class ShareDetail(BaseModel):
    user_id: UUID
    amount: decimal.Decimal
 
class CreateBillRequest(BaseModel):
    title: str = Field(..., max_length=255)
    total_amount: decimal.Decimal = Field(..., gt=0)
    category: str
    split_method: str = "equal"  # equal, exact, percentage
    shares: List[ShareDetail]
 
# Payment Verification Response Schema
class SlipVerificationResponse(BaseModel):
    transaction_id: str
    sender_name: str
    receiver_name: str
    amount: decimal.Decimal
    trans_datetime: datetime
    is_valid: bool
    status: str  # verified, failed

🚨 Common API Error Codes

AUTH_INVALID_CREDENTIALS (401): Incorrect username or password.
GROUP_NOT_FOUND (404): The requested group does not exist.
INVITE_CODE_INVALID (400): The provided join code is incorrect or expired.
BILL_SPLIT_MISMATCH (400): The sum of split shares does not equal the total bill amount.
SLIP_ALREADY_USED (400): This bank transfer transaction ID has already been uploaded.
SLIP_INVALID (400): Slip verification failed (amount mismatched, wrong receiver, or edited image).

Quartz 5

Explorer

API_Design