Calculation OT API Module
ภาพรวม (Overview)
โมดูล Calculation OT เป็น API สำหรับจัดการ งวดโอที (OT Round) ตั้งแต่การสร้างงวด กำหนดรายชื่อพนักงานในงวด สั่งคำนวณยอดโอที ไปจนถึงการปิดงวด รวมถึงการจัดการ Template รูปแบบงวดที่ใช้ซ้ำทุกเดือน
โมดูลนี้ใช้กับองค์กรที่ตั้งค่าให้ งวดโอทีแยกออกจากงวดเวลาทำงาน เช่น งวดเงินเดือนตัดรอบสิ้นเดือน แต่งวดโอทีตัดรอบวันที่ 21 ถึง 20 — องค์กรที่ไม่ได้แยกงวดโอทีไม่ต้องใช้โมดูลนี้ เพราะการคำนวณงวดเงินเดือนคิดยอดโอทีให้ในตัวอยู่แล้ว
สิทธิ์ที่ต้องการ: API ในโมดูลนี้ต้องการสิทธิ์ ข้อมูลเงินเดือนของพนักงาน (payroll:read:self) สำหรับข้อมูลรายคน หรือ ข้อมูลเงินเดือนทั้งองค์กร (payroll:read:all) สำหรับจัดการงวดและ Template — ขึ้นกับแต่ละ endpoint
งวดโอที (OT Round) คืออะไร?
งวดโอที คือรอบเวลาที่ใช้รวบรวมและคำนวณยอดโอทีของพนักงาน ซึ่งอาจไม่ตรงกับงวดเงินเดือน เช่น
- งวดเงินเดือน = 1–30 กันยายน 2026
- งวดโอที = 21 สิงหาคม – 20 กันยายน 2026
องค์กรที่แยกงวดแบบนี้ ระบบจะ ไม่ คิดยอดโอทีตอนคำนวณงวดเงินเดือน แต่จะดึง ยอดโอทีที่คำนวณเสร็จแล้ว ของรอบโอทีมารวมให้แทน จึงต้องสั่งคำนวณงวดโอทีก่อนเสมอ
อาการที่บอกว่าต้องใช้โมดูลนี้: คำนวณงวดเงินเดือนแล้วสำเร็จ (HTTP 200) เวลาทำงาน วันลา มาสาย ครบถ้วน แต่ยอดโอทีเป็นศูนย์ ทั้งที่เอกสารโอทีอนุมัติแล้วและพนักงานลงเวลาครบ
ลำดับการทำงานทั่วไป
- สร้างงวด — Create OT Round หรือ Create Round from Template
- กำหนดรายชื่อพนักงาน — Assign Employees
- ตั้งค่าการจ่าย — Save Paid Info (ตั้ง
ot_paid_in_normal = "Y"เพื่อให้ยอดรวมกับเงินเดือนงวดปกติ) - สั่งคำนวณรายคน — Calculate OT
- ตรวจผล — Get OT Round หรือ Get OT Detail
- ปิดงวดโอที — Finish OT Round
- คำนวณงวดเงินเดือน ของเดือนเดียวกัน เพื่อรวมยอดโอทีเข้าสลิป
ต้องปิดงวดโอทีก่อนคำนวณงวดเงินเดือนเสมอ — การคำนวณงวดเงินเดือนจะดึงยอดเฉพาะจากรอบโอทีที่ปิดงวดแล้วเท่านั้น ถ้าเรียกคำนวณงวดเงินเดือนขณะที่รอบโอทียังเปิดอยู่ ยอดโอทีในสลิปจะเป็น 0 แม้จะสั่ง Calculate OT ครบทุกคนแล้วก็ตาม
ข้อตกลงร่วมของทุก endpoint
การระบุรอบโอที
Endpoint ที่ทำงานกับงวด รับการระบุรอบได้ 2 ทาง:
| วิธี | ใช้เมื่อ |
|---|---|
master_salary_ot_report_id | ระบุรอบตรง ๆ ชัดเจนที่สุด |
year_month (YYYY-MM) | สะดวกกว่า ระบบหารอบให้เอง — ใช้ได้เมื่อเดือนนั้นมีรอบเดียว |
ถ้าเดือนนั้นมีมากกว่าหนึ่งรอบ ระบบจะ ไม่เลือกรอบให้ แต่จะตอบ error ขอให้ระบุ master_salary_ot_report_id เพื่อป้องกันการทำรายการผิดรอบ — ดูรอบที่มีอยู่ได้จาก List OT Rounds
รูปแบบของรหัส (ID)
| ตำแหน่ง | รูปแบบ | ตัวอย่าง |
|---|---|---|
Request parameter (เช่น master_salary_ot_report_id, master_salary_ot_report_template_id) | Base64 | MjAyNTExMjdENDU3M0M0MjE2Mzk= |
สมาชิกใน array (เช่น template_ids[]) | Raw | 20251127D4573C421639 |
| Response fields | Raw | 20251127D4573C421639 |
รหัสที่ได้จาก response เป็นค่า raw — ต้องแปลงเป็น Base64 ก่อนนำไปส่งเป็น request parameter ในครั้งถัดไป ระบบตรวจรูปแบบนี้จริง การส่งค่า raw จะถอดรหัสไม่ได้และได้ ไม่พบรอบการคำนวณ OT: {ค่าที่ส่งมา} ส่วนรหัส Template ที่ผิดรูปจะได้ ไม่พบ OT Template ตามรหัสที่ระบุ
รหัสพนักงาน
ทุก endpoint ใช้ employee_code (รหัสพนักงานที่เห็นในระบบ) — endpoint ที่รับหลายคนใช้ employee_codes เป็น array ของรหัส
งวดที่ปิดแล้ว
Endpoint ที่แก้ไขข้อมูล (คำนวณ, บันทึกรายชื่อ, ถอดคน, บันทึกวันจ่าย, ลบงวด) จะถูกปฏิเสธถ้ารอบปิดงวดอยู่ ต้องเรียก Unfinish OT Round ก่อน
นอกจากสถานะรอบโอทีแล้ว Assign Employees, Remove Employee, Delete OT Round, Finish OT Round และ Save Paid Info ยังตรวจสถานะงวดเงินเดือนที่รอบสังกัดด้วย ถ้างวดเงินเดือนปิดแล้วจะได้ งวดเงินเดือน {year_month} ถูกปิดแล้ว ไม่สามารถแก้ไขงวดโอทีได้ ส่วน Calculate OT ตรวจเฉพาะสถานะรอบโอที จึงยังคำนวณได้แม้งวดเงินเดือนปิดแล้ว
API Endpoints (21 endpoints)
คำนวณและดูผล
Calculate OT
สั่งคำนวณงวดโอทีของพนักงานรายคน — ต้องเรียกก่อนคำนวณงวดเงินเดือน
Get OT Detail
ดูผลโอทีรายคนในงวด ทั้งสลิปสรุปและรายการรายวัน
จัดการงวดโอที
List OT Rounds
ดูรายการงวดโอทีของเดือน — ใช้หา master_salary_ot_report_id ก่อนสั่งคำนวณ
Get OT Round
ดูรายละเอียดงวดพร้อมรายชื่อพนักงานและยอดโอทีของแต่ละคน
Create OT Round
สร้างงวดโอทีโดยกำหนดช่วงวันที่เอง
Create Round from Template
สร้างงวดจาก Template ระบบคำนวณช่วงวันที่ให้เอง เหมาะกับ automation รายเดือน
Save Paid Info
บันทึกวันที่จ่ายและรูปแบบการจ่ายของงวด
Finish OT Round
ปิดงวด ล็อกไม่ให้แก้ไขหรือคำนวณอีก
Unfinish OT Round
เปิดงวดที่ปิดแล้วกลับมาแก้ไขได้
Delete OT Round
ลบงวดทั้งรอบ รวมผลคำนวณของทุกคนในรอบ
Reload Employee Data
โหลดข้อมูลพนักงานในงวดใหม่ เมื่อแก้ข้อมูลพนักงานหลังสร้างงวดแล้ว
Reload Company Config
โหลดการตั้งค่าบริษัทของงวดใหม่ เมื่อแก้การตั้งค่าโอทีหลังสร้างงวดแล้ว
จัดการรายชื่อพนักงานในงวด
List Available Employees
ดูพนักงานที่เลือกเข้างวดได้ พร้อม flag บอกว่าคนไหนเลือกไม่ได้
Assign Employees
บันทึกรายชื่อพนักงานในงวด — เป็นการแทนที่ทั้งชุด
Remove Employee
ถอดพนักงานหนึ่งคนออกจากงวด พร้อมลบผลคำนวณของคนนั้น
OT Template
List OT Templates
ดูรายการ Template ทั้งหมด
Get OT Template
ดูรายละเอียด Template ตัวใดตัวหนึ่ง
Create OT Template
สร้าง Template เก็บรูปแบบงวดไว้ใช้ซ้ำทุกเดือน
Save Template Employees
บันทึกรายชื่อพนักงานใน Template — เป็นการแทนที่ทั้งชุด
List Available for Template
ดูพนักงานที่เลือกเข้า Template ได้
Delete OT Template
ลบ Template — ไม่กระทบงวดที่สร้างไปแล้ว
Base URL
| Environment | URL |
|---|---|
| Production | https://openapi.humansoft.co.th |
| UAT | https://openapi.humansoft.co.th/uat |
Related Modules
- Overtime (ทำงานล่วงเวลา) - ยื่นและอนุมัติเอกสารโอที ซึ่งเป็นข้อมูลตั้งต้นของการคำนวณงวดโอที
- Salary (เงินเดือน) - คำนวณงวดเงินเดือนที่ดึงยอดโอทีจากโมดูลนี้ไปรวม