Skip to Content
🚀 Welcome to Humansoft Open API Documentation

Submit Change Request

ยื่นคำขอเปลี่ยนกะใหม่

ใช้ API นี้เพื่อยื่นคำขอเปลี่ยนกะหรือสลับกะ คำขอที่ยื่นสำเร็จจะมีสถานะรออนุมัติ (01) และเข้าสู่ขั้นตอนการอนุมัติตามการตั้งค่าขององค์กร

Endpoint

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

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

Request Parameters

Required Parameters

ParameterTypeRequiredDescriptionExample
employee_codestringYesรหัสพนักงานEMP001
work_cycle_change_dtstringYesวันที่ต้องการเปลี่ยนกะ (YYYY-MM-DD)2026-01-20
work_cycle_mode_lvstringYesโหมด (change หรือ switch)change
work_cycle_idstringYesID ของกะที่ต้องการเปลี่ยนไป (Base64)MjAyNTExMjdENDU3M0M0MjE2Mzk=

Optional Parameters

ParameterTypeRequiredDescriptionExample
work_cycle_change_descstringNoรายละเอียด/เหตุผลต้องไปธุระช่วงเช้า
image_contentstringNoไฟล์แนบ (Base64 encoded)data:image/png;base64,...
authorize_idstringNoID ผู้ทำรายการ (Base64)MjAyNjA0MzBVU0VSMDAwMDAx

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

Switch Mode Additional Parameters

ParameterTypeRequiredDescriptionExample
work_cycle_switch_dtstringYes (switch)วันที่สลับกะ (YYYY-MM-DD)2026-01-21
switch_work_cycle_id_fromstringYes (switch)ID กะเดิม — ส่งเป็นค่า raw (ไม่ต้องเข้ารหัส Base64)20251127D4573C421639
switch_work_cycle_id_tostringYes (switch)ID กะที่สลับไป — ส่งเป็นค่า raw (ไม่ต้องเข้ารหัส Base64)20251127D4573C421639

Request Body Example

Change Mode

{ "employee_code": "EMP001", "work_cycle_change_dt": "2026-01-20", "work_cycle_mode_lv": "change", "work_cycle_id": "MjAyNTExMjdENDU3M0M0MjE2Mzk=", "work_cycle_change_desc": "ต้องไปธุระช่วงเช้า" }

Switch Mode

{ "employee_code": "EMP001", "work_cycle_change_dt": "2026-01-20", "work_cycle_mode_lv": "switch", "work_cycle_id": "MjAyNTExMjdENDU3M0M0MjE2Mzk=", "work_cycle_switch_dt": "2026-01-21", "switch_work_cycle_id_from": "20251127D4573C421639", "switch_work_cycle_id_to": "20251127D4573C421639", "work_cycle_change_desc": "ขอสลับกะ" }

Response Format

Success Response (HTTP 200)

{ "code": 200, "message": "Success", "payload": { "work_cycle_change_id": "20251127D4573C421639", "employee_id": "20251127D4573C421639", "employee_code": "EMP001", "work_cycle_change_dt": "2026-01-20", "work_cycle_mode_lv": "change", "work_cycle_id": "20251127D4573C421639", "work_cycle_code": "B", "work_cycle_switch_dt": null, "switch_work_cycle_id_from": null, "switch_work_cycle_id_to": null, "work_cycle_change_desc": "ต้องไปธุระช่วงเช้า", "approve_flag": "01", "approve_id": "20251127D4573C421639", "approve_upd": "2026-01-14 10:30:00", "approve_remark": "", "created": "2026-01-14 10:30:00", "last_upd": "2026-01-14 10:30:00", "image_url": null } }

Error Response - Validation Failed (HTTP 400)

