Skip to Content
🚀 Welcome to Humansoft Open API Documentation

Import Employee

นำเข้าข้อมูลพนักงานหลายคนพร้อมกัน (Bulk Import) รองรับการเพิ่ม แก้ไข และลบข้อมูลพนักงานในครั้งเดียว โดยใช้รูปแบบ Column-based เหมือน Excel

API นี้ใช้สำหรับนำเข้าข้อมูลจำนวนมาก ควรแบ่งเป็น batch ละ 50-100 รายการ เพื่อประสิทธิภาพที่ดี

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

  • Response จะ return raw string ID (เช่น 20260121FC89F3BB9120)
  • เมื่อนำ ID จาก response ไปใช้ใน request ถัดไป ต้อง encode เป็น Base64 ก่อน

Endpoint

POST /api/v1/open-apis/employee/import-employee

Request Body Parameters

Main Parameters

ParameterTypeRequiredDescription
import_dataarrayYesรายการข้อมูลพนักงานที่ต้องการ import
identify_user_idstringNoUser ID ที่ทำการ import (default: จาก JWT token)

Import Data Structure

แต่ละรายการใน import_data เป็น object ที่มี key เป็นตัวอักษร (A, B, C, … BE) เหมือน Excel columns:

{ "import_data": [ { "A": "1", "B": "EMP001", "C": "01-นาย", "D": "สมชาย", "E": "ใจดี", ... "BE": null } ] }

Column Mapping

Basic Information (A-T)

ColumnFieldRequiredDescriptionExample
Arecord_noNoหมายเลขลำดับ"1"
Bemployee_codeYesรหัสพนักงาน"EMP001"
Cemployee_title_lvNoคำนำหน้า (format: "01-นาย")"02-นางสาว"
Demployee_nameYesชื่อ (ไทย)"สมชาย"
Eemployee_last_nameYesนามสกุล (ไทย)"ใจดี"
Ffing_codeNoรหัสลายนิ้วมือ"EMP001"
Gemployee_genderNoเพศ (ชาย, หญิง, ไม่ระบุ)"ชาย"
Hemployee_foreignerNoสัญชาติ (Y=ต่างชาติ, N=ไทย)"N"
Icountry_idNoรหัสประเทศ (ถ้าต่างชาติ)"US"
Jid_noNoเลขบัตรประชาชน (13 หลัก)"1234567890123"
Kpassport_workpermit_noNoเลขหนังสือเดินทาง"A1234567"
Lsso_noNoเลขประกันสังคม"1234567890123"
Msso_start_monthNoเดือนเริ่มประกันสังคม"2026-01"
Nemployee_type_codeNoประเภทพนักงาน (01-04)"01"
Oemployee_type_group_codeNoรหัสกลุ่มประเภทพนักงาน"ET0002"
Pround_month_configNoการคำนวณเดือน"Full-เต็มเดือน"
Qemployee_nicknameNoชื่อเล่น (ไทย)"ชาย"
Remployee_name_enNoชื่อ (อังกฤษ)"Somchai"
Semployee_last_name_enNoนามสกุล (อังกฤษ)"Jaidee"
Temployee_nickname_enNoชื่อเล่น (อังกฤษ)"Chai"

Contact & Dates (U-AC)

ColumnFieldRequiredDescriptionExample
UmobilephoneNoเบอร์โทรศัพท์มือถือ"081-234-5678"
VemailaddressNoอีเมล"somchai@example.com"
Wbirth_dtNoวันเกิด (YYYY-MM-DD)"1990-05-15"
Xeffective_dtYesวันที่เริ่มงาน (YYYY-MM-DD)"2026-01-01"
Ybegin_dtNoวันที่บรรจุ (YYYY-MM-DD)"2026-01-01"
Ztax_start_monthNoเดือนเริ่มคำนวณภาษี"2026-01"
AAsignout_flagNoสถานะลาออก (Y/N)"N"
ABsignout_dtNoวันที่ลาออก (YYYY-MM-DD)""
ACsignout_remarkNoเหตุผลการลาออกnull

Salary & Payment (AD-AJ)

ColumnFieldRequiredDescriptionExample
ADsalaryNoเงินเดือน"25,000.00"
AEsalary_per_weekNoวงเงินเบิกล่วงหน้า"5,000.00"
AFpayment_methodNoวิธีการจ่ายเงิน"1-โอน"
AGcompany_payment_account_codeNoรหัสบัญชีจ่ายเงินบริษัท"B0002"
AHbank_codeNoรหัสธนาคาร"SCB"
AIbank_branch_codeNoรหัสสาขาธนาคาร"002"
AJbank_account_codeNoเลขบัญชีธนาคาร"1234567890"

