Skip to Content
🚀 Welcome to Humansoft Open API Documentation

Get OT List

ดึงรายการคำขอ OT ตามเงื่อนไขที่กำหนด พร้อมรองรับการ filter และ pagination

ใช้ API นี้เพื่อดึงรายการคำขอ OT ติดตามสถานะการอนุมัติ หรือสร้างรายงานสรุป

Endpoint

GET /api/v1/open-apis/overtime/get-list

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

Request Parameters

Required Parameters

ParameterTypeRequiredDescriptionExample
start_datestringYesวันที่เริ่มต้น (YYYY-MM-DD) — กรองตาม ot_work_dt2026-01-01
end_datestringYesวันที่สิ้นสุด (YYYY-MM-DD) ต้องไม่น้อยกว่า start_date — กรองตาม ot_work_dt2026-01-31

Optional Parameters

ParameterTypeRequiredDescriptionExample
employee_codestringNoรหัสพนักงานEMP001
approve_flagstringNoสถานะการอนุมัติ (01, 02, 03) — ดู Approve Flag Values01
ot_work_flag_lvstringNoประเภท OT (01-08) — response จะคืนเป็น OT_X_X format02
keywordstringNoคำค้นหาบางส่วนจากชื่อ นามสกุล ชื่อเล่น (ไทย/อังกฤษ) หรือรหัสพนักงานสมชาย
company_idstringNoID บริษัท (Base64)MjAyNTExMjdENDU3M0M0MjE2Mzk=
branch_idstringNoID สาขา (Base64)MjAyNTExMjdENDU3M0M0MjE2Mzk=
department_idstringNoID แผนก (Base64)MjAyNTExMjdENDU3M0M0MjE2Mzk=
sort_bystringNoเรียงตาม field — ดู Sort By Optionsot_work_dt
sort_orderstringNoลำดับการเรียง (ASC, DESC — ตัวพิมพ์เล็กก็ได้)DESC
_PAGEnumberNoหน้าที่ต้องการ (ค่าเริ่มต้น 1)1
_NUMBER_PER_PAGEnumberNoจำนวนรายการต่อหน้า (1-100, ค่าเริ่มต้น 10)10

Approve Flag Values

ValueStatusDescription
01Pendingเอกสารที่ยังไม่สิ้นสุดการอนุมัติ — ดึงสถานะ 01, 04, 05, 06, 07, 08
02Approvedอนุมัติแล้ว
03Not Approvedไม่อนุมัติ

Sort By Options

  • ot_work_dt - วันที่ทำ OT (default, เรียงจากเก่าไปใหม่)
  • employee_code - รหัสพนักงาน
  • approve_flag - สถานะการอนุมัติ
  • created - วันที่สร้าง
  • ot_work_hour - จำนวนชั่วโมง OT ที่ระบบคำนวณ (ใช้สำหรับเรียงลำดับเท่านั้น ไม่มี field นี้ใน response)

เมื่อเรียงตาม ot_work_dt (ค่าเริ่มต้น) ผลการเรียงจะกลับด้านกับ sort_order — ไม่ส่งหรือส่ง DESC จะได้วันที่ทำ OT จากเก่าไปใหม่ ส่วน ASC จะได้จากใหม่ไปเก่า การเรียงตาม field อื่นเป็นไปตาม sort_order ตามปกติ

Response Format

Success Response (HTTP 200)

