คู่มือการใช้งาน TPA Employee Directory API

API กลางสำหรับค้นหาข้อมูลพนักงาน TPA — sync จาก SharePoint อัตโนมัติ

ลิงก์ที่เกี่ยวข้อง

1. ขอสิทธิ์เชื่อมต่อ

หน่วยงานที่ต้องการเชื่อมต่อ ให้ติดต่อผู้ดูแลระบบ Employee Directory เพื่อ:

  1. ลงทะเบียนชื่อระบบ / หน่วยงาน
  2. รับ API Key (รูปแบบ tpae_...) — แสดงครั้งเดียวตอนสร้าง กรุณาเก็บรักษาให้ปลอดภัย
  3. แจ้ง IP หรือเครือข่ายที่จะเรียก API (production มี IP allowlist ที่ nginx)

ผู้ดูแลสามารถสร้างบัญชีผ่าน Admin UI หรือ Admin API โดยใช้ ADMIN_API_KEY

2. Base URL และ Authentication

สภาพแวดล้อมBase URL
Productionhttps://employee-api.tpa.or.th/api/v1
Developmenthttp://localhost:3100/api/v1

ส่ง API Key ในทุก request ที่ต้องการ authentication (ยกเว้น /health):

curl -H "X-API-Key: tpae_your_key_here" \
  "https://employee-api.tpa.or.th/api/v1/employees/search?q=somchai"

รองรับทั้ง header X-API-Key และ Authorization: Bearer <key>

3. รายการ API ทั้งหมด

Method Endpoint Auth คำอธิบาย
GET /health Public ตรวจสอบสถานะระบบ จำนวนพนักงาน sync ล่าสุด
GET /employees/search?q=&limit= API Key ค้นหาพนักงาน (ชื่อ, อีเมล, รหัสพนักงาน) — default limit 20, สูงสุด 100
GET /employees/by-email/:email API Key ค้นหาด้วยอีเมล (รองรับ @tpa.or.th ↔ @me.tpa.or.th)
GET /employees/by-emp-code/:code API Key ค้นหาด้วยรหัสพนักงาน (รองรับ leading zero)
GET /sync/status API Key ดูสถานะ sync ล่าสุด
POST /sync/run API Key สั่ง sync จาก SharePoint ทันที (สำหรับผู้ดูแล)

API คืนเฉพาะพนักงานที่ EmpStatus = Active (ตามการตั้งค่าระบบ)

4. รูปแบบข้อมูลพนักงาน (Response)

{
  "data": {
    "name": "นายสมชาย ใจดี",
    "emp_code": "0123456",
    "thai_first_name": "สมชาย",
    "thai_last_name": "ใจดี",
    "eng_first_name": "Somchai",
    "eng_last_name": "Jaidee",
    "unit": "ฝ่าย IT",
    "bu": null,
    "sex": "M",
    "post_level": null,
    "position": "นักวิชาการคอมพิวเตอร์",
    "division_code": "IT01",
    "division_code_label": null,
    "division": "สำนักเทคโนโลยีสารสนเทศ",
    "department": "ฝ่ายพัฒนาระบบ",
    "phone": "0812345678",
    "cost_center": null,
    "emp_status": "Active",
    "ms_account": "somchai@me.tpa.or.th",
    "email": "somchai@tpa.or.th"
  }
}

การค้นหา (/search) คืน { "data": [ ... ] } เป็น array

5. ตัวอย่างการใช้งาน

ค้นหาพนักงาน

GET /api/v1/employees/search?q=somchai&limit=10

ค้นหาด้วยอีเมล

GET /api/v1/employees/by-email/somchai%40tpa.or.th

ค้นหาด้วยรหัสพนักงาน

GET /api/v1/employees/by-emp-code/0123456

ตรวจสอบสถานะ (ไม่ต้องใช้ API Key)

GET /api/v1/health

6. ข้อผิดพลาดที่พบบ่อย

HTTPสาเหตุแนวทางแก้
401ไม่มี API Key หรือ Key ไม่ถูกต้อง/ถูก revokeตรวจสอบ header และติดต่อผู้ดูแล
404ไม่พบพนักงานตรวจสอบอีเมล/รหัส หรือสถานะ Active
403/timeoutIP ไม่อยู่ใน allowlistแจ้ง IP ให้ผู้ดูแล nginx
429เรียก API ถี่เกิน rate limitลดความถี่ หรือ cache ฝั่ง client

7. แนวทางที่แนะนำสำหรับระบบ Consumer