Registered Address (AK-AN)

ColumnFieldRequiredDescriptionExample
AKaddressNoที่อยู่ (ทะเบียนบ้าน)"99/1 ถนนนเรศวร"
ALsubdistrict_codeNoตำบล/แขวง (ชื่อ)"ในเมือง"
AMdistrict_codeNoอำเภอ/เขต (ชื่อ)"เมืองพิษณุโลก"
ANstate_codeNoจังหวัด (ชื่อ)"พิษณุโลก"

Current Address (AO-AR)

ColumnFieldRequiredDescriptionExample
AOcurrent_addressNoที่อยู่ปัจจุบัน"99/1 ถนนนเรศวร"
APcurrent_subdistrict_codeNoตำบล/แขวงปัจจุบัน"ในเมือง"
AQcurrent_district_codeNoอำเภอ/เขตปัจจุบัน"เมืองพิษณุโลก"
ARcurrent_state_codeNoจังหวัดปัจจุบัน"พิษณุโลก"

Organization Structure (AS-AZ)

ColumnFieldRequiredDescriptionExample
ASdepartment_codeNoรหัสแผนก"D00-002"
ATdivision_codeNoรหัสฝ่ายงานnull
AUsection_codeNoรหัสหน่วยงานnull
AVsection_lv01_codeNoรหัสงานระดับ 1null
AWsection_lv02_codeNoรหัสงานระดับ 2null
AXsection_lv03_codeNoรหัสงานระดับ 3null
AYsection_lv04_codeNoรหัสงานระดับ 4null
AZsection_lv05_codeNoรหัสงานระดับ 5null

ระบบจะค้นหา organization structure จาก column ที่มีข้อมูลก่อน (ตามลำดับ: AZ → AY → AX → AW → AV → AU → AT → AS) และจะ resolve parent IDs ทั้งหมดให้อัตโนมัติ

Additional Info (BA-BE)

ColumnFieldRequiredDescriptionExample
BAposition_codeNoรหัสตำแหน่งงาน"POS-00004"
BBon_board_flagNoสถานะ Onboarding (Y/N)"Y"
BCsalary_calNoสถานะคำนวณเงินเดือน (Y/N)"N"
BDot_template_codeNoรหัส Template OTnull
BEworktime_template_codeNoรหัส Template Worktimenull

Validation Rules

Required Fields

ColumnFieldValidation
Bemployee_codeต้องระบุ (ถ้าไม่ระบุระบบจะสร้างอัตโนมัติ)
Demployee_nameต้องระบุ
Eemployee_last_nameต้องระบุ
Xeffective_dtต้องระบุรูปแบบ YYYY-MM-DD (ถ้าไม่ระบุใช้วันที่ปัจจุบัน)

Additional Validations

  • Column O (employee_type_group_code) ต้องตรงกับ Column N (employee_type_code)
  • แต่ละ column ต้องเป็น String หรือ null

How Import Works

Employee Lookup

ระบบจะค้นหาพนักงานที่มีอยู่แล้วโดย:

  1. ค้นหาจาก employee_code (Column B)
  2. ถ้าไม่เจอ จะค้นหาจาก id_no (Column J)

Insert/Update/Delete Logic

ScenarioAction
ไม่เจอพนักงานในระบบInsert - สร้างพนักงานใหม่
เจอพนักงานในระบบUpdate - แก้ไขข้อมูลที่ส่งมา
Column AA = "Y"Delete - Mark เป็นลาออก

Auto Actions

  • Auto-generate employee_code ถ้าไม่ระบุหรือซ้ำ
  • Resolve Organization Structure (parent IDs)
  • Resolve Address codes (จังหวัด/อำเภอ/ตำบล)
  • Create User Account (ถ้า on_board_flag = "Y" และมี email)
  • Send Onboarding Email (ถ้าเงื่อนไขครบ)
  • Log tracking และ Activity Log

Response Format

Success Response (HTTP 200)

