Finish OT Round

ปิดงวดโอที ล็อกไม่ให้แก้ไขหรือคำนวณอีก

ใช้เมื่อตรวจยอดของทุกคนในรอบเรียบร้อยแล้วและต้องการล็อกข้อมูลไม่ให้เปลี่ยนแปลง

Endpoint


POST /api/v1/open-apis/calculation-ot/finish-ot-round

สิทธิ์ที่ต้องการ: API Key ต้องมีสิทธิ์ ข้อมูลเงินเดือนทั้งองค์กร (payroll:read:all)

Request Parameters

Optional Parameters

Parameter	Type	Default	Description
`master_salary_ot_report_id`	string	-	รหัสรอบโอที (Base64) — ระบุรอบตรง ๆ จำเป็นเมื่อเดือนนั้นมีมากกว่าหนึ่งรอบ
`year_month`	string	-	งวดเดือนของรอบโอที (YYYY-MM) ระบบจะหารอบให้เอง ใช้ได้เมื่อเดือนนั้นมีรอบเดียว

การระบุรอบโอที: ต้องส่ง master_salary_ot_report_id หรือ year_month อย่างน้อยหนึ่งอย่าง หากเดือนนั้นมีรอบโอทีมากกว่าหนึ่งรอบ ระบบจะไม่เลือกรอบให้ แต่จะตอบ error ให้ระบุ master_salary_ot_report_id เพื่อป้องกันการทำรายการผิดรอบ ถ้าส่งมาทั้งคู่ ระบบใช้ master_salary_ot_report_id หารอบโดยไม่ตรวจว่าตรงกับเดือนใน year_month หรือไม่ แต่ year_month ยังต้องถูกรูปแบบ YYYY-MM — ดูรหัสรอบที่มีอยู่ได้จาก List OT Rounds

Request Body Example


{
  "master_salary_ot_report_id": "MjAyNTExMjdENDU3M0M0MjE2Mzk="
}

Response Format

Success Response (HTTP 200)


{
  "code": 200,
  "message": "Finish OT round (20251127D4573C421639) Accept",
  "payload": {
    "master_salary_ot_report_id": "20251127D4573C421639",
    "ot_round_name": "งวดโอที ก.ย. 2026",
    "master_salary_month": "2026-09",
    "read_only_flag": "Y"
  }
}

Error Response - Round Not Found (HTTP 400)


{
  "code": 400,
  "message": "ไม่พบรอบการคำนวณ OT ของเดือน 2026-09",
  "payload": []
}

วิธีแก้: ตรวจสอบว่าสร้างรอบโอทีของเดือนนั้นแล้ว หรือเรียก List OT Rounds เพื่อดูรอบที่มีอยู่

Error Response - Multiple Rounds in Month (HTTP 400)


{
  "code": 400,
  "message": "ไม่สำเร็จ",
  "errors": [
    "เดือน 2026-09 มีรอบ OT มากกว่าหนึ่งรอบ กรุณาระบุ 'master_salary_ot_report_id'"
  ]
}

วิธีแก้: ส่ง master_salary_ot_report_id ของรอบที่ต้องการแทน year_month

Error Response - Round Already Closed (HTTP 400)


{
  "code": 400,
  "message": "รอบ OT นี้ถูกปิดงวดแล้ว กรุณาเปิดงวดก่อน (unfinish_ot_round)",
  "payload": []
}

วิธีแก้: เรียก Unfinish OT Round เพื่อเปิดงวดก่อน แล้วทำรายการนี้ใหม่

Error Response - Round ID Not Base64-Encoded (HTTP 400)


{
  "code": 400,
  "message": "ไม่พบรอบการคำนวณ OT: 20251127D4573C421639",
  "payload": []
}

วิธีแก้: เกิดจากส่ง master_salary_ot_report_id เป็นค่า raw ที่ยังไม่ได้เข้ารหัส ระบบจึงอ่านรหัสไม่ได้และแจ้งว่าไม่พบรอบ โดยข้อความจะแสดงค่าที่ส่งมาให้ตรวจสอบ — ต้องเข้ารหัส Base64 ก่อนเสมอ เช่น 20251127D4573C421639 → MjAyNTExMjdENDU3M0M0MjE2Mzk=

Error Response - Salary Period Closed (HTTP 400)


{
  "code": 400,
  "message": "งวดเงินเดือน 2026-09 ถูกปิดแล้ว ไม่สามารถแก้ไขงวดโอทีได้",
  "payload": []
}

วิธีแก้: งวดเงินเดือนที่รอบโอทีสังกัดถูกปิดแล้ว ต้องเปิดงวดเงินเดือนของเดือนนั้นก่อนจึงจะแก้ไขรอบโอทีได้

