Excel Import

Import การตั้งค่าวงเงินสวัสดิการพนักงานจากไฟล์ Excel (.xlsx) หลายพนักงานพร้อมกันในครั้งเดียว ระบบจะอ่านข้อมูลจาก Excel แล้วแทนที่ Config เดิมด้วยข้อมูลใหม่

Endpoint


POST /api/v1/open-apis/welfare/excel_import

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

Content-Type: multipart/form-data

Request Body

Parameter	Type	Required	Description	Example
`_fileUpd`	file	Yes	ไฟล์ Excel (.xlsx)	`@/path/to/welfare_config.xlsx`
`year`	string	Yes	ปีสวัสดิการ (YYYY)	`"2026"`

โครงสร้างไฟล์ Excel

ข้อมูลเริ่มที่ Row 3 (Row 1-2 เป็น Header)


Row 1: [Header Row - ไม่อ่านข้อมูล]
Row 2: [Header Row - ไม่อ่านข้อมูล]
Row 3: EMP001  |  ...  |  ...  |  ...  |  ...  |  SAL_MED  |  ...  |  5000  |  20000
Row 4: EMP002  |  ...  |  ...  |  ...  |  ...  |  SAL_DEN  |  ...  |  0     |  10000
...

Column	Field	Description
A	employee_code	รหัสพนักงาน (ต้องมีอยู่ในระบบ)
F	salary_type_code	รหัสประเภทสวัสดิการ (ต้องมีอยู่ในระบบ)
H	welfare_prev_amt	ยอดยกมาจากปีก่อน (ตัวเลข) · เว้นว่าง = คงค่าเดิม
I	welfare_quota_amt	วงเงินสวัสดิการ (ตัวเลข) · เว้นว่าง = คงค่าเดิม
J	welfare_claim_limit_amt	วงเงินต่อการเบิก 1 ฉบับ · เว้นว่าง = คงค่าเดิม · ค่าติดลบ/ไม่ใช่ตัวเลข = `NULL` (ไม่จำกัด) · ถ้าเกิน `H + I` จะถูก clamp ลงเป็นยอดรวม
K	row-index	ไม่ใช้ — ระบบ ignore

Validation Rules

Rule	Description
`_fileUpd`	ต้องแนบไฟล์มาด้วย
`year`	ต้องไม่ว่างเปล่า (รูปแบบ YYYY)
ไฟล์	ต้องเป็นไฟล์ `.xlsx` เท่านั้น
employee_code (Column A)	ต้องมีอยู่ในระบบ — ถ้าไม่พบจะข้ามรายการนั้น
salary_type_code (Column F)	ต้องมีอยู่ในระบบ — ถ้าไม่พบจะข้ามรายการนั้น

Response Format

Success Response (HTTP 200)


{
  "code": 200,
  "message": "Import สำเร็จ",
  "payload": {
    "year": "2026",
    "all_record": 50,
    "insert_record": 45,
    "update_record": 0,
    "delete_record": 0,
    "error_record": 5,
    "import_log_file_path": "https://example.com/file-import/employee-welfares/20260327/ABCD1234.xlsx",
    "error_log": "https://example.com/file-import/employee-welfares/20260327/ABCD1234_error_log.txt"
  }
}

Response Fields

Field	Type	Nullable	Description
`year`	string	No	ปีที่ Import
`all_record`	integer	No	จำนวน Row ทั้งหมดที่อ่านได้
`insert_record`	integer	No	จำนวน Row ที่เพิ่มสำเร็จ
`update_record`	integer	No	จำนวน Row ที่อัปเดต (ปัจจุบัน = 0 เสมอ)
`delete_record`	integer	No	จำนวน Row ที่ลบ (= จำนวนที่ถูก replace)
`error_record`	integer	No	จำนวน Row ที่ Error (ข้ามไป)
`import_log_file_path`	string	Yes	URL ไฟล์ Excel ที่ upload ไว้
`error_log`	string	Yes	URL ไฟล์ Log ผลการ Import

Error Response - Validation Failed (HTTP 422)


{
  "code": 422,
  "message": "Validation failed",
  "errors": [
    "'_fileUpd' file and 'year' are required"
  ]
}

Error Response - Wrong File Type (HTTP 400)


{
  "code": 400,
  "message": "Exception File type not support"
}

Error Response - Server Error (HTTP 400)


{
  "code": 400,
  "message": "Exception Cannot copy files"
}

Code Examples

cURL


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/welfare/excel_import" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -F "year=2026" \
  -F "_fileUpd=@/path/to/welfare_config_2026.xlsx"

JavaScript


const formData = new FormData()
formData.append('year', '2026')
formData.append('_fileUpd', fileInput.files[0])
 
const response = await fetch(
  'https://openapi.humansoft.co.th/api/v1/open-apis/welfare/excel_import',
  {
    method: 'POST',
    headers: {
      'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY'
    },
    body: formData
  }
)
const data = await response.json()
console.log(data.payload)

Python


import requests
 
url = "https://openapi.humansoft.co.th/api/v1/open-apis/welfare/excel_import"
headers = {"Ocp-Apim-Subscription-Key": "YOUR_API_KEY"}
files = {"_fileUpd": open("/path/to/welfare_config_2026.xlsx", "rb")}
data = {"year": "2026"}
 
response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

PHP


<?php
$url = "https://openapi.humansoft.co.th/api/v1/open-apis/welfare/excel_import";
$headers = ["Ocp-Apim-Subscription-Key: YOUR_API_KEY"];
$postFields = [
    "year" => "2026",
    "_fileUpd" => new CURLFile("/path/to/welfare_config_2026.xlsx", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postFields);
$response = curl_exec($ch);
print_r(json_decode($response, true));
curl_close($ch);
?>

Notes

ข้อควรทราบ:

ไฟล์ต้องเป็น .xlsx เท่านั้น (ไม่รองรับ .xls, .csv)
ข้อมูลต้องเริ่มที่ Row 3 (Row 1-2 เป็น Header)
ระบบจะ แทนที่ Config เดิม ก่อนสร้างใหม่เสมอ (Replace ไม่ใช่ Update)
Row ที่ Column A ว่างจะถือเป็นสัญญาณหยุดอ่าน
Row ที่ Column H, I และ J ว่างทั้งหมดจะถูกข้ามไป (ไม่แตะข้อมูลเดิม)
ช่องที่เว้นว่างใน Row ที่ถูกประมวลผล = คงค่าเดิม (merge ก่อน replace)
ตัวเลขใน Excel รองรับ comma separator เช่น 20,000.00
Column J (วงเงินต่อฉบับ): ค่าที่ไม่ใช่ตัวเลขหรือติดลบ = NULL (ไม่จำกัด) · ถ้าเกิน H + I จะถูก clamp เป็นยอดรวมอัตโนมัติ · ระวังไฟล์เก่าที่มี row-index อยู่ Column J — format ใหม่ย้าย row-index ไป Column K แล้ว

Excel Template - ดาวน์โหลด template Excel พร้อม pre-fill ข้อมูลพนักงาน
Import File Log - อัปโหลดไฟล์ + สร้าง import log (ยังไม่ประมวลผลข้อมูลในไฟล์)
Import JSON - ส่งข้อมูลแถวที่ parse แล้วเป็น JSON เพื่อ import
Update Multiple - อัปเดตหลายพนักงานผ่าน JSON แทน Excel
List Welfare Employee By Type - ตรวจสอบผลหลัง Import