Skip to Content
🚀 Welcome to Humansoft Open API Documentation

Approve Work Cycle Change

อนุมัติ ปฏิเสธ หรือส่งเอกสารเปลี่ยนกะการทำงานกลับให้ตรวจสอบอีกครั้ง รองรับการอนุมัติแบบหลายขั้นตอน (Multi-level Approval)

ใช้ API นี้เพื่ออนุมัติ ปฏิเสธ หรือส่งเอกสารเปลี่ยนกะกลับให้ตรวจสอบอีกครั้ง (Recheck) เมื่ออนุมัติขั้นสุดท้ายระบบจะเปลี่ยนกะให้พนักงานอัตโนมัติ

Endpoint

POST /api/v1/open-apis/work-cycle-change/approve

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

Request Parameters

Required Parameters

ParameterTypeRequiredDescriptionExample
work_cycle_change_idstringYesรหัสเอกสารเปลี่ยนกะ (Base64)MjAyNTExMjdENDU3M0M0MjE2Mzk=
employee_codestringYesรหัสพนักงานเจ้าของเอกสารEMP001
approve_flagstringYesการดำเนินการ (02-08) ดูตาราง Option Values02
authorize_idstringYesรหัสผู้อนุมัติ (Base64)MjAyNTExMjdENDU3M0M0MjE2Mzk=

หา authorize_id ได้อย่างไร: รับค่าจาก Get Employee Data Filter โดยใช้ path_action=get-user พร้อม employee_code ของผู้ทำรายการ — ใช้ค่า user_id ที่ได้กลับมาเป็น authorize_id

Optional Parameters

ParameterTypeDefaultDescription
approve_remarkstring""หมายเหตุการอนุมัติ (บังคับเมื่อ approve_flag = 03)
authorize_lineboolean-ส่ง true เพื่อทำรายการในฐานะผู้อนุมัติตามสายอนุมัติ ระบบจะคำนวณขั้นอนุมัติตามสายแม้ผู้ทำรายการมีสิทธิ์ HR และใช้ประกอบการตรวจ cut-off date
extra_roundstring"N"Y = ข้ามการตรวจสอบงวดเงินเดือนที่ปิดแล้ว (งวดพิเศษ)
no_hr_permissionbooleanfalsetrue = ยกเลิกการยกเว้นการตรวจสอบ cut-off date ของผู้ทำรายการที่มีสิทธิ์ HR

Option Values for approve_flag

ค่าสถานะ (TH)สถานะ (EN)การทำงาน
02อนุมัติApprovedอนุมัติเอกสาร — ระบบคำนวณขั้นตามสายอนุมัติ ถ้าเป็นขั้นสุดท้ายจะเปลี่ยนกะให้พนักงานอัตโนมัติ
03ไม่อนุมัติNot Approvedปฏิเสธเอกสาร (ต้องส่ง approve_remark)
04หัวหน้าอนุมัติขั้นที่ 1Manager Approved Step 1ส่งต่อไปยังขั้นตอนถัดไป
05ส่งกลับตรวจสอบอีกครั้งRecheckส่งเอกสารกลับให้ตรวจสอบอีกครั้ง เอกสารกลับไปอยู่ในกลุ่มรออนุมัติ
06หัวหน้าอนุมัติขั้นที่ 2Manager Approved Step 2ส่งต่อไปยังขั้นตอนถัดไป
07หัวหน้าอนุมัติขั้นที่ 3Manager Approved Step 3ส่งต่อไปยังขั้นตอนถัดไป
08หัวหน้าอนุมัติขั้นที่ 4Manager Approved Step 4ส่งต่อไปยังขั้นตอนถัดไป

การคำนวณขั้นอนุมัติเมื่อส่ง approve_flag = 02

  • ผู้ทำรายการมีสิทธิ์ HR และไม่ได้ส่ง authorize_line = true — ระบบบันทึกเป็น 02 (อนุมัติขั้นสุดท้าย) ทันที
  • กรณีอื่น ระบบตรวจว่าผู้ทำรายการเป็นผู้อนุมัติขั้นใดในสายอนุมัติของพนักงาน — ขั้นสุดท้ายได้ 02 ขั้นก่อนหน้าได้ 04, 06, 07 หรือ 08 ตามลำดับขั้น
  • ถ้าผู้ทำรายการไม่ได้อยู่ในสายอนุมัติ ระบบจะบันทึกสถานะเป็น 01 (รออนุมัติ) และตอบกลับ HTTP 200 — ความคืบหน้าการอนุมัติเดิมของเอกสารจะถูกรีเซ็ต
  • ถ้าองค์กรกำหนดให้เอกสารประเภทนี้อนุมัติโดย HR หรือพนักงานไม่มีผู้อนุมัติในสาย ระบบบันทึกเป็น 02

