Submit Report

ส่งคำขอสร้างรายงานเงินเดือนแบบ asynchronous ระบบจะรับงานไว้และคืน trace_id กลับทันที

API นี้ทำงานแบบ asynchronous — ไม่ได้คืนไฟล์รายงานในทันที แต่คืน trace_id สำหรับใช้ติดตามสถานะ (Report Status) และดาวน์โหลดผลลัพธ์ (Report Result) เมื่อประมวลผลเสร็จ

Endpoint


POST /api/v1/open-apis/report-builder/reports

สิทธิ์ที่ต้องการ: API Key ต้องมีสิทธิ์ การสร้างรายงาน (report:generate) จึงจะส่งคำขอสร้างรายงานได้

Request Parameters

Parameter	Type	Required	Default	Description
`report`	string	Yes	-	Report ID ที่ต้องการสร้าง (ดูรายการที่ List Templates)
`type`	string	No	`csv`	รูปแบบไฟล์ผลลัพธ์ — `csv` หรือ `json` (เปิดใช้งานทั้งคู่; ค่าเริ่มต้น `csv`) ค่าอื่นเช่น `excel`/`pdf` จะได้ `400`
`selected_columns`	string[]	No	คอลัมน์เริ่มต้นของรายงาน	คอลัมน์ที่ต้องการแสดง (ดู key ที่เลือกได้จาก Available Columns) — ถ้าไม่ระบุหรือเป็น array ว่าง ระบบจะใช้คอลัมน์เริ่มต้นของรายงาน
`filter`	object	No	`{}`	เงื่อนไขการกรองข้อมูล — โครงสร้างขึ้นกับรายงาน (ดูด้านล่าง)
`language_code`	string	No	`TH`	ภาษาของข้อมูลที่แปลได้ (`TH`, `EN`)
`identify_user_id`	string	No	`""`	รหัสผู้ใช้ที่ทำรายการ (ใช้อ้างอิงผู้เรียก)

รูปแบบไฟล์: API รองรับ type เป็น csv หรือ json (เปิดใช้งานทั้งคู่) — ค่าที่ไม่รองรับ (เช่น excel, pdf) จะได้รับ HTTP 400

selected_columns ไม่ถูกตรวจสอบกับชุดคอลัมน์ขณะส่งคำขอ — ควรเลือก key จาก Available Columns ของรายงานและงวดเดือนนั้นโดยตรง เพื่อให้รายงานแสดงคอลัมน์ตามที่ต้องการ

Filter Fields

โครงสร้างของ object filter แตกต่างกันตามรายงาน

`net_total_month_custom`

Field	Type	Required	Description	Example
`year_month`	string	Yes	งวดเดือน รูปแบบ `YYYY-MM`	`2026-05`
`company_lists`	string[]	No	กรองตามรหัสบริษัท	`["C001"]`
`branch_lists`	string[]	No	กรองตามรหัสสาขา	`["B001"]`
`department_lists`	string[]	No	กรองตามรหัสแผนก	`["D001", "D002"]`
`division_lists`	string[]	No	กรองตามรหัสฝ่าย	`["DV01"]`
`section_lists`	string[]	No	กรองตามรหัสหน่วยงาน	`["S001"]`
`section_lists_lv01` - `section_lists_lv05`	string[]	No	กรองตามหน่วยงานย่อยระดับ 1-5	`["S0101"]`
`employee_type_code`	string[]	No	กรองตามประเภทพนักงาน	`["FULL"]`
`keyword`	string	No	ค้นหาด้วยคำสำคัญ (เช่น ชื่อ/รหัสพนักงาน)	`EMP001`

`payroll_period_summary`

