Submit Adjust

ยื่นเอกสารขอเพิ่มเวลาทำงานใหม่

ใช้ API นี้เพื่อสร้างเอกสารขอเพิ่มเวลาทำงานใหม่ ระบบจะตรวจสอบข้อมูล แล้วสร้างเอกสารในสถานะรออนุมัติ (01)

Endpoint


POST /api/v1/open-apis/time-adjust/submit

สิทธิ์ที่ต้องการ: API Key ต้องมีสิทธิ์ ข้อมูลการยื่นเอกสาร (document:manage)

Request Parameters

Required Parameters

Parameter	Type	Required	Description	Example
`employee_code`	string	Yes	รหัสพนักงาน	`EMP001`
`time_adjust_dt`	string	Yes	วันที่เอกสาร (YYYY-MM-DD)	`2026-02-18`
`time_adjust_flag_lv`	string	Yes	ประเภทเอกสาร ต้องเป็นประเภทที่เปิดใช้งาน (ดู Get Adjust Types)	`01`
`time_adjust_list_dt`	array	Yes	รายการเวลา 1-4 รายการ	ดูตัวอย่างด้านล่าง

Optional Parameters

Parameter	Type	Required	Description	Example
`time_adjust_desc`	string	No	คำอธิบายเพิ่มเติม	`ลืมลงเวลาเนื่องจากประชุม`
`extra_round`	string	No	งวดพิเศษ (`Y`/`N`) ค่าเริ่มต้น: `N` — `Y` จะข้ามการตรวจสอบงวดเงินเดือนที่ปิดแล้ว ค่าอื่นนอกจาก `Y`/`N` จะถือเป็น `N`	`N`
`base64`	string	No	ไฟล์แนบ เช่น รูปภาพ (Base64 encoded)	`data:image/png;base64,...`
`authorize_id`	string	No	ID ผู้ทำรายการ (Base64)	`MjAyNjA0MzBVU0VSMDAwMDAx`
`language_code`	string	No	ภาษาของข้อความใน `message` (`TH` หรือ `EN`) ค่าเริ่มต้น: `TH`	`TH`

หา authorize_id ได้อย่างไร: รับค่าจาก Get Employee Data Filter โดยใช้ path_action=get-user พร้อม employee_code ของผู้ทำรายการ — ใช้ค่า user_id ที่ได้กลับมาเป็น authorize_id

time_adjust_list_dt Structure

แต่ละรายการใน array ต้องเป็น object ที่มี field time_adjust_list_dt ในรูปแบบ YYYY-MM-DD HH:MM:SS (สูงสุด 4 รายการ)


[
  { "time_adjust_list_dt": "2026-02-18 09:00:00" },
  { "time_adjust_list_dt": "2026-02-18 18:00:00" }
]

Request Body Example


{
  "employee_code": "EMP001",
  "time_adjust_dt": "2026-02-18",
  "time_adjust_flag_lv": "01",
  "time_adjust_desc": "ลืมลงเวลาเนื่องจากประชุม",
  "extra_round": "N",
  "time_adjust_list_dt": [
    { "time_adjust_list_dt": "2026-02-18 09:00:00" },
    { "time_adjust_list_dt": "2026-02-18 18:00:00" }
  ]
}

Response Format

Success Response (HTTP 200)


{
  "code": 200,
  "message": "สำเร็จ",
  "payload": {
    "time_adjust_id": "20251127D4573C421639",
    "employee_code": "EMP001",
    "time_adjust_dt": "2026-02-18",
    "time_adjust_flag_lv": "01",
    "time_adjust_desc": "ลืมลงเวลาเนื่องจากประชุม",
    "approve_flag": "01",
    "created": "2026-02-18 10:30:00",
    "image_url": null
  }
}

ตัวอย่าง image_url เมื่อแนบไฟล์: "https://cdn.humansoft.co.th/.../image/a1B2c3D4e5F6.png"

