Submit Time Attendance
บันทึกเวลาเข้า-ออกของพนักงาน
ใช้ API นี้เพื่อบันทึกเวลาเข้า-ออกของพนักงาน รองรับ 2 ประเภทการบันทึก: Checkin (GPS) และ Device (อุปกรณ์) โดยข้อมูลจะถูกส่งเข้าระบบคิว (Queue) เพื่อประมวลผลแบบ Asynchronous
Endpoint
POST /api/v1/open-apis/time-attendance/submitสิทธิ์ที่ต้องการ: API Key ต้องมีสิทธิ์ ข้อมูลการลงเวลา (attendance:read)
ต้องส่ง payload เป็น JSON ใน Request Body เท่านั้น ไม่รองรับการส่งผ่าน Query Parameters
Attendance Types
| Type | Description | Required เพิ่มเติม |
|---|---|---|
Checkin | บันทึกเวลาแบบ GPS | location_id, latitude, longitude |
Device | บันทึกเวลาผ่านอุปกรณ์ | device_sn |
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 หรือ Device) | Checkin |
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 อุปกรณ์ | SN123456789 |
device_name | string | No | ชื่ออุปกรณ์ | |
image_path | string | No | URL รูปภาพ |
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",
"work_cycle_date": "2026-02-11",
"work_cycle_type_lv": "00",
"location_id": "MjAyNjAyMTJEOUY2MTE1ODA1NTA=",
"latitude": 13.7563,
"longitude": 100.5018,
"attendance_remark": "บันทึกเวลาเข้างาน"
}Case: Device
บันทึกเวลาผ่านอุปกรณ์ (เช่น เครื่องสแกนลายนิ้วมือ) ต้องระบุ device_sn ของอุปกรณ์ที่ลงทะเบียนในระบบ
Required เพิ่มเติม
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
device_sn | string | Yes | Serial number อุปกรณ์ (ต้องมีอยู่จริงในระบบ) | SN123456789 |
Request Body Example
{
"attendance_datetime": "2026-02-11T09:00:00.000",
"employee_code": "EMP001",
"time_attendance_type_lv": "Device",
"work_cycle_date": "2026-02-11",
"work_cycle_type_lv": "00",
"device_sn": "SN123456789",
"attendance_remark": "บันทึกเวลาด้วยอุปกรณ์"
}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",
"work_cycle_date": "2026-02-11",
"work_cycle_type_lv": "00",
"location_id": "MjAyNjAyMTJEOUY2MTE1ODA1NTA=",
"latitude": 13.7563,
"longitude": 100.5018,
"attendance_remark": "บันทึกเวลาเข้างาน"
}'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 | ต้องเป็น Checkin หรือ Device | 'time_attendance_type_lv' must be one of: Checkin, Device |
work_cycle_date | ต้องเป็นวันที่ถูกต้อง YYYY-MM-DD | 'work_cycle_date' must be in YYYY-MM-DD format |
เฉพาะ Checkin
| Parameter | Validation |
|---|---|
location_id | ต้องเป็น Base64-encoded string และมีอยู่จริงในระบบ |
latitude | ต้องเป็นตัวเลข -90 ถึง 90 |
longitude | ต้องเป็นตัวเลข -180 ถึง 180 |
เฉพาะ Device
| Parameter | Validation |
|---|---|
device_sn | ต้องส่งมาและมีอยู่จริงในระบบ |
Business Rules
ข้อจำกัด:
- ข้อมูลจะถูกส่งเข้าระบบคิว (Queue) เพื่อประมวลผล — API จะตอบกลับทันทีหลังจาก validate สำเร็จ
location_id(ถ้ามี) ต้องเป็น Base64-encoded string- สำหรับ Checkin — ต้องระบุ
location_id,latitude,longitudeเพื่อยืนยันสถานที่และตำแหน่ง - สำหรับ Device — ต้องระบุ
device_snของอุปกรณ์ที่ลงทะเบียนในระบบ work_date_seqdefault เป็น 1 ถ้าไม่ระบุ
Error Handling
| Error | Cause | Solution |
|---|---|---|
Missing required parameter: 'location_id' | ไม่ได้ส่ง location_id สำหรับ Checkin | เพิ่ม location_id ใน request body |
Missing required parameter: 'latitude' | ไม่ได้ส่ง latitude สำหรับ Checkin | เพิ่ม latitude ใน request body |
Missing required parameter: 'longitude' | ไม่ได้ส่ง longitude สำหรับ Checkin | เพิ่ม longitude ใน request body |
Missing required parameter: 'device_sn' | ไม่ได้ส่ง device_sn สำหรับ Device | เพิ่ม device_sn ใน request body |
employee_code 'XXX' not found | ไม่พบพนักงาน | ตรวจสอบ employee_code |
'time_attendance_type_lv' must be one of: Checkin, Device | ส่งค่า type อื่นที่ไม่รองรับ | ใช้ Checkin หรือ Device เท่านั้น |
Related APIs
- Import Time Attendance - นำเข้าข้อมูลบันทึกเวลาแบบกลุ่ม
- Get Device List - ดึง
device_snสำหรับประเภทDevice - Get Location List - ดึง
location_idสำหรับประเภทCheckin
Last updated on