Import Time Attendance

นำเข้าข้อมูลบันทึกเวลาแบบกลุ่ม (Batch Import)

ใช้ API นี้เพื่อนำเข้าข้อมูลบันทึกเวลาเข้า-ออกจำนวนมากพร้อมกัน รองรับทั้งการเพิ่ม (ADD) และการลบ (DEL) ข้อมูลจะถูกส่งเข้า Queue เพื่อประมวลผลแบบ Asynchronous

Endpoint


POST /api/v1/open-apis/time-attendance/import

สิทธิ์ที่ต้องการ: API Key ต้องมีสิทธิ์ ข้อมูลการลงเวลา (attendance:read)

จำกัดสูงสุด 1,000 รายการ ต่อหนึ่ง request

Supported Types

Endpoint นี้ยอมรับ time_attendance_type_lv เฉพาะ 2 รูปแบบ:

รูปแบบที่ส่ง	ผลลัพธ์ที่บันทึก	คำอธิบาย
ไม่ส่งฟิลด์ หรือส่งค่าว่าง	`Import`	ค่า default สำหรับการนำเข้าข้อมูลทั่วไป
`Device` (ไม่สนตัวพิมพ์เล็ก/ใหญ่)	`Fingerprint`	สำหรับข้อมูลจากเครื่องสแกนลายนิ้วมือ

ค่าอื่นๆ (เช่น Wifi, Checkin, Manual) จะถูก ปฏิเสธ ด้วย validation

Request Parameters

พารามิเตอร์หลัก

Parameter	Type	Required	Description	Example
`import_data`	array	Yes	รายการข้อมูลบันทึกเวลาที่ต้องการนำเข้า (สูงสุด 1,000 รายการ)	(ดูตัวอย่างด้านล่าง)

ฟิลด์ใน `import_data` แต่ละรายการ

Required

Parameter	Type	Required	Description	Example
`status`	string	Yes	การดำเนินการ: `ADD` หรือ `DEL`	`ADD`
`employee_code`	string	Yes	รหัสพนักงาน (ต้องมีอยู่ในระบบ)	`EMP001`
`date`	string	Yes	วันที่บันทึก (YYYY-MM-DD) — ต้องตรงกับวันที่ใน `datetime`	`2025-11-15`
`datetime`	string	Yes	วันเวลาบันทึก (YYYY-MM-DD HH:mm:ss)	`2025-11-15 08:30:00`

Optional

Parameter	Type	Required	Description	Example
`time_attendance_type_lv`	string	No	ไม่ส่ง/ว่าง = `Import` หรือส่ง `Device` (ค่าอื่น error)	`Device`
`time_attendance_type`	string	No	ประเภทเวลา: `AUTO`, `IN`, `OUT` (default: `AUTO`)	`IN`
`device_sn`	string	Conditional	บังคับ เมื่อ `time_attendance_type_lv` เป็น `Device`	`SN-FP-001`
`location_id`	string	No	รหัสสถานที่	`MjAyNjAyMTJEOUY2MTE1ODA1NTA=`
`latitude`	number	No	ละติจูด (-90 ถึง 90)	`13.7563`
`longitude`	number	No	ลองจิจูด (-180 ถึง 180)	`100.5018`
`image_content`	string	No	รูป Base64 หรือ data URI (`data:image/jpeg;base64,...`)	`data:image/jpeg;base64,...`

Time Attendance Types (`time_attendance_type`)

Type	Description
`AUTO`	ระบบตัดสินใจอัตโนมัติว่าเป็นเข้างานหรือออกงาน (default)
`IN`	กำหนดเป็นเวลาเข้างานโดยตรง
`OUT`	กำหนดเป็นเวลาออกงานโดยตรง

Request Body Examples

ตัวอย่างที่ 1: นำเข้าแบบทั่วไป (ไม่ส่ง `time_attendance_type_lv`)


{
  "import_data": [
    {
      "status": "ADD",
      "employee_code": "EMP001",
      "date": "2025-11-15",
      "datetime": "2025-11-15 08:30:00",
      "time_attendance_type": "IN"
    },
    {
      "status": "ADD",
      "employee_code": "EMP001",
      "date": "2025-11-15",
      "datetime": "2025-11-15 17:45:00",
      "time_attendance_type": "OUT"
    }
  ]
}

