Report Builder API Module

ภาพรวม (Overview)

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

โมดูลนี้ทำงานแบบ Submit → Poll → Download ต่างจากโมดูล Report เดิมที่คืนข้อมูลแบบ synchronous ในครั้งเดียว — เหมาะกับการออกไฟล์ที่มีปริมาณข้อมูลมาก (ปัจจุบันรองรับไฟล์ CSV)

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

ขั้นตอนการใช้งาน (Workflow)

ค้นหารายงานที่ใช้ได้ — เรียก List Templates เพื่อดูรายงานที่ API Key เข้าถึงได้ พร้อมรายการ filter ของแต่ละรายงาน
ดูคอลัมน์ที่เลือกได้ — เรียก Available Columns เพื่อดูคอลัมน์ที่สามารถเลือกแสดงในรายงาน (ขึ้นกับงวดเดือนและภาษา)
ส่งคำขอสร้างรายงาน — เรียก Submit Report ระบบจะคืน trace_id พร้อมสถานะ PENDING (HTTP 202)
ตรวจสอบสถานะ — เรียก Report Status ด้วย trace_id เป็นระยะ จนสถานะเป็น DONE
ดาวน์โหลดไฟล์ — เรียก Report Result เพื่อรับลิงก์ดาวน์โหลดไฟล์แบบมีอายุจำกัด

API Endpoints

Operation	Endpoint	Method
ส่งคำขอสร้างรายงาน	`/api/v1/open-apis/report-builder/reports`	`POST`
รายการรายงานที่ใช้ได้	`/api/v1/open-apis/report-builder/reports/templates`	`GET`
คอลัมน์ที่เลือกได้	`/api/v1/open-apis/report-builder/reports/{report}/columns`	`GET`
ตรวจสอบสถานะงาน	`/api/v1/open-apis/report-builder/reports/{traceId}/status`	`GET`
รับลิงก์ดาวน์โหลด	`/api/v1/open-apis/report-builder/reports/{traceId}/result`	`GET`

รายงานที่รองรับ (Available Reports)

ปัจจุบันโมดูลนี้รองรับ 5 รายงาน ทั้งหมดต้องใช้สิทธิ์ report:generate:

Report ID	ชื่อรายงาน	Output ที่รองรับ
`net_total_month_custom`	รายงานผลการคำนวณเงินเดือนสุทธิงวดปกติ Custom	`csv`, `json`
`payroll_period_summary`	สรุปงวดเงินเดือน	`csv`, `json`
`payroll_attendance_detail`	รายละเอียดการลงเวลารายวัน	`csv`, `json`
`master_employee`	ทะเบียนพนักงาน	`csv`, `json`
`leave_transaction`	รายการการลา	`csv`, `json`

ดูรายการ filter และคอลัมน์ของแต่ละรายงานได้ที่ List Templates และ Available Columns

Output Types

กำหนดรูปแบบไฟล์ผลลัพธ์ผ่าน parameter type ตอนส่งคำขอ — ค่าที่รับได้คือ csv และ json (ค่าเริ่มต้น csv)

รองรับทั้ง csv และ json — ค่าที่ไม่ใช่ csv/json (เช่น excel, pdf) จะได้รับ HTTP 400

Value	Description	สถานะ
`csv`	ไฟล์ CSV (ค่าเริ่มต้นเมื่อไม่ระบุ `type`)	✅ เปิดใช้งาน
`json`	ข้อมูลในรูปแบบ JSON	✅ เปิดใช้งาน

สถานะของงาน (Job Status)

ทุกคำขอสร้างรายงานจะมีสถานะหนึ่งใน 4 ค่า ตรวจสอบได้จาก Report Status:

Status	ความหมาย
`PENDING`	รับคำขอแล้ว กำลังรอประมวลผล
`PROCESSING`	กำลังสร้างรายงาน
`DONE`	สร้างรายงานเสร็จ พร้อมดาวน์โหลด
`FAILED`	สร้างรายงานไม่สำเร็จ

Standard Response Format

Submit Response (HTTP 202)


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

Error Response

ทุก error ใช้รูปแบบเดียวกัน — มี object error ที่ประกอบด้วย code และ message (และ details เมื่อมีรายละเอียดเพิ่มเติม):


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

Error Codes ที่พบบ่อย

Code	HTTP	ความหมาย
`UNAUTHORIZED`	401	ไม่ได้ส่ง API Key หรือ Key ไม่ถูกต้อง/ถูกยกเลิก
`BAD_REQUEST`	400	คำขอไม่ถูกต้อง เช่น parameter หาย, ส่งฟิลด์ที่ไม่รู้จัก, รูปแบบผิด
`REPORT_NOT_FOUND`	400 / 404	ไม่พบ Report ID ที่ระบุ
`UNSUPPORTED_TYPE`	422	ค่า `type` ไม่อยู่ในรายการที่รายงานรองรับ
`FORBIDDEN_PERMISSION`	403	API Key ไม่มีสิทธิ์ที่รายงานต้องการ
`MISSING_FILTER`	400	ไม่ได้ส่ง filter ที่จำเป็น
`INVALID_FILTER`	400	ค่าของ filter ผิดประเภท, ไม่อยู่ในค่าที่อนุญาต, ไม่ตรงรูปแบบ (`pattern`) หรือผิดกฎ cross-field
`NO_MASTER_REPORT`	422	ขอคอลัมน์ของ `net_total_month_custom` หรือ `payroll_period_summary` แต่ยังไม่มีผลการคำนวณเงินเดือนของงวดเดือนนั้น
`JOB_NOT_FOUND`	404	ไม่พบงานตาม `trace_id` ที่ระบุ
`JOB_FORBIDDEN`	403	`trace_id` เป็นของผู้เช่ารายอื่น
`JOB_NOT_READY`	409	ขอผลลัพธ์ขณะที่งานยังไม่เสร็จ (`status` ยังไม่ใช่ `DONE`)
`JOB_FAILED`	422	ขอผลลัพธ์ของงานที่สถานะเป็น `FAILED`

Report - รายงานเงินเดือนและภาษีแบบ synchronous
Salary - จัดการข้อมูลเงินเดือนและเวลาทำงาน
API Permissions - รายการสิทธิ์การเข้าถึง