Field	Type	Required	Description	Example
`year_month`	string	Yes	งวดเดือน รูปแบบ `YYYY-MM`	`2026-05`
`round_flag`	string	Yes	ประเภทงวด — ต้องเป็น `Full` หรือ `Split`	`Split`
`master_salary_split_seq`	number	เงื่อนไข	ลำดับงวดจ่าย — ต้องเป็น `1`, `2`, `3` หรือ `4`; จำเป็นเมื่อ `round_flag = Split` (ไม่ต้องส่งเมื่อ `Full`)	`1`
`company_lists`	string[]	No	กรองตามรหัสบริษัท	`["C001"]`
`branch_lists`	string[]	No	กรองตามรหัสสาขา	`["B001"]`
`department_lists`	string[]	No	กรองตามรหัสแผนก	`["D001", "D002"]`
`division_lists`	string[]	No	กรองตามรหัสฝ่าย	`["DV01"]`
`section_lists`	string[]	No	กรองตามรหัสหน่วยงาน	`["S001"]`
`section_lists_lv01` – `section_lists_lv05`	string[]	No	กรองตามหน่วยงานย่อยระดับ 1–5	`["S0101"]`
`employee_type_code`	string[]	No	กรองตามประเภทพนักงาน	`["FULL"]`
`keyword`	string	No	ค้นหาด้วยคำสำคัญ (เช่น ชื่อ/รหัสพนักงาน)	`EMP001`

`payroll_attendance_detail`

Field	Type	Required	Description	Example
`work_date_start`	string	Yes	วันที่เริ่มช่วง รูปแบบ `YYYY-MM-DD`	`2026-05-01`
`work_date_end`	string	Yes	วันที่สิ้นสุดช่วง รูปแบบ `YYYY-MM-DD` (ต้องไม่ก่อน `work_date_start`)	`2026-05-31`
`company_lists`	string[]	No	กรองตามรหัสบริษัท	`["C001"]`
`branch_lists`	string[]	No	กรองตามรหัสสาขา	`["B001"]`
`department_lists`	string[]	No	กรองตามรหัสแผนก	`["D001", "D002"]`
`division_lists`	string[]	No	กรองตามรหัสฝ่าย	`["DV01"]`
`section_lists`	string[]	No	กรองตามรหัสหน่วยงาน	`["S001"]`
`section_lists_lv01` – `section_lists_lv05`	string[]	No	กรองตามหน่วยงานย่อยระดับ 1–5	`["S0101"]`
`employee_type_code`	string[]	No	กรองตามประเภทพนักงาน	`["FULL"]`
`keyword`	string	No	ค้นหาด้วยคำสำคัญ (เช่น ชื่อ/รหัสพนักงาน)	`EMP001`

`master_employee`

ทะเบียนพนักงานรายงานตามสถานะ ณ งวดเดือนที่ระบุ จึงต้องส่ง year_month เสมอ

Field	Type	Required	Description	Example
`year_month`	string	Yes	งวดเดือนที่ต้องการดูทะเบียน รูปแบบ `YYYY-MM`	`2026-05`
`company_lists`	string[]	No	กรองตามรหัสบริษัท	`["C001"]`
`branch_lists`	string[]	No	กรองตามรหัสสาขา	`["B001"]`
`department_lists`	string[]	No	กรองตามรหัสแผนก	`["D001", "D002"]`
`division_lists`	string[]	No	กรองตามรหัสฝ่าย	`["DV01"]`
`section_lists`	string[]	No	กรองตามรหัสหน่วยงาน	`["S001"]`
`section_lists_lv01` – `section_lists_lv05`	string[]	No	กรองตามหน่วยงานย่อยระดับ 1–5	`["S0101"]`
`employee_type_code`	string[]	No	กรองตามประเภทพนักงาน	`["FULL"]`
`keyword`	string	No	ค้นหาด้วยคำสำคัญ (เช่น ชื่อ/รหัสพนักงาน)	`EMP001`

`leave_transaction`

Field	Type	Required	Description	Example
`year`	string	Yes	ปี (`YYYY`)	`2026`
`date_from`	string	Yes	วันที่เริ่ม รูปแบบ `YYYY-MM-DD`	`2026-01-01`
`date_to`	string	Yes	วันที่สิ้นสุด รูปแบบ `YYYY-MM-DD`	`2026-12-31`
`leave_type_code`	string[]	No	กรองตามรหัสประเภทการลา	`["SICK"]`
`company_lists`	string[]	No	กรองตามรหัสบริษัท	`["C001"]`
`branch_lists`	string[]	No	กรองตามรหัสสาขา	`["B001"]`
`department_lists`	string[]	No	กรองตามรหัสแผนก	`["D001", "D002"]`
`division_lists`	string[]	No	กรองตามรหัสฝ่าย	`["DV01"]`
`section_lists`	string[]	No	กรองตามรหัสหน่วยงาน	`["S001"]`
`section_lists_lv01` – `section_lists_lv05`	string[]	No	กรองตามหน่วยงานย่อยระดับ 1–5	`["S0101"]`
`employee_type_code`	string[]	No	กรองตามประเภทพนักงาน	`["FULL"]`
`approve_flag`	string	No	กรองตามสถานะการอนุมัติ	`Y`
`keyword`	string	No	ค้นหาด้วยคำสำคัญ (เช่น ชื่อ/รหัสพนักงาน)	`EMP001`