ตัวอย่างที่ 2: นำเข้าจากอุปกรณ์ (Device)


{
  "import_data": [
    {
      "status": "ADD",
      "employee_code": "EMP001",
      "date": "2025-11-15",
      "datetime": "2025-11-15 08:30:00",
      "time_attendance_type_lv": "Device",
      "time_attendance_type": "IN",
      "device_sn": "SN-FP-001"
    }
  ]
}

Response Format

Success Response (HTTP 200)

เมื่อมีข้อมูลที่ถูกต้องอย่างน้อย 1 รายการ ระบบจะส่งข้อมูลที่ถูกต้องเข้า Queue และตอบกลับรายการที่ไม่ผ่าน validation


{
  "code": 200,
  "message": "successfully en-queued",
  "payload": {
    "invalid_items": [
      {
        "index": 1,
        "data": {
          "status": "ADD",
          "employee_code": "EMP999",
          "date": "2025-11-15",
          "datetime": "2025-11-15 17:45:00",
          "time_attendance_type": "OUT"
        },
        "errors": ["employee_code 'EMP999' not found"]
      }
    ]
  }
}

Error Response - Validation Failed (HTTP 400)

เมื่อโครงสร้างข้อมูลระดับนอกสุดไม่ถูกต้อง (ไม่มี import_data, ไม่ใช่ array, หรือว่างเปล่า)


{
  "code": 400,
  "message": "Validation failed",
  "errors": ["'import_data' must be an array"]
}

Error Response - No Valid Data (HTTP 400)

เมื่อไม่มีข้อมูลที่ผ่าน validation เลย (ทุกรายการใน import_data ผิดเงื่อนไข)


{
  "code": 400,
  "message": "No valid data to import",
  "payload": {
    "invalid_items": [
      {
        "index": 0,
        "data": { "employee_code": "BAD-CODE" },
        "errors": ["status is required", "date is required"]
      }
    ]
  }
}

Response Fields

Field	Type	Description
`code`	number	รหัสสถานะ (200 = สำเร็จ, 400 = ไม่สำเร็จ)
`message`	string	ข้อความตอบกลับ
`payload.invalid_items`	array	รายการข้อมูลที่ไม่ผ่าน validation
`errors`	array	รายการข้อผิดพลาดของโครงสร้างข้อมูล (กรณี validation ระดับนอกสุดไม่ผ่าน)

Code Examples

cURL


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/time-attendance/import" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "import_data": [
      {
        "status": "ADD",
        "employee_code": "EMP001",
        "date": "2025-11-15",
        "datetime": "2025-11-15 08:30:00",
        "time_attendance_type_lv": "Device",
        "time_attendance_type": "IN",
        "device_sn": "SN-FP-001"
      }
    ]
  }'

JavaScript


const response = await fetch(
  'https://openapi.humansoft.co.th/api/v1/open-apis/time-attendance/import',
  {
    method: 'POST',
    headers: {
      'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      import_data: [
        {
          status: 'ADD',
          employee_code: 'EMP001',
          date: '2025-11-15',
          datetime: '2025-11-15 08:30:00',
          time_attendance_type_lv: 'Device',
          time_attendance_type: 'IN',
          device_sn: 'SN-FP-001'
        }
      ]
    })
  }
)
 
const data = await response.json()
console.log(data)

Python


import requests
 
url = "https://openapi.humansoft.co.th/api/v1/open-apis/time-attendance/import"
headers = {
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "import_data": [
        {
            "status": "ADD",
            "employee_code": "EMP001",
            "date": "2025-11-15",
            "datetime": "2025-11-15 08:30:00",
            "time_attendance_type_lv": "Device",
            "time_attendance_type": "IN",
            "device_sn": "SN-FP-001"
        }
    ]
}
 
response = requests.post(url, headers=headers, json=payload)
print(response.json())

PHP


<?php
$url = "https://openapi.humansoft.co.th/api/v1/open-apis/time-attendance/import";
 
$headers = [
    "Ocp-Apim-Subscription-Key: YOUR_API_KEY",
    "Content-Type: application/json"
];
 
$payload = [
    "import_data" => [
        [
            "status" => "ADD",
            "employee_code" => "EMP001",
            "date" => "2025-11-15",
            "datetime" => "2025-11-15 08:30:00",
            "time_attendance_type_lv" => "Device",
            "time_attendance_type" => "IN",
            "device_sn" => "SN-FP-001"
        ]
    ]
];
 