{ "code": 400, "message": "Validation failed", "errors": [ "Missing required parameter: 'employee_code'", "'work_cycle_change_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 - OT Conflict (HTTP 400)

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

Error Response - Salary Period Closed (HTTP 400)

{ "code": 400, "message": "ไม่สามารถเพิ่มข้อมูลได้เนื่องจากปิดงวดเงินเดือนแล้ว" }

Error Response - Duplicate Request (HTTP 400)

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

ข้อความ error ที่เป็นภาษาไทยจะแสดงเป็นภาษาอังกฤษเมื่อส่ง language_code = EN เช่น ไม่สามารถเพิ่มข้อมูลได้เนื่องจากปิดงวดเงินเดือนแล้ว → Payroll period has been closed

Response Fields

FieldTypeDescription
work_cycle_change_idstringID ของคำขอเปลี่ยนกะ
employee_idstringID ของพนักงาน
employee_codestringรหัสพนักงาน
work_cycle_change_dtstringวันที่เปลี่ยนกะ (YYYY-MM-DD)
work_cycle_mode_lvstringโหมด (change, switch)
work_cycle_idstringID ของกะที่เปลี่ยนไป
work_cycle_codestringรหัสกะ
work_cycle_switch_dtstring | nullวันที่สลับกะ (ใช้กับโหมด switch)
switch_work_cycle_id_fromstring | nullID กะเดิม (ใช้กับโหมด switch)
switch_work_cycle_id_tostring | nullID กะที่สลับไป (ใช้กับโหมด switch)
work_cycle_change_descstringเหตุผล/รายละเอียด
approve_flagstringรหัสสถานะอนุมัติ — คำขอที่ยื่นใหม่เป็น 01 (รออนุมัติ)
approve_idstringuser_id ของผู้ทำรายการล่าสุด (ผู้ยื่น/แก้ไขคำขอ หรือผู้อนุมัติ)
approve_upddatetimeวันเวลาที่ปรับสถานะล่าสุด (ยื่น/แก้ไข/อนุมัติ)
approve_remarkstringหมายเหตุการอนุมัติ
createddatetimeวันเวลาที่สร้าง
last_upddatetimeวันเวลาที่แก้ไขล่าสุด
image_urlstring | nullURL ของไฟล์แนบ, null หากไม่มีไฟล์แนบ

Code Examples

curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/work-cycle-change/submit" \ -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "employee_code": "EMP001", "work_cycle_change_dt": "2026-01-20", "work_cycle_mode_lv": "change", "work_cycle_id": "MjAyNTExMjdENDU3M0M0MjE2Mzk=", "work_cycle_change_desc": "ต้องไปธุระช่วงเช้า" }'

Validation Rules

ParameterValidationError Message
employee_codeต้องระบุและเป็น stringMissing required parameter: 'employee_code'
employee_codeต้องพบพนักงานในระบบEmployee not found: EMP001
work_cycle_change_dtต้องระบุและรูปแบบ YYYY-MM-DD'work_cycle_change_dt' must be in Y-m-d format (e.g., 2024-01-15)
work_cycle_mode_lvต้องระบุMissing required parameter: 'work_cycle_mode_lv'
work_cycle_mode_lvต้องเป็น change หรือ switch'work_cycle_mode_lv' must be 'change' or 'switch'
work_cycle_idต้องระบุMissing required parameter: 'work_cycle_id'
work_cycle_switch_dtต้องระบุ (switch mode)Missing required parameter: 'work_cycle_switch_dt' for switch mode
work_cycle_switch_dtรูปแบบ YYYY-MM-DD (switch mode)'work_cycle_switch_dt' must be in Y-m-d format
switch_work_cycle_id_fromต้องระบุ (switch mode)Missing required parameter: 'switch_work_cycle_id_from' for switch mode
switch_work_cycle_id_toต้องระบุ (switch mode)Missing required parameter: 'switch_work_cycle_id_to' for switch mode
work_cycle_change_descต้องเป็น string (ถ้าระบุ)'work_cycle_change_desc' must be a string
image_contentต้องเป็น string (ถ้าระบุ)'image_content' must be a string

Business Rules

ข้อจำกัดการยื่นคำขอ:

  • ไม่สามารถยื่นได้หากมีเอกสาร OT ที่อนุมัติแล้วในวันเดียวกัน
  • ไม่สามารถยื่นได้หากงวดเงินเดือนของวันที่ในคำขอปิดแล้ว ยกเว้นวันที่นั้นอยู่ในงวด OT หรืองวดเวลาทำงานที่ยังเปิดอยู่
  • ไม่สามารถยื่นได้หากพนักงานมีคำขอเปลี่ยนกะในวันเดียวกันอยู่แล้ว (ไม่นับคำขอที่ไม่อนุมัติ 03)
  • ตรวจ cut-off date ตามการตั้งค่า cut-off ของเอกสารเปลี่ยนกะขององค์กร
  • จำกัดจำนวนคำขอต่อรอบเงินเดือนตามการตั้งค่าโควตาขององค์กร

Error Handling

ErrorCauseSolution
Validation failedข้อมูลใน request ไม่ถูกต้อง (ดูรายละเอียดใน errors)แก้ไขตาม Validation Rules
Employee not found: EMP001ไม่พบพนักงานจาก employee_codeตรวจสอบ employee_code
ไม่สามารถบันทึกได้ เพราะ มีเอกสารโอทีแล้ว!!มีเอกสาร OT ที่อนุมัติแล้วในวันเดียวกันตรวจสอบเอกสาร OT ของพนักงานในวันนั้น
ไม่สามารถเพิ่มข้อมูลได้เนื่องจากปิดงวดเงินเดือนแล้วงวดเงินเดือนปิดแล้วเลือกวันที่ในงวดที่เปิด
ไม่สามารถขอเอกสารได้ เนื่องจากเกินกำหนดวันที่ขอเอกสารแล้วเกิน Cut-off dateติดต่อ HR
ไม่สามารถขอเอกสารได้ เนื่องจากเกินจำนวนโควตาแล้วเกิน Quota limitรอรอบถัดไป
ไม่สามารถบันทึกได้ เพราะได้มีการขอเอกสารทับซ้อนกับที่ขอมาก่อนหน้าแล้ว!!มีคำขอเปลี่ยนกะของพนักงานในวันเดียวกันอยู่แล้วแก้ไขคำขอเดิมแทน

Notes

Use Cases

  1. ขอเปลี่ยนกะ - ส่ง work_cycle_mode_lv = change พร้อมกะที่ต้องการ (work_cycle_id) ของวันที่ work_cycle_change_dt
  2. ขอสลับกะ - ส่ง work_cycle_mode_lv = switch พร้อม work_cycle_switch_dt, switch_work_cycle_id_from และ switch_work_cycle_id_to
  3. ยื่นคำขอแทนพนักงาน - ระบุ employee_code ของพนักงานที่ต้องการยื่นคำขอให้

หา work_cycle_id

  • ใช้ Get Work Cycle Types เพื่อดู work_cycle_id ของกะทั้งหมด แล้วเข้ารหัส Base64 ก่อนส่งใน work_cycle_id ส่วน switch_work_cycle_id_from และ switch_work_cycle_id_to ให้ส่งค่า raw ตามที่ได้รับ (ไม่ต้องเข้ารหัส Base64)
Last updated on