Get Employee Loans List
ดึงรายการเงินกู้/ภาระหนี้สินของพนักงาน พร้อมฟิลเตอร์และการแบ่งหน้า (pagination)
ใช้ API นี้เพื่อค้นหาและดึงรายการเงินกู้ของพนักงาน สามารถกรองตามสถานะเงินกู้ ช่วงวันที่ ประเภทเงินกู้ สถานะพนักงาน หรือรายการรหัสพนักงานได้ เหมาะสำหรับแสดงรายการเงินกู้ที่กำลังผ่อน ปิดบัญชี หรือผ่อนครบแล้ว
Endpoint
POST /api/v1/open-apis/employee-loans/get-listสิทธิ์ที่ต้องการ: API Key ต้องมีสิทธิ์ ข้อมูลการยื่นเอกสาร (document:manage)
Request Parameters
Required Parameters
ไม่มี Required Parameters — หากไม่ส่งพารามิเตอร์ใดเลย ระบบจะคืนรายการเงินกู้ทั้งหมดตามสิทธิ์ของ API Key
Optional Parameters
| Parameter | Type | Default | Description | Example |
|---|---|---|---|---|
_PAGE | integer | 1 | หมายเลขหน้า (ค่าต่ำกว่า 1 จะถูกปรับเป็น 1) | 1 |
_NUMBER_PER_PAGE | integer | 10 | จำนวนรายการต่อหน้า (ปรับให้อยู่ในช่วง 1–100 อัตโนมัติ) | 10 |
keyword | string | '' | ค้นหาจากรหัสหรือชื่อพนักงาน | EMP001 |
start_dt | string | '' | วันที่เริ่มต้นของช่วงวันที่ทำรายการเงินกู้ (YYYY-MM-DD) | 2026-01-01 |
end_dt | string | '' | วันที่สิ้นสุดของช่วงวันที่ทำรายการเงินกู้ (YYYY-MM-DD) | 2026-12-31 |
salary_type_id | string | '' | กรองตามประเภทเงินกู้ ใช้ค่า salary_type_id ที่ได้จาก Get Loan Types (Base64) | MjAyNjAzMTY2RTZCQzg3NjQ4MDI= |
status | string | '' | สถานะเงินกู้: N = Active (กำลังผ่อน), C = Cancel (ปิดบัญชี), Y = Finished (ผ่อนครบแล้ว) | N |
employee_status | string | '' | สถานะพนักงาน: N = Active, Y = Out; ค่าว่าง = ทั้งหมด | N |
employee_code_list | array | [] | กรองพนักงานตามรายการรหัสพนักงาน (array ของ employee_code) — ไม่ส่ง = พนักงานทั้งหมด; หากมีรหัสที่ไม่พบแม้ตัวเดียวจะได้ HTTP 422 | ["EMP001", "EMP002"] |
Request Body Example
{
"_PAGE": 1,
"_NUMBER_PER_PAGE": 10,
"start_dt": "2026-01-01",
"end_dt": "2026-12-31",
"salary_type_id": "MjAyNjAzMTY2RTZCQzg3NjQ4MDI=",
"status": "N",
"employee_status": "N",
"employee_code_list": ["EMP001", "EMP002"]
}Response Format
Success Response (HTTP 200)
โครงสร้างระดับบนสุดของ payload คือ data / current_page / total_count / pages / current_count แต่ละ item ใน data[] คือพนักงาน 1 คนที่มีเงินกู้ โดยฟิลด์ระดับบนแสดงข้อมูลเงินกู้รายการหนึ่งของพนักงานคนนั้น และ employee_loan_list[] จะรวมเงินกู้ทั้งหมดของพนักงาน (กรณีมีมากกว่า 1 รายการ) ทั้งนี้ total_count และ current_count นับจากจำนวนพนักงาน (unique) ไม่ใช่จำนวนเงินกู้
{
"code": 200,
"message": "สำเร็จ",
"payload": {
"data": [
{
"employee_id": "20260704112233AABBCC",
"employee_code": "EMP001",
"employee_name": "สมชาย",
"employee_last_name": "ใจดี",
"employee_nickname": "ชาย",
"department_name": "ฝ่ายบุคคล",
"position_name": "เจ้าหน้าที่บุคคล",
"employee_loan_dt": "2026-07-04",
"employee_loan_id": "20260704A1B2C3D4E5F6",
"employee_loan_status": "N",
"employee_loan_amt_principle": 9900,
"employee_loan_amt_interest": 0,
"current_loan_period": 0,
"employee_loan_period": 10,
"salary_type_name": "เงินกู้ยืมพนักงาน",
"employee_loan_interest_type": "0",
"employee_loan_total": 10000,
"employee_loan_down": 100,
"salary_type_id": "MjAyNjAzMTY2RTZCQzg3NjQ4MDI=",
"employee_loan_list": [
{
"employee_id": "20260704112233AABBCC",
"employee_loan_id": "20260704A1B2C3D4E5F6",
"employee_loan_status": "N",
"employee_loan_period": 10,
"employee_loan_total": 10000
}
]
}
],
"current_page": 1,
"total_count": 5,
"pages": 1,
"current_count": 5
}
}salary_type_id ใน response ถูกส่งกลับมาในรูปแบบ Base64 อยู่แล้ว จึงสามารถนำค่านี้ไปใช้เป็นพารามิเตอร์ salary_type_id ในคำขอถัดไปได้โดยตรง
Error Response - Forbidden (HTTP 403)
{
"code": 403,
"message": "Forbidden: Insufficient permissions",
"error": {
"type": "PERMISSION_DENIED"
}
}สาเหตุ: API Key ไม่มีสิทธิ์ document:manage
Error Response - Validation Failed (HTTP 422)
{
"code": 422,
"message": "การตรวจสอบข้อมูลล้มเหลว",
"errors": ["'status' must be one of: N (Active), C (Cancel), Y (Finished)"]
}สาเหตุ: ค่าพารามิเตอร์ไม่ถูกต้อง เช่น status ไม่ใช่ N/C/Y, employee_status ไม่ใช่ N/Y, employee_code_list ไม่ใช่ array หรือมีรหัสที่ไม่พบในระบบ, หรือ start_dt/end_dt ผิดรูปแบบ (ต้องเป็น YYYY-MM-DD) — หมายเหตุ: _PAGE และ _NUMBER_PER_PAGE จะถูกปรับค่าอัตโนมัติ (clamp) จึงไม่ทำให้เกิด 422
Error Response - Invalid Request (HTTP 400)
{
"code": 400,
"message": "ล้มเหลว"
}สาเหตุ: เกิดข้อผิดพลาดอื่นที่ไม่ใช่การตรวจสอบพารามิเตอร์ — ข้อความใน message จะสะท้อนสาเหตุจริงที่เกิดขึ้น (ไม่ใช่ข้อความคงที่)
Response Fields
| Field | Type | Description |
|---|---|---|
data[] | array | รายการพนักงานที่มีเงินกู้ (ตาม _PAGE/_NUMBER_PER_PAGE ที่ระบุ) |
data[].employee_id | string | รหัสพนักงาน (Plain text) |
data[].employee_code | string | รหัสพนักงาน |
data[].employee_name | string | ชื่อพนักงาน |
data[].employee_last_name | string | นามสกุลพนักงาน |
data[].employee_nickname | string | ชื่อเล่น |
data[].department_name | string | แผนก |
data[].position_name | string | ตำแหน่ง |
data[].employee_loan_dt | string | วันที่ทำรายการเงินกู้ (YYYY-MM-DD) |
data[].employee_loan_id | string | รหัสเงินกู้ของรายการที่แสดงในแถวนี้ (Plain text) |
data[].employee_loan_status | string | สถานะเงินกู้: N = Active, C = Cancel (ปิดบัญชี), Y = Finished |
data[].employee_loan_amt_principle | number | เงินต้น |
data[].employee_loan_amt_interest | number | ดอกเบี้ย |
data[].current_loan_period | int | งวดที่ผ่อนไปแล้ว |
data[].employee_loan_period | int | จำนวนงวดทั้งหมด |
data[].salary_type_name | string | ชื่อประเภทเงินกู้ |
data[].employee_loan_interest_type | string | ประเภทดอกเบี้ย: 0 = ต้นลดดอกลด, 1 = คงที่, 2 = ระบุดอกเบี้ยรวม |
data[].employee_loan_total | number | ยอดกู้ทั้งหมด |
data[].employee_loan_down | number | เงินดาวน์ (ยอดหักครั้งแรก ไม่ใช่ยอดผ่อนต่องวด) |
data[].salary_type_id | string | รหัสประเภทเงินกู้ (Base64 — ส่งกลับไปใช้เป็น request salary_type_id ได้โดยตรง) |
data[].employee_loan_list[] | array | เงินกู้ทั้งหมดของพนักงานคนนี้ (กรณีมีมากกว่า 1 รายการ) |
data[].employee_loan_list[].employee_id | string | รหัสพนักงาน (Plain text) |
data[].employee_loan_list[].employee_loan_id | string | รหัสเงินกู้ (Plain text) |
data[].employee_loan_list[].employee_loan_status | string | สถานะเงินกู้ |
data[].employee_loan_list[].employee_loan_period | int | จำนวนงวดทั้งหมด |
data[].employee_loan_list[].employee_loan_total | number | ยอดกู้ทั้งหมด |
current_page | int | หมายเลขหน้าปัจจุบัน |
total_count | int | จำนวนพนักงานที่มีเงินกู้ทั้งหมด (unique) |
pages | int | จำนวนหน้าทั้งหมด |
current_count | int | จำนวนพนักงานในหน้านี้ |
Code Examples
cURL
curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/employee-loans/get-list" \
-H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"_PAGE": 1,
"_NUMBER_PER_PAGE": 10,
"start_dt": "2026-01-01",
"end_dt": "2026-12-31",
"status": "N",
"employee_status": "N",
"employee_code_list": ["EMP001", "EMP002"]
}'Validation Rules
| Parameter | Validation | Error Message |
|---|---|---|
status | ต้องเป็น N, C, หรือ Y เท่านั้น | 'status' must be one of: N (Active), C (Cancel), Y (Finished) |
employee_status | ต้องเป็น N หรือ Y เท่านั้น (ค่าว่าง = ทั้งหมด) | 'employee_status' must be one of: N (Active), Y (Out) |
start_dt / end_dt | ต้องเป็นรูปแบบ YYYY-MM-DD ถ้าส่งมา | 'start_dt' must be in YYYY-MM-DD format |
salary_type_id | ต้องเป็นค่า Base64 ที่ได้จาก Get Loan Types | — |
employee_code_list | ต้องเป็น array ของรหัสพนักงาน หากมีรหัสที่ไม่พบแม้ตัวเดียวจะได้ 422 | employee_code_list contains unknown code(s): ... |
_PAGE / _NUMBER_PER_PAGE | ปรับค่าอัตโนมัติ (_PAGE ต่ำสุด 1, _NUMBER_PER_PAGE อยู่ในช่วง 1–100) — ไม่ทำให้เกิด 422 | — |
Notes
Use Cases
- แสดงรายการเงินกู้ที่กำลังผ่อน — ใช้
status=Nเพื่อดูเฉพาะเงินกู้ที่ยังใช้งานอยู่ - ดูเงินกู้ของพนักงานเฉพาะกลุ่ม — ส่ง
employee_code_listเป็น array ของรหัสพนักงานที่ต้องการ - กรองตามประเภทเงินกู้ — ใช้
salary_type_id(Base64) ที่ได้จาก Get Loan Types - รายงานตามช่วงเวลา — ใช้
start_dtและend_dtเพื่อกรองตามช่วงวันที่ทำรายการเงินกู้
Related APIs
- Get Loan Types - ดึงรายการประเภทเงินกู้ (ที่มาของค่า
salary_type_idที่ใช้ใน filter) - Create Employee Loan - สร้างเงินกู้ใหม่
- Get Loan Detail - ดูรายละเอียดเงินกู้รายการเดียว
- Update Employee Loan - แก้ไขข้อมูลเงินกู้