Calculate Month Queue

คำนวณสรุปเวลาทำงาน ขาด ลา มาสาย และค่าล่วงเวลาประจำเดือนแบบ Batch Processing สำหรับพนักงานหลายคนพร้อมกัน

Endpoint


POST /api/v1/open-apis/salary/update-data-filter?path_action=calculate_month_queue

Request Body

Required Parameters

Parameter	Type	Required	Description	Example
`employee_codes`	array	Yes*	รายการรหัสพนักงาน (สูงสุด 100 รายการ)	`["EMP001", "EMP002"]`
`year_month`	string	Yes	งวดเดือนที่ต้องการคำนวณ (YYYY-MM)	`"2026-02"`

*ไม่จำเป็นเมื่อใช้ calculate_all = true

Optional Parameters

Parameter	Type	Default	Description	Example
`calculate_to`	string	`"NOW"`	คำนวณถึง: `"NOW"` (วันปัจจุบัน), `"END"` (วันสิ้นสุดงวด)	`"END"`
`calculate_all`	boolean	`false`	คำนวณพนักงานทุกคนในงวด (ไม่ต้องส่ง `employee_codes`)	`true`
`keyword`	string	-	ค้นหาพนักงาน (ใช้ร่วมกับ `calculate_all`)	`"สมชาย"`
`branch_lists`	array	-	กรองตามสาขา (Base64 encoded ID)	`[{"id": "YnJhbmNoXzAw"}]`
`department_lists`	array	-	กรองตามฝ่าย (Base64 encoded ID)	`[{"id": "ZGVwdF8wMQ=="}]`
`division_lists`	array	-	กรองตามแผนก (Base64 encoded ID)
`section_lists`	array	-	กรองตามหน่วยงาน (Base64 encoded ID)
`position_lists`	array	-	กรองตามตำแหน่ง (Base64 encoded ID)

พารามิเตอร์ที่ลงท้ายด้วย _lists ต้องส่งเป็น array ของ object โดยมี key id ที่เป็น Base64 encoded

Validation Rules

Rule	Description
`employee_codes`	ต้องเป็น array มี 1-100 รายการ (ยกเว้นเมื่อใช้ `calculate_all`)
`year_month`	ต้องเป็นรูปแบบ YYYY-MM
`calculate_to`	ต้องเป็น `"NOW"` หรือ `"END"` เท่านั้น

Response Format

Success Response


{
  "code": 200,
  "message": "Batch calculation month queued",
  "results": {
    "success": [
      {
        "employee_code": "EMP001",
        "employee_id": "12345",
        "employee_name": "นายสมชาย ใจดี"
      }
    ],
    "failed": [
      {
        "employee_code": "EMP999",
        "error": "Employee not found"
      }
    ],
    "already_in_queue": [
      {
        "employee_code": "EMP002",
        "employee_id": "12346",
        "employee_name": "นางสมหญิง ใจงาม"
      }
    ]
  },
  "summary": {
    "total_resolved": 2,
    "success_count": 1,
    "failed_count": 1,
    "already_queued_count": 1
  }
}

Response Fields - results

Field	Type	Description
`success`	array	รายการพนักงานที่เข้าคิวสำเร็จ
`failed`	array	รายการพนักงานที่เข้าคิวไม่สำเร็จ
`already_in_queue`	array	รายการพนักงานที่อยู่ในคิวแล้ว

Response Fields - summary

Field	Type	Description
`total_resolved`	number	จำนวนพนักงานทั้งหมดที่ประมวลผล
`success_count`	number	จำนวนที่เข้าคิวสำเร็จ
`failed_count`	number	จำนวนที่เข้าคิวไม่สำเร็จ
`already_queued_count`	number	จำนวนที่อยู่ในคิวแล้ว

API นี้เป็น Asynchronous — การส่งเข้าคิวสำเร็จไม่ได้หมายความว่าคำนวณเสร็จแล้ว ผลลัพธ์การคำนวณจะพร้อมใช้งานภายหลัง

Error Response


{
  "code": 400,
  "message": "ไม่สำเร็จ",
  "payload": {
    "errors": [
      "กรุณาระบุ 'employee_codes' (array)",
      "กรุณาระบุ 'year_month' (รูปแบบ YYYY-MM)"
    ]
  }
}

HTTP Status	Description
`400`	พารามิเตอร์ไม่ถูกต้อง หรือเกินจำนวนสูงสุด 100 รายการ
`401`	API Key ไม่ถูกต้องหรือไม่ได้ส่ง

Code Examples

cURL


# Batch calculation
curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/salary/update-data-filter?path_action=calculate_month_queue" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_codes": ["EMP001", "EMP002", "EMP003"],
    "year_month": "2026-02"
  }'
 
# Calculate all employees
curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/salary/update-data-filter?path_action=calculate_month_queue" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "calculate_all": true,
    "year_month": "2026-02",
    "calculate_to": "END"
  }'

JavaScript


const response = await fetch(
  'https://openapi.humansoft.co.th/api/v1/open-apis/salary/update-data-filter?path_action=calculate_month_queue',
  {
    method: 'POST',
    headers: {
      'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      employee_codes: ['EMP001', 'EMP002', 'EMP003'],
      year_month: '2026-02'
    })
  }
)
const data = await response.json()
console.log(`Success: ${data.summary.success_count}, Failed: ${data.summary.failed_count}`)
data.results.failed.forEach(f => console.error(`${f.employee_code}: ${f.error}`))

Python


import requests
 
url = "https://openapi.humansoft.co.th/api/v1/open-apis/salary/update-data-filter"
headers = {"Ocp-Apim-Subscription-Key": "YOUR_API_KEY"}
params = {"path_action": "calculate_month_queue"}
payload = {
    "employee_codes": ["EMP001", "EMP002", "EMP003"],
    "year_month": "2026-02"
}
 
response = requests.post(url, headers=headers, params=params, json=payload)
data = response.json()
print(f"Success: {data['summary']['success_count']}")
print(f"Failed: {data['summary']['failed_count']}")
for f in data["results"]["failed"]:
    print(f"  {f['employee_code']}: {f['error']}")

PHP


<?php
$url = "https://openapi.humansoft.co.th/api/v1/open-apis/salary/update-data-filter?path_action=calculate_month_queue";
$data = json_encode([
    "employee_codes" => ["EMP001", "EMP002", "EMP003"],
    "year_month" => "2026-02"
]);
 
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Ocp-Apim-Subscription-Key: YOUR_API_KEY",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 
$response = curl_exec($ch);
curl_close($ch);
 
$result = json_decode($response, true);
echo "Success: {$result['summary']['success_count']}\n";
echo "Failed: {$result['summary']['failed_count']}\n";
?>

Notes

แนะนำใช้ batch size 20-50 รายการต่อครั้งเพื่อประสิทธิภาพที่ดี
ระบบจะป้องกันการเข้าคิวซ้ำ — ตรวจสอบ already_in_queue ใน response
ระบบจะประมวลผลต่อไปแม้บางรายการล้มเหลว
สำหรับการคำนวณรายบุคคล ใช้ Calculate Month แทน

Calculate Month - คำนวณรายบุคคล
Daily In Month - ดูข้อมูลก่อน/หลังคำนวณ
Salary Summary - ดูผลลัพธ์การคำนวณ