กฎ cross-field ของ leave_transaction: date_from ต้องไม่เกิน date_to, ทั้งคู่ต้องอยู่ในปีเดียวกัน และต้องตรงกับค่า year มิฉะนั้นจะได้รับ HTTP 400 (INVALID_FILTER)

*_lists ทุก parameter ใช้ array ของ รหัส (code) เป็น string ตรงๆ เช่น ["D001", "D002"] — ไม่ต้องเข้ารหัส Base64 หาก filter มี key ที่ไม่ได้อยู่ในรายงานนั้น ระบบจะตัดทิ้งโดยไม่แจ้ง error

Validation Rules

กฎ	รายละเอียด	Error
`report`	ต้องเป็น Report ID ที่มีอยู่จริง	`REPORT_NOT_FOUND` (400)
`type`	ต้องเป็นค่าที่รายงานรองรับ — ปัจจุบันทุกรายงานรองรับ `csv`/`json`	`UNSUPPORTED_TYPE` (422)
สิทธิ์	API Key ต้องมีสิทธิ์ที่รายงานต้องการ	`FORBIDDEN_PERMISSION` (403)
filter ที่จำเป็น	ต้องส่ง filter ที่ระบุว่า required (เช่น `year_month`, `round_flag`, `work_date_start`, `work_date_end`, `year`, `date_from`, `date_to`)	`MISSING_FILTER` (400)
ประเภทของ filter	`string[]` ต้องเป็น array, `number` ต้องเป็นตัวเลข	`INVALID_FILTER` (400)
รูปแบบ (`pattern`)	ค่าต้องตรง regex ที่กำหนด เช่น `year` = `^\d{4}$`; `date_from`/`date_to`/`work_date_start`/`work_date_end` = `^\d{4}-\d{2}-\d{2}$`	`INVALID_FILTER` (400)
ค่าที่อนุญาต	`round_flag` ต้องเป็น `Full`/`Split`; `master_salary_split_seq` ต้องเป็น `1`–`4` (จำเป็นเมื่อ `round_flag = Split`)	`INVALID_FILTER` (400)
ช่วงวันที่ (`payroll_attendance_detail`)	`work_date_start` ต้องไม่เกิน `work_date_end`	`INVALID_FILTER` (400)
ช่วงวันที่ (`leave_transaction`)	`date_from` ≤ `date_to`, อยู่ในปีเดียวกัน และตรงกับ `year`	`INVALID_FILTER` (400)
ฟิลด์ใน body / ค่า `type`	ส่งเฉพาะฟิลด์ที่รองรับ — ฟิลด์ที่ไม่รู้จัก หรือค่า `type` ที่ไม่ใช่ `csv`/`json` (เช่น `excel`, `pdf`) จะถูกปฏิเสธ	`BAD_REQUEST` (400)

Code Examples

cURL


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/report-builder/reports" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "report": "payroll_period_summary",
    "type": "csv",
    "selected_columns": ["employee_code", "employee_name", "year_month", "total_working_days"],
    "filter": {
      "year_month": "2026-05",
      "round_flag": "Split",
      "master_salary_split_seq": 1,
      "department_lists": ["D001", "D002"]
    },
    "language_code": "TH"
  }'

JavaScript


const url = 'https://openapi.humansoft.co.th/api/v1/open-apis/report-builder/reports'
 
const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    report: 'payroll_period_summary',
    type: 'csv',
    selected_columns: ['employee_code', 'employee_name', 'year_month', 'total_working_days'],
    filter: {
      year_month: '2026-05',
      round_flag: 'Split',
      master_salary_split_seq: 1,
      department_lists: ['D001', 'D002']
    },
    language_code: 'TH'
  })
})
 
const data = await response.json()
console.log(`trace_id: ${data.trace_id} (status: ${data.status})`)

Python


import requests
 
