Create OT Round

สร้างงวดโอทีใหม่โดยกำหนดช่วงวันที่เอง

งวดที่สร้างจะผูกกับงวดเงินเดือนของ year_month ที่ระบุ — ถ้าองค์กรใช้รูปแบบงวดเดิมทุกเดือน แนะนำใช้ Create Round from Template แทน จะไม่ต้องกรอกวันที่ใหม่ทุกเดือน

Endpoint


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

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

Request Parameters

Required Parameters

Parameter	Type	Required	Description	Example
`year_month`	string	Yes	งวดเงินเดือนที่รอบนี้จะสังกัด (YYYY-MM)	`2026-09`
`master_salary_ot_name`	string	Yes	ชื่อรอบโอที	`งวดโอที ก.ย. 2026`
`ot_report_start_dt`	string	Yes	วันเริ่มรอบ — รับทั้ง `YYYY-MM-DD` และ `YYYY-MM-DD HH:MM:SS` บันทึกตามที่ส่ง	`2026-08-21 00:00:00`
`ot_report_end_dt`	string	Yes	วันสิ้นรอบ — รับทั้ง `YYYY-MM-DD` และ `YYYY-MM-DD HH:MM:SS`	`2026-09-20 23:59:59`

Request Body Example


{
  "year_month": "2026-09",
  "master_salary_ot_name": "งวดโอที ก.ย. 2026",
  "ot_report_start_dt": "2026-08-21 00:00:00",
  "ot_report_end_dt": "2026-09-20 23:59:59"
}

Response Format

Success Response (HTTP 200)


{
  "code": 200,
  "message": "Create OT round (2026-09) Accept",
  "payload": {
    "master_salary_ot_report_id": "20251127D4573C421639",
    "master_salary_month": "2026-09",
    "master_salary_ot_name": "งวดโอที ก.ย. 2026",
    "master_salary_ot_seq": 1,
    "ot_report_start_dt": "2026-08-21 00:00:00",
    "ot_report_end_dt": "2026-09-20 23:59:59",
    "ot_day_in_month": 31
  }
}

Error Response - Salary Period Closed (HTTP 400)


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

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

Error Response - Validation Failed (HTTP 400)


{
  "code": 400,
  "message": "ไม่สำเร็จ",
  "errors": [
    "กรุณาระบุ 'master_salary_ot_name'"
  ]
}

วิธีแก้: ตรวจสอบว่าส่งพารามิเตอร์ที่จำเป็นครบทุกตัว

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	รหัสรอบโอที — ใช้ส่งต่อให้ endpoint อื่น (ต้องแปลงเป็น Base64 ก่อนส่งกลับเข้า request)
`master_salary_month`	string	งวดเดือนที่รอบนี้สังกัด
`master_salary_ot_name`	string	ชื่อรอบตามที่ตั้งไว้
`master_salary_ot_seq`	int	ลำดับรอบภายในเดือน
`ot_report_start_dt`	string	วันเริ่มรอบ
`ot_report_end_dt`	string	วันสิ้นรอบ
`ot_day_in_month`	int	จำนวนวันในรอบ — คำนวณจากผลต่างของสองวันที่ ดูข้อควรระวังใน Notes
`read_only_flag`	string	`Y` = ปิดงวดแล้ว แก้ไข/คำนวณไม่ได้, `N` = เปิดอยู่
`ot_paid_dt`	string	วันที่จ่าย
`ot_paid_in_normal`	string	`Y` = ยอดโอทีจ่ายรวมกับเงินเดือนงวดปกติ

Code Examples

cURL


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/calculation-ot/create-ot-round" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "year_month": "2026-09",
    "master_salary_ot_name": "งวดโอที ก.ย. 2026",
    "ot_report_start_dt": "2026-08-21",
    "ot_report_end_dt": "2026-09-20"
  }'

JavaScript


const response = await fetch(
  'https://openapi.humansoft.co.th/api/v1/open-apis/calculation-ot/create-ot-round',
  {
    method: 'POST',
    headers: {
      'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      year_month: '2026-09',
      master_salary_ot_name: 'งวดโอที ก.ย. 2026',
      ot_report_start_dt: '2026-08-21',
      ot_report_end_dt: '2026-09-20'
    })
  }
)
 
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/create-ot-round"
headers = {
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "year_month": "2026-09",
    "master_salary_ot_name": "งวดโอที ก.ย. 2026",
    "ot_report_start_dt": "2026-08-21",
    "ot_report_end_dt": "2026-09-20"
}
 
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/create-ot-round";
 
$headers = [
    "Ocp-Apim-Subscription-Key: YOUR_API_KEY",
    "Content-Type: application/json"
];
 
$payload = [
    "year_month" => "2026-09",
    "master_salary_ot_name" => "งวดโอที ก.ย. 2026",
    "ot_report_start_dt" => "2026-08-21",
    "ot_report_end_dt" => "2026-09-20"
];
 
$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
`year_month`	ต้องเป็นรูปแบบ YYYY-MM	`'year_month' ต้องเป็นรูปแบบ YYYY-MM`
งวดเงินเดือน	เดือนนั้นต้องมีงวดเงินเดือนอยู่แล้วและยังไม่ปิด	`งวดเงินเดือน 2026-09 ถูกปิดแล้ว ไม่สามารถแก้ไขงวดโอทีได้`
`master_salary_ot_name`	ต้องระบุ	`กรุณาระบุ 'master_salary_ot_name'`
`ot_report_start_dt`	ต้องเป็นรูปแบบ YYYY-MM-DD	`'ot_report_start_dt' ต้องเป็นรูปแบบ YYYY-MM-DD`
`ot_report_end_dt`	ต้องเป็นรูปแบบ YYYY-MM-DD และไม่น้อยกว่าวันเริ่มรอบ	`'ot_report_end_dt' ต้องเป็นรูปแบบ YYYY-MM-DD`

Notes

สร้างเสร็จแล้วงวดจะยังไม่มีพนักงาน ต้องเรียก Assign Employees ต่อ
เดือนหนึ่งสร้างได้หลายรอบ ระบบจะให้ลำดับ (master_salary_ot_seq) อัตโนมัติ
ต้องมีงวดเงินเดือนของเดือนนั้นก่อน ถ้ายังไม่มี ระบบจะไม่สร้างรอบให้ จึงควรตรวจผลด้วย List OT Rounds ว่ารอบถูกสร้างจริงก่อนทำขั้นตอนถัดไป
รอบคร่อมเดือนได้ เช่น 21 ส.ค. – 20 ก.ย. ให้สังกัดงวด 2026-09
ot_day_in_month คิดจากผลต่างของสองวันที่ ถ้าส่งวันที่แบบ YYYY-MM-DD เฉย ๆ จะได้ค่าน้อยกว่าจำนวนวันจริง 1 วัน (21 ส.ค. – 20 ก.ย. ได้ 30) ถ้าต้องการให้นับรวมวันสุดท้ายด้วย ให้ส่งวันสิ้นรอบเป็น 2026-09-20 23:59:59 จะได้ 31
เก็บ master_salary_ot_report_id ที่ได้ไว้ใช้กับ endpoint อื่น

Assign Employees - เพิ่มพนักงานเข้างวดที่เพิ่งสร้าง
Create Round from Template - สร้างจากรูปแบบที่บันทึกไว้แทนการกรอกเอง
List OT Rounds - หารหัสรอบของเดือนที่ต้องการ