Calculate OT

สั่งคำนวณงวดโอทีของพนักงานรายคน

ใช้กับองค์กรที่ตั้งค่าให้งวดโอทีแยกออกจากงวดเวลาทำงาน เช่น งวดเงินเดือนตัดรอบสิ้นเดือน แต่งวดโอทีตัดรอบวันที่ 21 ถึง 20 — องค์กรกลุ่มนี้การคำนวณงวดเงินเดือนจะไม่คิดยอดโอทีให้ แต่จะดึงยอดที่คำนวณเสร็จแล้วของรอบโอทีมารวมแทน จึงต้องเรียก API นี้ก่อนคำนวณงวดเงินเดือน

Endpoint


POST /api/v1/open-apis/calculation-ot/calculate-ot

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

Request Parameters

Required Parameters

Parameter	Type	Required	Description	Example
`employee_code`	string	Yes	รหัสพนักงานที่ต้องการคำนวณ	`EMP001`

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


{
  "employee_code": "EMP001",
  "year_month": "2026-09"
}

ระบุรอบโอทีโดยตรง (กรณีเดือนนั้นมีหลายรอบ)


{
  "employee_code": "EMP001",
  "master_salary_ot_report_id": "MjAyNTExMjdENDU3M0M0MjE2Mzk="
}

Response Format

Success Response (HTTP 200)


{
  "code": 200,
  "message": "Calculate OT (20251127D4573C421639) Accept",
  "payload": {
    "employee_code": "EMP001",
    "master_salary_ot_report_id": "20251127D4573C421639",
    "master_salary_month": "2026-09",
    "ot_round_name": "งวดโอที ก.ย. 2026",
    "ot_report_start_date": "2026-08-21 00:00:00",
    "ot_report_end_date": "2026-09-20 00:00:00",
    "master_salary_ot_slip_id": "20251127S1180E9B47C5",
    "total_ot": 1250.00,
    "ot_summary": {
      "ot_1_0": {
        "day": 0,
        "sum_time": "00:00:00",
        "total": 0
      },
      "ot_1_5": {
        "day": 1,
        "sum_time": "05:00:00",
        "total": 1250.00
      },
      "ot_2_0": {
        "day": 0,
        "sum_time": "00:00:00",
        "total": 0
      },
      "ot_3_0": {
        "day": 0,
        "sum_time": "00:00:00",
        "total": 0
      }
    },
    "next_step": "เรียก finish-ot-round เมื่อคำนวณครบทุกคน แล้วจึงเรียก salary/update-data-filter?path_action=calculate_month ของเดือนเดียวกัน เพื่อรวมยอด OT เข้างวดเงินเดือน"
  }
}

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 นี้ถูกปิดงวดแล้ว ไม่สามารถคำนวณซ้ำได้",
  "payload": []
}

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

Error Response - Employee Not Found (HTTP 400)


{
  "code": 400,
  "message": "Employee not found with code: EMP001",
  "payload": []
}

วิธีแก้: ตรวจสอบรหัสพนักงานให้ตรงกับที่แสดงในระบบ

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 - Unauthorized (HTTP 401)


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

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

Response Fields

Field	Type	Description
`employee_code`	string	รหัสพนักงานที่คำนวณ
`master_salary_ot_report_id`	string	รหัสรอบโอทีที่ถูกคำนวณ
`master_salary_month`	string	งวดเดือนที่รอบโอทีนี้สังกัดอยู่
`ot_round_name`	string	ชื่อรอบโอทีตามที่ตั้งไว้ในระบบ
`ot_report_start_date`	string	วันเริ่มต้นของรอบโอที
`ot_report_end_date`	string	วันสิ้นสุดของรอบโอที
`master_salary_ot_slip_id`	string	รหัสผลการคำนวณโอทีของพนักงานคนนี้ในรอบนี้
`total_ot`	number	ยอดเงินโอทีรวมทุกอัตราของรอบนี้
`ot_summary`	object	ยอดแยกตามอัตรา (`ot_1_0`, `ot_1_5`, `ot_2_0`, `ot_3_0`, `ot_4_0`, `ot_5_0`, `ot_6_0`, `ot_7_0`) แต่ละตัวมี `day`, `sum_time`, `total`
`next_step`	string	ข้อความแนะนำขั้นตอนถัดไปจากระบบ — ระบุให้เรียก `finish-ot-round` เมื่อคำนวณครบทุกคน แล้วจึงคำนวณงวดเงินเดือน

