Skip to Content
🚀 Welcome to Humansoft Open API Documentation

Submit OT

ยื่นคำขอ OT ใหม่

ใช้ API นี้เพื่อสร้างคำขอ OT ใหม่ ระบบจะตรวจสอบข้อมูลและส่งเข้าสู่ขั้นตอนการอนุมัติอัตโนมัติ

Endpoint

POST /api/v1/open-apis/overtime/submit

สิทธิ์ที่ต้องการ: API Key ต้องมีสิทธิ์ ข้อมูลการยื่นเอกสาร (document:manage)

Request Parameters

Required Parameters

ParameterTypeRequiredDescriptionExample
employee_codestringYesรหัสพนักงานEMP001
ot_work_dtstringYesวันที่ของรอบกะการทำงานที่ OT นี้สังกัด (YYYY-MM-DD) — ดู OT Work Date2026-01-15
ot_work_start_hourstringYesเวลาเริ่มต้น (YYYY-MM-DD HH:mm:ss)2026-01-15 18:00:00
ot_work_end_hourstringYesเวลาสิ้นสุด (YYYY-MM-DD HH:mm:ss) ต้องมากกว่า ot_work_start_hour2026-01-15 21:00:00
ot_work_flag_lvstringYesประเภท OT รองรับทั้งรูปแบบตัวเลข (01-08) หรือ string format (OT_1_0-OT_7_0)02 หรือ OT_1_5

Optional Parameters

ParameterTypeRequiredDescriptionExample
ot_work_descstringNoรายละเอียด/เหตุผลทำงานเพิ่มเติมตามโปรเจค
image_contentstringNoไฟล์แนบในรูปแบบ Base64 (สำหรับเอกสารประกอบ) แนะนำให้มี prefix data:<mime>;base64, หากไม่มี ระบบจะระบุชนิดไฟล์จากเนื้อหาไฟล์data:image/jpeg;base64,/9j/4AAQ...
extra_roundstringNoอนุญาตให้บันทึกแม้วันที่ของ OT อยู่ในงวดที่ปิดแล้ว (Y / N) ค่าเริ่มต้นคือ NN
language_codestringNoภาษาของข้อความตอบกลับ: TH (ค่าเริ่มต้น) หรือ ENTH

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": "20251127D4573C421639", "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_flag_lv": "OT_1_5", "ot_work_desc": "ทำงานเพิ่มเติมตามโปรเจค", "approve_flag": "01", "created": "2026-01-13 09:00:00", "image_url": "https://cdn.humansoft.co.th/.../image/a1B2c3D4e5F6.png" } }

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 (e.g., 2024-01-15)" ] }

Error Response - Employee Not Found (HTTP 400)

{ "code": 400, "message": "Employee not found: EMP001" }

Error Response - Overlapping OT (HTTP 400)

{ "code": 400, "message": "ได้มีการขอเอกสารทับซ้อนกับที่ขอมาก่อนหน้าแล้ว" }

Error Response - Salary Period Closed (HTTP 400)

{ "code": 400, "message": "สิ้นสุดการคำนวณเงินเดือนไปแล้ว" }

ข้อผิดพลาดจากการตรวจสอบรูปแบบข้อมูลจะอยู่ใน errors (array) ส่วนข้อผิดพลาดอื่นจะอยู่ใน message ข้อความทางธุรกิจ (เช่น งวดปิดแล้ว, OT ทับซ้อน) แสดงเป็นภาษาไทยโดยค่าเริ่มต้น และเป็นภาษาอังกฤษเมื่อส่ง language_code เป็น EN

Response Fields

FieldTypeDescription
ot_work_idstringID ของคำขอที่สร้าง
employee_idstringID ของพนักงาน
employee_codestringรหัสพนักงาน
ot_work_dtstringวันที่ของรอบกะการทำงานที่ OT นี้สังกัด
ot_work_start_hourdatetimeเวลาเริ่มต้นที่บันทึก
ot_work_end_hourdatetimeเวลาสิ้นสุดที่บันทึก
ot_work_flag_lvstringประเภท OT — คืนกลับเป็นรูปแบบ string เสมอ (OT_1_0-OT_7_0)
ot_work_descstringรายละเอียดงาน OT
approve_flagstringสถานะการอนุมัติ (01 = รออนุมัติ)
createddatetimeวันเวลาที่สร้าง
image_urlstring | nullURL ของไฟล์แนบ, null หากไม่มีไฟล์แนบ

แม้ส่ง ot_work_flag_lv มาเป็นรหัสตัวเลข (เช่น 02) ระบบจะคืนกลับเป็นรูปแบบ string เสมอ (เช่น OT_1_5) หากระบบของท่านเทียบค่าที่ได้รับกับค่าที่ส่งไป ต้องแปลงรูปแบบก่อนเปรียบเทียบ

ระบบอาจปรับเวลาเริ่มต้น/สิ้นสุดให้สอดคล้องกับเวลากะการทำงานของพนักงานในวันนั้น (เช่น ตัดช่วงที่ทับกับเวลากะออก) — ot_work_start_hour และ ot_work_end_hour ใน response คือค่าที่บันทึกจริง ซึ่งอาจไม่ตรงกับค่าที่ส่งมา

Code Examples

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

