Time Manage (จัดการกะการทำงาน-วันหยุด)
API สำหรับจัดตารางกะการทำงาน วันหยุด และกำลังพลของพนักงานแบบ Grid รายเดือน/สัปดาห์
ภาพรวม
Time Manage API ใช้จัดการตารางเวลาทำงานของพนักงานเป็น 4 มุมมองบนตาราง Grid เดียวกัน โดยแต่ละมุมมองมี API สำหรับ ค้นหา (ดึงตาราง) และ บันทึก (แก้ไขตาราง) เป็นคู่กัน:
| มุมมอง | ดึงข้อมูล | บันทึกข้อมูล |
|---|---|---|
| กะการทำงาน | Get Work Cycle Grid | Save Work Cycle Grid |
| วันหยุด | Get Holiday Grid | Save Holiday Grid |
| กะ + วันหยุด | Get Work Cycle & Holiday Grid | Save Work Cycle & Holiday Grid |
| กำลังพล (สาขาปฏิบัติงานจริง) | Get Manpower Grid | Save Manpower Grid |
รูปแบบการใช้งานทั่วไป: เรียก API กลุ่ม ค้นหา เพื่อดึงตารางในรอบเดือน/สัปดาห์ก่อน แล้วนำ time_attendance_group_transac_id และ ID อื่นๆ ในแต่ละวันที่ได้กลับมา ส่งต่อให้ API กลุ่ม บันทึก เพื่อแก้ไข
สิทธิ์ที่ต้องการ: API Key ต้องมีสิทธิ์ ข้อมูลการยื่นเอกสาร (document:manage) จึงจะเรียกใช้ API ในโมดูลนี้ได้
Available Endpoints
ค้นหา (Search Grid)
| Endpoint | Method | Description |
|---|---|---|
| Get Work Cycle Grid | POST | ดึงตารางกะการทำงานแบบ Grid |
| Get Holiday Grid | POST | ดึงตารางวันหยุดแบบ Grid |
| Get Work Cycle & Holiday Grid | POST | ดึงตารางกะ + วันหยุดพร้อมกัน |
| Get Manpower Grid | POST | ดึงตารางสาขาที่ปฏิบัติงานจริงรายพนักงาน |
| Get Manpower Summary by Branch | POST | สรุปจำนวนกำลังพลรายสาขา (นับต่อวัน) |
| Get Work Cycle List | GET | ดึงรายการกะทั้งหมด (ใช้เป็น dropdown) |
บันทึก (Save Grid)
| Endpoint | Method | Description |
|---|---|---|
| Save Work Cycle Grid | POST | บันทึกกะการทำงานที่แก้ไข |
| Save Holiday Grid | POST | บันทึกวันหยุดที่แก้ไข |
| Save Work Cycle & Holiday Grid | POST | บันทึกกะ + วันหยุดพร้อมกัน |
| Save Manpower Grid | POST | บันทึกสาขาที่ปฏิบัติงานจริง |
API กลุ่มค้นหาใช้ POST แม้เป็นการอ่านข้อมูล เนื่องจากพารามิเตอร์กรอง (รายชื่อสาขา/แผนก/พนักงาน) เป็นอาร์เรย์ที่ต้องส่งเป็น JSON body
การเลือกช่วงเวลา (month_no / week_no)
API กลุ่มค้นหาทุกตัวรับช่วงเวลาแบบใดแบบหนึ่ง (ห้ามส่งพร้อมกัน):
| Parameter | รูปแบบ | ความหมาย |
|---|---|---|
month_no | YYYY-MM | ดึงทั้งรอบเดือน เช่น "2026-07" |
week_no | YYYY-MM-DD | ดึงทั้งสัปดาห์ที่คร่อมวันที่ระบุ เช่น "2026-07-01" |
ช่วงเวลาที่ได้กลับมา (payload.time_range) อ้างอิงตามขอบเขตรอบจ่ายเงินเดือนของบริษัท ไม่จำเป็นต้องตรงกับเดือนตามปฏิทิน เช่น month_no: "2026-07" อาจคืนช่วง 2026-06-26 ถึง 2026-07-25 (day_range 30) ขึ้นอยู่กับการตั้งค่ารอบจ่าย
รหัสประเภทวันหยุด (holiday_flag_lv)
ใช้ในกลุ่ม Holiday และ Work Cycle & Holiday:
| รหัส | ความหมาย |
|---|---|
00 | วันทำงาน (Workday) |
01 | วันหยุดนักขัตฤกษ์ (Public Holiday) |
03 | วันหยุดพนักงาน (Employee Holiday) |
04 | วันหยุดพิเศษ (Special Holiday) |
สถานะการแก้ไขรายวัน (is_change_*)
response กลุ่มค้นหาจะมีฟิลด์สถานะการแก้ไขรายวัน โดยชื่อฟิลด์ต่างกันตามมุมมอง:
| Endpoint | ฟิลด์สถานะ |
|---|---|
| Get Work Cycle Grid | is_change_work_cycle |
| Get Holiday Grid | is_change_holiday |
| Get Work Cycle & Holiday Grid | ทั้ง is_change_work_cycle และ is_change_holiday |
| Get Manpower Grid / Summary | ไม่มีฟิลด์นี้ (ตรวจเงื่อนไขตอนบันทึกแทน) |
ค่าที่เป็นไปได้:
| ค่า | ความหมาย |
|---|---|
Y | วันนั้นยังแก้ไขได้ |
N | วันนั้นแก้ไขไม่ได้ เนื่องจากผ่านวันปิดงวด/ปิดบัญชีแล้ว |
Quick Start
1. ดึงตารางกะการทำงานของพนักงาน
curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/time-manage/get-work-cycle-multiple" \
-H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"month_no": "2026-07",
"employee_code": "EMP001"
}'2. ดึงรายการกะทั้งหมด (สำหรับเลือกกะใหม่)
curl -X GET "https://openapi.humansoft.co.th/api/v1/open-apis/time-manage/get-work-cycle-list" \
-H "Ocp-Apim-Subscription-Key: YOUR_API_KEY"3. บันทึกกะใหม่ให้พนักงาน
curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/time-manage/edit-work-cycle-multiple" \
-H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"employee_lists": [
{
"employee_code": "EMP001",
"day_lists": [
{
"work_date": "2026-07-01",
"time_attendance_group_transac_id": "20260701ACD8956C44C3",
"work_cycle_id": "202401083EAE7D1F9711",
"work_cycle_code": "M1"
}
]
}
]
}'Common Use Cases
- จัดกะพนักงานรายเดือน — ดึงตารางกะทั้งเดือน แล้วบันทึกกะที่ปรับใหม่ทีละหลายคน
- กำหนดวันหยุดพนักงาน — ปรับสถานะวันหยุด (
holiday_flag_lv) รายวันบนตาราง - จัดกำลังพลตามสาขา — ระบุสาขาที่พนักงานไปปฏิบัติงานจริงรายวัน และดูสรุปจำนวนกำลังพลรายสาขา
- จัดกะและวันหยุดพร้อมกัน — แก้ไขทั้งกะและวันหยุดในคำขอเดียว
Business Rules
- ไม่สามารถแก้ไขข้อมูลในวัน/งวดที่ปิดงวดหรือพ้นกำหนดเวลาส่งข้อมูลแล้ว (ดูฟิลด์
is_change_*ในผลลัพธ์การค้นหา) time_attendance_group_transac_idต้องนำมาจาก response ของ API กลุ่มค้นหา — ห้ามสร้างค่าขึ้นเอง- เมื่อบันทึกหลายคนพร้อมกัน หากมีพนักงานบางคนอยู่ในงวดที่ปิดแล้ว คำขอบันทึกของคนนั้นจะถูกปฏิเสธ
Related APIs
- Work Cycle - ตั้งค่ากะการทำงานหลักขององค์กร
- Work Cycle Change - คำขอเปลี่ยน/สลับกะรายบุคคล
- Holiday - วันหยุดขององค์กร
- Time Attendance - ข้อมูลการลงเวลา