Employee Loans API Module

ภาพรวม (Overview)

โมดูล Employee Loans เป็น API สำหรับจัดการเงินกู้/ภาระหนี้สินของพนักงานที่หักชำระผ่านเงินเดือน ครอบคลุมตั้งแต่การสร้างรายการเงินกู้พร้อมตารางงวดผ่อนอัตโนมัติ การแก้ไข การปิดบัญชี/ยกเลิกการปิดบัญชี การลบข้อมูล ไปจนถึงการดึงรายการและรายละเอียดเงินกู้พร้อมสถานะการชำระของแต่ละงวด

Employee Loans คืออะไร?

Employee Loans (เงินกู้พนักงาน) คือรายการเงินกู้ยืมหรือภาระหนี้สินของพนักงานที่หักชำระผ่านเงินเดือนเป็นงวดๆ แต่ละเงินกู้ประกอบด้วย 2 ส่วนหลัก:

• ข้อมูลเงินกู้ (Loan) = ยอดกู้สุทธิ เงินต้น ดอกเบี้ย จำนวนงวด และประเภทเงินหัก (salary type)
• ตารางงวดผ่อน (Period) = รายการงวดที่ต้องหักในแต่ละเดือน พร้อมสถานะการชำระของแต่ละงวด

เมื่อสร้างเงินกู้ ระบบจะคำนวณและสร้างตารางงวดผ่อนให้อัตโนมัติตามเงินต้น จำนวนงวด และประเภทดอกเบี้ยที่เลือก จากนั้นจะหักเงินตามงวดในแต่ละเดือนจนกว่าจะครบทุกงวด (สถานะ Y) หรือถูกปิดบัญชีก่อนกำหนด (สถานะ C)

API Endpoints (8 endpoints)

ข้อมูลพื้นฐาน

Get Loan Types — GET

ดึงรายการประเภทเงินหักแบบเงินกู้ (salary type) ทั้งหมดของบริษัท ไม่รับพารามิเตอร์ใดๆ

Use Cases:

• แสดง dropdown เลือกประเภทเงินกู้ตอนสร้างเงินกู้
• ใช้อ้างอิงค่า salary_type_id สำหรับ endpoint create

ดึงข้อมูล

Get Loan List — POST

ดึงรายการเงินกู้ของพนักงาน พร้อมฟิลเตอร์ตามสถานะ ช่วงวันที่ ประเภทเงินกู้ หรือรหัสพนักงาน และรองรับ pagination

Use Cases:

• แสดงรายชื่อเงินกู้ที่ยังผ่อนอยู่หรือปิดบัญชีไปแล้ว
• ค้นหาเงินกู้ตามพนักงานหรือประเภทเงินกู้
• หน้าจอ HR Dashboard

Get Loan Detail — GET

ดึงรายละเอียดเงินกู้รายการเดียว รวมข้อมูลพนักงาน ยอดเงินต้น ดอกเบี้ย และตารางงวดผ่อนทั้งหมด

Use Cases:

• แสดงรายละเอียดเงินกู้และตารางงวดผ่อน
• ตรวจสอบสถานะการชำระก่อนแก้ไข/ปิด/ลบ

จัดการเงินกู้

Create Loan — POST

สร้างรายการเงินกู้ใหม่ พร้อมสร้างตารางงวดผ่อนอัตโนมัติตามเงินต้น จำนวนงวด และประเภทดอกเบี้ย

Use Cases:

• บันทึกเงินกู้/ภาระหนี้สินให้พนักงาน
• นำเข้าข้อมูลเงินกู้จากระบบเดิม

Update Loan — POST

แก้ไขรายละเอียดเงินกู้และปรับปรุงตารางงวดผ่อน (แก้ไขได้เฉพาะเงินกู้สถานะ N)

Use Cases:

• แก้ไขข้อผิดพลาดของข้อมูลเงินกู้
• ปรับปรุงเงินต้น/ดอกเบี้ย/ยอดชำระของแต่ละงวดตามข้อตกลงใหม่

Remove Loan — POST

ลบเงินกู้และตารางงวดผ่อนทั้งหมดออกจากระบบ (ไม่สามารถกู้คืนได้)

Use Cases:

• ลบข้อมูลเงินกู้ที่สร้างผิดพลาดหรือซ้ำซ้อน

เปลี่ยนสถานะบัญชีเงินกู้

Close Loan — POST

ปิดบัญชีเงินกู้เพื่อหยุดการหักเงินเดือนในงวดถัดไป เปลี่ยนสถานะเป็น C โดยข้อมูลยังคงอยู่และเปิดกลับมาได้ (ปิดได้เฉพาะเงินกู้สถานะ N)

