Submit Time Attendance

บันทึกเวลาเข้า-ออกของพนักงาน

ใช้ API นี้เพื่อบันทึกเวลาเข้า-ออกของพนักงาน รองรับหลายประเภทการบันทึก เช่น Checkin, Wifi, Beacon, QR, Facial, Manager และ Offline โดยข้อมูลจะถูกส่งเข้าระบบคิว (Queue) เพื่อประมวลผลแบบ Asynchronous

Endpoint


POST /api/v1/open-apis/time_attendance/submit

ต้องส่ง payload เป็น JSON ใน Request Body เท่านั้น ไม่รองรับการส่งผ่าน Query Parameters

Attendance Types

Type	Description	Required เพิ่มเติม
`Checkin`	บันทึกเวลาแบบ GPS	`location_id`, `latitude`, `longitude`
`Wifi`	บันทึกเวลาผ่าน Wifi	`device_sn`, `device_name`
`Beacon`	บันทึกเวลาผ่าน Beacon	`device_sn`, `device_name`
`QR`	บันทึกเวลาผ่าน QR Code (Time Attendance App)	`location_id` หรือ (`device_sn` + `device_name`)
`Facial`	บันทึกเวลาด้วยใบหน้า	`location_id`, `latitude`, `longitude`, `image_content`
`Manager`	ผู้จัดการสแกนให้พนักงาน	`image_content`
`Offline`	บันทึกเวลาแบบ Offline	`latitude`, `longitude` (ไม่ต้องมี `company_id`, `work_cycle_date`)

Common Parameters

Required Parameters (ทุกประเภท)

Parameter	Type	Required	Description	Example
`attendance_datetime`	string	Yes	วันเวลาที่บันทึก (ISO 8601 หรือ YYYY-MM-DD HH:mm:ss)	`2026-02-11T09:00:00.000`
`employee_code`	string	Yes	รหัสพนักงาน	`EMP001`
`time_attendance_type_lv`	string	Yes	ประเภทการบันทึกเวลา	`Checkin`

Required Parameters (ส่วนใหญ่ ยกเว้น Offline)

Parameter	Type	Required	Description	Example
`company_id`	string	Yes	รหัสบริษัท (Base64-encoded)	`MjAyNTExMTMzMjBCQzlGODVFNDQ=`
`work_cycle_date`	string	Yes	วันที่กะการทำงาน (YYYY-MM-DD)	`2026-02-11`

Optional Parameters (ทุกประเภท)

Parameter	Type	Required	Description	Example
`work_cycle_type_lv`	string	No	ประเภทกะการทำงาน	`00`
`work_date_seq`	number	No	ลำดับวันทำงาน (default: 1)	`1`
`attendance_remark`	string	No	หมายเหตุการบันทึกเวลา	`บันทึกเวลาเข้างาน`
`approve_remark`	string	No	หมายเหตุการอนุมัติ
`device_sn`	string	No	Serial number อุปกรณ์
`device_name`	string	No	ชื่ออุปกรณ์
`image_path`	string	No	URL รูปภาพ
`latitude`	number	No	ละติจูด (-90 ถึง 90)	`13.7563`
`longitude`	number	No	ลองจิจูด (-180 ถึง 180)	`100.5018`
`location_id`	string	No	รหัสสถานที่ (Base64-encoded)	`MjAyNjAyMTJEOUY2MTE1ODA1NTA=`
`round_month_config`	string	No	การตั้งค่ารอบเดือน (default: 1)	`1`

Case: Checkin

บันทึกเวลาแบบ GPS ต้องระบุสถานที่และพิกัด

Required เพิ่มเติม

Parameter	Type	Required	Description	Example
`location_id`	string	Yes	รหัสสถานที่ (Base64-encoded)	`MjAyNjAyMTJEOUY2MTE1ODA1NTA=`
`latitude`	number	Yes	ละติจูด (-90 ถึง 90)	`13.7563`
`longitude`	number	Yes	ลองจิจูด (-180 ถึง 180)	`100.5018`

Request Body Example