{ "code": 200, "message": "สำเร็จ", "payload": [ { "ot_work_id": "20251127D4573C421639", "employee_code": "EMP001", "employee_name": "สมชาย", "employee_last_name": "ใจดี", "employee_nickname": "ชาย", "employee_name_en": "Somchai", "employee_last_name_en": "Jaidee", "employee_nickname_en": "Chai", "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_flag_name": "OT 1.5", "ot_work_flag_name_en": "OT 1.5x", "ot_work_desc": "ทำงานเพิ่มเติมตามโปรเจค", "approve_flag": "01", "approve_status": "Pending", "approve_id": "20251127D4573C421639", "approve_upd": "2026-01-13 10:30:00", "approve_remark": "", "created": "2026-01-13 09:00:00", "created_by": "20251127D4573C421639", "last_upd": "2026-01-13 10:30:00", "last_upd_by": "20251127D4573C421639", "image_url": "https://cdn.humansoft.co.th/.../image/a1B2c3D4e5F6.png" } ], "_PAGINATION": { "_TOTAL_RECORDS": 25, "_PAGE": 1, "_NUMBER_PER_PAGE": 20 } }

Success Response - No Data (HTTP 200)

{ "code": 200, "message": "สำเร็จ", "payload": [], "_PAGINATION": { "_TOTAL_RECORDS": 0, "_PAGE": 1, "_NUMBER_PER_PAGE": 10 } }

Error Response - Validation Failed (HTTP 400)

{ "code": 400, "message": "ไม่สำเร็จ", "errors": [ "Missing required parameter: 'start_date'", "'end_date' must be in format YYYY-MM-DD" ] }

Error Response - Employee Not Found (HTTP 400)

{ "code": 400, "message": "ไม่สำเร็จ", "error": "Employee not found: EMP001" }

ข้อผิดพลาดจากการตรวจสอบ parameter จะอยู่ใน errors (array) ส่วนข้อผิดพลาดอื่น (เช่น ไม่พบพนักงาน) จะอยู่ใน error (string)

Response Fields

FieldTypeDescription
ot_work_idstringID ของคำขอ OT
employee_codestringรหัสพนักงาน
employee_namestringชื่อพนักงาน (ไทย)
employee_last_namestringนามสกุลพนักงาน (ไทย)
employee_nicknamestringชื่อเล่น (ไทย)
employee_name_enstringชื่อพนักงาน (อังกฤษ)
employee_last_name_enstringนามสกุลพนักงาน (อังกฤษ)
employee_nickname_enstringชื่อเล่น (อังกฤษ)
ot_work_dtstringวันที่ของรอบกะการทำงานที่ OT นี้สังกัด (YYYY-MM-DD)
ot_work_start_hourdatetimeเวลาเริ่มต้น
ot_work_end_hourdatetimeเวลาสิ้นสุด
ot_work_flag_lvstringประเภท OT ในรูปแบบ string (OT_1_0-OT_7_0)
ot_work_flag_namestringชื่อประเภท OT (ไทย)
ot_work_flag_name_enstringชื่อประเภท OT (อังกฤษ)
ot_work_descstringรายละเอียดการทำ OT
approve_flagstringรหัสสถานะการอนุมัติ
approve_statusstringชื่อสถานะการอนุมัติ (ดูตาราง Approve Status Values)
approve_idstringuser ID ของผู้ดำเนินการกับสถานะเอกสารล่าสุด (ผู้ยื่น/ผู้แก้ไข หรือผู้อนุมัติ)
approve_upddatetimeวันเวลาที่ดำเนินการกับสถานะเอกสารล่าสุด
approve_remarkstringหมายเหตุการอนุมัติ
createddatetimeวันเวลาที่สร้าง
created_bystringuser ID ของผู้สร้างเอกสาร
last_upddatetimeวันเวลาที่แก้ไขล่าสุด
last_upd_bystringuser ID ของผู้แก้ไขล่าสุด
image_urlstring | nullURL ของไฟล์แนบ, null หากไม่มีไฟล์แนบ

Approve Status Values

approve_flagapprove_statusDescription
01Pendingรออนุมัติ
02Approvedอนุมัติแล้ว
03Not Approvedไม่อนุมัติ
04Manager Approvedผ่านการอนุมัติขั้นที่ 1 แล้ว รอขั้นถัดไป
05Recheckส่งกลับตรวจสอบอีกครั้ง
06Manager Approvedผ่านการอนุมัติขั้นที่ 2 แล้ว รอขั้นถัดไป
07Manager Approvedผ่านการอนุมัติขั้นที่ 3 แล้ว รอขั้นถัดไป
08Manager Approvedผ่านการอนุมัติขั้นที่ 4 แล้ว รอขั้นถัดไป
ค่าอื่นunknown—