Code Examples

cURL


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/calculation-ot/calculate-ot" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_code": "EMP001",
    "year_month": "2026-09"
  }'

JavaScript


const response = await fetch(
  'https://openapi.humansoft.co.th/api/v1/open-apis/calculation-ot/calculate-ot',
  {
    method: 'POST',
    headers: {
      'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      employee_code: 'EMP001',
      year_month: '2026-09'
    })
  }
)
 
const data = await response.json()
 
if (data.code === 200) {
  console.log('ยอดโอทีรวม:', data.payload.total_ot)
} else {
  console.error('Error:', data.message)
}

Python


import requests
 
url = "https://openapi.humansoft.co.th/api/v1/open-apis/calculation-ot/calculate-ot"
headers = {
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "employee_code": "EMP001",
    "year_month": "2026-09"
}
 
response = requests.post(url, headers=headers, json=payload)
data = response.json()
 
if data['code'] == 200:
    print('ยอดโอทีรวม:', data['payload']['total_ot'])
else:
    print('Error:', data.get('message'))

PHP


<?php
$url = "https://openapi.humansoft.co.th/api/v1/open-apis/calculation-ot/calculate-ot";
 
$headers = [
    "Ocp-Apim-Subscription-Key: YOUR_API_KEY",
    "Content-Type: application/json"
];
 
$payload = [
    "employee_code" => "EMP001",
    "year_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']['total_ot'];
} else {
    echo "Error: " . $data['message'];
}
 
curl_close($ch);
?>

Validation Rules

Parameter	Validation	Error Message
`employee_code`	ต้องระบุและมีอยู่จริงในระบบ	`Employee not found with code: EMP001`
`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 นี้ถูกปิดงวดแล้ว ไม่สามารถคำนวณซ้ำได้`

Business Rules

ลำดับการเรียกที่ถูกต้อง:

เรียก Calculate OT (API นี้) ให้ครบทุกคนก่อน
เรียก Finish OT Round เพื่อปิดงวดโอที
แล้วจึงเรียก Calculate Month ของเดือนเดียวกัน เพื่อรวมยอดโอทีเข้างวดเงินเดือน

เงื่อนไขที่ทำให้ยอดเข้าสลิปเงินเดือน:

รอบโอทีต้องปิดงวดแล้ว — การคำนวณงวดเงินเดือนจะไม่เห็นรอบที่ยังเปิดอยู่ และยอดจะเป็น 0
รอบนั้นต้องตั้งค่าให้จ่ายรวมกับเงินเดือนงวดปกติ (ot_paid_in_normal = "Y")
API นี้ไม่ถูกเรียกอัตโนมัติจากการคำนวณงวดเงินเดือน — ผู้เรียกควบคุมลำดับเอง

Notes

การเรียกซ้ำด้วยพารามิเตอร์เดิมให้ผลลัพธ์เดิมเสมอ (idempotent) ยิงซ้ำได้ไม่ทำให้ยอดบวกทบ
องค์กรที่ไม่ได้แยกงวดโอที ไม่ต้องเรียก API นี้ — การคำนวณงวดเงินเดือนคิดโอทีให้ในตัวอยู่แล้ว
API นี้คำนวณทีละคน ถ้ารันหลายคนควรแบ่ง batch และเว้นจังหวะ ไม่ควรยิงพร้อมกันจำนวนมาก
ต้องมีข้อมูลตั้งต้นครบก่อนคำนวณ: เอกสารโอทีอนุมัติแล้ว และพนักงานมีบันทึกเวลาเข้า–ออกของวันนั้น
การคำนวณนับเฉพาะวันที่อยู่ในช่วงของรอบโอทีเท่านั้น ถ้าวันที่ทำโอทีอยู่นอกช่วง ต้องเลือกรอบให้ถูก

Get OT Detail - ตรวจผลโอทีรายวันหลังคำนวณ
List OT Rounds - หารหัสรอบของเดือนที่ต้องการ
Save Paid Info - ตั้งค่าให้ยอดจ่ายรวมกับเงินเดือนงวดปกติ