{
  "attendance_datetime": "2026-02-11T09:00:00.000",
  "employee_code": "EMP001",
  "time_attendance_type_lv": "Checkin",
  "company_id": "MjAyNTExMTMzMjBCQzlGODVFNDQ=",
  "work_cycle_date": "2026-02-11",
  "work_cycle_type_lv": "00",
  "location_id": "MjAyNjAyMTJEOUY2MTE1ODA1NTA=",
  "latitude": 13.7563,
  "longitude": 100.5018,
  "attendance_remark": "บันทึกเวลาเข้างาน"
}

Case: Wifi

บันทึกเวลาผ่านอุปกรณ์ Wifi ต้องระบุ device ที่ลงทะเบียนในระบบ

Required เพิ่มเติม

Parameter	Type	Required	Description	Example
`device_sn`	string	Yes	Serial number อุปกรณ์ (ต้องมีในระบบและเป็นประเภท Wifi)	`00:E2:E3:E4:E5:E6`
`device_name`	string	Yes	ชื่ออุปกรณ์	`Office Wifi`

Request Body Example


{
  "attendance_datetime": "2026-02-11T08:40:00.000",
  "employee_code": "EMP001",
  "time_attendance_type_lv": "Wifi",
  "company_id": "MjAyNTExMTMzMjBCQzlGODVFNDQ=",
  "work_cycle_date": "2026-02-11",
  "work_cycle_type_lv": "00",
  "device_sn": "00:E2:E3:E4:E5:E6",
  "device_name": "Office Wifi",
  "attendance_remark": "บันทึกเวลาผ่าน Wifi"
}

Case: Beacon

บันทึกเวลาผ่านอุปกรณ์ Beacon ต้องระบุ device ที่ลงทะเบียนในระบบ

Required เพิ่มเติม

Parameter	Type	Required	Description	Example
`device_sn`	string	Yes	Serial number อุปกรณ์ (ต้องมีในระบบและเป็นประเภท Beacon)	`00:E2:E3:E4:E5:E7`
`device_name`	string	Yes	ชื่ออุปกรณ์	`Office Beacon`

Request Body Example


{
  "attendance_datetime": "2026-02-11T09:10:00.000",
  "employee_code": "EMP001",
  "time_attendance_type_lv": "Beacon",
  "company_id": "MjAyNTExMTMzMjBCQzlGODVFNDQ=",
  "work_cycle_date": "2026-02-11",
  "work_cycle_type_lv": "00",
  "device_sn": "00:E2:E3:E4:E5:E7",
  "device_name": "Office Beacon",
  "attendance_remark": "บันทึกเวลาผ่าน Beacon"
}

Case: QR

บันทึกเวลาผ่าน QR Code (Time Attendance App) ต้องระบุ location_id หรือ (device_sn + device_name) อย่างใดอย่างหนึ่ง

Required เพิ่มเติม (เลือกอย่างใดอย่างหนึ่ง)

ตัวเลือกที่ 1 — ใช้ Location:

Parameter	Type	Required	Description	Example
`location_id`	string	Conditional	รหัสสถานที่ (Base64-encoded) — Required ถ้าไม่มี device	`MjAyNjAyMTJEOUY2MTE1ODA1NTA=`

ตัวเลือกที่ 2 — ใช้ Device:

Parameter	Type	Required	Description	Example
`device_sn`	string	Conditional	Serial number อุปกรณ์ (ต้องมีในระบบและเป็นประเภท TimeApp)	`202602135BE4EB20778E`
`device_name`	string	Conditional	ชื่ออุปกรณ์ (ต้องมีพร้อม `device_sn`)	`Time App Test`

Request Body Example (ใช้ Location)


{
  "attendance_datetime": "2026-02-13T13:00:00.000",
  "employee_code": "EMP001",
  "time_attendance_type_lv": "QR",
  "company_id": "MjAyNTExMTMzMjBCQzlGODVFNDQ=",
  "work_cycle_date": "2026-02-13",
  "work_cycle_type_lv": "00",
  "location_id": "MjAyNjAyMTJEOUY2MTE1ODA1NTA=",
  "attendance_remark": "บันทึกเวลาผ่าน QR Code"
}

Request Body Example (ใช้ Device)


