Skip to Content
🚀 Welcome to Humansoft Open API Documentation

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

TypeDescriptionRequired เพิ่มเติม
Checkinบันทึกเวลาแบบ GPSlocation_id, latitude, longitude
Deviceบันทึกเวลาผ่านอุปกรณ์device_sn

Common Parameters

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

ParameterTypeRequiredDescriptionExample
attendance_datetimestringYesวันเวลาที่บันทึก (ISO 8601 หรือ YYYY-MM-DD HH:mm:ss)2026-02-11T09:00:00.000
employee_codestringYesรหัสพนักงานEMP001
time_attendance_type_lvstringYesประเภทการบันทึกเวลา (Checkin หรือ Device)Checkin
work_cycle_datestringYesวันที่กะการทำงาน (YYYY-MM-DD)2026-02-11

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

ParameterTypeRequiredDescriptionExample
work_cycle_type_lvstringNoประเภทกะการทำงาน00
work_date_seqnumberNoลำดับวันทำงาน (default: 1)1
attendance_remarkstringNoหมายเหตุการบันทึกเวลาบันทึกเวลาเข้างาน
approve_remarkstringNoหมายเหตุการอนุมัติ
device_snstringNoSerial number อุปกรณ์SN123456789
device_namestringNoชื่ออุปกรณ์
image_pathstringNoURL รูปภาพ

Case: Checkin

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

Required เพิ่มเติม

ParameterTypeRequiredDescriptionExample
location_idstringYesรหัสสถานที่ (Base64-encoded)MjAyNjAyMTJEOUY2MTE1ODA1NTA=
latitudenumberYesละติจูด (-90 ถึง 90)13.7563
longitudenumberYesลองจิจูด (-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 เพิ่มเติม

ParameterTypeRequiredDescriptionExample
device_snstringYesSerial 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

FieldTypeDescription
codenumberรหัสสถานะ (200 = สำเร็จ, 400 = ไม่สำเร็จ)
messagestringข้อความตอบกลับ
payloadarrayข้อมูลผลลัพธ์ (ว่างเมื่อสำเร็จ — ระบบประมวลผลแบบ Asynchronous)
errorsarrayรายการข้อผิดพลาด (กรณี validation ไม่ผ่าน)

Code Examples

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

ทุกประเภท

ParameterValidationError 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

ParameterValidation
location_idต้องเป็น Base64-encoded string และมีอยู่จริงในระบบ
latitudeต้องเป็นตัวเลข -90 ถึง 90
longitudeต้องเป็นตัวเลข -180 ถึง 180

เฉพาะ Device

ParameterValidation
device_snต้องส่งมาและมีอยู่จริงในระบบ

Business Rules

ข้อจำกัด:

  • ข้อมูลจะถูกส่งเข้าระบบคิว (Queue) เพื่อประมวลผล — API จะตอบกลับทันทีหลังจาก validate สำเร็จ
  • location_id (ถ้ามี) ต้องเป็น Base64-encoded string
  • สำหรับ Checkin — ต้องระบุ location_id, latitude, longitude เพื่อยืนยันสถานที่และตำแหน่ง
  • สำหรับ Device — ต้องระบุ device_sn ของอุปกรณ์ที่ลงทะเบียนในระบบ
  • work_date_seq default เป็น 1 ถ้าไม่ระบุ

Error Handling

ErrorCauseSolution
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 เท่านั้น
  • Import Time Attendance - นำเข้าข้อมูลบันทึกเวลาแบบกลุ่ม
  • Get Device List - ดึง device_sn สำหรับประเภท Device
  • Get Location List - ดึง location_id สำหรับประเภท Checkin
Last updated on