ParameterValidationError 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 อยู่ในงวด OT หรืองวดเวลาทำงานที่ยังเปิดอยู่
  • เวลาสิ้นสุดต้องมากกว่าเวลาเริ่มต้น
  • ot_work_dt ต้องอยู่ในช่วง +/- 1 วันจากทั้งเวลาเริ่มต้นและเวลาสิ้นสุด
  • ช่วงเวลา OT ต้องไม่ทับกับคำขอ OT อื่นของพนักงานคนเดียวกัน (ไม่นับคำขอที่ไม่อนุมัติหรือถูกลบแล้ว)
  • ประเภท OT ต้องไม่ถูกปิดใช้งานสำหรับประเภทพนักงานของพนักงานคนนั้น และพนักงานต้องไม่ถูกปิดสิทธิ์ขอ OT ประเภทนั้น
  • employee_code ต้องมีอยู่ในระบบ
  • ระบบจะคำนวณชั่วโมง OT อัตโนมัติจากเวลาเริ่มต้นและสิ้นสุด

Side Effects

เมื่อสร้างคำขอสำเร็จ ระบบจะ:

  1. Calculate OT Hours - คำนวณชั่วโมง OT
  2. Set Initial Status - ตั้งสถานะเป็นรออนุมัติ (01)
  3. Create Notification - แจ้งเตือนผู้อนุมัติ (เมื่อองค์กรเปิดใช้การแจ้งเตือนเอกสาร)
  4. Create Feed - สร้าง feed ของเอกสารตามสายอนุมัติ

Error Handling

ErrorCauseSolution
Missing required parameter: 'employee_code'ไม่ได้ส่ง employee_codeตรวจสอบ request body
Employee not found: EMP001ไม่พบพนักงานจาก employee_codeตรวจสอบ employee_code
ได้มีการขอเอกสารทับซ้อนกับที่ขอมาก่อนหน้าแล้วช่วงเวลา OT ทับกับคำขอ OT อื่นของพนักงานตรวจสอบคำขอเดิมด้วย Get OT List
เวลาโอทีทับซ้อนกับกะการทำงานช่วงเวลา OT อยู่ในเวลากะการทำงานของวันนั้นปรับเวลา OT ให้อยู่นอกเวลากะ
สิ้นสุดการคำนวณเงินเดือนไปแล้วot_work_dt อยู่ในงวดที่ปิดแล้วเลือกวันที่ในงวดที่เปิดอยู่
เนื่องจากพนักงานไม่สามารถขอโอทีประเภทนี้ได้!!พนักงานถูกปิดสิทธิ์ขอ OT ประเภทนี้ตรวจสอบการตั้งค่า OT ของพนักงาน
ประเภทโอทีนี้ถูกปิดใช้งานสำหรับประเภทพนักงานของพนักงานคนนี้ ...ประเภท OT ถูกปิดสำหรับประเภทพนักงานนี้ตรวจสอบการตั้งค่าประเภท OT
โอทีประเภทนี้ขอได้เฉพาะวันทำงานเท่านั้นขอ OT ประเภทที่จำกัดให้ใช้เฉพาะวันทำงาน ในวันที่ไม่ใช่วันทำงาน (ตามการตั้งค่าขององค์กร)เลือกประเภท OT ให้ตรงกับวัน
ไม่สามารถขอเอกสารได้ เนื่องจากเกินกำหนดวันที่ขอเอกสารแล้วเกินกำหนดวันตัดรอบการขอเอกสาร OT (เมื่อองค์กรเปิดใช้)ติดต่อ HR
ไม่สามารถขอเอกสารได้ เนื่องจากเกินจำนวนโควตาการขอเอกสารเกินโควตาจำนวนเอกสาร OT ในรอบเงินเดือน (เมื่อองค์กรเปิดใช้)ติดต่อ HR
'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คำอธิบาย
011.0xOT อัตราปกติ
021.5xOT อัตรา 1.5 เท่า
032.0xOT อัตรา 2 เท่า
043.0xOT อัตรา 3 เท่า
054.0xOT อัตรา 4 เท่า
065.0xOT อัตรา 5 เท่า
076.0xOT อัตรา 6 เท่า
087.0xOT อัตรา 7 เท่า

รูปแบบที่ 2: String Format

Codeอัตรา OTเทียบเท่ากับ
OT_1_01.0x01
OT_1_51.5x02
OT_2_02.0x03
OT_3_03.0x04
OT_4_04.0x05
OT_5_05.0x06
OT_6_06.0x07
OT_7_07.0x08

ระบบจะแปลง OT_X_X เป็นรหัสตัวเลขอัตโนมัติ เช่น OT_1_5 → 02

Notes

Use Cases

  1. พนักงานยื่นคำขอ OT - สร้างคำขอผ่าน Self-service
  2. HR สร้างคำขอแทน - สร้างคำขอให้พนักงานที่ไม่มี access
  3. สร้างหลายรายการ - API นี้สร้างคำขอได้ครั้งละ 1 รายการ หากต้องการนำเข้าหลายรายการพร้อมกันให้ใช้ Import OT

Time Format

  • ot_work_dt ใช้รูปแบบ YYYY-MM-DD เช่น 2026-01-15
  • ot_work_start_hour และ ot_work_end_hour ใช้รูปแบบ YYYY-MM-DD HH:mm:ss เช่น 2026-01-15 18:00:00
Last updated on