url = "https://openapi.humansoft.co.th/api/v1/open-apis/report-builder/reports"
headers = {
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "report": "payroll_period_summary",
    "type": "csv",
    "selected_columns": ["employee_code", "employee_name", "year_month", "total_working_days"],
    "filter": {
        "year_month": "2026-05",
        "round_flag": "Split",
        "master_salary_split_seq": 1,
        "department_lists": ["D001", "D002"]
    },
    "language_code": "TH"
}
 
response = requests.post(url, headers=headers, json=payload)
data = response.json()
print(f"trace_id: {data['trace_id']} (status: {data['status']})")

PHP


<?php
$url = "https://openapi.humansoft.co.th/api/v1/open-apis/report-builder/reports";
 
$payload = [
    "report" => "payroll_period_summary",
    "type" => "csv",
    "selected_columns" => ["employee_code", "employee_name", "year_month", "total_working_days"],
    "filter" => [
        "year_month" => "2026-05",
        "round_flag" => "Split",
        "master_salary_split_seq" => 1,
        "department_lists" => ["D001", "D002"]
    ],
    "language_code" => "TH"
];
 
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Ocp-Apim-Subscription-Key: YOUR_API_KEY",
    "Content-Type: application/json"
]);
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);
 
echo "trace_id: {$data['trace_id']} (status: {$data['status']})\n";
 
curl_close($ch);
?>

Response Format

Success Response (HTTP 202)

ระบบรับคำขอแล้ว และคืน trace_id พร้อมสถานะเริ่มต้น PENDING


{
  "trace_id": "0190f8a1-2b3c-7def-8123-456789abcdef",
  "status": "PENDING"
}

Response Fields

Field	Type	Description
`trace_id`	string	รหัสติดตามงาน — ใช้กับ Report Status และ Report Result
`status`	string	สถานะเริ่มต้นของงาน — เป็น `PENDING` เสมอเมื่อเพิ่งส่งคำขอ

Error Responses

Missing Required Filter (HTTP 400)


{
  "error": {
    "code": "MISSING_FILTER",
    "message": "Missing required filter: year_month"
  }
}

Invalid Type (HTTP 400)

ส่ง type ที่ไม่ใช่ csv/json (เช่น excel, pdf) จะถูกปฏิเสธที่ชั้น validation:


{
  "error": {
    "code": "BAD_REQUEST",
    "message": "type must be one of: csv, json"
  }
}

Permission Denied (HTTP 403)


{
  "error": {
    "code": "FORBIDDEN_PERMISSION",
    "message": "Missing required permission"
  }
}

Status Codes

Code	ความหมาย
`202`	รับคำขอแล้ว — คืน `trace_id`
`400`	คำขอไม่ถูกต้อง เช่น Report ID ไม่พบ, filter ที่จำเป็นหาย, ค่า filter ผิดประเภท, ค่า `type` ที่ไม่ใช่ `csv`/`json` (เช่น `excel`, `pdf`) หรือส่งฟิลด์ที่ไม่รู้จัก
`401`	ไม่ได้ส่ง API Key หรือ Key ไม่ถูกต้อง
`403`	API Key ไม่มีสิทธิ์ `report:generate`
`422`	(`UNSUPPORTED_TYPE`) ส่งค่า `type` ที่รายงานนั้นไม่รองรับ — ปัจจุบันทุกรายงานรองรับ `csv`/`json`
`500`	เกิดข้อผิดพลาดระหว่างประมวลผลบนเซิร์ฟเวอร์

Notes & Best Practices

หลังได้ trace_id ให้เรียก Report Status เป็นระยะ (เช่น ทุก 2–5 วินาที) จนสถานะเป็น DONE แล้วจึงเรียก Report Result
selected_columns ที่ส่งไปจะถูกใช้ตามที่ระบุ — ควรเลือกจาก Available Columns ของงวดเดือนนั้น
รองรับไฟล์ csv และ json — หากไม่ส่ง type ระบบจะสร้างไฟล์เป็น csv (ค่าเริ่มต้น) ส่วน excel/pdf ไม่รองรับแล้ว (400)

List Templates - รายการรายงานและ filter ที่ใช้ได้
Available Columns - คอลัมน์ที่เลือกแสดงได้
Report Status - ตรวจสอบสถานะงาน
Report Result - รับลิงก์ดาวน์โหลด