Skip to Content
🚀 Welcome to Humansoft Open API Documentation

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

ParameterTypeRequiredDescriptionExample
import_dataarrayYesรายการข้อมูล OT ที่ต้องการนำเข้า(ดูตัวอย่างด้านล่าง)
import_data[].statusstringYesการดำเนินการ: UPSERT หรือ DELUPSERT
import_data[].employee_codestringYesรหัสพนักงานEMP001
import_data[].typestringYesรหัสประเภท OT — ดู OT Type CodesOT_1_5
import_data[].start_dtstringYesวันเวลาเริ่มต้น (YYYY-MM-DD HH:MM:SS)2026-09-10 18:00:00
import_data[].end_dtstringYesวันเวลาสิ้นสุด (YYYY-MM-DD HH:MM:SS) ต้องมากกว่า start_dt2026-09-10 22:00:00
import_data[].ot_work_dtstringNoวันที่ของกะการทำงานที่ OT รายการนี้สังกัด (YYYY-MM-DD) — ดู OT Work Date2026-09-10
import_data[].descriptionstringNoรายละเอียดงาน OTทำงานโปรเจกต์พิเศษ

OT Type Codes

Type CodeRateDescription
OT_1_01.0xOT อัตราปกติ
OT_1_51.5xOT วันทำงานปกติ
OT_2_02.0xOT วันหยุด
OT_3_03.0xOT วันหยุดนักขัตฤกษ์
OT_4_0 - OT_7_04.0x - 7.0xOT พิเศษ

OT Work Date

ot_work_dt ใช้ระบุว่าชั่วโมง OT รายการนี้สังกัด กะการทำงานของวันไหน ซึ่งอาจไม่ตรงกับวันที่ใน start_dt ในกรณีกะข้ามคืน

กรณีค่า ot_work_dtใช้เมื่อ
กะปกติไม่ระบุ หรือระบุวันเดียวกับ start_dtOT ต่อจากเลิกงานในกะเดียวกัน
กะข้ามคืน (ย้อนหลัง 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

FieldTypeDescription
codenumberรหัสสถานะ (200 = สำเร็จ, 400 = ไม่สำเร็จ)
messagestringข้อความตอบกลับ
payload.invalid_itemsarrayรายการข้อมูลที่ไม่ผ่าน validation
payload.invalid_items[].indexnumberลำดับของรายการใน import_data ที่ส่งมา (เริ่มจาก 0)
payload.invalid_items[].dataobjectข้อมูลของรายการนั้นตามที่ส่งเข้ามา
payload.invalid_items[].errorsarrayรายการข้อผิดพลาดของรายการนั้น (1 รายการอาจมีหลาย error)
errorsarrayข้อผิดพลาดของโครงสร้างข้อมูลโดยรวม (เฉพาะกรณี Validation failed)

Code Examples

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_dataMissing 'import_data' field
import_data ไม่ใช่ array'import_data' must be an array
import_data เป็น array ว่าง'import_data' cannot be empty

รายการแต่ละแถว (แถวที่ผิดกลายเป็น invalid item)

ParameterValidationError Message
statusต้องระบุstatus is required
statusต้องเป็น UPSERT หรือ DELstatus must be 'UPSERT' or 'DEL'
employee_codeต้องระบุemployee_code is required
employee_codeต้องเป็น stringemployee_code must be a string
employee_codeต้องมีอยู่ในระบบemployee_code 'EMP999' not found
typeต้องระบุtype is required
typeต้องเป็นหนึ่งใน OT Type Codestype 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:SSstart_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:SSend_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ต้องเป็น stringot_work_dt must be a string
ot_work_dtต้องอยู่ในรูปแบบ YYYY-MM-DDot_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

StatusDescription
UPSERTเพิ่มหรือแก้ไขข้อมูล OT
DELลบข้อมูล OT ที่มีอยู่

Use Cases

  1. Migration - ย้ายข้อมูล OT จากระบบเดิม
  2. Bulk Update - อัปเดตข้อมูล OT จำนวนมาก
  3. Integration - รับข้อมูลจากระบบภายนอก
  4. กะข้ามคืน - ผูกชั่วโมง OT เข้ากับรอบกะที่ถูกต้องด้วย ot_work_dt
  • Get OT Types - ดึงรายการประเภท OT
  • Get OT List - ดึงรายการคำขอ OT เพื่อตรวจผลการนำเข้า
  • Submit OT - ยื่นคำขอ OT ทีละรายการ
  • Delete OT - ลบคำขอ OT
Last updated on