Create Employee Loan
สร้างรายการเงินกู้/ภาระหนี้สินของพนักงาน พร้อมสร้างตารางงวดผ่อนให้อัตโนมัติ
ใช้ API นี้เพื่อบันทึกเงินกู้ของพนักงาน ระบบจะคำนวณและสร้างงวดผ่อน (installment periods) ให้อัตโนมัติตามเงินต้น จำนวนงวด และประเภทดอกเบี้ยที่ระบุ
Endpoint
POST /api/v1/open-apis/employee-loans/createสิทธิ์ที่ต้องการ: API Key ต้องมีสิทธิ์ ข้อมูลการยื่นเอกสาร (document:manage)
Request Parameters
Required Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
employee_code | string | Yes | รหัสพนักงาน (หรือส่ง employee_id แบบ Base64 แทน) | EMP001 |
salary_type_id | string | Yes | ประเภทเงินหักในสลิป (Base64) ดู Get Loan Types | MjAyNjAzMTY2RTZCQzg3NjQ4MDI= |
employee_loan_dt | string | Yes | วันที่ยื่นกู้ (YYYY-MM-DD) | 2026-07-04 |
employee_loan_start | string | Yes | เดือนเริ่มหัก (YYYY-MM) | 2026-07 |
employee_loan_amt | float | Yes | ยอดกู้สุทธิ (ต้องมากกว่า 0) | 9900 |
employee_loan_period | int | Yes | จำนวนงวดผ่อน (จำนวนเต็ม 1–500) | 10 |
Optional Parameters
| Parameter | Type | Default | Description | Example |
|---|---|---|---|---|
employee_loan_total | float | amt + down | ยอดกู้ทั้งหมดก่อนหักเงินดาวน์ — ถ้าไม่ส่ง ระบบจะคำนวณให้จาก employee_loan_amt + employee_loan_down | 10000 |
employee_loan_down | float | 0 | เงินดาวน์ | 100 |
employee_loan_pay_period | float | 0 | ยอดชำระต่องวด (0 = เฉลี่ยยอดผ่อนอัตโนมัติ) | 990 |
employee_loan_interest | float | 0 | อัตรา/ยอดดอกเบี้ย | 0 |
employee_loan_interest_type | int | 0 | ประเภทดอกเบี้ย: 0 = ต้นลดดอกลด, 1 = คงที่, 2 = ระบุดอกเบี้ยรวม | 0 |
employee_loan_interest_decimal | string | '' | '01' = ปัดเศษยอดผ่อน | 01 |
employee_loan_desc | string | '' | รายละเอียด/หมายเหตุ | งวดผ่อนเงินกู้ยืม |
authorize_id | string | '' | ID ผู้ทำรายการ (Base64) — ถ้าส่งมา ต้องเป็น user ที่มีอยู่จริง มิฉะนั้นได้ 422 | MjAyNjA3MDRVU0VSMDAwMDAx |
หา authorize_id ได้อย่างไร: รับค่าจาก Get Employee Data Filter โดยใช้ path_action=get-user พร้อม employee_code ของผู้ทำรายการ — ใช้ค่า user_id ที่ได้กลับมาเป็น authorize_id
Request Body Example
{
"employee_code": "EMP001",
"salary_type_id": "MjAyNjAzMTY2RTZCQzg3NjQ4MDI=",
"employee_loan_dt": "2026-07-04",
"employee_loan_start": "2026-07",
"employee_loan_total": 10000,
"employee_loan_down": 100,
"employee_loan_amt": 9900,
"employee_loan_period": 10,
"employee_loan_pay_period": 990,
"employee_loan_interest": 0,
"employee_loan_interest_type": 0,
"employee_loan_interest_decimal": "01",
"employee_loan_desc": "งวดผ่อนเงินกู้ยืม"
}Response Format
Success Response (HTTP 200)
payload มีเฉพาะ employee_loan_id (รหัสเงินกู้ที่ระบบสร้างให้) และ period_summary (ผลรวมจากการคำนวณตารางงวดผ่อนทั้งหมด) เท่านั้น — ไม่ใช่ระเบียนเงินกู้แบบเต็มตามพารามิเตอร์ที่ส่งเข้ามา
{
"code": 200,
"message": "สร้างข้อมูลเงินกู้สำเร็จ",
"payload": {
"employee_loan_id": "20260704A1B2C3D4E5F6",
"period_summary": {
"principle": 9900,
"interest": 0,
"period": 9900
}
}
}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": [
"'employee_loan_amt' is required and must be numeric > 0",
"'employee_loan_total' must have at most 2 decimal places",
"'employee_loan_amt' must equal employee_loan_total - employee_loan_down (expected 9,900.00)"
]
}สาเหตุ: ข้อมูลไม่ผ่านการตรวจสอบ เช่น ไม่ได้ส่ง Required Parameter, ยอดเงินติดลบ/ทศนิยมเกิน 2 ตำแหน่ง, ยอดกู้สุทธิ (employee_loan_amt) ไม่เท่ากับ employee_loan_total - employee_loan_down, employee_loan_period เกิน 500, วันที่/เดือนไม่มีอยู่จริง, employee_loan_pay_period เกินยอดกู้, หรือ authorize_id ที่ส่งมาไม่มีในระบบ
Error Response - Salary Type Not Found (HTTP 422)
{
"code": 422,
"message": "การตรวจสอบข้อมูลล้มเหลว",
"errors": [
"'salary_type_id' is invalid or does not exist"
]
}สาเหตุ: salary_type_id ที่ส่งมาไม่มีอยู่ในระบบ — ดึงค่าที่ถูกต้องจาก Get Loan Types แล้วเข้ารหัส Base64 ก่อนส่ง
Error Response - Employee Not Found (HTTP 404)
{
"code": 404,
"message": "ไม่พบข้อมูลพนักงาน"
}สาเหตุ: employee_code หรือ employee_id ไม่มีอยู่ในระบบ
Error Response - Invalid Request (HTTP 400)
{
"code": 400,
"message": "ล้มเหลว"
}สาเหตุ: เกิดข้อผิดพลาดขณะสร้างเงินกู้ (เช่น เดือนที่ระบุปิดการคำนวณเงินเดือนแล้ว หรือข้อผิดพลาดของระบบ) — ค่า message จะสะท้อน error จริงที่เกิดขึ้น ณ ขณะนั้น ไม่ใช่ข้อความคงที่ตามตัวอย่างด้านบนเสมอไป (กรณี salary_type_id ไม่ถูกต้องจะได้ HTTP 422 ไม่ใช่ 400)
Response Fields
| Field | Type | Description |
|---|---|---|
employee_loan_id | string | รหัสเงินกู้ที่สร้าง ใช้อ้างอิงกับ API อื่น (Plain text) |
period_summary.principle | float | ยอดเงินต้นรวมทั้งสัญญา (รวมทุกงวด) |
period_summary.interest | float | ยอดดอกเบี้ยรวมทั้งสัญญา (รวมทุกงวด) |
period_summary.period | float | ยอดรวมเงินต้น + ดอกเบี้ยตลอดสัญญา (principle + interest) — ไม่ใช่ยอดต่องวด |
period_summary.period คือยอดรวมตลอดทั้งสัญญา (เงินต้น + ดอกเบี้ย) ไม่ใช่ยอดชำระต่องวด หากต้องการยอดต่องวด ให้นำ period หารด้วย employee_loan_period หรือดูจากตารางงวดผ่อนที่ระบบสร้างให้ผ่าน Get Loan Detail
Code Examples
cURL
curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/employee-loans/create" \
-H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"employee_code": "EMP001",
"salary_type_id": "MjAyNjAzMTY2RTZCQzg3NjQ4MDI=",
"employee_loan_dt": "2026-07-04",
"employee_loan_start": "2026-07",
"employee_loan_total": 10000,
"employee_loan_down": 100,
"employee_loan_amt": 9900,
"employee_loan_period": 10,
"employee_loan_pay_period": 990,
"employee_loan_interest": 0,
"employee_loan_interest_type": 0,
"employee_loan_interest_decimal": "01",
"employee_loan_desc": "งวดผ่อนเงินกู้ยืม"
}'Validation Rules
| Parameter | Validation | Error Message |
|---|---|---|
employee_code / employee_id | ต้องระบุอย่างใดอย่างหนึ่ง (employee_id เป็น Base64) | 'employee_id' or 'employee_code' is required |
salary_type_id | ต้องระบุ (Base64) และอ้างถึงประเภทเงินที่มีอยู่จริง | 'salary_type_id' is required / 'salary_type_id' is invalid or does not exist |
employee_loan_dt | ต้องระบุ และเป็นวันที่ที่มีอยู่จริง (YYYY-MM-DD) | 'employee_loan_dt' is required / 'employee_loan_dt' must be in YYYY-MM-DD format / 'employee_loan_dt' is not a valid calendar date |
employee_loan_start | ต้องระบุ และเดือนต้องอยู่ในช่วง 01–12 (YYYY-MM) | 'employee_loan_start' is required / 'employee_loan_start' must be in YYYY-MM format / 'employee_loan_start' has an invalid month (must be 01-12) |
employee_loan_amt | ต้องเป็นตัวเลข > 0 และมีทศนิยมไม่เกิน 2 ตำแหน่ง | 'employee_loan_amt' is required and must be numeric > 0 / 'employee_loan_amt' must have at most 2 decimal places |
employee_loan_period | จำนวนเต็ม 1–500 | 'employee_loan_period' is required and must be an integer > 0 / 'employee_loan_period' must not exceed 500 |
employee_loan_total / employee_loan_down / employee_loan_pay_period | หากระบุ ต้องเป็นตัวเลข ≥ 0 และทศนิยมไม่เกิน 2 ตำแหน่ง | '<field>' must be numeric and >= 0 / '<field>' must have at most 2 decimal places |
employee_loan_amt (net) | หากส่ง employee_loan_total มา ต้องเท่ากับ employee_loan_total - employee_loan_down — ถ้าไม่ส่ง employee_loan_total ระบบจะคำนวณให้ = employee_loan_amt + employee_loan_down | 'employee_loan_amt' must equal employee_loan_total - employee_loan_down (expected ...) |
employee_loan_pay_period | ต้องไม่เกิน employee_loan_amt | 'employee_loan_pay_period' must not exceed 'employee_loan_amt' |
employee_loan_interest | หากระบุ ต้องเป็นตัวเลข ≥ 0 (เป็นอัตรา/ยอดดอกเบี้ย ระบุทศนิยมได้ไม่จำกัด) | 'employee_loan_interest' must be numeric and >= 0 |
employee_loan_interest_type | หากระบุ ต้องเป็น 0, 1, หรือ 2 | 'employee_loan_interest_type' must be 0, 1, or 2 |
employee_loan_interest_decimal | หากระบุ ต้องเป็น '' หรือ '01' เท่านั้น | 'employee_loan_interest_decimal' must be '' or '01' |
authorize_id | optional — หากส่งมาต้องเป็น user ที่มีอยู่จริง | 'authorize_id' is invalid or does not exist |
Business Rules
ข้อกำหนดการสร้างเงินกู้:
- ระบบจะสร้างตารางงวดผ่อนให้อัตโนมัติตามจำนวนงวด (
employee_loan_period) และประเภทดอกเบี้ย (employee_loan_interest_type) ที่ระบุ period_summary.periodคือยอดรวมเงินต้น + ดอกเบี้ยตลอดทั้งสัญญา ไม่ใช่ยอดชำระต่องวดsalary_type_idต้องมีอยู่จริงในระบบ (ดู Get Loan Types) มิฉะนั้นจะได้รับ HTTP 422- ไม่สามารถสร้างเงินกู้ในเดือนที่ปิดการคำนวณเงินเดือนแล้ว
employee_loan_amtต้อง > 0 และemployee_loan_periodเป็นจำนวนเต็ม 1–500- ยอดเงิน (
employee_loan_amt,employee_loan_total,employee_loan_down,employee_loan_pay_period) ระบุทศนิยมได้ไม่เกิน 2 ตำแหน่ง และหากส่งemployee_loan_totalมา ยอดกู้สุทธิต้องเท่ากับemployee_loan_total - employee_loan_down employee_loan_totalเป็น optional — ถ้าไม่ส่งมา ระบบจะคำนวณให้อัตโนมัติจากemployee_loan_amt + employee_loan_down- เมื่อ
employee_loan_pay_periodเป็น0ระบบจะเฉลี่ยยอดผ่อนต่องวดให้อัตโนมัติ (หากระบุ ต้องไม่เกินemployee_loan_amt)
Notes
Use Cases
- บันทึกเงินกู้พนักงาน - สร้างรายการเงินกู้พร้อมงวดผ่อนที่คำนวณอัตโนมัติ
- สินเชื่อแบบมีดอกเบี้ย - เลือก
employee_loan_interest_typeตามรูปแบบดอกเบี้ยที่ต้องการ (ต้นลดดอกลด / คงที่ / ระบุดอกเบี้ยรวม) - สินเชื่อแบบมีเงินดาวน์ - ระบุ
employee_loan_totalและemployee_loan_downเพื่อคำนวณยอดกู้สุทธิ
Related APIs
- Get Loan Types - ดึงรายการประเภทเงินหัก (
salary_type_id) - Get Loan List - ดึงรายการเงินกู้ทั้งหมด
- Get Loan Detail - ดูรายละเอียดเงินกู้และตารางงวดผ่อน
- Update Loan - แก้ไขข้อมูลเงินกู้
- Close Loan - ปิดบัญชีเงินกู้