Available Columns

ดึงรายการคอลัมน์ที่สามารถเลือกแสดงในรายงาน สำหรับงวดเดือนและภาษาที่ระบุ

คอลัมน์ของรายงานเป็นแบบ dynamic — ขึ้นกับการตั้งค่าของแต่ละองค์กรและงวดเดือนที่เลือก ใช้ API นี้เพื่อดู key ที่ใช้ได้ก่อนนำไปใส่ใน selected_columns ตอนเรียก Submit Report

Endpoint


GET /api/v1/open-apis/report-builder/reports/{report}/columns

สิทธิ์ที่ต้องการ: API Key ต้องมีสิทธิ์ การสร้างรายงาน (report:generate) จึงจะเรียกดูคอลัมน์ได้ หากไม่มีสิทธิ์นี้จะได้รับ HTTP 403

Request Parameters

Path Parameters

Parameter	Type	Required	Description	Example
`report`	string	Yes	Report ID (ดูรายการที่ List Templates)	`payroll_period_summary`

Query Parameters

Parameter	Type	Required	Default	Description	Example
`year_month`	string	Yes	-	งวดเดือน รูปแบบ `YYYY-MM`	`2026-05`
`language_code`	string	No	`TH`	ภาษาของ label (`TH`, `EN`)	`TH`

Column Groups

แต่ละคอลัมน์อยู่ในกลุ่ม (group) เพื่อช่วยจัดหมวดในการแสดงผล:

Group	ความหมาย
`employee_info`	ข้อมูลพนักงานพื้นฐาน เช่น รหัส, ชื่อ, แผนก, ตำแหน่ง
`period`	ข้อมูลงวด เช่น งวดเดือน, ลำดับงวดจ่าย
`attendance`	ข้อมูลการมาทำงาน เช่น จำนวนวันทำงาน, วันที่มาทำงาน
`leave`	ข้อมูลการลา (แต่ละประเภทการลาที่องค์กรเปิดใช้)
`petty_cash`	เบิกเงินสดย่อยแยกตามประเภทที่เปิดใช้ (key `petty_cash_{id}`)
`ot`	ทำงานล่วงเวลาแยกตามอัตรา — ชั่วโมง/ยอดเงิน/จำนวนวัน/จำนวนเอกสาร (ดูคอลัมน์ OT ด้านล่าง)
`allowance`	เบี้ยเลี้ยง/เงินช่วยเหลือ
`income`	รายการรายได้
`expense`	รายการรายจ่าย
`summary`	ยอดสรุป เช่น รวมรายได้, รวมสุทธิ
`custom_field`	ฟิลด์ที่องค์กรกำหนดเอง
`approver`	ช่องผู้อนุมัติ (ใช้ในรายงาน `master_employee`)
`shift`	กะการทำงานรายวัน (ใช้ในรายงาน `master_employee`)
`quota`	โควตาการลา (ใช้ในรายงาน `leave_transaction`)

รายงาน payroll_period_summary มีคอลัมน์การลา (leave) ต่อประเภทการลาที่องค์กรเปิดใช้งาน (แต่ละประเภทมี leave_{code}_days และ leave_{code}_hours), คอลัมน์เบิกเงินสดย่อยหนึ่งคอลัมน์ต่อประเภทที่เปิดใช้งาน (key รูปแบบ petty_cash_{id}), คอลัมน์ OT ต่ออัตรา (แต่ละอัตรามี ot_{code}_total_hours, ot_{code}_total, ot_{code}_total_days, ot_{code}_total_amount โดย label มาจากการตั้งค่าของบริษัท) และคอลัมน์รายได้/รายจ่ายที่อ้างอิงจากผลการคำนวณเงินเดือนของงวดเดือนนั้น (จึงเกิด NO_MASTER_REPORT หากยังไม่มีผลการคำนวณ)
รายงาน net_total_month_custom มีคอลัมน์รายได้/รายจ่ายตามผลการคำนวณเงินเดือนของงวดเดือนนั้น (จึงเกิด NO_MASTER_REPORT หากยังไม่มีผลการคำนวณ)
รายงาน payroll_attendance_detail มีคอลัมน์ข้อมูลพนักงานและการลงเวลาแบบคงที่, คอลัมน์ OT ต่ออัตรา (ot_{code}_total_hours, ot_{code}_total, ot_{code}_total_days, ot_{code}_total_amount โดย label มาจากการตั้งค่าของบริษัท) พร้อมคอลัมน์เบิกเงินสดย่อยหนึ่งคอลัมน์ต่อประเภทที่เปิดใช้งาน (key รูปแบบ petty_cash_{id}) และคอลัมน์การลาต่อประเภท (แต่ละประเภทมี leave_{code}_days และ leave_{code}_hours)
รายงาน master_employee เป็นทะเบียนพนักงานที่มีคอลัมน์คงที่ทั้งหมด — ข้อมูลพนักงาน (รวม signout_date, last_modified_date), ช่องผู้อนุมัติ 5 ลำดับ (approver_employee_{code,name,last_name,name_en,last_name_en}_{n}) และคอลัมน์ของแต่ละวันในสัปดาห์ (จันทร์–อาทิตย์) ได้แก่ รหัสรอบการทำงานและเวลาเข้า/ออก (work_cycle_code_{day}, work_start_time_{day}, work_end_time_{day}) — ต้องส่ง filter year_month ตอนสร้างรายงาน
รายงาน leave_transaction มีหนึ่งแถวต่อหนึ่งใบลา — คอลัมน์ข้อมูลพนักงานและรายละเอียดการลาแบบคงที่ พร้อมคอลัมน์โควตาการลาต่อประเภทที่เปิดใช้งาน (leave_quota_{code}, leave_used_{code}, leave_remaining_{code})

