Skip to Content
🚀 Welcome to Humansoft Open API Documentation

Get Employee List

ดึงรายการพนักงานทั้งหมด รองรับการกรองข้อมูลตามเงื่อนไขต่างๆ เช่น บริษัท สาขา แผนก ตำแหน่ง สถานะ และรองรับการแบ่งหน้า (Pagination)

API นี้เหมาะสำหรับแสดงรายการพนักงานในหน้า List View หรือ Dashboard ถ้าต้องการข้อมูลครบถ้วนรายบุคคล ใช้ Get Employee Info แทน

Convention ID: พารามิเตอร์ที่ลงท้าย _id ต้องส่งเป็น Base64-encoded string (เช่น base64_encode("20241225C3024958C974")MjAyNDEyMjVDMzAyNDk1OEM5NzQ=). Response คืนค่า ID เป็น raw string — เมื่อนำไปใช้ใน request อื่นที่รับ *_id ต้อง encode เป็น Base64 ก่อนส่ง

Endpoint

GET /api/v1/open-apis/employee/get-employee-list

สิทธิ์ที่ต้องการ: API Key ต้องมีสิทธิ์ ข้อมูลพนักงานพื้นฐาน (employee:read:basic)

การกรองข้อมูลตามสิทธิ์ (Field-Level Filtering): ระบบจะกรองข้อมูลใน response อัตโนมัติตามระดับสิทธิ์ของ API Key

  • ไม่มีสิทธิ์ employee:read:personal → ฟิลด์ข้อมูลส่วนตัวจะถูกตัดออก เช่น id_no, mobilephone, emailaddress, ข้อมูลที่อยู่ (address, full_address, current_address) และรายการประวัติส่วนตัวทั้งหมด (family_lists, education_lists, ability_lists, trainning_lists, language_skill_lists, typing_skill_lists, driving_skill_lists, possess_lists, document_lists)
  • ไม่มีสิทธิ์ payroll:read:self หรือ payroll:read:all → ฟิลด์ข้อมูลการเงินจะถูกตัดออก เช่น บัญชีธนาคาร (bank_id, bank_code, bank_name, bank_account_code), ข้อมูลภาษี/ประกันสังคม (tax_method_lv, social_insurance_method_lv, sso_no), รายการการเงินสะสม (loan_lists, constant_lists, fund_lists, tax_lists, work_insurance_lists) และอัตราเงินเดือนในโปรไฟล์

Query Parameters

พารามิเตอร์การค้นหา

ParameterTypeRequiredDescriptionExample
keywordstringNoคำค้นหา (รหัส, ชื่อ, นามสกุล, ชื่อเล่น)สมชาย

พารามิเตอร์การกรอง (Filter)

พารามิเตอร์ที่ลงท้าย _id ต้องส่งเป็น Base64-encoded ของ raw internal ID

ParameterTypeRequiredDescriptionExample (Base64)
company_idstringNoกรองตาม ID บริษัทMjAyNDEyMjVDMzAyNDk1OEM5NzQ=
branch_idstringNoกรองตาม ID สาขาMjAyNDEyMjU0MzU4NjQ2QjM0RTQ=
department_idstringNoกรองตาม ID แผนก/ฝ่ายMjAyNDEyMjVGNTIwQUM4NDU2RUQ=
division_idstringNoกรองตาม ID ส่วน-
section_idstringNoกรองตาม ID งาน-
position_idstringNoกรองตาม ID ตำแหน่งMjAyNDEyMjU4N0MyMTZEQTJDMTk=
employee_type_codestringNoกรองตามประเภทพนักงาน (01-04)01
employee_type_group_idstringNoกรองตามกลุ่มประเภทพนักงานMjAyNDEyMjU1NkQzMjkxM0Y1MUU=
sys_del_flagstringNoกรองตามสถานะพนักงาน (A=ทั้งหมด, Y=ลาออก, N=ทำงาน)N

พารามิเตอร์เพิ่มเติม

ParameterTypeRequiredDescriptionExample
include_salarystringNoรวมข้อมูลเงินเดือน (Y=รวม, N=ไม่รวม)Y
sort_bystringNoเรียงข้อมูลตามฟิลด์employee_code
sort_orderstringNoลำดับการเรียง (ASC, DESC)ASC