ค่าอื่น (03-08) ระบบบันทึกตามค่าที่ส่งมาโดยไม่คำนวณขั้น — ตรวจสอบสถานะที่บันทึกจริงได้จาก approve_flag ใน response

authorize_line ต้องส่งเป็น boolean true (ไม่ใช่ string) จึงจะมีผลกับการคำนวณขั้นอนุมัติ

ระบบไม่ได้ปฏิเสธการทำรายการกับเอกสารที่อนุมัติ (02) หรือไม่อนุมัติ (03) ไปแล้ว ควรตรวจสถานะเอกสารจาก Get List ก่อนเรียก API นี้ทุกครั้ง

Request Body Example

{ "work_cycle_change_id": "MjAyNTExMjdENDU3M0M0MjE2Mzk=", "employee_code": "EMP001", "approve_flag": "02", "authorize_id": "MjAyNTExMjdENDU3M0M0MjE2Mzk=", "approve_remark": "อนุมัติเปลี่ยนกะ" }

Response Format

Success Response (HTTP 200)

{ "code": 200, "message": "สำเร็จ", "payload": { "work_cycle_change_id": "20251127D4573C421639", "employee_code": "EMP001", "approve_flag": "02", "approve_remark": "อนุมัติเปลี่ยนกะ", "approved_at": "2026-04-30 10:30:00" } }

Error Response - Validation Failed (HTTP 400)

{ "code": 400, "message": "Validation failed", "errors": [ "'approve_flag' must be one of: 02, 03, 04, 05, 06, 07, 08", "Missing required parameter: 'authorize_id'" ] }

Error Response - Remark Required for Rejection (HTTP 400)

{ "code": 400, "message": "Validation failed", "errors": [ "'approve_remark' is required for rejection (approve_flag='03')" ] }

Error Response - Employee Not Found (HTTP 400)

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

Error Response - Document Not Found (HTTP 400)

{ "code": 400, "message": "ไม่พบเอกสาร" }

Error Response - Overtime Exists (HTTP 400)

{ "code": 400, "message": "ไม่สามารถบันทึกได้ เพราะ มีเอกสารโอทีแล้ว!!" }

Error Response - Salary Period Closed (HTTP 400)

{ "code": 400, "message": "Cannot approve because salary calculation period is closed" }

Error Response - Cut-off Date Exceeded (HTTP 400)

{ "code": 400, "message": "Unable to approve the document as the request deadline has already passed." }

ข้อความ error ที่เป็นภาษาไทยจะแสดงเป็นภาษาอังกฤษเมื่อส่ง language_code = EN เช่น ไม่พบเอกสาร → Document not found

Response Fields

FieldTypeDescription
work_cycle_change_idstringรหัสเอกสารเปลี่ยนกะ
employee_codestringรหัสพนักงานเจ้าของเอกสาร
approve_flagstringสถานะที่บันทึกจริงหลังระบบคำนวณขั้นอนุมัติ (อาจต่างจากค่าที่ส่งมา เช่น ส่ง 02 แต่ได้ 04)
approve_remarkstringหมายเหตุการอนุมัติ
approved_atstringวันเวลาที่ทำรายการ (YYYY-MM-DD HH:MM:SS)

Code Examples

curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/work-cycle-change/approve" \ -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "work_cycle_change_id": "MjAyNTExMjdENDU3M0M0MjE2Mzk=", "employee_code": "EMP001", "approve_flag": "02", "authorize_id": "MjAyNTExMjdENDU3M0M0MjE2Mzk=", "approve_remark": "อนุมัติเปลี่ยนกะ" }'

Validation Rules

ParameterValidationError Message
work_cycle_change_idต้องระบุและเป็น stringMissing required parameter: 'work_cycle_change_id'
employee_codeต้องระบุและเป็น stringMissing required parameter: 'employee_code'
employee_codeต้องพบพนักงานในระบบEmployee not found: EMP001
approve_flagต้องระบุMissing required parameter: 'approve_flag'
approve_flagต้องเป็น 02-08'approve_flag' must be one of: 02, 03, 04, 05, 06, 07, 08
approve_remarkบังคับเมื่อ approve_flag = 03 (ปฏิเสธ)'approve_remark' is required for rejection (approve_flag='03')
authorize_idต้องระบุและเป็น stringMissing required parameter: 'authorize_id'
authorize_idต้องพบผู้ใช้ในระบบUser associated with 'authorize_id' not found in the system
work_cycle_change_idต้องมีอยู่ในระบบไม่พบเอกสาร

Business Rules

