Import Time Attendance

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

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

Endpoint


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

Request Parameters

Parameter	Type	Required	Description	Example
`import_data`	array	Yes	รายการข้อมูลบันทึกเวลาที่ต้องการนำเข้า	(ดูตัวอย่างด้านล่าง)
`import_data[].status`	string	Yes	การดำเนินการ: `ADD` หรือ `DEL`	`ADD`
`import_data[].employee_code`	string	Yes	รหัสพนักงาน	`EMP001`
`import_data[].date`	string	Yes	วันที่บันทึก (YYYY-MM-DD)	`2025-11-15`
`import_data[].datetime`	string	Yes	วันเวลาบันทึก (YYYY-MM-DD HH:mm:ss)	`2025-11-15 08:30:00`
`import_data[].time_attendance_type`	string	No	ประเภท: `AUTO`, `IN`, `OUT` (default: `AUTO`)	`IN`

Time Attendance Types

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

Request Body Example


{
  "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"
    },
    {
      "status": "ADD",
      "employee_code": "EMP002",
      "date": "2025-11-16",
      "datetime": "2025-11-16 09:00:00",
      "time_attendance_type": "AUTO"
    }
  ]
}

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": ["Missing 'import_data' field"]
}

Error Response - No Valid Data (HTTP 400)

เมื่อไม่มีข้อมูลที่ผ่าน validation เลย


{
  "code": 400,
  "message": "No valid data to import",
  "payload": {
    "invalid_items": [
      {
        "index": 0,
        "data": {
          "status": "ADD",
          "employee_code": "EMP999",
          "date": "2025-11-15",
          "datetime": "2025-11-15 08:30:00"
        },
        "errors": ["employee_code 'EMP999' not found"]
      }
    ]
  }
}

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": "IN"
      }
    ]
  }'

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: 'IN'
        }
      ]
    })
  }
)
 
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": "IN"
        }
    ]
}
 
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" => "IN"
        ]
    ]
];
 
$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	Validation	Error Message
`status`	ต้องเป็น `ADD` หรือ `DEL`	`status must be 'ADD' or 'DEL'`
`employee_code`	ต้องมีอยู่ในระบบ	`employee_code 'XXX' not found`
`date`	ต้องอยู่ในรูปแบบ YYYY-MM-DD	`date must be in format YYYY-MM-DD`
`datetime`	ต้องอยู่ในรูปแบบ YYYY-MM-DD HH:mm:ss	`datetime must be in format YYYY-MM-DD HH:mm:ss`
`time_attendance_type`	ต้องเป็น `AUTO`, `IN`, หรือ `OUT`	`time_attendance_type must be 'AUTO', 'IN', or 'OUT'`

Business Rules

Partial Success:

ระบบจะประมวลผลเฉพาะรายการที่ถูกต้อง และแจ้งรายการที่ไม่ถูกต้องกลับมาใน response
รายการที่ผ่าน validation จะถูกส่งเข้า Queue ทันที
รายการที่ไม่ผ่าน validation จะถูกส่งกลับมาพร้อม error message

Asynchronous Processing

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

Notes

Status Values

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

Important Notes

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

Use Cases

Migration - ย้ายข้อมูลบันทึกเวลาจากระบบเดิม
Integration - รับข้อมูลจากเครื่องสแกนลายนิ้วมือ
Correction - แก้ไขข้อมูลบันทึกเวลาจำนวนมาก

Employee Overview - ภาพรวม Employee APIs