Skip to Content
🚀 Welcome to Humansoft Open API Documentation

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

ParameterTypeDefaultDescriptionExample
_PAGEinteger1หมายเลขหน้า (ค่าต่ำกว่า 1 จะถูกปรับเป็น 1)1
_NUMBER_PER_PAGEinteger10จำนวนรายการต่อหน้า (ปรับให้อยู่ในช่วง 1–100 อัตโนมัติ)10
keywordstring''ค้นหาจากรหัสหรือชื่อพนักงานEMP001
start_dtstring''วันที่เริ่มต้นของช่วงวันที่ทำรายการเงินกู้ (YYYY-MM-DD)2026-01-01
end_dtstring''วันที่สิ้นสุดของช่วงวันที่ทำรายการเงินกู้ (YYYY-MM-DD)2026-12-31
salary_type_idstring''กรองตามประเภทเงินกู้ ใช้ค่า salary_type_id ที่ได้จาก Get Loan Types (Base64)MjAyNjAzMTY2RTZCQzg3NjQ4MDI=
statusstring''สถานะเงินกู้: N = Active (กำลังผ่อน), C = Cancel (ปิดบัญชี), Y = Finished (ผ่อนครบแล้ว)N
employee_statusstring''สถานะพนักงาน: N = Active, Y = Out; ค่าว่าง = ทั้งหมดN
employee_code_listarray[]กรองพนักงานตามรายการรหัสพนักงาน (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

FieldTypeDescription
data[]arrayรายการพนักงานที่มีเงินกู้ (ตาม _PAGE/_NUMBER_PER_PAGE ที่ระบุ)
data[].employee_idstringรหัสพนักงาน (Plain text)
data[].employee_codestringรหัสพนักงาน
data[].employee_namestringชื่อพนักงาน
data[].employee_last_namestringนามสกุลพนักงาน
data[].employee_nicknamestringชื่อเล่น
data[].department_namestringแผนก
data[].position_namestringตำแหน่ง
data[].employee_loan_dtstringวันที่ทำรายการเงินกู้ (YYYY-MM-DD)
data[].employee_loan_idstringรหัสเงินกู้ของรายการที่แสดงในแถวนี้ (Plain text)
data[].employee_loan_statusstringสถานะเงินกู้: N = Active, C = Cancel (ปิดบัญชี), Y = Finished
data[].employee_loan_amt_principlenumberเงินต้น
data[].employee_loan_amt_interestnumberดอกเบี้ย
data[].current_loan_periodintงวดที่ผ่อนไปแล้ว
data[].employee_loan_periodintจำนวนงวดทั้งหมด
data[].salary_type_namestringชื่อประเภทเงินกู้
data[].employee_loan_interest_typestringประเภทดอกเบี้ย: 0 = ต้นลดดอกลด, 1 = คงที่, 2 = ระบุดอกเบี้ยรวม
data[].employee_loan_totalnumberยอดกู้ทั้งหมด
data[].employee_loan_downnumberเงินดาวน์ (ยอดหักครั้งแรก ไม่ใช่ยอดผ่อนต่องวด)
data[].salary_type_idstringรหัสประเภทเงินกู้ (Base64 — ส่งกลับไปใช้เป็น request salary_type_id ได้โดยตรง)
data[].employee_loan_list[]arrayเงินกู้ทั้งหมดของพนักงานคนนี้ (กรณีมีมากกว่า 1 รายการ)
data[].employee_loan_list[].employee_idstringรหัสพนักงาน (Plain text)
data[].employee_loan_list[].employee_loan_idstringรหัสเงินกู้ (Plain text)
data[].employee_loan_list[].employee_loan_statusstringสถานะเงินกู้
data[].employee_loan_list[].employee_loan_periodintจำนวนงวดทั้งหมด
data[].employee_loan_list[].employee_loan_totalnumberยอดกู้ทั้งหมด
current_pageintหมายเลขหน้าปัจจุบัน
total_countintจำนวนพนักงานที่มีเงินกู้ทั้งหมด (unique)
pagesintจำนวนหน้าทั้งหมด
current_countintจำนวนพนักงานในหน้านี้

Code Examples

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

ParameterValidationError 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 ของรหัสพนักงาน หากมีรหัสที่ไม่พบแม้ตัวเดียวจะได้ 422employee_code_list contains unknown code(s): ...
_PAGE / _NUMBER_PER_PAGEปรับค่าอัตโนมัติ (_PAGE ต่ำสุด 1, _NUMBER_PER_PAGE อยู่ในช่วง 1–100) — ไม่ทำให้เกิด 422

Notes

Use Cases

  1. แสดงรายการเงินกู้ที่กำลังผ่อน — ใช้ status=N เพื่อดูเฉพาะเงินกู้ที่ยังใช้งานอยู่
  2. ดูเงินกู้ของพนักงานเฉพาะกลุ่ม — ส่ง employee_code_list เป็น array ของรหัสพนักงานที่ต้องการ
  3. กรองตามประเภทเงินกู้ — ใช้ salary_type_id (Base64) ที่ได้จาก Get Loan Types
  4. รายงานตามช่วงเวลา — ใช้ start_dt และ end_dt เพื่อกรองตามช่วงวันที่ทำรายการเงินกู้
  • Get Loan Types - ดึงรายการประเภทเงินกู้ (ที่มาของค่า salary_type_id ที่ใช้ใน filter)
  • Create Employee Loan - สร้างเงินกู้ใหม่
  • Get Loan Detail - ดูรายละเอียดเงินกู้รายการเดียว
  • Update Employee Loan - แก้ไขข้อมูลเงินกู้
Last updated on