Skip to Content
🚀 Welcome to Humansoft Open API Documentation

Create Employee Loan

สร้างรายการเงินกู้/ภาระหนี้สินของพนักงาน พร้อมสร้างตารางงวดผ่อนให้อัตโนมัติ

ใช้ API นี้เพื่อบันทึกเงินกู้ของพนักงาน ระบบจะคำนวณและสร้างงวดผ่อน (installment periods) ให้อัตโนมัติตามเงินต้น จำนวนงวด และประเภทดอกเบี้ยที่ระบุ

Endpoint

POST /api/v1/open-apis/employee-loans/create

สิทธิ์ที่ต้องการ: API Key ต้องมีสิทธิ์ ข้อมูลการยื่นเอกสาร (document:manage)

Request Parameters

Required Parameters

ParameterTypeRequiredDescriptionExample
employee_codestringYesรหัสพนักงาน (หรือส่ง employee_id แบบ Base64 แทน)EMP001
salary_type_idstringYesประเภทเงินหักในสลิป (Base64) ดู Get Loan TypesMjAyNjAzMTY2RTZCQzg3NjQ4MDI=
employee_loan_dtstringYesวันที่ยื่นกู้ (YYYY-MM-DD)2026-07-04
employee_loan_startstringYesเดือนเริ่มหัก (YYYY-MM)2026-07
employee_loan_amtfloatYesยอดกู้สุทธิ (ต้องมากกว่า 0)9900
employee_loan_periodintYesจำนวนงวดผ่อน (จำนวนเต็ม 1–500)10

Optional Parameters

ParameterTypeDefaultDescriptionExample
employee_loan_totalfloatamt + downยอดกู้ทั้งหมดก่อนหักเงินดาวน์ — ถ้าไม่ส่ง ระบบจะคำนวณให้จาก employee_loan_amt + employee_loan_down10000
employee_loan_downfloat0เงินดาวน์100
employee_loan_pay_periodfloat0ยอดชำระต่องวด (0 = เฉลี่ยยอดผ่อนอัตโนมัติ)990
employee_loan_interestfloat0อัตรา/ยอดดอกเบี้ย0
employee_loan_interest_typeint0ประเภทดอกเบี้ย: 0 = ต้นลดดอกลด, 1 = คงที่, 2 = ระบุดอกเบี้ยรวม0
employee_loan_interest_decimalstring'''01' = ปัดเศษยอดผ่อน01
employee_loan_descstring''รายละเอียด/หมายเหตุงวดผ่อนเงินกู้ยืม
authorize_idstring''ID ผู้ทำรายการ (Base64) — ถ้าส่งมา ต้องเป็น user ที่มีอยู่จริง มิฉะนั้นได้ 422MjAyNjA3MDRVU0VSMDAwMDAx

หา 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

FieldTypeDescription
employee_loan_idstringรหัสเงินกู้ที่สร้าง ใช้อ้างอิงกับ API อื่น (Plain text)
period_summary.principlefloatยอดเงินต้นรวมทั้งสัญญา (รวมทุกงวด)
period_summary.interestfloatยอดดอกเบี้ยรวมทั้งสัญญา (รวมทุกงวด)
period_summary.periodfloatยอดรวมเงินต้น + ดอกเบี้ยตลอดสัญญา (principle + interest) — ไม่ใช่ยอดต่องวด

period_summary.period คือยอดรวมตลอดทั้งสัญญา (เงินต้น + ดอกเบี้ย) ไม่ใช่ยอดชำระต่องวด หากต้องการยอดต่องวด ให้นำ period หารด้วย employee_loan_period หรือดูจากตารางงวดผ่อนที่ระบบสร้างให้ผ่าน Get Loan Detail

Code Examples

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

ParameterValidationError 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_idoptional — หากส่งมาต้องเป็น 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

  1. บันทึกเงินกู้พนักงาน - สร้างรายการเงินกู้พร้อมงวดผ่อนที่คำนวณอัตโนมัติ
  2. สินเชื่อแบบมีดอกเบี้ย - เลือก employee_loan_interest_type ตามรูปแบบดอกเบี้ยที่ต้องการ (ต้นลดดอกลด / คงที่ / ระบุดอกเบี้ยรวม)
  3. สินเชื่อแบบมีเงินดาวน์ - ระบุ employee_loan_total และ employee_loan_down เพื่อคำนวณยอดกู้สุทธิ
  • Get Loan Types - ดึงรายการประเภทเงินหัก (salary_type_id)
  • Get Loan List - ดึงรายการเงินกู้ทั้งหมด
  • Get Loan Detail - ดูรายละเอียดเงินกู้และตารางงวดผ่อน
  • Update Loan - แก้ไขข้อมูลเงินกู้
  • Close Loan - ปิดบัญชีเงินกู้
Last updated on