ข้ามไปที่เนื้อหา

Standard API Specifications

เอกสารฉบับนี้อธิบายถึงมาตรฐานการเชื่อมต่อ (Standard Specifications) สำหรับ API ทั้งหมดของระบบ Card2U เพื่อให้ผู้พัฒนาระบบภายนอกใช้เป็นแนวทางเดียวกัน

1. Connection Endpoints

https://<domain>/openapi/v1

https://<domain>/openapi/v1

2. Authentication

ทุกการเรียกใช้งาน API จะต้องส่งรหัสรับรองความปลอดภัยผ่าน HTTP Headers เสมอ โดยสนับสนุนการระบุตัวตน 2 รูปแบบหลัก (ขึ้นอยู่กับบริการที่เลือกใช้):

2.1 API Key Authentication (Server-to-Server)

ต้องส่งค่าใน Header ดังนี้:

Header Name Type Description Example
X-API-Key String รหัสลับเฉพาะของระบบภายนอกเพื่อเข้าถึงบริการ c2u_live_5f3b79...
Content-Type String รูปแบบของข้อมูลที่ส่ง (บังคับส่งเป็น JSON) application/json

2.2 Bearer Token Authentication (User/Admin Sessions)

ต้องส่งค่าใน Header ดังนี้:

Header Name Type Description Example
Authorization String Bearer Token ที่ได้รับหลังจากสำเร็จขั้นตอน Login Bearer eyJhbGciOi...
Content-Type String รูปแบบของข้อมูลที่ส่ง (บังคับส่งเป็น JSON) application/json

3. Standard Response Formats

ระบบ Card2U ตอบกลับข้อมูลในรูปแบบ JSON ทั้งหมด โดยมีโครงสร้างมาตรฐานดังนี้:

3.1 Success Response

ระบบจะส่งสถานะ HTTP Status 2xx พร้อมโครงสร้างข้อมูลดังนี้:

{
  "success": true,
  "data": {
    // ข้อมูลที่ส่งกลับ (ข้อมูลเชิงลึกจะเปลี่ยนไปตามแต่ละ API)
  },
  "message": "Operation completed successfully."
}

3.2 Error Response

ระบบจะส่งสถานะ HTTP Status 4xx หรือ 5xx พร้อมรหัสข้อผิดพลาดและคำอธิบาย:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "คำอธิบายข้อผิดพลาดโดยละเอียด (สามารถแสดงให้ผู้ใช้ดูได้)",
    "details": [
      // ข้อมูลข้อผิดพลาดเชิงลึก เช่น ปัญหาการตรวจสอบฟิลด์ (Validation Errors)
    ]
  }
}

4. HTTP Status Codes

Status Code Description Usage Case
200 OK สำเร็จ (Success) ข้อมูลถูกต้องและทำรายการสำเร็จเรียบร้อย
201 Created สร้างสำเร็จ (Created) ลงทะเบียนหรือสร้างข้อมูลชุดใหม่สำเร็จ
400 Bad Request ข้อมูลไม่ถูกต้อง รูปแบบ Request หรือข้อมูลที่ส่งมาไม่ตรงตามเงื่อนไข
401 Unauthorized ไม่ได้รับอนุญาต ไม่ได้ส่ง API Key/Token หรือคีย์หมดอายุ
403 Forbidden ไม่มีสิทธิ์เข้าถึง คีย์ถูกต้องแต่ไม่มีสิทธิ์เรียกใช้งาน Endpoint นี้
404 Not Found ไม่พบข้อมูล ไม่พบสมาชิก บัตร หรือไม่พบหน้าเส้นทางดังกล่าว
422 Unprocessable Entity ตรวจสอบข้อมูลไม่ผ่าน ข้อมูลไม่ผ่านการ Validation เช่น เบอร์โทรศัพท์ซ้ำ หรือฟิลด์ที่บังคับเป็นค่าว่าง
500 Internal Server Error ข้อผิดพลาดจากระบบ เกิดปัญหาทางเทคนิคที่ฝั่งเซิร์ฟเวอร์ Card2U