Error Response - Unauthorized (HTTP 401)


{
  "code": 401,
  "message": "Unauthorized",
  "payload": []
}

วิธีแก้: ตรวจสอบว่า API Key ถูกต้องและมีสิทธิ์ตามที่ระบุไว้ด้านบน — ดูวิธีตั้งค่าได้ที่ Get Started

Response Fields

Field	Type	Description
`master_salary_ot_report_id`	string	รหัสรอบโอทีที่ทำรายการ
`ot_round_name`	string	ชื่อรอบ
`master_salary_month`	string	งวดเดือนที่รอบสังกัด
`read_only_flag`	string	สถานะรอบหลังทำรายการ — `Y` = ปิดงวดแล้ว

Code Examples

cURL


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/calculation-ot/finish-ot-round" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "master_salary_ot_report_id": "MjAyNTExMjdENDU3M0M0MjE2Mzk="
  }'

JavaScript


const response = await fetch(
  'https://openapi.humansoft.co.th/api/v1/open-apis/calculation-ot/finish-ot-round',
  {
    method: 'POST',
    headers: {
      'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      master_salary_ot_report_id: 'MjAyNTExMjdENDU3M0M0MjE2Mzk='
    })
  }
)
 
const data = await response.json()
 
if (data.code === 200) {
  console.log('ปิดงวดสำเร็จ:', data.payload.master_salary_ot_report_id)
} else {
  console.error('Error:', data.message)
}

Python


import requests
 
url = "https://openapi.humansoft.co.th/api/v1/open-apis/calculation-ot/finish-ot-round"
headers = {
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "master_salary_ot_report_id": "MjAyNTExMjdENDU3M0M0MjE2Mzk="
}
 
response = requests.post(url, headers=headers, json=payload)
data = response.json()
 
if data['code'] == 200:
    print('ปิดงวดสำเร็จ:', data['payload']['master_salary_ot_report_id'])
else:
    print('Error:', data.get('message'))

PHP


<?php
$url = "https://openapi.humansoft.co.th/api/v1/open-apis/calculation-ot/finish-ot-round";
 
$headers = [
    "Ocp-Apim-Subscription-Key: YOUR_API_KEY",
    "Content-Type: application/json"
];
 
$payload = [
    "master_salary_ot_report_id" => "MjAyNTExMjdENDU3M0M0MjE2Mzk="
];
 
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
 
$response = curl_exec($ch);
$data = json_decode($response, true);
 
if ($data['code'] === 200) {
    echo "ปิดงวดสำเร็จ: " . $data['payload']['master_salary_ot_report_id'];
} else {
    echo "Error: " . $data['message'];
}
 
curl_close($ch);
?>

Validation Rules

Parameter	Validation	Error Message
`master_salary_ot_report_id` / `year_month`	ต้องระบุอย่างน้อยหนึ่งอย่าง	`กรุณาระบุ 'master_salary_ot_report_id' หรือ 'year_month' (รูปแบบ YYYY-MM)`
`year_month`	ต้องเป็นรูปแบบ YYYY-MM	`'year_month' ต้องเป็นรูปแบบ YYYY-MM`
สถานะงวด	รอบต้องยังไม่ปิดงวด (ปิดซ้ำจะถูกปฏิเสธ)	`รอบ OT นี้ถูกปิดงวดแล้ว กรุณาเปิดงวดก่อน (unfinish_ot_round)`

Business Rules

การปิดงวดเป็นเงื่อนไขบังคับก่อนคำนวณงวดเงินเดือน:

การคำนวณงวดเงินเดือนจะดึงยอดเฉพาะจากรอบโอทีที่ปิดงวดแล้วเท่านั้น
ถ้าคำนวณงวดเงินเดือนขณะรอบยังเปิดอยู่ ยอดโอทีในสลิปจะเป็น 0 แม้สั่ง Calculate OT ครบทุกคนแล้ว

ผลของการปิดงวด:

Calculate OT, Assign Employees, Remove Employee, Save Paid Info และ Delete OT Round จะถูกปฏิเสธทั้งหมด
การอ่านข้อมูล (Get OT Round, Get OT Detail) ยังทำได้ตามปกติ
ต้องเรียก Unfinish OT Round เพื่อเปิดงวดก่อนจึงจะแก้ไขได้อีก

Notes

ควรเรียก Calculate OT ให้ครบทุกคนและตรวจยอดก่อนปิดงวด

Unfinish OT Round - เปิดงวดกลับมาแก้ไข
Calculate OT - สั่งคำนวณโอทีรายคนก่อนปิดงวด
Get OT Round - ตรวจรายชื่อและยอดก่อนปิดงวด