{ "code": 200, "message": "Import completed", "summary": { "total": 10, "inserted": 5, "updated": 3, "deleted": 2, "failed": 0 }, "details": [ { "index": 0, "action": "insert", "employee_code": "EMP001", "status": "success", "employee_id": "20260121FC89F3BB9120" }, { "index": 1, "action": "update", "employee_code": "EMP002", "status": "success", "employee_id": "20260121AB01C2D3E4F5" } ], "errors": [] }

Error Response (HTTP 400)

{ "code": 400, "message": "Import failed", "summary": { "total": 10, "inserted": 0, "updated": 0, "deleted": 0, "failed": 10 }, "details": [], "errors": [ "Missing or invalid 'import_data' field" ] }

Response Fields

Summary

FieldTypeDescription
totalintegerจำนวนรายการทั้งหมดที่ส่งมา
insertedintegerจำนวนรายการที่เพิ่มสำเร็จ
updatedintegerจำนวนรายการที่แก้ไขสำเร็จ
deletedintegerจำนวนรายการที่ลบสำเร็จ
failedintegerจำนวนรายการที่ล้มเหลว

Details

FieldTypeDescription
indexintegerIndex ของรายการใน import_data
actionstringประเภทการดำเนินการ (insert/update/delete)
employee_codestringรหัสพนักงาน
statusstringสถานะ (success/failed)
employee_idstringID ของพนักงาน (ถ้าสำเร็จ)
errorstringข้อความ error (ถ้าล้มเหลว)

Code Examples

# Import พนักงานใหม่ curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/employee/import-employee" \ -H "Content-Type: application/json" \ -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \ -d '{ "import_data": [ { "A": "1", "B": "EMP001", "C": "01-นาย", "D": "สมชาย", "E": "ใจดี", "G": "ชาย", "H": "N", "J": "1234567890123", "N": "01", "U": "081-234-5678", "V": "somchai@example.com", "X": "2026-01-15", "AD": "25,000.00", "AF": "1-โอน", "AH": "SCB", "AJ": "1234567890", "AS": "D00-002", "BA": "POS-00004" } ] }' # Import หลายคนพร้อมกัน curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/employee/import-employee" \ -H "Content-Type: application/json" \ -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \ -d '{ "import_data": [ { "A": "1", "B": "EMP001", "D": "สมชาย", "E": "ใจดี", "X": "2026-01-15" }, { "A": "2", "B": "EMP002", "D": "สมหญิง", "E": "รักดี", "X": "2026-01-15" } ] }' # Mark พนักงานเป็นลาออก curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/employee/import-employee" \ -H "Content-Type: application/json" \ -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \ -d '{ "import_data": [ { "B": "EMP001", "D": "สมชาย", "E": "ใจดี", "X": "2026-01-01", "AA": "Y", "AB": "2026-12-31", "AC": "ลาออก" } ] }'

Notes

Best Practices:

  • แบ่งข้อมูลเป็น batch ละ 50-100 รายการ
  • ตรวจสอบ summary และ details เพื่อดูผลลัพธ์แต่ละรายการ
  • ใช้ identify_user_id เพื่อระบุผู้ที่ทำการ import สำหรับ audit log

Warning:

  • การลบพนักงาน (Column AA = "Y") เป็นการ mark เป็นลาออก ไม่สามารถกู้คืนได้
  • Column ที่เป็น null หรือ "" จะถูกข้าม (ไม่ update ค่าเดิม)
  • สำหรับ Column ที่มีรูปแบบพิเศษ (เช่น "02-นางสาว", "1-โอน"): ระบบจะแยกส่วนแรก (ก่อน -) มาใช้

Troubleshooting

ErrorSolution
Missing or invalid ‘import_data’ fieldตรวจสอบว่า import_data เป็น array ที่มีอย่างน้อย 1 รายการ
Missing required field: Column D or Eต้องระบุ employee_name (D) และ employee_last_name (E)
Missing required field: Column Xต้องระบุ effective_dt ในรูปแบบ YYYY-MM-DD
Employee Type Group does not matchColumn O ต้องตรงกับ Column N

Address Resolution

ระบบจะ resolve codes สำหรับที่อยู่ให้อัตโนมัติ:

  • ระบุชื่อจังหวัด/อำเภอ/ตำบล ระบบจะแปลงเป็น code ให้

  • Add Employee - เพิ่มพนักงานรายบุคคล
  • Update Employee - แก้ไขข้อมูลพนักงานรายบุคคล
  • Get Employee List - ดึงรายการพนักงานทั้งหมด
Last updated on