sort_by Options:

  • employee_code - รหัสพนักงาน
  • employee_name - ชื่อพนักงาน
  • created - วันที่สร้าง
  • begin_dt - วันที่เริ่มงานจริง
  • effective_dt - วันที่เริ่มงาน

พารามิเตอร์ Pagination

ParameterTypeRequiredDescriptionExample
_PAGEnumberNoหน้าที่ต้องการ (เริ่มต้นที่ 1)1
_NUMBER_PER_PAGEnumberNoจำนวนรายการต่อหน้า (1-1000)50

Response Format

Success Response (HTTP 200)

ค่า field ที่ลงท้าย _id ใน response เป็น raw string (ไม่ใช่ Base64) เมื่อนำไปใช้ใน request อื่นต้อง encode เป็น Base64 ก่อนส่ง

{ "code": 200, "message": "สำเร็จ", "payload": [ { "employee_id": "20260121FC89F3BB9120", "employee_code": "EMP0001", "employee_name": "สมชาย", "employee_last_name": "ใจดี", "employee_nickname": "ชาย", "employee_title_lv": "01", "employee_title_name": "นาย", "employee_title_name_en": "Mr.", "employee_type_code": "01", "employee_type_name": "พนักงานรายเดือน", "employee_type_group_id": "2024122556D32913F51E", "employee_type_group_name": "พนักงานประจำ", "company_id": "20241225C3024958C974", "company_name": "บริษัท ABC จำกัด", "branch_id": "202412254358646B34E4", "branch_name": "สาขากรุงเทพ", "department_id": "20241225F520AC8456ED", "department_name": "ฝ่ายบริหาร", "position_id": "2024122587C216DA2C19", "position_name": "ผู้จัดการ", "effective_dt": "2024-01-15", "effective_dt_age": "2 ปี 0 เดือน 0 วัน", "begin_dt": "2024-01-15", "begin_dt_age": "2 ปี 0 เดือน 0 วัน", "created": "2024-01-10 10:30:00" } ], "_PAGINATION": { "_TOTAL_RECORDS": 100, "_PAGE": 1, "_NUMBER_PER_PAGE": 50 } }

Response with Salary (include_salary=Y)

{ "code": 200, "message": "สำเร็จ", "payload": [ { "employee_id": "20260121FC89F3BB9120", "employee_code": "EMP0001", "employee_name": "สมชาย", "employee_last_name": "ใจดี", "company_id": "20241225C3024958C974", "company_name": "บริษัท ABC จำกัด", "salary": 30000, "salary_amt": 30000, "total_salary": 30000, "total_income": 35000, "total_expense": 3000, "empNodes": [...], "tax_list": [...] } ] }

Error Response (HTTP 400)

{ "code": 400, "message": "ไม่สำเร็จ", "errors": [ "'sys_del_flag' must be one of: A (All employees), Y (Resigned), N (Active)", "'_PAGE' must be a positive number" ] }

Response Fields

ข้อมูลพนักงาน

FieldTypeDescription
employee_idstringID ของพนักงาน
employee_codestringรหัสพนักงาน
employee_namestringชื่อพนักงาน (ตามภาษาที่เลือก)
employee_last_namestringนามสกุลพนักงาน
employee_nicknamestringชื่อเล่น
employee_title_lvstringรหัสคำนำหน้าชื่อ เช่น 01, 02, 03
employee_title_namestringคำนำหน้าชื่อ (ไทย)
employee_title_name_enstringคำนำหน้าชื่อ (อังกฤษ)
employee_type_codestringประเภทพนักงาน (01-04)
employee_type_namestringชื่อประเภทพนักงาน
employee_type_group_idstringID กลุ่มประเภทพนักงาน
employee_type_group_namestringชื่อกลุ่มประเภทพนักงาน

ข้อมูลองค์กร

FieldTypeDescription
company_idstringID ของบริษัท
company_namestringชื่อบริษัท
branch_idstringID ของสาขา
branch_namestringชื่อสาขา
department_idstringID ของแผนก
department_namestringชื่อแผนก
division_idstringID ของส่วน
division_namestringชื่อส่วน
section_idstringID ของงาน
section_namestringชื่องาน
section_lv01_id ถึง section_lv05_idstringID ของงานระดับ 1-5
section_lv01_name ถึง section_lv05_namestringชื่องานระดับ 1-5
position_idstringID ของตำแหน่ง
position_namestringชื่อตำแหน่ง