{
  "attendance_datetime": "2026-02-13T14:10:00.000",
  "employee_code": "EMP001",
  "time_attendance_type_lv": "QR",
  "company_id": "MjAyNTExMTMzMjBCQzlGODVFNDQ=",
  "work_cycle_date": "2026-02-13",
  "work_cycle_type_lv": "00",
  "device_sn": "202602135BE4EB20778E",
  "device_name": "Time App Test",
  "attendance_remark": "บันทึกเวลาผ่าน QR Code"
}

Case: Facial

บันทึกเวลาด้วยการยืนยันใบหน้า ต้องระบุสถานที่ พิกัด และรูปภาพใบหน้า

Required เพิ่มเติม

Parameter	Type	Required	Description	Example
`location_id`	string	Yes	รหัสสถานที่ (Base64-encoded)	`MjAyNjAyMTJEOUY2MTE1ODA1NTA=`
`latitude`	number	Yes	ละติจูด (-90 ถึง 90)	`13.7563`
`longitude`	number	Yes	ลองจิจูด (-180 ถึง 180)	`100.5018`
`image_content`	string	Yes	รูปภาพ Base64-encoded (รองรับ data URI เช่น `data:image/png;base64,...`)	`data:image/png;base64,iVBORw0KG...`

ระบบจะจัดเก็บรูปภาพอัตโนมัติหลังจากได้รับข้อมูล

Request Body Example


{
  "attendance_datetime": "2026-02-22T10:50:00.000",
  "employee_code": "EMP001",
  "time_attendance_type_lv": "Facial",
  "company_id": "MjAyNTExMTMzMjBCQzlGODVFNDQ=",
  "work_cycle_date": "2026-02-11",
  "work_cycle_type_lv": "00",
  "location_id": "MjAyNjAyMTJEOUY2MTE1ODA1NTA=",
  "latitude": 13.7563,
  "longitude": 100.5018,
  "attendance_remark": "บันทึกเวลาด้วยใบหน้า",
  "image_content": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}

Case: Manager

ผู้จัดการสแกนบันทึกเวลาให้พนักงาน ต้องระบุรูปภาพ

Required เพิ่มเติม

Parameter	Type	Required	Description	Example
`image_content`	string	Yes	รูปภาพ Base64-encoded (รองรับ data URI เช่น `data:image/png;base64,...`)	`data:image/png;base64,iVBORw0KG...`

ระบบจะจัดเก็บรูปภาพอัตโนมัติหลังจากได้รับข้อมูล

Request Body Example


{
  "attendance_datetime": "2026-02-13T12:30:00.000",
  "employee_code": "EMP001",
  "time_attendance_type_lv": "Manager",
  "company_id": "MjAyNTExMTMzMjBCQzlGODVFNDQ=",
  "work_cycle_date": "2026-02-13",
  "work_cycle_type_lv": "00",
  "attendance_remark": "ผู้จัดการบันทึกเวลาให้",
  "image_content": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}

Case: Offline

บันทึกเวลาแบบ Offline ต้องระบุพิกัด แต่ ไม่จำเป็นต้องมี company_id และ work_cycle_date

Required เพิ่มเติม

Parameter	Type	Required	Description	Example
`latitude`	number	Yes	ละติจูด (-90 ถึง 90)	`13.7563`
`longitude`	number	Yes	ลองจิจูด (-180 ถึง 180)	`100.5018`

Case Offline ไม่ require company_id และ work_cycle_date ต่างจากประเภทอื่นๆ

Request Body Example


{
  "attendance_datetime": "2026-02-13T12:30:00.000",
  "employee_code": "EMP001",
  "time_attendance_type_lv": "Offline",
  "latitude": 13.7563,
  "longitude": 100.5018,
  "attendance_remark": "บันทึกเวลาแบบ Offline"
}

Response Format

Success Response (HTTP 200)

เมื่อส่งข้อมูลเข้าระบบคิวสำเร็จ


{
  "code": 200,
  "message": "successfully en-queued",
  "payload": []
}

Error Response - Validation Failed (HTTP 400)