Code Examples

cURL


curl -X GET "https://openapi.humansoft.co.th/api/v1/open-apis/report-builder/reports/payroll_period_summary/columns?year_month=2026-05&language_code=TH" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY"

JavaScript


const params = new URLSearchParams({ year_month: '2026-05', language_code: 'TH' })
const url = `https://openapi.humansoft.co.th/api/v1/open-apis/report-builder/reports/payroll_period_summary/columns?${params}`
 
const response = await fetch(url, {
  method: 'GET',
  headers: {
    'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY'
  }
})
 
const data = await response.json()
data.available_columns.forEach(c => {
  console.log(`${c.key} (${c.group}) - ${c.label}`)
})

Python


import requests
 
url = "https://openapi.humansoft.co.th/api/v1/open-apis/report-builder/reports/payroll_period_summary/columns"
headers = {
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
params = {
    "year_month": "2026-05",
    "language_code": "TH"
}
 
response = requests.get(url, headers=headers, params=params)
data = response.json()
 
for c in data["available_columns"]:
    print(f"{c['key']} ({c['group']}) - {c['label']}")

PHP


<?php
$query = http_build_query([
    "year_month" => "2026-05",
    "language_code" => "TH"
]);
$url = "https://openapi.humansoft.co.th/api/v1/open-apis/report-builder/reports/payroll_period_summary/columns?{$query}";
 
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Ocp-Apim-Subscription-Key: YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 
$response = curl_exec($ch);
$data = json_decode($response, true);
 
foreach ($data["available_columns"] as $c) {
    echo "{$c['key']} ({$c['group']}) - {$c['label']}\n";
}
 
curl_close($ch);
?>

Response Format

Success Response (HTTP 200)


{
  "report": "payroll_period_summary",
  "year_month": "2026-05",
  "available_columns": [
    { "key": "employee_code", "label": "รหัสพนักงาน", "group": "employee_info" },
    { "key": "employee_name", "label": "ชื่อพนักงาน", "group": "employee_info" },
    { "key": "year_month", "label": "งวดเดือน", "group": "period" },
    { "key": "master_salary_split_seq", "label": "ลำดับงวดจ่าย", "group": "period" },
    { "key": "total_working_days", "label": "จำนวนวันทำงาน", "group": "attendance" },
    { "key": "total_attendance_days", "label": "จำนวนวันที่มาทำงาน", "group": "attendance" },
    { "key": "leave_SICK_days", "label": "ลาป่วย", "group": "leave" },
    { "key": "ot_01_total_hours", "label": "OT 1.0", "group": "ot" },
    { "key": "has_living_allowance", "label": "เบี้ยเลี้ยง", "group": "allowance" }
  ]
}

Response Fields

Field	Type	Description
`report`	string	Report ID ที่เรียก
`year_month`	string	งวดเดือนที่ใช้ดึงคอลัมน์
`available_columns`	array	รายการคอลัมน์ที่เลือกแสดงได้
`available_columns[].key`	string	key ของคอลัมน์ — ใช้ใส่ใน `selected_columns` ตอน Submit
`available_columns[].label`	string	ชื่อคอลัมน์ตาม `language_code`
`available_columns[].group`	string	กลุ่มของคอลัมน์ (ดูตาราง Column Groups)

Error Responses

Missing / Invalid `year_month` (HTTP 400)


{
  "error": {
    "code": "BAD_REQUEST",
    "message": "year_month is required in YYYY-MM format"
  }
}

Report Not Found (HTTP 404)


{
  "error": {
    "code": "REPORT_NOT_FOUND",
    "message": "Unknown report: unknown_report"
  }
}

No Master Report (HTTP 422)

ขอคอลัมน์ของ net_total_month_custom หรือ payroll_period_summary ในงวดเดือนที่ยังไม่มีผลการคำนวณเงินเดือน:


{
  "error": {
    "code": "NO_MASTER_REPORT",
    "message": "No calculated payroll for 2026-05"
  }
}

Permission Denied (HTTP 403)


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

Status Codes

Code	ความหมาย
`200`	สำเร็จ
`400`	ไม่ได้ส่ง `year_month` หรือรูปแบบไม่ใช่ `YYYY-MM`
`401`	ไม่ได้ส่ง API Key หรือ Key ไม่ถูกต้อง
`403`	API Key ไม่มีสิทธิ์ `report:generate` (`FORBIDDEN_PERMISSION`)
`404`	ไม่พบ Report ID ที่ระบุ
`422`	(`NO_MASTER_REPORT`) ขอคอลัมน์ของ `net_total_month_custom` หรือ `payroll_period_summary` แต่ยังไม่มีผลการคำนวณเงินเดือนของงวดเดือนนั้น
`500`	เกิดข้อผิดพลาดระหว่างประมวลผลบนเซิร์ฟเวอร์

สำหรับรายงาน net_total_month_custom และ payroll_period_summary คอลัมน์รายได้/รายจ่ายอ้างอิงจากผลการคำนวณเงินเดือนของงวดเดือนที่ระบุ หากยังไม่มีผลการคำนวณของงวดนั้น จะได้รับ HTTP 422 (NO_MASTER_REPORT)

List Templates - รายการรายงานที่ใช้ได้
Submit Report - ส่งคำขอสร้างรายงาน