Endpoint นี้คืน employee_title_* แล้ว แต่ยังไม่คืน position_level — หากต้องการระดับตำแหน่งให้ใช้ Get Employee Info หรือ lookup Get List Position

ข้อมูลวันที่

FieldTypeDescription
effective_dtdateวันที่เริ่มงาน
effective_dt_agestringอายุงาน (นับจาก effective_dt)
begin_dtdateวันที่เริ่มงานจริง
begin_dt_agestringอายุงาน (นับจาก begin_dt)
createddatetimeวันเวลาที่สร้างข้อมูล

ข้อมูลเงินเดือน (เมื่อ include_salary=Y)

FieldTypeDescription
salarynumberเงินเดือนพื้นฐาน
salary_amtnumberเงินเดือนรายเดือน
salary_dailynumberเงินเดือนรายวัน
salary_lawnumberเงินเดือนตามกฎหมาย
salary_per_weeknumberเงินเดือนรายสัปดาห์
total_salarynumberรวมเงินเดือน
total_incomenumberรวมรายรับ
total_expensenumberรวมรายจ่าย
empNodesarrayรายการประเภทพนักงานทั้งหมด
tax_listarrayรายการวิธีคำนวณภาษี

Pagination

FieldTypeDescription
_PAGINATION._TOTAL_RECORDSnumberจำนวนรายการทั้งหมด
_PAGINATION._PAGEnumberหน้าปัจจุบัน
_PAGINATION._NUMBER_PER_PAGEnumberจำนวนรายการต่อหน้า

Code Examples

# ดึงรายการพนักงานทั้งหมด curl -X GET "https://openapi.humansoft.co.th/api/v1/open-apis/employee/get-employee-list" \ -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" # ดึงพร้อม Filter และ Pagination (company_id ส่งเป็น Base64) curl -X GET "https://openapi.humansoft.co.th/api/v1/open-apis/employee/get-employee-list?company_id=MjAyNDEyMjVDMzAyNDk1OEM5NzQ=&sys_del_flag=N&_PAGE=1&_NUMBER_PER_PAGE=50" \ -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" # ค้นหาด้วย Keyword curl -X GET "https://openapi.humansoft.co.th/api/v1/open-apis/employee/get-employee-list?keyword=สมชาย" \ -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" # รวมข้อมูลเงินเดือน curl -X GET "https://openapi.humansoft.co.th/api/v1/open-apis/employee/get-employee-list?include_salary=Y" \ -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY"

Validation Rules

ParameterRule
sys_del_flagต้องเป็น A, Y, หรือ N
employee_type_codeต้องเป็น 01, 02, 03, หรือ 04
include_salaryต้องเป็น Y หรือ N
sort_byต้องเป็น employee_code, employee_name, created, begin_dt, หรือ effective_dt
sort_orderต้องเป็น ASC หรือ DESC
_PAGEต้องเป็นตัวเลขบวก (≥ 1)
_NUMBER_PER_PAGEต้องเป็นตัวเลข 1-1000

Notes

Performance Tips:

  • ใช้ Filter เพื่อจำกัดขอบเขตข้อมูล
  • ใช้ Pagination ไม่เกิน 100 รายการต่อหน้า
  • หลีกเลี่ยง include_salary=Y ถ้าไม่จำเป็น

keyword จะค้นหาใน:

  • รหัสพนักงาน (employee_code)
  • ชื่อ (employee_name)
  • นามสกุล (employee_last_name)
  • ชื่อเล่น (employee_nickname)

Include Salary

เมื่อ include_salary=Y:

  • รวมข้อมูลเงินเดือนและรายรับ/รายจ่าย
  • รวม empNodes (รายการประเภทพนักงานทั้งหมด)
  • รวม tax_list (รายการวิธีคำนวณภาษี)

ข้อมูลเงินเดือนเป็นข้อมูลที่มีความละเอียดอ่อน ใช้ด้วยความระมัดระวัง

Language Support

  • API รองรับทั้งภาษาไทย (TH) และภาษาอังกฤษ (EN)
  • ฟิลด์ที่รองรับหลายภาษาจะแสดงตามภาษาที่เลือก

Last updated on