{
  "code": 400,
  "message": "Validation failed",
  "errors": [
    "Missing required parameter: 'location_id' (required when time_attendance_type_lv is 'Checkin')",
    "Missing required parameter: 'latitude' (required when time_attendance_type_lv is 'Checkin')"
  ]
}

Response Fields

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

Code Examples

cURL


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/time_attendance/submit" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attendance_datetime": "2026-02-11T09:00:00.000",
    "employee_code": "EMP001",
    "time_attendance_type_lv": "Checkin",
    "company_id": "MjAyNTExMTMzMjBCQzlGODVFNDQ=",
    "work_cycle_date": "2026-02-11",
    "work_cycle_type_lv": "00",
    "location_id": "MjAyNjAyMTJEOUY2MTE1ODA1NTA=",
    "latitude": 13.7563,
    "longitude": 100.5018,
    "attendance_remark": "บันทึกเวลาเข้างาน"
  }'

JavaScript


const response = await fetch(
  'https://openapi.humansoft.co.th/api/v1/open-apis/time_attendance/submit',
  {
    method: 'POST',
    headers: {
      'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      attendance_datetime: '2026-02-11T09:00:00.000',
      employee_code: 'EMP001',
      time_attendance_type_lv: 'Checkin',
      company_id: 'MjAyNTExMTMzMjBCQzlGODVFNDQ=',
      work_cycle_date: '2026-02-11',
      work_cycle_type_lv: '00',
      location_id: 'MjAyNjAyMTJEOUY2MTE1ODA1NTA=',
      latitude: 13.7563,
      longitude: 100.5018,
      attendance_remark: 'บันทึกเวลาเข้างาน'
    })
  }
)
 
const data = await response.json()
 
if (data.code === 200) {
  console.log('บันทึกเวลาสำเร็จ:', data.message)
} else {
  console.error('Error:', data.errors || data.message)
}

Python


import requests
 
url = "https://openapi.humansoft.co.th/api/v1/open-apis/time_attendance/submit"
headers = {
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "attendance_datetime": "2026-02-11T09:00:00.000",
    "employee_code": "EMP001",
    "time_attendance_type_lv": "Checkin",
    "company_id": "MjAyNTExMTMzMjBCQzlGODVFNDQ=",
    "work_cycle_date": "2026-02-11",
    "work_cycle_type_lv": "00",
    "location_id": "MjAyNjAyMTJEOUY2MTE1ODA1NTA=",
    "latitude": 13.7563,
    "longitude": 100.5018,
    "attendance_remark": "บันทึกเวลาเข้างาน"
}
 
response = requests.post(url, headers=headers, json=payload)
data = response.json()
 
if data["code"] == 200:
    print("บันทึกเวลาสำเร็จ:", data["message"])
else:
    print("Error:", data.get("errors") or data.get("message"))

PHP


<?php
$url = "https://openapi.humansoft.co.th/api/v1/open-apis/time_attendance/submit";
 
$headers = [
    "Ocp-Apim-Subscription-Key: YOUR_API_KEY",
    "Content-Type: application/json"
];
 
$payload = [
    "attendance_datetime" => "2026-02-11T09:00:00.000",
    "employee_code" => "EMP001",
    "time_attendance_type_lv" => "Checkin",
    "company_id" => "MjAyNTExMTMzMjBCQzlGODVFNDQ=",
    "work_cycle_date" => "2026-02-11",
    "work_cycle_type_lv" => "00",
    "location_id" => "MjAyNjAyMTJEOUY2MTE1ODA1NTA=",
    "latitude" => 13.7563,
    "longitude" => 100.5018,
    "attendance_remark" => "บันทึกเวลาเข้างาน"
];
 
$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);
$data = json_decode($response, true);
 
if ($data['code'] === 200) {
    echo "บันทึกเวลาสำเร็จ: " . $data['message'];
} else {
    echo "Error: " . ($data['errors'][0] ?? $data['message']);
}
 
curl_close($ch);
?>

Validation Rules

ทุกประเภท