Error Response - Validation Failed (HTTP 422)


{
  "code": 422,
  "message": "Validation failed",
  "errors": [
    "Missing required parameter: 'employee_code'"
  ]
}

ระบบตรวจสอบ parameter ตามลำดับและคืนเฉพาะข้อผิดพลาดแรกที่พบใน errors

Error Response - Employee Not Found (HTTP 400)


{
  "code": 400,
  "message": "Employee not found: EMP999"
}

Error Response - Salary Period Closed (HTTP 400)


{
  "code": 400,
  "message": "ไม่สามารถเพิ่มข้อมูลได้เนื่องจากปิดงวดเงินเดือนแล้ว"
}

Error Response - Cut-off Date Exceeded (HTTP 400)


{
  "code": 400,
  "message": "ไม่สามารถขอเอกสารได้ เนื่องจากเกินกำหนดวันที่ขอเอกสารแล้ว"
}

Error Response - Quota Exceeded (HTTP 400)


{
  "code": 400,
  "message": "ไม่สามารถขอเอกสารได้ เนื่องจากเกินจำนวนโควตาการขอเอกสาร"
}

ข้อความใน message ของกรณีงวดเงินเดือนปิด, เกิน Cut-off และเกินโควตา เป็นภาษาไทยโดยค่าเริ่มต้น ส่ง language_code=EN เพื่อรับข้อความภาษาอังกฤษ

Response Fields

Field	Type	Description
`time_adjust_id`	string	รหัสเอกสารที่สร้าง (ต้องเข้ารหัส Base64 ก่อนส่งให้ API อื่น)
`employee_code`	string	รหัสพนักงาน
`time_adjust_dt`	string	วันที่เอกสาร
`time_adjust_flag_lv`	string	ประเภทเอกสาร
`time_adjust_desc`	string	คำอธิบาย
`approve_flag`	string	สถานะการอนุมัติ (เริ่มต้น: `01` = รออนุมัติ)
`created`	datetime	วันเวลาที่สร้าง
`image_url`	string \| null	URL ของไฟล์แนบ, `null` หากไม่มีไฟล์แนบ

Code Examples

cURL


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/time-adjust/submit" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_code": "EMP001",
    "time_adjust_dt": "2026-02-18",
    "time_adjust_flag_lv": "01",
    "time_adjust_desc": "ลืมลงเวลาเนื่องจากประชุม",
    "time_adjust_list_dt": [
      { "time_adjust_list_dt": "2026-02-18 09:00:00" },
      { "time_adjust_list_dt": "2026-02-18 18:00:00" }
    ]
  }'

JavaScript


const response = await fetch(
  'https://openapi.humansoft.co.th/api/v1/open-apis/time-adjust/submit',
  {
    method: 'POST',
    headers: {
      'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      employee_code: 'EMP001',
      time_adjust_dt: '2026-02-18',
      time_adjust_flag_lv: '01',
      time_adjust_desc: 'ลืมลงเวลาเนื่องจากประชุม',
      time_adjust_list_dt: [
        { time_adjust_list_dt: '2026-02-18 09:00:00' },
        { time_adjust_list_dt: '2026-02-18 18:00:00' }
      ]
    })
  }
)
 
const data = await response.json()
 
if (data.code === 200) {
  console.log('สร้างเอกสารสำเร็จ:', data.payload.time_adjust_id)
  console.log('สถานะ:', data.payload.approve_flag)
} else {
  console.error('Error:', data.errors || data.message)
}

Python


import requests
 
url = "https://openapi.humansoft.co.th/api/v1/open-apis/time-adjust/submit"
headers = {
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "employee_code": "EMP001",
    "time_adjust_dt": "2026-02-18",
    "time_adjust_flag_lv": "01",
    "time_adjust_desc": "ลืมลงเวลาเนื่องจากประชุม",
    "time_adjust_list_dt": [
        {"time_adjust_list_dt": "2026-02-18 09:00:00"},
        {"time_adjust_list_dt": "2026-02-18 18:00:00"}
    ]
}
 
