Save Paid Info

บันทึกวันที่จ่ายและรูปแบบการจ่ายของงวดโอที

ot_paid_in_normal = "Y" คือให้ยอดโอทีของรอบนี้ไปรวมกับเงินเดือนงวดปกติ ซึ่งเป็นเงื่อนไขที่ทำให้การคำนวณงวดเงินเดือนดึงยอดโอทีเข้าไปรวมในสลิปได้ ถ้าตั้งเป็น "N" ยอดจะอยู่ในรอบโอทีของตัวเองและไม่ไปปรากฏในสลิปเงินเดือนงวดนั้น

Endpoint


POST /api/v1/open-apis/calculation-ot/save-ot-round-paid

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

Request Parameters

Required Parameters

Parameter	Type	Required	Description	Example
`ot_paid_dt`	string	Yes	วันที่จ่าย (YYYY-MM-DD)	`2026-09-25`

Optional Parameters

Parameter	Type	Default	Description
`master_salary_ot_report_id`	string	-	รหัสรอบโอที (Base64) — ระบุรอบตรง ๆ จำเป็นเมื่อเดือนนั้นมีมากกว่าหนึ่งรอบ
`year_month`	string	-	งวดเดือนของรอบโอที (YYYY-MM) ระบบจะหารอบให้เอง ใช้ได้เมื่อเดือนนั้นมีรอบเดียว
`ot_paid_in_normal`	string	ค่าเดิมของงวด	`Y` = จ่ายรวมกับเงินเดือนงวดปกติ, `N` = จ่ายแยก
`ot_paid_month`	string	ค่าเดิมของงวด	งวดเดือนที่จ่าย (YYYY-MM)
`ot_paid_month_seq`	integer	ค่าเดิมของงวด	ลำดับงวดย่อยที่จ่าย (กรณีบริษัทแบ่งจ่ายหลายงวด) ต้องเป็นจำนวนเต็มไม่ติดลบ และต้องมีงวดย่อยลำดับนั้นอยู่จริง

การระบุรอบโอที: ต้องส่ง 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=",
  "ot_paid_dt": "2026-09-25",
  "ot_paid_in_normal": "Y",
  "ot_paid_month": "2026-09"
}

Response Format

Success Response (HTTP 200)


{
  "code": 200,
  "message": "Save OT round paid info (20251127D4573C421639) Accept",
  "payload": {
    "master_salary_ot_report_id": "20251127D4573C421639",
    "ot_paid_dt": "2026-09-25",
    "ot_paid_in_normal": "Y",
    "ot_paid_month": "2026-09",
    "ot_paid_month_seq": 1
  }
}

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 - Invalid Paid Flag (HTTP 400)


{
  "code": 400,
  "message": "ไม่สำเร็จ",
  "errors": [
    "ot_paid_in_normal ต้องเป็น Y หรือ N"
  ]
}

วิธีแก้: ส่ง ot_paid_in_normal เป็น Y หรือ N เท่านั้น

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 - Paid Month Sequence Not Found (HTTP 400)


{
  "code": 400,
  "message": "ไม่พบงวดย่อยลำดับที่ 3 ในเดือน 2026-09 (ระบุได้ 1 ถึง 2)",
  "payload": []
}