Use Cases:

• พนักงานขอพักชำระ / หยุดหักชั่วคราว
• ปิดเงินกู้ที่ยังไม่ต้องการหักต่อ

Resume Loan — POST

ยกเลิกการปิดบัญชี เปลี่ยนสถานะจาก C กลับเป็น N (Active) เพื่อเริ่มหักเงินเดือนตามงวดที่เหลือ (ทำได้เฉพาะเงินกู้สถานะ C)

Use Cases:

• กลับมาหักเงินเดือนหลังจากพักชำระ
• ยกเลิกการปิดบัญชีเงินกู้ที่ทำไว้ก่อนหน้า

Employee Loan Status (สถานะเงินกู้)

ฟิลด์ employee_loan_status แสดงสถานะโดยรวมของเงินกู้แต่ละรายการ

Loan Period Status (สถานะงวดผ่อน)

ฟิลด์ employee_loan_period_status แสดงสถานะการชำระของแต่ละงวดในตารางงวดผ่อน

Interest Type (ประเภทดอกเบี้ย)

ฟิลด์ employee_loan_interest_type กำหนดวิธีคำนวณดอกเบี้ยตอนสร้างเงินกู้

Standard Response Format

Success Response

{
  "code": 200,
  "message": "สำเร็จ",
  "payload": { }
}

Error Response (400 / 404)

{
  "code": 404,
  "message": "ไม่พบข้อมูลเงินกู้"
}

Validation Error Response (422)

{
  "code": 422,
  "message": "การตรวจสอบข้อมูลล้มเหลว",
  "errors": [
    "'employee_loan_id' is required",
    "'employee_loan_amt' is required and must be numeric > 0"
  ]
}

Forbidden (403)

{
  "code": 403,
  "message": "Forbidden: Insufficient permissions",
  "error": {
    "type": "PERMISSION_DENIED"
  }
}

สาเหตุ: API Key ไม่มีสิทธิ์ document:manage

หมายเหตุสำคัญ

1. ID Encoding - พารามิเตอร์ *_id ระดับบนสุดใน request (เช่น employee_loan_id, salary_type_id, authorize_id) ต้องเข้ารหัส Base64 ก่อนส่ง ส่วนฟิลด์ *_id ที่คืนมาใน response จะเป็น Plain text

2. salary_type_id - ค่าที่ได้จาก Get Loan Types เป็น plain text ต้องเข้ารหัส Base64 ก่อนนำไปใช้ในการสร้างเงินกู้ ส่วน salary_type_id ที่คืนมาใน response ของเงินกู้ (get-detail / get-list / update / close / resume) จะถูกเข้ารหัส Base64 มาแล้ว สามารถนำไปใช้เป็นค่า request salary_type_id ต่อได้ทันที

3. Employee Code - endpoint create รับ employee_code (plain text เช่น "EMP001") หรือ employee_id (Base64) อย่างใดอย่างหนึ่ง แนะนำให้ใช้ employee_code เพื่อความสะดวก

4. Status Guard - การเปลี่ยนสถานะขึ้นอยู่กับสถานะปัจจุบันของเงินกู้: Update และ Close ทำได้เฉพาะเงินกู้สถานะ N (Active); Resume ทำได้เฉพาะเงินกู้สถานะ C (Cancel); เงินกู้ที่ชำระครบแล้ว (Y Finished) ไม่สามารถแก้ไข ปิด หรือเปิดกลับได้

5. Close vs Remove - การ Close จะหยุดการหักเงินเดือนในงวดถัดไปแต่ข้อมูลยังคงอยู่ และเปิดกลับมาได้ด้วย Resume ส่วนการ Remove จะลบเงินกู้พร้อมตารางงวดผ่อนทั้งหมดและ ไม่สามารถกู้คืนได้ หากต้องการเพียงหยุดการหักชั่วคราว ควรใช้ Close และแนะนำให้สำรองข้อมูลก่อนลบหากต้องอ้างอิงในภายหลัง

6. authorize_id - พารามิเตอร์ทางเลือกสำหรับระบุผู้ทำรายการ (attribution) ในการสร้าง/แก้ไข/ปิด/เปิด/ลบเงินกู้ ต้องเข้ารหัส Base64

Related APIs

• Employee (พนักงาน) - จัดการข้อมูลพนักงานและรหัสพนักงานที่ใช้อ้างอิง
• Salary (เงินเดือน) - จัดการข้อมูลเงินเดือนและประเภทเงินหัก
• Organization (โครงสร้างองค์กร) - ข้อมูลสาขา แผนก และตำแหน่ง