response = requests.post(url, headers=headers, json=payload)
data = response.json()
 
if data['code'] == 200:
    print('สร้างเอกสารสำเร็จ:', data['payload']['time_adjust_id'])
    print('สถานะ:', data['payload']['approve_flag'])
else:
    print('Error:', data.get('errors') or data.get('message'))

PHP


<?php
$url = "https://openapi.humansoft.co.th/api/v1/open-apis/time-adjust/submit";
 
$headers = [
    "Ocp-Apim-Subscription-Key: YOUR_API_KEY",
    "Content-Type: application/json"
];
 
$payload = [
    "employee_code" => "EMP001",
    "time_adjust_dt" => "2026-02-18",
    "time_adjust_flag_lv" => "01",
    "time_adjust_desc" => "ลืมลงเวลาเนื่องจากประชุม",
    "time_adjust_list_dt" => [
        ["time_adjust_list_dt" => "2026-02-18 09:00:00"],
        ["time_adjust_list_dt" => "2026-02-18 18:00:00"]
    ]
];
 
$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['payload']['time_adjust_id'] . "\n";
    echo "สถานะ: " . $data['payload']['approve_flag'];
} else {
    echo "Error: " . ($data['errors'][0] ?? $data['message']);
}
 
curl_close($ch);
?>

Validation Rules

Parameter	Validation	Error Message
`employee_code`	ต้องระบุและเป็น string	`Missing required parameter: 'employee_code'`, `'employee_code' must be a string`
`time_adjust_dt`	ต้องระบุ รูปแบบ YYYY-MM-DD และเป็นวันที่ที่มีอยู่จริง	`Missing required parameter: 'time_adjust_dt'`, `'time_adjust_dt' must be in format YYYY-MM-DD`, `'time_adjust_dt' is not a valid date`
`time_adjust_flag_lv`	ต้องระบุและเป็นประเภทที่เปิดใช้งาน	`Missing required parameter: 'time_adjust_flag_lv'`, `'time_adjust_flag_lv' must be one of: 01, 02, ...` (แสดงรหัสที่ใช้ได้)
`time_adjust_list_dt`	ต้องเป็น array ที่ไม่ว่าง และไม่เกิน 4 รายการ	`Missing required parameter: 'time_adjust_list_dt' (must be a non-empty array)`, `'time_adjust_list_dt' cannot exceed 4 entries (received 5)`
`time_adjust_list_dt[n].time_adjust_list_dt`	ต้องระบุ และอยู่ในรูปแบบ YYYY-MM-DD HH:MM:SS	`'time_adjust_list_dt[0].time_adjust_list_dt' is required`, `'time_adjust_list_dt[0].time_adjust_list_dt' must be in format YYYY-MM-DD HH:MM:SS`
`time_adjust_desc`	ถ้าส่ง ต้องเป็น string	`'time_adjust_desc' must be a string`
`base64`	ถ้าส่ง ต้องเป็น string	`'base64' must be a string`

Business Rules

ข้อจำกัดการยื่นเอกสาร:

รายการเวลาต้องมี 1-4 รายการต่อเอกสาร ถ้าส่งเกิน 4 รายการ ระบบจะปฏิเสธคำขอ (HTTP 422)
ไม่สามารถยื่นเอกสารในงวดเงินเดือนที่ปิดแล้ว ยกเว้นส่ง extra_round=Y หรือวันที่เอกสารอยู่ในรอบ OT หรือรอบเวลาทำงานที่ยังเปิดอยู่
หากองค์กรเปิดใช้การกำหนดวันส่งเอกสาร (Cut-off) จะไม่สามารถยื่นเอกสารของงวดที่เลยกำหนดส่งแล้ว ผู้ที่ได้รับการยกเว้น (เช่น HR) ขึ้นอยู่กับการตั้งค่าขององค์กร
หากองค์กรเปิดใช้โควตาเอกสาร จำนวนเอกสารของพนักงานในงวดเงินเดือนต้องไม่เกินโควตาที่กำหนด (นับรวมทุกประเภทหรือแยกตามประเภท ตามการตั้งค่า) ผู้เรียก API ที่มีสิทธิ์ HR ไม่ถูกตรวจโควตา
ต้องมีพนักงานตาม employee_code อยู่ในระบบ
ประเภทเอกสารต้องเปิดใช้งานในบริษัท

