Import OT
นำเข้าเอกสาร OT แบบกลุ่ม (Batch Import)
ใช้ API นี้เพื่อนำเข้าข้อมูล OT จำนวนมากพร้อมกัน รองรับทั้งการเพิ่ม/แก้ไข (UPSERT) และการลบ (DEL) ข้อมูลจะถูกส่งเข้า Queue เพื่อประมวลผลแบบ Asynchronous
Endpoint
POST /api/v1/open-apis/overtime/importสิทธิ์ที่ต้องการ: API Key ต้องมีสิทธิ์ ข้อมูลการยื่นเอกสาร (document:manage)
Request Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
import_data | array | Yes | รายการข้อมูล OT ที่ต้องการนำเข้า | (ดูตัวอย่างด้านล่าง) |
import_data[].status | string | Yes | การดำเนินการ: UPSERT หรือ DEL | UPSERT |
import_data[].employee_code | string | Yes | รหัสพนักงาน | EMP001 |
import_data[].type | string | Yes | รหัสประเภท OT — ดู OT Type Codes | OT_1_5 |
import_data[].start_dt | string | Yes | วันเวลาเริ่มต้น (YYYY-MM-DD HH:MM:SS) | 2026-09-10 18:00:00 |
import_data[].end_dt | string | Yes | วันเวลาสิ้นสุด (YYYY-MM-DD HH:MM:SS) ต้องมากกว่า start_dt | 2026-09-10 22:00:00 |
import_data[].ot_work_dt | string | No | วันที่ของกะการทำงานที่ OT รายการนี้สังกัด (YYYY-MM-DD) — ดู OT Work Date | 2026-09-10 |
import_data[].description | string | No | รายละเอียดงาน OT | ทำงานโปรเจกต์พิเศษ |
OT Type Codes
| Type Code | Rate | Description |
|---|---|---|
OT_1_0 | 1.0x | OT อัตราปกติ |
OT_1_5 | 1.5x | OT วันทำงานปกติ |
OT_2_0 | 2.0x | OT วันหยุด |
OT_3_0 | 3.0x | OT วันหยุดนักขัตฤกษ์ |
OT_4_0 - OT_7_0 | 4.0x - 7.0x | OT พิเศษ |
OT Work Date
ot_work_dt ใช้ระบุว่าชั่วโมง OT รายการนี้สังกัด กะการทำงานของวันไหน ซึ่งอาจไม่ตรงกับวันที่ใน start_dt ในกรณีกะข้ามคืน
| กรณี | ค่า ot_work_dt | ใช้เมื่อ |
|---|---|---|
| กะปกติ | ไม่ระบุ หรือระบุวันเดียวกับ start_dt | OT ต่อจากเลิกงานในกะเดียวกัน |
| กะข้ามคืน (ย้อนหลัง 1 วัน) | วันก่อนหน้า start_dt | เข้ากะดึกข้ามคืน แล้วทำ OT ต่อในเช้าวันรุ่งขึ้น แต่ต้องการผูกกับรอบกะของวันที่เข้างาน |
| ก่อนเข้ากะ (ล่วงหน้า 1 วัน) | วันถัดจาก start_dt | ถูกเรียกมาทำ OT ช่วงดึก ก่อนเริ่มกะของวันรุ่งขึ้น |
- หากไม่ระบุ
ot_work_dtระบบจะใช้วันที่ของstart_dtให้อัตโนมัติ - หากระบุ ต้องเป็นวันที่ที่มีอยู่จริงตามปฏิทิน และต่างได้ไม่เกิน 1 วัน (ก่อนหน้าหรือถัดไป) เมื่อเทียบกับทั้ง วันที่ของ
start_dtและ วันที่ของend_dtมิฉะนั้นรายการนั้นจะกลายเป็น invalid item - กรณี OT คาบเกี่ยวข้ามวัน (
start_dtกับend_dtคนละวัน) ค่าที่ใช้ได้จึงเหลือเพียง 2 วัน คือวันของstart_dtหรือวันของend_dtเท่านั้น
Request Body Example
ตัวอย่างที่ 1 — กะปกติ
รายการแรกระบุ ot_work_dt ตรงกับวันของ start_dt ส่วนรายการที่สองไม่ระบุ ระบบจะเติมวันที่ของ start_dt ให้เอง
{
"import_data": [
{
"status": "UPSERT",
"employee_code": "EMP001",
"type": "OT_1_5",
"ot_work_dt": "2026-09-10",
"start_dt": "2026-09-10 18:00:00",
"end_dt": "2026-09-10 22:00:00",
"description": "OT กะปกติ ทำงานต่อหลังเลิกงาน"
},
{
"status": "UPSERT",
"employee_code": "EMP001",
"type": "OT_2_0",
"start_dt": "2026-09-10 22:00:00",
"end_dt": "2026-09-11 00:00:00",
"description": "OT ต่อเนื่องช่วงดึก"
}
]
}ตัวอย่างที่ 2 — กะข้ามคืน (ย้อนหลัง 1 วัน)
พนักงานเข้ากะดึกวันที่ 10 (20:00 – 05:00) แล้วทำ OT ต่อในเช้าวันที่ 11 แต่ต้องการผูกชั่วโมง OT เข้ากับรอบกะของวันที่ 10
{
"import_data": [
{
"status": "UPSERT",
"employee_code": "EMP001",
"type": "OT_1_5",
"ot_work_dt": "2026-09-10",
"start_dt": "2026-09-11 07:00:00",
"end_dt": "2026-09-11 09:00:00",
"description": "OT เช้าวันที่ 11 ผูกรอบกะของวันที่ 10"
}
]
}ตัวอย่างที่ 3 — ก่อนเข้ากะ (ล่วงหน้า 1 วัน)
พนักงานถูกเรียกมาทำ OT ช่วงดึกของวันที่ 10 ก่อนเริ่มกะของวันที่ 11
{
"import_data": [
{
"status": "UPSERT",
"employee_code": "EMP001",
"type": "OT_1_5",
"ot_work_dt": "2026-09-11",
"start_dt": "2026-09-10 22:30:00",
"end_dt": "2026-09-11 00:30:00",
"description": "OT ก่อนเข้ากะเช้าวันที่ 11"
}
]
}ตัวอย่างที่ 4 — ลบรายการ OT
{
"import_data": [
{
"status": "DEL",
"employee_code": "EMP001",
"type": "OT_1_5",
"ot_work_dt": "2026-09-10",
"start_dt": "2026-09-10 18:00:00",
"end_dt": "2026-09-10 22:00:00",
"description": "ขอลบรายการ OT ที่ระบุ"
}
]
}รายการที่ใช้ status = DEL ต้องส่งฟิลด์บังคับครบเหมือน UPSERT (employee_code, type, start_dt, end_dt) เพราะระบบใช้ค่าเหล่านี้ระบุว่าจะลบรายการใด
Response Format
Success Response (HTTP 200)
เมื่อมีข้อมูลที่ถูกต้องอย่างน้อย 1 รายการ ระบบจะส่งข้อมูลที่ถูกต้องเข้า Queue และตอบกลับรายการที่ไม่ผ่าน validation
{
"code": 200,
"message": "successfully en-queued",
"payload": {
"invalid_items": [
{
"index": 1,
"data": {
"status": "UPSERT",
"employee_code": "EMP999",
"type": "OT_1_5",
"start_dt": "2026-09-16 18:00:00",
"end_dt": "2026-09-16 21:00:00"
},
"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": "UPSERT",
"employee_code": "EMP001",
"type": "OT_1_5",
"ot_work_dt": "2026-09-08",
"start_dt": "2026-09-10 18:00:00",
"end_dt": "2026-09-10 22:00:00"
},
"errors": [
"ot_work_dt must be within +/- 1 day of start_dt (2026-09-10)",
"ot_work_dt must be within +/- 1 day of end_dt (2026-09-10)"
]
}
]
}
}Response Fields
| Field | Type | Description |
|---|---|---|
code | number | รหัสสถานะ (200 = สำเร็จ, 400 = ไม่สำเร็จ) |
message | string | ข้อความตอบกลับ |
payload.invalid_items | array | รายการข้อมูลที่ไม่ผ่าน validation |
payload.invalid_items[].index | number | ลำดับของรายการใน import_data ที่ส่งมา (เริ่มจาก 0) |
payload.invalid_items[].data | object | ข้อมูลของรายการนั้นตามที่ส่งเข้ามา |
payload.invalid_items[].errors | array | รายการข้อผิดพลาดของรายการนั้น (1 รายการอาจมีหลาย error) |
errors | array | ข้อผิดพลาดของโครงสร้างข้อมูลโดยรวม (เฉพาะกรณี Validation failed) |
Code Examples
cURL
curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/overtime/import" \
-H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"import_data": [
{
"status": "UPSERT",
"employee_code": "EMP001",
"type": "OT_1_5",
"ot_work_dt": "2026-09-10",
"start_dt": "2026-09-10 18:00:00",
"end_dt": "2026-09-10 22:00:00",
"description": "ทำงานโปรเจกต์พิเศษ"
}
]
}'Validation Rules
โครงสร้างข้อมูล (ตอบกลับเป็น HTTP 400 ทั้งคำขอ)
| เงื่อนไข | Error Message |
|---|---|
ไม่มี import_data | Missing 'import_data' field |
import_data ไม่ใช่ array | 'import_data' must be an array |
import_data เป็น array ว่าง | 'import_data' cannot be empty |
รายการแต่ละแถว (แถวที่ผิดกลายเป็น invalid item)
| Parameter | Validation | Error Message |
|---|---|---|
status | ต้องระบุ | status is required |
status | ต้องเป็น UPSERT หรือ DEL | status must be 'UPSERT' or 'DEL' |
employee_code | ต้องระบุ | employee_code is required |
employee_code | ต้องเป็น string | employee_code must be a string |
employee_code | ต้องมีอยู่ในระบบ | employee_code 'EMP999' not found |
type | ต้องระบุ | type is required |
type | ต้องเป็นหนึ่งใน OT Type Codes | type must be one of: OT_1_0, OT_1_5, OT_2_0, OT_3_0, OT_4_0, OT_5_0, OT_6_0, OT_7_0 |
start_dt | ต้องระบุ | start_dt is required |
start_dt | ต้องอยู่ในรูปแบบ YYYY-MM-DD HH:MM:SS | start_dt must be in format YYYY-MM-DD HH:MM:SS |
start_dt | ต้องเป็นวันเวลาที่มีอยู่จริง | start_dt is not a valid datetime |
end_dt | ต้องระบุ | end_dt is required |
end_dt | ต้องอยู่ในรูปแบบ YYYY-MM-DD HH:MM:SS | end_dt must be in format YYYY-MM-DD HH:MM:SS |
end_dt | ต้องเป็นวันเวลาที่มีอยู่จริง | end_dt is not a valid datetime |
end_dt | ต้องมากกว่า start_dt (เท่ากันไม่ได้) | end_dt must be greater than start_dt |
ot_work_dt | ต้องเป็น string | ot_work_dt must be a string |
ot_work_dt | ต้องอยู่ในรูปแบบ YYYY-MM-DD | ot_work_dt must be in format YYYY-MM-DD |
ot_work_dt | ต้องเป็นวันที่ที่มีอยู่จริงตามปฏิทิน | ot_work_dt is not a valid date |
ot_work_dt | ต่างจากวันที่ของ start_dt ได้ไม่เกิน 1 วัน | ot_work_dt must be within +/- 1 day of start_dt (2026-09-10) |
ot_work_dt | ต่างจากวันที่ของ end_dt ได้ไม่เกิน 1 วัน | ot_work_dt must be within +/- 1 day of end_dt (2026-09-10) |
description | ต้องเป็น string (ถ้าระบุ) | description must be a string |
เงื่อนไขช่วงวันของ ot_work_dt ถูกตรวจแยกกันสองครั้ง (เทียบกับ start_dt และเทียบกับ end_dt) ดังนั้นรายการเดียวอาจได้รับ error ทั้งสองข้อความพร้อมกัน
Business Rules
Partial Success:
- ระบบจะประมวลผลเฉพาะรายการที่ถูกต้อง และแจ้งรายการที่ไม่ถูกต้องกลับมาใน response
- รายการที่ผ่าน validation จะถูกส่งเข้า Queue ทันที
- รายการที่ไม่ผ่าน validation จะถูกส่งกลับมาพร้อม error message โดยไม่ถูกนำเข้า
ได้ code = 200 ไม่ได้แปลว่านำเข้าครบทุกแถว — ต้องตรวจ payload.invalid_items เสมอ เพราะรายการที่ไม่ผ่าน validation จะถูกข้ามไปเงียบ ๆ
Asynchronous Processing
- ข้อมูลที่ผ่าน validation จะถูกส่งเข้าระบบคิว (Queue) เพื่อประมวลผล
- API จะตอบกลับทันทีหลังจาก validate และส่งข้อมูลเข้า Queue สำเร็จ โดยยังไม่ได้บันทึกเอกสารจริง
- ผลลัพธ์การนำเข้าจริงตรวจสอบได้จาก Get OT List หลังจากคิวประมวลผลเสร็จ
- เหมาะสำหรับการนำเข้าข้อมูลจำนวนมาก
Notes
Status Values
| Status | Description |
|---|---|
UPSERT | เพิ่มหรือแก้ไขข้อมูล OT |
DEL | ลบข้อมูล OT ที่มีอยู่ |
Use Cases
- Migration - ย้ายข้อมูล OT จากระบบเดิม
- Bulk Update - อัปเดตข้อมูล OT จำนวนมาก
- Integration - รับข้อมูลจากระบบภายนอก
- กะข้ามคืน - ผูกชั่วโมง OT เข้ากับรอบกะที่ถูกต้องด้วย
ot_work_dt
Related APIs
- Get OT Types - ดึงรายการประเภท OT
- Get OT List - ดึงรายการคำขอ OT เพื่อตรวจผลการนำเข้า
- Submit OT - ยื่นคำขอ OT ทีละรายการ
- Delete OT - ลบคำขอ OT