Parameter	Validation	Error Message
`attendance_datetime`	ต้องเป็นวันเวลาที่ถูกต้อง (ISO 8601 หรือ YYYY-MM-DD HH:mm:ss)	`'attendance_datetime' must be a valid datetime`
`employee_code`	ต้องมีอยู่จริงในระบบ	`employee_code 'XXX' not found`
`time_attendance_type_lv`	ต้องเป็นค่าที่รองรับ	`Invalid time_attendance_type_lv`
`company_id`	ต้องเป็น Base64-encoded และมีอยู่จริงในระบบ (ยกเว้น Offline)	`company_id not found`
`work_cycle_date`	ต้องเป็นวันที่ถูกต้อง YYYY-MM-DD (ยกเว้น Offline)	`'work_cycle_date' must be in YYYY-MM-DD format`
`latitude`	ต้องเป็นตัวเลข -90 ถึง 90 (เมื่อ required)	`'latitude' must be between -90 and 90`
`longitude`	ต้องเป็นตัวเลข -180 ถึง 180 (เมื่อ required)	`'longitude' must be between -180 and 180`

เฉพาะบางประเภท

ประเภท	Parameter	Validation
Checkin	`location_id`	ต้องเป็น Base64-encoded และมีอยู่จริงในระบบ
Wifi	`device_sn`	ต้องมีอยู่จริงในระบบและ device type เป็น `Wifi`
Beacon	`device_sn`	ต้องมีอยู่จริงในระบบและ device type เป็น `Beacon`
QR	`location_id` หรือ `device_sn`	ต้องมีอย่างใดอย่างหนึ่ง — device type ต้องเป็น `TimeApp`
Facial	`image_content`	ต้องเป็น Base64-encoded image (รองรับ data URI)
Manager	`image_content`	ต้องเป็น Base64-encoded image (รองรับ data URI)

Business Rules

ข้อจำกัด:

ข้อมูลจะถูกส่งเข้าระบบคิว (Queue) เพื่อประมวลผล — API จะตอบกลับทันทีหลังจาก validate สำเร็จ
company_id และ location_id ต้องเป็น Base64-encoded string
สำหรับ Wifi และ Beacon — device ต้องลงทะเบียนในระบบก่อนพร้อม device type ที่ตรงกัน
สำหรับ QR — ต้องระบุ location_id หรือ (device_sn + device_name) อย่างใดอย่างหนึ่ง
สำหรับ Offline — ไม่จำเป็นต้องมี company_id และ work_cycle_date
work_date_seq default เป็น 1 ถ้าไม่ระบุ

Error Handling

Error	Cause	Solution
`Missing required parameter: 'location_id'`	ไม่ได้ส่ง location_id สำหรับ Checkin/Facial	เพิ่ม location_id ใน request body
`employee_code 'XXX' not found`	ไม่พบพนักงาน	ตรวจสอบ employee_code
`company_id not found`	ไม่พบบริษัท	ตรวจสอบ company_id (Base64-encoded)
`device_sn not found or invalid type`	ไม่พบ device หรือ type ไม่ตรง	ตรวจสอบ device_sn และ device type ในระบบ

Import Time Attendance - นำเข้าข้อมูลบันทึกเวลาแบบกลุ่ม

Submit Time Attendance

Endpoint

Attendance Types

Common Parameters

Required Parameters (ทุกประเภท)

Required Parameters (ส่วนใหญ่ ยกเว้น Offline)

Optional Parameters (ทุกประเภท)

Case: Checkin

Required เพิ่มเติม

Request Body Example

Case: Wifi

Required เพิ่มเติม

Request Body Example

Case: Beacon

Required เพิ่มเติม

Request Body Example

Case: QR

Required เพิ่มเติม (เลือกอย่างใดอย่างหนึ่ง)

Request Body Example (ใช้ Location)

Request Body Example (ใช้ Device)

Case: Facial

Required เพิ่มเติม

Request Body Example

Case: Manager

Required เพิ่มเติม

Request Body Example

Case: Offline

Required เพิ่มเติม

Request Body Example

Response Format

Success Response (HTTP 200)

Error Response - Validation Failed (HTTP 400)

Response Fields

Code Examples

cURL

JavaScript

Python

PHP

Validation Rules

ทุกประเภท

เฉพาะบางประเภท

Business Rules

Error Handling

Related APIs