วิธีแก้: ส่ง ot_paid_month_seq ให้อยู่ในช่วงงวดย่อยที่มีอยู่จริงของเดือนนั้น

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_paid_dt`	string	วันที่จ่ายที่บันทึกไว้
`ot_paid_in_normal`	string	รูปแบบการจ่ายที่มีผลอยู่
`ot_paid_month`	string	งวดเดือนที่จ่าย
`ot_paid_month_seq`	integer	ลำดับงวดย่อยที่จ่าย

Code Examples

cURL


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/calculation-ot/save-ot-round-paid" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "master_salary_ot_report_id": "MjAyNTExMjdENDU3M0M0MjE2Mzk=",
    "ot_paid_dt": "2026-09-25",
    "ot_paid_in_normal": "Y",
    "ot_paid_month": "2026-09"
  }'

JavaScript


const response = await fetch(
  'https://openapi.humansoft.co.th/api/v1/open-apis/calculation-ot/save-ot-round-paid',
  {
    method: 'POST',
    headers: {
      'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      master_salary_ot_report_id: 'MjAyNTExMjdENDU3M0M0MjE2Mzk=',
      ot_paid_dt: '2026-09-25',
      ot_paid_in_normal: 'Y',
      ot_paid_month: '2026-09'
    })
  }
)
 
const data = await response.json()
 
if (data.code === 200) {
  console.log('วันที่จ่าย:', data.payload.ot_paid_dt)
} else {
  console.error('Error:', data.message)
}

Python


import requests
 
url = "https://openapi.humansoft.co.th/api/v1/open-apis/calculation-ot/save-ot-round-paid"
headers = {
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "master_salary_ot_report_id": "MjAyNTExMjdENDU3M0M0MjE2Mzk=",
    "ot_paid_dt": "2026-09-25",
    "ot_paid_in_normal": "Y",
    "ot_paid_month": "2026-09"
}
 
response = requests.post(url, headers=headers, json=payload)
data = response.json()
 
if data['code'] == 200:
    print('วันที่จ่าย:', data['payload']['ot_paid_dt'])
else:
    print('Error:', data.get('message'))

PHP


<?php
$url = "https://openapi.humansoft.co.th/api/v1/open-apis/calculation-ot/save-ot-round-paid";
 
$headers = [
    "Ocp-Apim-Subscription-Key: YOUR_API_KEY",
    "Content-Type: application/json"
];
 
$payload = [
    "master_salary_ot_report_id" => "MjAyNTExMjdENDU3M0M0MjE2Mzk=",
    "ot_paid_dt" => "2026-09-25",
    "ot_paid_in_normal" => "Y",
    "ot_paid_month" => "2026-09"
];
 
$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']['ot_paid_dt'];
} 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)`
`ot_paid_dt`	ต้องระบุและเป็นรูปแบบ YYYY-MM-DD	`กรุณาระบุ 'ot_paid_dt' (รูปแบบ YYYY-MM-DD)`
`ot_paid_in_normal`	ถ้าส่งมา ต้องเป็น `Y` หรือ `N`	`'ot_paid_in_normal' ต้องเป็น Y หรือ N`
`ot_paid_month_seq`	ถ้าส่งมา ต้องเป็นจำนวนเต็มไม่ติดลบ	`'ot_paid_month_seq' ต้องเป็นจำนวนเต็มไม่ติดลบ`
`ot_paid_month_seq`	ต้องมีงวดย่อยลำดับนั้นอยู่จริงในเดือนนั้น	`ไม่พบงวดย่อยลำดับที่ 3 ในเดือน 2026-09 (ระบุได้ 1 ถึง 2)`
สถานะงวดเงินเดือน	งวดเงินเดือนที่รอบสังกัดต้องยังไม่ปิด	`งวดเงินเดือน 2026-09 ถูกปิดแล้ว ไม่สามารถแก้ไขงวดโอทีได้`
`ot_paid_month`	ถ้าส่งมา ต้องเป็นรูปแบบ YYYY-MM	`'ot_paid_month' ต้องเป็นรูปแบบ YYYY-MM`
สถานะงวด	รอบต้องยังไม่ปิดงวด	`รอบ OT นี้ถูกปิดงวดแล้ว กรุณาเปิดงวดก่อน (unfinish_ot_round)`

Notes

ฟิลด์ที่ไม่ได้ส่งมาหรือส่งเป็น null จะคงค่าเดิมของงวดไว้ ส่วนการส่งสตริงว่าง "" จะถูกปฏิเสธด้วย validation error
การตั้ง ot_paid_in_normal = "Y" อย่างเดียวยังไม่ทำให้ยอดเข้าสลิปเงินเดือน ต้องเรียก Finish OT Round ปิดงวดโอทีก่อนคำนวณงวดเงินเดือนด้วย
ถ้าเปลี่ยน ot_paid_in_normal หลังจากคำนวณเงินเดือนไปแล้ว ต้องสั่งคำนวณงวดเงินเดือนของเดือนนั้นใหม่ เพื่อให้ยอดในสลิปตรงกับการตั้งค่าล่าสุด

Calculate OT - สั่งคำนวณโอทีรายคนในรอบนี้
Get OT Round - ตรวจค่าที่บันทึกไว้
List OT Rounds - หารหัสรอบของเดือนที่ต้องการ