ข้อจำกัดการอนุมัติ:

  • เมื่อส่ง approve_flag = 02 ระบบคำนวณขั้นถัดไปตามสายอนุมัติ (ดูหัวข้อ Option Values)
  • เมื่อสถานะที่บันทึกเป็น 02 ระบบจะตรวจเอกสารเปลี่ยนกะที่ทับซ้อน แล้วเปลี่ยนกะให้พนักงานอัตโนมัติ
  • การปฏิเสธ (approve_flag = 03) ต้องระบุ approve_remark เสมอ
  • การตรวจสอบต่อไปนี้ทำกับทุกค่า approve_flag รวมถึงการปฏิเสธและการส่งกลับตรวจสอบ:
    • ไม่สามารถทำรายการได้หากมีเอกสาร OT ที่อนุมัติแล้วในวันเดียวกัน
    • ไม่สามารถทำรายการได้หากงวดเงินเดือนของวันที่ในเอกสารปิดแล้ว ยกเว้นส่ง extra_round = Y หรือวันที่นั้นอยู่ในงวด OT หรืองวดเวลาทำงานที่ยังเปิดอยู่
    • ตรวจ cut-off date ตามการตั้งค่า cut-off ของเอกสารเปลี่ยนกะขององค์กร (ขึ้นกับกลุ่มผู้ใช้ที่องค์กรกำหนดให้มีผล)
  • ระบบจะส่งการแจ้งเตือนตามการตั้งค่าการแจ้งเตือนเอกสารขององค์กร

Error Handling

ErrorCauseSolution
Missing required parameter: 'work_cycle_change_id'ไม่ได้ส่ง work_cycle_change_idตรวจสอบ request body
Missing required parameter: 'authorize_id'ไม่ได้ส่ง authorize_idตรวจสอบ request body
'approve_flag' must be one of: 02, 03, 04, 05, 06, 07, 08ค่า approve_flag ไม่ถูกต้องใช้ค่า 02-08 ตามตาราง Option Values
'approve_remark' is required for rejection (approve_flag='03')ปฏิเสธโดยไม่ระบุหมายเหตุส่ง approve_remark เมื่อ approve_flag = 03
Employee not found: EMP001ไม่พบพนักงานจาก employee_codeตรวจสอบ employee_code
User associated with 'authorize_id' not found in the systemไม่พบผู้ใช้จาก authorize_idตรวจสอบ authorize_id
ไม่พบเอกสารไม่พบเอกสารตรวจสอบ work_cycle_change_id
ไม่สามารถบันทึกได้ เพราะได้มีการขอเอกสารทับซ้อนกับที่ขอมาก่อนหน้าแล้ว!!มีเอกสารเปลี่ยนกะทับซ้อน (ตรวจเมื่ออนุมัติขั้นสุดท้าย)ตรวจสอบเอกสารเปลี่ยนกะของพนักงานในวันนั้น
ไม่สามารถบันทึกได้ เพราะ มีเอกสารโอทีแล้ว!!มีเอกสาร OT ที่อนุมัติแล้วในวันเดียวกันตรวจสอบเอกสาร OT ของพนักงานในวันนั้น
Cannot approve because salary calculation period is closedงวดเงินเดือนปิดแล้วส่ง extra_round = Y หากต้องการทำรายการในงวดพิเศษ
Unable to approve the document as the request deadline has already passed.เกินวัน cut-offติดต่อ HR เพื่อดำเนินการ

Notes

Use Cases

  1. หัวหน้าอนุมัติคำขอ - ส่ง approve_flag = 02 ระบบจะคำนวณขั้นตามตำแหน่งของผู้ทำรายการในสายอนุมัติ
  2. HR อนุมัติหรือปฏิเสธเอกสาร - อนุมัติหรือปฏิเสธเอกสารในฐานะ HR
  3. ส่งกลับตรวจสอบอีกครั้ง - ส่ง approve_flag = 05 เพื่อส่งเอกสารกลับให้ตรวจสอบอีกครั้ง

Approval Flow

  • 04 -> 06 -> 07 -> 08 -> 02 (ตามจำนวนขั้นในสายอนุมัติที่กำหนด สูงสุด 5 ขั้น)
  • ส่ง approve_flag = 02 แล้วให้ระบบคำนวณขั้นถัดไปเอง ไม่จำเป็นต้องส่ง 04-08 เอง
  • เมื่อผู้อนุมัติขั้นสุดท้ายอนุมัติ ระบบจะเปลี่ยนสถานะเป็น 02 (Approved) และเปลี่ยนกะให้พนักงานทันที

HR Special Permission

  • ผู้ทำรายการที่มีสิทธิ์ HR สามารถอนุมัติขั้นสุดท้ายได้ทันทีโดยไม่ต้องผ่านสายอนุมัติ
  • โดยปกติ HR ไม่ถูกตรวจสอบ cut-off date ยกเว้นองค์กรตั้งค่าให้ cut-off มีผลกับผู้ใช้ทุกกลุ่ม
  • หากต้องการให้ HR อนุมัติตามสายอนุมัติ ให้ส่ง authorize_line = true
  • ส่ง no_hr_permission = true เพื่อยกเลิกการยกเว้น cut-off date ของ HR — การตรวจจริงยังขึ้นกับการตั้งค่า cut-off ขององค์กร
Last updated on