Side Effects

เมื่อสร้างเอกสารสำเร็จ ระบบจะ:

Set Initial Status - ตั้งสถานะเป็น Pending (01)
Create Notification - ส่งการแจ้งเตือนไปยังผู้อนุมัติ ตามการตั้งค่าการแจ้งเตือนขององค์กร
Store Attachment - ถ้าส่ง base64 ระบบจะจัดเก็บไฟล์แนบ และคืน URL ใน image_url

Error Handling

Error	Cause	Solution
`Missing required parameter: 'employee_code'`	ไม่ได้ส่ง employee_code	ตรวจสอบ request body
`Employee not found: XXX`	ไม่พบพนักงาน	ตรวจสอบ employee_code
`'time_adjust_flag_lv' must be one of: ...`	ประเภทเอกสารไม่ได้เปิดใช้งาน	ใช้ Get Adjust Types ดูประเภทที่ใช้ได้
`'time_adjust_list_dt' cannot exceed 4 entries (received N)`	ส่งรายการเวลาเกิน 4 รายการ	ส่งรายการเวลา 1-4 รายการ
`ไม่สามารถเพิ่มข้อมูลได้เนื่องจากปิดงวดเงินเดือนแล้ว`	งวดเงินเดือนปิดแล้ว	เลือกวันที่ในงวดที่เปิดอยู่ หรือใช้ `extra_round=Y`
`ไม่สามารถขอเอกสารได้ เนื่องจากเกินกำหนดวันที่ขอเอกสารแล้ว`	เกินกำหนดวันส่งเอกสาร (Cut-off)	ติดต่อ HR
`ไม่สามารถขอเอกสารได้ เนื่องจากเกินจำนวนโควตาการขอเอกสาร`	โควตาเต็ม	ติดต่อ HR

Notes

Use Cases

พนักงานยื่นคำขอเพิ่มเวลา - สร้างเอกสารเมื่อลืมลงเวลาหรือระบบมีปัญหา
HR สร้างเอกสารแทน - สร้างเอกสารให้พนักงาน (ผู้เรียก API ที่มีสิทธิ์ HR ไม่ถูกตรวจโควตา ส่วนการยกเว้น Cut-off ขึ้นอยู่กับการตั้งค่าขององค์กร)

Time Format

time_adjust_dt ใช้รูปแบบ YYYY-MM-DD เช่น 2026-02-18
time_adjust_list_dt แต่ละรายการใช้รูปแบบ YYYY-MM-DD HH:MM:SS เช่น 2026-02-18 09:00:00

File Attachment

ส่งไฟล์แนบเป็น Base64 encoded string ใน base64 (มี prefix data:<mime type>;base64, หรือไม่มีก็ได้)
รองรับไฟล์รูปภาพ เช่น PNG, JPG
ไม่สามารถกำหนด URL ของไฟล์แนบเองได้ ต้องส่งไฟล์ผ่าน base64 เท่านั้น
URL ของไฟล์แนบจะคืนใน image_url และดูภายหลังได้จาก Get Adjust List หรือ Get Adjust Detail

Get Adjust Types - ดึงรายการประเภทการขอเพิ่มเวลา
Get Adjust List - ดึงรายการเอกสารขอเพิ่มเวลา
Update Adjust - แก้ไขเอกสารขอเพิ่มเวลา
Delete Adjust - ลบเอกสารขอเพิ่มเวลา