Code Examples

curl -X GET "https://openapi.humansoft.co.th/api/v1/open-apis/overtime/get-list?start_date=2026-01-01&end_date=2026-01-31&approve_flag=01&_NUMBER_PER_PAGE=20" \ -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY"

Validation Rules

ParameterValidationError Message
start_dateต้องระบุMissing required parameter: 'start_date'
start_dateต้องอยู่ในรูปแบบ YYYY-MM-DD'start_date' must be in format YYYY-MM-DD
start_dateต้องเป็นวันที่ที่มีอยู่จริงตามปฏิทิน'start_date' is not a valid date
end_dateต้องระบุMissing required parameter: 'end_date'
end_dateต้องอยู่ในรูปแบบ YYYY-MM-DD'end_date' must be in format YYYY-MM-DD
end_dateต้องเป็นวันที่ที่มีอยู่จริงตามปฏิทิน'end_date' is not a valid date
end_dateต้อง >= start_date'end_date' must be greater than or equal to 'start_date'
approve_flagต้องเป็น 01, 02, หรือ 03'approve_flag' must be one of: 01, 02, 03
ot_work_flag_lvต้องเป็น 01-08'ot_work_flag_lv' must be one of: 01, 02, 03, 04, 05, 06, 07, 08
sort_byต้องเป็นค่าใน Sort By Options'sort_by' must be one of: ot_work_dt, employee_code, approve_flag, created, ot_work_hour
sort_orderต้องเป็น ASC หรือ DESC'sort_order' must be either 'ASC' or 'DESC'
_PAGEต้องเป็นตัวเลขตั้งแต่ 1 ขึ้นไป'_PAGE' must be a positive number
_NUMBER_PER_PAGEต้องเป็นตัวเลข 1-100'_NUMBER_PER_PAGE' must be a number between 1 and 100

Notes

  • approve_flag = '01' จะดึงรายการที่ยังไม่สิ้นสุดการอนุมัติทั้งหมด (01, 04, 05, 06, 07, 08) รวมถึงสถานะ 05 (Recheck)
  • start_date และ end_date ใช้กรองตาม ot_work_dt โดยรวมทั้งวันเริ่มต้นและวันสิ้นสุด
  • คำขอที่ถูกลบแล้วจะไม่แสดงในรายการ

Use Cases

  1. แสดงรายการรออนุมัติ - ใช้ approve_flag=01 เพื่อดึงคำขอที่รออนุมัติ
  2. ค้นหาตามพนักงาน - ใช้ employee_code หรือ keyword เพื่อค้นหา
  3. รายงานประจำเดือน - ใช้ start_date และ end_date ของเดือนนั้น
  4. Filter ตามแผนก - ใช้ department_id เพื่อกรองตามแผนก
  5. Filter ตามประเภท OT - ใช้ ot_work_flag_lv เพื่อกรองตามประเภท

Error Handling

ErrorCauseSolution
Missing required parameter: 'start_date'ไม่ได้ส่ง start_dateตรวจสอบ query parameter
'start_date' must be in format YYYY-MM-DDรูปแบบวันที่ไม่ถูกต้องใช้รูปแบบ YYYY-MM-DD
'end_date' must be greater than or equal to 'start_date'end_date น้อยกว่า start_dateตรวจสอบช่วงวันที่
Employee not found: EMP001ไม่พบพนักงานจาก employee_code (อยู่ใน field error)ตรวจสอบ employee_code
  • Get OT Types - ดึงรายการประเภท OT
  • Submit OT - ยื่นคำขอ OT ใหม่
Last updated on