Submit OT
ยื่นคำขอ OT ใหม่
ใช้ API นี้เพื่อสร้างคำขอ OT ใหม่ ระบบจะตรวจสอบข้อมูลและส่งเข้าสู่ขั้นตอนการอนุมัติอัตโนมัติ
Endpoint
POST /api/v1/open-apis/overtime/submitสิทธิ์ที่ต้องการ: API Key ต้องมีสิทธิ์ ข้อมูลการยื่นเอกสาร (document:manage)
Request Parameters
Required Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
employee_code | string | Yes | รหัสพนักงาน | EMP001 |
ot_work_dt | string | Yes | วันที่ของรอบกะการทำงานที่ OT นี้สังกัด (YYYY-MM-DD) — ดู OT Work Date | 2026-01-15 |
ot_work_start_hour | string | Yes | เวลาเริ่มต้น (YYYY-MM-DD HH:mm:ss) | 2026-01-15 18:00:00 |
ot_work_end_hour | string | Yes | เวลาสิ้นสุด (YYYY-MM-DD HH:mm:ss) ต้องมากกว่า ot_work_start_hour | 2026-01-15 21:00:00 |
ot_work_flag_lv | string | Yes | ประเภท OT รองรับทั้งรูปแบบตัวเลข (01-08) หรือ string format (OT_1_0-OT_7_0) | 02 หรือ OT_1_5 |
Optional Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
ot_work_desc | string | No | รายละเอียด/เหตุผล | ทำงานเพิ่มเติมตามโปรเจค |
image_content | string | No | ไฟล์แนบในรูปแบบ Base64 (สำหรับเอกสารประกอบ) | data:image/jpeg;base64,/9j/4AAQ... |
extra_round | string | No | อนุญาตให้บันทึกแม้วันที่ของ OT อยู่ในงวดที่ปิดแล้ว (Y / N) ค่าเริ่มต้นคือ N | N |
OT Work Date
ot_work_dt ใช้ระบุว่าชั่วโมง OT นี้สังกัด รอบกะการทำงานของวันไหน ซึ่งอาจไม่ตรงกับวันที่ใน ot_work_start_hour ในกรณีกะข้ามคืน
ot_work_dt ต้องต่างได้ไม่เกิน 1 วัน (ก่อนหน้าหรือถัดไป) เมื่อเทียบกับทั้ง วันที่ของ ot_work_start_hour และ วันที่ของ ot_work_end_hour
กรณี OT คาบเกี่ยวข้ามวัน (เวลาเริ่มกับเวลาสิ้นสุดคนละวัน) ค่าที่ใช้ได้จึงเหลือเพียง 2 วัน คือวันของเวลาเริ่ม หรือวันของเวลาสิ้นสุดเท่านั้น
Request Body Example
ตัวอย่างที่ 1 — กะปกติ
ทำงานต่อหลังเลิกกะในวันเดียวกัน ot_work_dt จึงตรงกับวันที่ของเวลาเริ่มและเวลาสิ้นสุด
{
"employee_code": "EMP001",
"ot_work_dt": "2026-01-15",
"ot_work_start_hour": "2026-01-15 18:00:00",
"ot_work_end_hour": "2026-01-15 21:00:00",
"ot_work_flag_lv": "02",
"ot_work_desc": "ทำงานเพิ่มเติมตามโปรเจค"
}ตัวอย่างที่ 2 — กะข้ามคืน
พนักงานเข้ากะวันที่ 15 (14:00 – 00:00) แล้วทำ OT ต่อในช่วงเช้าตรู่ของวันที่ 16 แต่ต้องการให้ชั่วโมง OT นับเข้ารอบกะของวันที่ 15 — ot_work_dt จึงเป็นวันก่อนหน้าเวลาที่ทำจริง
{
"employee_code": "EMP001",
"ot_work_dt": "2026-01-15",
"ot_work_start_hour": "2026-01-16 00:00:00",
"ot_work_end_hour": "2026-01-16 00:30:00",
"ot_work_flag_lv": "02",
"ot_work_desc": "OT ต่อเนื่องหลังเลิกกะดึก นับเข้ากะวันที่ 15"
}Response Format
Success Response (HTTP 200)
{
"code": 200,
"message": "สำเร็จ",
"payload": {
"ot_work_id": "20260115OT0000000001",
"employee_id": "20251127D4573C421639",
"employee_code": "EMP001",
"ot_work_dt": "2026-01-15",
"ot_work_start_hour": "2026-01-15 18:00:00",
"ot_work_end_hour": "2026-01-15 21:00:00",
"ot_work_time": 3.0,
"ot_work_flag_lv": "OT_1_5",
"ot_work_desc": "ทำงานเพิ่มเติมตามโปรเจค",
"approve_flag": "01",
"created": "2026-01-13 09:00:00"
}
}Error Response - Validation Failed (HTTP 400)
{
"code": 400,
"message": "Validation failed",
"errors": [
"Missing required parameter: 'employee_code'",
"'ot_work_dt' must be in Y-m-d format"
]
}Error Response - Employee Not Found (HTTP 400)
{
"code": 400,
"message": "ไม่สำเร็จ",
"error": "Employee not found: EMP999"
}Error Response - OT Type Not Enabled (HTTP 400)
{
"code": 400,
"message": "ไม่สำเร็จ",
"error": "OT type '05' is not enabled for this company"
}Error Response - Salary Period Closed (HTTP 400)
{
"code": 400,
"message": "ไม่สำเร็จ",
"error": "ไม่สามารถบันทึกได้ งวดเงินเดือนปิดแล้ว"
}Response Fields
| Field | Type | Description |
|---|---|---|
ot_work_id | string | ID ของคำขอที่สร้าง |
employee_id | string | ID ของพนักงาน |
employee_code | string | รหัสพนักงาน |
ot_work_dt | string | วันที่ทำ OT |
ot_work_start_hour | datetime | เวลาเริ่มต้น |
ot_work_end_hour | datetime | เวลาสิ้นสุด |
ot_work_time | number | จำนวนชั่วโมง OT |
ot_work_flag_lv | string | ประเภท OT — คืนกลับเป็นรูปแบบ string เสมอ (OT_1_0-OT_7_0) |
ot_work_desc | string | รายละเอียดงาน OT |
approve_flag | string | สถานะการอนุมัติ (01 = รออนุมัติ) |
created | datetime | วันเวลาที่สร้าง |
แม้ส่ง ot_work_flag_lv มาเป็นรหัสตัวเลข (เช่น 02) ระบบจะคืนกลับเป็นรูปแบบ string เสมอ (เช่น OT_1_5) หากระบบของท่านเทียบค่าที่ได้รับกับค่าที่ส่งไป ต้องแปลงรูปแบบก่อนเปรียบเทียบ
Code Examples
cURL
curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/overtime/submit" \
-H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"employee_code": "EMP001",
"ot_work_dt": "2026-01-15",
"ot_work_start_hour": "2026-01-15 18:00:00",
"ot_work_end_hour": "2026-01-15 21:00:00",
"ot_work_flag_lv": "02",
"ot_work_desc": "ทำงานเพิ่มเติมตามโปรเจค"
}'Validation Rules
| Parameter | Validation | Error Message |
|---|---|---|
employee_code | ต้องระบุ | Missing required parameter: 'employee_code' |
employee_code | ต้องเป็น string | 'employee_code' must be a string |
ot_work_dt | ต้องระบุ | Missing required parameter: 'ot_work_dt' |
ot_work_dt | ต้องเป็น string | 'ot_work_dt' must be a string |
ot_work_dt | ต้องอยู่ในรูปแบบ YYYY-MM-DD | 'ot_work_dt' must be in Y-m-d format (e.g., 2024-01-15) |
ot_work_dt | ต้องเป็นวันที่ที่มีอยู่จริงตามปฏิทิน | 'ot_work_dt' is not a valid date |
ot_work_dt | ต่างจากวันที่ของ ot_work_start_hour ได้ไม่เกิน 1 วัน | 'ot_work_dt' (2026-01-13) must be within +/- 1 day of 'ot_work_start_hour' date (2026-01-15) |
ot_work_dt | ต่างจากวันที่ของ ot_work_end_hour ได้ไม่เกิน 1 วัน | 'ot_work_dt' (2026-01-13) must be within +/- 1 day of 'ot_work_end_hour' date (2026-01-15) |
ot_work_start_hour | ต้องระบุ | Missing required parameter: 'ot_work_start_hour' |
ot_work_start_hour | ต้องอยู่ในรูปแบบ YYYY-MM-DD HH:mm:ss | 'ot_work_start_hour' must be in Y-m-d H:i:s format (e.g., 2024-01-15 18:00:00) |
ot_work_end_hour | ต้องระบุ | Missing required parameter: 'ot_work_end_hour' |
ot_work_end_hour | ต้องอยู่ในรูปแบบ YYYY-MM-DD HH:mm:ss | 'ot_work_end_hour' must be in Y-m-d H:i:s format (e.g., 2024-01-15 22:00:00) |
ot_work_end_hour | ต้องมากกว่า ot_work_start_hour | 'ot_work_start_hour' must be before 'ot_work_end_hour' |
ot_work_flag_lv | ต้องระบุ | Missing required parameter: 'ot_work_flag_lv' |
ot_work_flag_lv | ต้องรองรับ 01-08 หรือ OT_1_0-OT_7_0 | 'ot_work_flag_lv' must be one of: 01, 02, 03, 04, 05, 06, 07, 08 or OT_1_0, OT_1_5, OT_2_0, OT_3_0, OT_4_0, OT_5_0, OT_6_0, OT_7_0 |
ot_work_desc | ต้องเป็น string (ถ้าระบุ) | 'ot_work_desc' must be a string |
image_content | ต้องเป็น string (ถ้าระบุ) | 'image_content' must be a string |
extra_round | ต้องเป็น Y หรือ N (ถ้าระบุ) | 'extra_round' must be either 'Y' or 'N' |
เงื่อนไขช่วงวันของ ot_work_dt ถูกตรวจแยกกันสองครั้ง (เทียบกับเวลาเริ่มและเทียบกับเวลาสิ้นสุด) จึงอาจได้รับ error ทั้งสองข้อความพร้อมกันใน errors
Business Rules
ข้อจำกัดการยื่นคำขอ:
- ไม่สามารถยื่นคำขอในงวดเงินเดือนที่ปิดแล้ว
- เวลาสิ้นสุดต้องมากกว่าเวลาเริ่มต้น
ot_work_dtต้องอยู่ในช่วง +/- 1 วันจากทั้งเวลาเริ่มต้นและเวลาสิ้นสุด- ประเภท OT ต้องเปิดใช้งานในบริษัท
- ต้องตรวจสอบว่าพนักงานมีอยู่ในระบบ
- ระบบจะคำนวณชั่วโมง OT อัตโนมัติจากเวลาเริ่มต้นและสิ้นสุด
Side Effects
เมื่อสร้างคำขอสำเร็จ ระบบจะ:
- Calculate OT Hours - คำนวณชั่วโมง OT
- Set Initial Status - ตั้งสถานะเป็น Pending (01)
- Create Notification - แจ้งเตือนผู้อนุมัติ
- Create Feed - สร้าง feed สำหรับพนักงาน
Error Handling
| Error | Cause | Solution |
|---|---|---|
Missing required parameter: 'employee_code' | ไม่ได้ส่ง employee_code | ตรวจสอบ request body |
Employee not found: XXX | ไม่พบพนักงาน | ตรวจสอบ employee_code |
OT type 'XX' is not enabled for this company | ประเภท OT ไม่เปิดใช้ | ใช้ Get OT Types ดูประเภทที่ใช้ได้ |
ไม่สามารถบันทึกได้ งวดเงินเดือนปิดแล้ว | ot_work_dt อยู่ในงวดที่ปิดแล้ว | เลือกวันที่ในงวดที่เปิดอยู่ |
'ot_work_start_hour' must be before 'ot_work_end_hour' | เวลาไม่ถูกต้อง | ตรวจสอบเวลาเริ่มต้น/สิ้นสุด |
'ot_work_dt' (...) must be within +/- 1 day of ... | วันที่รอบกะห่างจากเวลาที่ทำ OT เกิน 1 วัน | ตรวจสอบว่า ot_work_dt ตรงกับวันของเวลาเริ่มหรือเวลาสิ้นสุด |
OT Types (ประเภท OT)
API รองรับการส่งค่า ot_work_flag_lv ได้ 2 รูปแบบ:
รูปแบบที่ 1: ตัวเลข (Numeric Code)
| Code | อัตรา OT | คำอธิบาย |
|---|---|---|
01 | 1.0x | OT อัตราปกติ |
02 | 1.5x | OT อัตรา 1.5 เท่า |
03 | 2.0x | OT อัตรา 2 เท่า |
04 | 3.0x | OT อัตรา 3 เท่า |
05 | 4.0x | OT อัตรา 4 เท่า |
06 | 5.0x | OT อัตรา 5 เท่า |
07 | 6.0x | OT อัตรา 6 เท่า |
08 | 7.0x | OT อัตรา 7 เท่า |
รูปแบบที่ 2: String Format
| Code | อัตรา OT | เทียบเท่ากับ |
|---|---|---|
OT_1_0 | 1.0x | 01 |
OT_1_5 | 1.5x | 02 |
OT_2_0 | 2.0x | 03 |
OT_3_0 | 3.0x | 04 |
OT_4_0 | 4.0x | 05 |
OT_5_0 | 5.0x | 06 |
OT_6_0 | 6.0x | 07 |
OT_7_0 | 7.0x | 08 |
ระบบจะแปลง OT_X_X เป็นรหัสตัวเลขอัตโนมัติ เช่น OT_1_5 → 02
Notes
Use Cases
- พนักงานยื่นคำขอ OT - สร้างคำขอผ่าน Self-service
- HR สร้างคำขอแทน - สร้างคำขอให้พนักงานที่ไม่มี access
- Batch Submit - สร้างคำขอหลายรายการพร้อมกัน
Time Format
ot_work_dtใช้รูปแบบYYYY-MM-DDเช่น2026-01-15ot_work_start_hourและot_work_end_hourใช้รูปแบบYYYY-MM-DD HH:mm:ssเช่น2026-01-15 18:00:00
Related APIs
- Get OT Types - ดึงรายการประเภท OT
- Get OT List - ดึงรายการคำขอ OT
- Update OT - แก้ไขคำขอ OT
- Delete OT - ลบคำขอ OT