📘 คู่มือ API ระบบ Employee (Full Reference)

เอกสารสำหรับการเชื่อมต่อระบบสแกนใบหน้าและจัดการเวลาทำงาน (API Version 2.0)

📌 ข้อมูลเบื้องต้น (Introduction)

Base URL

https://emp.bosshub.io

Authentication: API เกือบทั้งหมด (ยกเว้นการสร้างบริษัทครั้งแรก) จำเป็นต้องส่ง api_token ใน Request เพื่อยืนยันสิทธิ์การเข้าถึงข้อมูลของแต่ละบริษัท

Format: ระบบรองรับการรับ-ส่งข้อมูลรูปแบบ JSON และ multipart/form-data (สำหรับการส่งรูปภาพ)

1. Company Management (จัดการบริษัท)

1.1 สร้างบริษัทใหม่ (Create Company)

ใช้สำหรับลงทะเบียนบริษัทใหม่ เพื่อรับ api_token ไปใช้งานกับ API อื่นๆ

POST /api/create_company

`company_name`	* ชื่อบริษัท
`office_lat`	ละติจูด (Latitude)
`office_lng`	ลองจิจูด (Longitude)
`radius_meters`	ระยะอนุญาตให้สแกนหน้าได้ (เมตร) ค่าเริ่มต้น 50
`expected_in_time`	เวลาเข้างาน HH:MM (ค่าเริ่มต้น 09:00)
`expected_out_time`	เวลาเลิกงาน HH:MM (ค่าเริ่มต้น 18:00)
`webhook_url`	URL รับแจ้งเตือนเมื่อพนักงานลงเวลาสำเร็จ

{ "status": "success", "message": "สร้างบริษัทและออก API Token สำเร็จ", "api_token": "bh_a1b2c3d4e5f6g7h8" }

1.2 ดูข้อมูลบริษัท (Get Company)

GET /api/get_company?api_token={token}

{ "status": "success", "data": { "company_name": "Employee Corp", "expected_in": "09:00", "expected_out": "18:00", "office_lat": 13.7563, "office_lng": 100.5018, "radius_meters": 100, "webhook_url": "https://..." } }

1.3 อัปเดตข้อมูลบริษัท (Update Company)

POST /api/update_company

พารามิเตอร์เหมือนกับ 1.1 สร้างบริษัทใหม่ แต่ต้องส่ง api_token มาด้วย

2. Employee Management (จัดการพนักงาน)

2.1 เพิ่มพนักงานใหม่ (Add Employee)

POST /api/add_employee

`api_token`	* Token บริษัท
`emp_code`	* รหัสพนักงาน (เช่น EMP-001)
`full_name`	* ชื่อ นามสกุล

{ "status": "success", "emp_id": 15, "company_name": "Employee Corp" }

2.2 ตรวจสอบสถานะบัญชีและใบหน้า (Check Status)

ใช้เช็คว่ารหัสพนักงานนี้มีอยู่หรือไม่ และ "ถ่ายรูปใบหน้าเข้าระบบหรือยัง"

GET /api/check_employee_status?api_token={token}&emp_code={code}

🛠 ทดลองใช้งาน (Try it out)

// Response...

2.3 ดึงข้อมูลพนักงานเบื้องต้น (Get Employee Info)

ดึงข้อมูลจาก ID ภายใน (ใช้น้อยมาก ปกติใช้ตอนทำลิงก์ให้พนักงานลงทะเบียนหน้าเอง)

GET /api/get_employee_info?emp_id={id}

2.4 ลงทะเบียนใบหน้า (Register Face)

ส่งรูปถ่ายใบหน้าพนักงานเพื่อนำไปแปลงเป็น Face Vector บันทึกลงฐานข้อมูล

POST /api/register_face (Content-Type: multipart/form-data)

`emp_id`	* ID อ้างอิงของพนักงาน (ได้จาก 2.1)
`image`	* ไฟล์รูปภาพใบหน้าพนักงาน (.jpg, .png)

3. Attendance System (ระบบลงเวลา)

3.1 ตรวจสอบใบหน้า Step 1 (Verify Face)

ส่งรูปภาพมาค้นหาว่าตรงกับพนักงานคนใดในบริษัท (ยังไม่บันทึกเวลาจริง)

POST /api/verify_face_widget (multipart/form-data)

`api_token`	* Token บริษัท
`image`	* ไฟล์รูปภาพที่จับจากกล้อง

{ "status": "success", "emp_id": 15, "emp_code": "EMP-001", "full_name": "สมชาย ใจดี", "confidence": 95.42 }

3.2 ยืนยันการบันทึกเวลา Step 2 (Confirm Attendance)

นำ emp_id และ confidence ที่ได้จาก Step 1 มาส่งยืนยันเพื่อบันทึกลง Database

POST /api/confirm_attendance_widget

`api_token`	* Token บริษัท
`emp_id`	* ID พนักงาน
`action_type`	* `IN` (เข้างาน) หรือ `OUT` (ออกงาน)
`latitude`	* พิกัด GPS ผู้สแกน
`longitude`	* พิกัด GPS ผู้สแกน
`confidence`	* เปอร์เซ็นต์ความแม่นยำ

3.3 Widget สำหรับฝังหน้าเว็บลูกค้า

นำโค้ดนี้ไปวางในเว็บไซต์เพื่อเรียกใช้งานกล้องสแกนใบหน้าอัตโนมัติ (ครอบคลุม Step 1 และ Step 2)

4. Report & Webhook (รายงานและการแจ้งเตือน)

4.1 สรุปรายงานการลงเวลารายวัน (Attendance Summary)

คำนวณเวลาเข้าเช้าสุด ออกดึกสุด ชั่วโมงทำงาน พร้อมเช็คสถานะ มาสาย/ออกก่อนเวลา อัตโนมัติ (อิงตามเวลามาตรฐานบริษัท)

GET /api/attendance_summary

🛠 ทดลองใช้งาน (Try it out)

// Response JSON...

4.2 โครงสร้าง Webhook Payload

หากตั้งค่า Webhook URL ไว้ในบริษัท ระบบจะยิงข้อมูล POST JSON ทันทีที่มีพนักงานสแกนหน้าสำเร็จ หน้าตาข้อมูลเป็นดังนี้:

{ "event": "attendance_logged", "timestamp": "2026-03-20 08:25:10", "data": { "company": { "company_id": 1, "company_name": "BossHub Corp" }, "employee": { "emp_id": 15, "emp_code": "EMP-001", "full_name": "สมชาย ใจดี" }, "attendance": { "action_type": "IN", "action_text": "เข้างาน (IN)", "log_time": "2026-03-20 08:25:10", "confidence_score": 95.42 }, "location": { "lat": "13.756334", "lng": "100.501822", "is_gps_valid": true, "allowed_radius_meters": 50 } } }