$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, json_encode($payload));
 
$response = curl_exec($ch);
print_r(json_decode($response, true));
 
curl_close($ch);
?>

Validation Rules

Parameter	Required	Validation
`import_data`	Yes	ต้องเป็น array บรรจุ object และไม่ว่างเปล่า — จำกัดไม่เกิน 1,000 รายการ
`status`	Yes	ต้องเป็น `ADD` หรือ `DEL` เท่านั้น
`employee_code`	Yes	ต้องมีพนักงานอยู่จริงในระบบ
`date`	Yes	ต้องเป็นวันที่ที่ถูกต้องตามปฏิทิน และเลขวันที่ต้องตรงกับใน `datetime`
`datetime`	Yes	ต้องเป็นรูปแบบ YYYY-MM-DD HH:mm:ss ที่ถูกต้อง
`time_attendance_type`	No	ถ้าส่ง ต้องเป็น `AUTO`, `IN`, หรือ `OUT`
`time_attendance_type_lv`	No	ถ้าส่ง ต้องเป็น `Device` เท่านั้น (ไม่สนตัวพิมพ์); ไม่ส่งหรือว่าง = `Import`; ค่าอื่น error
`device_sn`	Conditional	บังคับต้องส่ง ถ้า `time_attendance_type_lv` เป็น `Device` และต้องมีอยู่จริงในระบบ
`location_id`	No	ถ้าส่ง ต้องเป็น string
`latitude` / `longitude`	No	ถ้าส่ง ต้องอยู่ในช่วงที่กำหนด
`image_content`	No	ถ้าส่ง ต้องเป็น Base64 / data URI ตามรูปแบบที่ API รองรับ

Business Rules

Partial Success:

หากส่งมา 10 รายการ ผ่าน 8 ไม่ผ่าน 2 — ระบบจะส่ง 8 รายการที่ถูกต้องเข้า Queue ทันที
ไม่ต้องส่งข้อมูลเข้ามาซ่อมใหม่ทั้งชุด — ส่งมาเฉพาะรายการที่พังก็พอ
รายการที่ไม่ผ่าน validation จะถูกส่งกลับมาพร้อม error message ใน payload.invalid_items

Asynchronous Processing

ข้อมูลที่ผ่าน validation จะถูกส่งเข้าระบบคิว (Queue) เพื่อประมวลผลเบื้องหลัง
API จะตอบกลับทันทีหลังจาก validate และส่งข้อมูลเข้า Queue สำเร็จ
เหมาะสำหรับการนำเข้าข้อมูลจำนวนมาก

Device Validation

เมื่อใช้ time_attendance_type_lv เป็น Device ระบบจะตรวจสอบว่า device_sn มีอยู่จริงในระบบและเป็นประเภทอุปกรณ์ที่ถูกต้อง
การส่ง device หรือ DEVICE (ตัวพิมพ์เล็ก/ใหญ่) ถือว่าเทียบเท่า Device

Notes

Status Values

Status	Description
`ADD`	เพิ่มข้อมูลบันทึกเวลาใหม่
`DEL`	ลบข้อมูลบันทึกเวลาที่มีอยู่

Important Notes

วันที่ใน date และ datetime ต้องตรงกัน
เวลาใน datetime ควรอยู่ในช่วงเวลาทำงานของพนักงาน
การลบ (DEL) ควรระบุข้อมูลให้ตรงกับที่มีอยู่ในระบบ
ข้อมูลที่ส่งเข้า Queue จะถูกประมวลผลตามลำดับ (FIFO)
รายการที่มี image_content รูปภาพจะถูกจัดเก็บอัตโนมัติและบันทึก URL ในข้อมูลปลายทาง

Use Cases

Migration — ย้ายข้อมูลบันทึกเวลาจากระบบเดิม
Integration — รับข้อมูลจากเครื่องสแกนลายนิ้วมือ (ใช้ time_attendance_type_lv: "Device")
Correction — แก้ไขข้อมูลบันทึกเวลาจำนวนมาก

Submit Time Attendance - บันทึกเวลาแบบรายการเดียว
Employee Overview - ภาพรวม Employee APIs