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-employeeRequest Body Parameters
Main Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
import_data | array | Yes | รายการข้อมูลพนักงานที่ต้องการ import |
identify_user_id | string | No | User 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)
| Column | Field | Required | Description | Example |
|---|---|---|---|---|
| A | record_no | No | หมายเลขลำดับ | "1" |
| B | employee_code | Yes | รหัสพนักงาน | "EMP001" |
| C | employee_title_lv | No | คำนำหน้า (format: "01-นาย") | "02-นางสาว" |
| D | employee_name | Yes | ชื่อ (ไทย) | "สมชาย" |
| E | employee_last_name | Yes | นามสกุล (ไทย) | "ใจดี" |
| F | fing_code | No | รหัสลายนิ้วมือ | "EMP001" |
| G | employee_gender | No | เพศ (ชาย, หญิง, ไม่ระบุ) | "ชาย" |
| H | employee_foreigner | No | สัญชาติ (Y=ต่างชาติ, N=ไทย) | "N" |
| I | country_id | No | รหัสประเทศ (ถ้าต่างชาติ) | "US" |
| J | id_no | No | เลขบัตรประชาชน (13 หลัก) | "1234567890123" |
| K | passport_workpermit_no | No | เลขหนังสือเดินทาง | "A1234567" |
| L | sso_no | No | เลขประกันสังคม | "1234567890123" |
| M | sso_start_month | No | เดือนเริ่มประกันสังคม | "2026-01" |
| N | employee_type_code | No | ประเภทพนักงาน (01-04) | "01" |
| O | employee_type_group_code | No | รหัสกลุ่มประเภทพนักงาน | "ET0002" |
| P | round_month_config | No | การคำนวณเดือน | "Full-เต็มเดือน" |
| Q | employee_nickname | No | ชื่อเล่น (ไทย) | "ชาย" |
| R | employee_name_en | No | ชื่อ (อังกฤษ) | "Somchai" |
| S | employee_last_name_en | No | นามสกุล (อังกฤษ) | "Jaidee" |
| T | employee_nickname_en | No | ชื่อเล่น (อังกฤษ) | "Chai" |
Contact & Dates (U-AC)
| Column | Field | Required | Description | Example |
|---|---|---|---|---|
| U | mobilephone | No | เบอร์โทรศัพท์มือถือ | "081-234-5678" |
| V | emailaddress | No | อีเมล | "somchai@example.com" |
| W | birth_dt | No | วันเกิด (YYYY-MM-DD) | "1990-05-15" |
| X | effective_dt | Yes | วันที่เริ่มงาน (YYYY-MM-DD) | "2026-01-01" |
| Y | begin_dt | No | วันที่บรรจุ (YYYY-MM-DD) | "2026-01-01" |
| Z | tax_start_month | No | เดือนเริ่มคำนวณภาษี | "2026-01" |
| AA | signout_flag | No | สถานะลาออก (Y/N) | "N" |
| AB | signout_dt | No | วันที่ลาออก (YYYY-MM-DD) | "" |
| AC | signout_remark | No | เหตุผลการลาออก | null |
Salary & Payment (AD-AJ)
| Column | Field | Required | Description | Example |
|---|---|---|---|---|
| AD | salary | No | เงินเดือน | "25,000.00" |
| AE | salary_per_week | No | วงเงินเบิกล่วงหน้า | "5,000.00" |
| AF | payment_method | No | วิธีการจ่ายเงิน | "1-โอน" |
| AG | company_payment_account_code | No | รหัสบัญชีจ่ายเงินบริษัท | "B0002" |
| AH | bank_code | No | รหัสธนาคาร | "SCB" |
| AI | bank_branch_code | No | รหัสสาขาธนาคาร | "002" |
| AJ | bank_account_code | No | เลขบัญชีธนาคาร | "1234567890" |
Registered Address (AK-AN)
| Column | Field | Required | Description | Example |
|---|---|---|---|---|
| AK | address | No | ที่อยู่ (ทะเบียนบ้าน) | "99/1 ถนนนเรศวร" |
| AL | subdistrict_code | No | ตำบล/แขวง (ชื่อ) | "ในเมือง" |
| AM | district_code | No | อำเภอ/เขต (ชื่อ) | "เมืองพิษณุโลก" |
| AN | state_code | No | จังหวัด (ชื่อ) | "พิษณุโลก" |
Current Address (AO-AR)
| Column | Field | Required | Description | Example |
|---|---|---|---|---|
| AO | current_address | No | ที่อยู่ปัจจุบัน | "99/1 ถนนนเรศวร" |
| AP | current_subdistrict_code | No | ตำบล/แขวงปัจจุบัน | "ในเมือง" |
| AQ | current_district_code | No | อำเภอ/เขตปัจจุบัน | "เมืองพิษณุโลก" |
| AR | current_state_code | No | จังหวัดปัจจุบัน | "พิษณุโลก" |
Organization Structure (AS-AZ)
| Column | Field | Required | Description | Example |
|---|---|---|---|---|
| AS | department_code | No | รหัสแผนก | "D00-002" |
| AT | division_code | No | รหัสฝ่ายงาน | null |
| AU | section_code | No | รหัสหน่วยงาน | null |
| AV | section_lv01_code | No | รหัสงานระดับ 1 | null |
| AW | section_lv02_code | No | รหัสงานระดับ 2 | null |
| AX | section_lv03_code | No | รหัสงานระดับ 3 | null |
| AY | section_lv04_code | No | รหัสงานระดับ 4 | null |
| AZ | section_lv05_code | No | รหัสงานระดับ 5 | null |
ระบบจะค้นหา organization structure จาก column ที่มีข้อมูลก่อน (ตามลำดับ: AZ → AY → AX → AW → AV → AU → AT → AS) และจะ resolve parent IDs ทั้งหมดให้อัตโนมัติ
Additional Info (BA-BE)
| Column | Field | Required | Description | Example |
|---|---|---|---|---|
| BA | position_code | No | รหัสตำแหน่งงาน | "POS-00004" |
| BB | on_board_flag | No | สถานะ Onboarding (Y/N) | "Y" |
| BC | salary_cal | No | สถานะคำนวณเงินเดือน (Y/N) | "N" |
| BD | ot_template_code | No | รหัส Template OT | null |
| BE | worktime_template_code | No | รหัส Template Worktime | null |
Validation Rules
Required Fields
| Column | Field | Validation |
|---|---|---|
| B | employee_code | ต้องระบุ (ถ้าไม่ระบุระบบจะสร้างอัตโนมัติ) |
| D | employee_name | ต้องระบุ |
| E | employee_last_name | ต้องระบุ |
| X | effective_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
ระบบจะค้นหาพนักงานที่มีอยู่แล้วโดย:
- ค้นหาจาก
employee_code(Column B) - ถ้าไม่เจอ จะค้นหาจาก
id_no(Column J)
Insert/Update/Delete Logic
| Scenario | Action |
|---|---|
| ไม่เจอพนักงานในระบบ | 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
| Field | Type | Description |
|---|---|---|
total | integer | จำนวนรายการทั้งหมดที่ส่งมา |
inserted | integer | จำนวนรายการที่เพิ่มสำเร็จ |
updated | integer | จำนวนรายการที่แก้ไขสำเร็จ |
deleted | integer | จำนวนรายการที่ลบสำเร็จ |
failed | integer | จำนวนรายการที่ล้มเหลว |
Details
| Field | Type | Description |
|---|---|---|
index | integer | Index ของรายการใน import_data |
action | string | ประเภทการดำเนินการ (insert/update/delete) |
employee_code | string | รหัสพนักงาน |
status | string | สถานะ (success/failed) |
employee_id | string | ID ของพนักงาน (ถ้าสำเร็จ) |
error | string | ข้อความ error (ถ้าล้มเหลว) |
Code Examples
cURL
# 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
| Error | Solution |
|---|---|
| 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 match | Column O ต้องตรงกับ Column N |
Address Resolution
ระบบจะ resolve codes สำหรับที่อยู่ให้อัตโนมัติ:
- ระบุชื่อจังหวัด/อำเภอ/ตำบล ระบบจะแปลงเป็น code ให้
Related APIs
- Add Employee - เพิ่มพนักงานรายบุคคล
- Update Employee - แก้ไขข้อมูลพนักงานรายบุคคล
- Get Employee List - ดึงรายการพนักงานทั้งหมด
Last updated on