Time Adjust API Module

ภาพรวม (Overview)

โมดูล Time Adjust เป็น API สำหรับจัดการเอกสารขอเพิ่มเวลาทำงาน ใช้เมื่อพนักงานต้องการแก้ไขหรือเพิ่มเวลาเข้า-ออกงานย้อนหลัง รวมถึงการยื่นคำขอ การอนุมัติ และการนำเข้าข้อมูลแบบกลุ่ม

Time Adjust คืออะไร?

Time Adjust (การขอเพิ่มเวลาทำงาน) คือการยื่นคำขอแก้ไขเวลาเข้า-ออกงานย้อนหลัง ด้วยเหตุผลต่างๆ:

• ลืมลงเวลา = พนักงานลืมสแกนบัตรหรือลงเวลาเข้า-ออกงาน
• ระบบมีปัญหา = ระบบลงเวลาขัดข้อง
• เครื่องลงเวลาใช้งานไม่ได้ = อุปกรณ์ลงเวลาเสียหรือใช้งานไม่ได้
• ไฟฟ้าดับ = ไม่สามารถลงเวลาได้เนื่องจากไฟฟ้าดับ
• ทำงานนอกสถานที่ = ทำงานนอกออฟฟิศ
• ทำงานเกินเวลา = ทำงานเกินเวลาปกติ

ประเภทการขอเพิ่มเวลา (Adjust Types)

API Endpoints (8 endpoints)

ข้อมูลพื้นฐาน

Get Adjust Types

ดึงรายการประเภทการขอเพิ่มเวลาทั้งหมดที่เปิดใช้งาน

Use Cases:

• แสดง dropdown เลือกประเภทการขอเพิ่มเวลา
• ใช้อ้างอิง code กับชื่อประเภท

ดึงข้อมูล

Get Adjust List

ดึงรายการเอกสารขอเพิ่มเวลาตามเงื่อนไข รองรับ 3 โหมด: self, hr, lasted

Use Cases:

• แสดงรายการเอกสารขอเพิ่มเวลา
• ติดตามสถานะการอนุมัติ
• หน้าจอ HR Dashboard

Get Adjust Detail

ดึงรายละเอียดเอกสารขอเพิ่มเวลารายการเดียว

Use Cases:

• แสดงรายละเอียดเอกสาร
• ตรวจสอบข้อมูลก่อนอนุมัติ/แก้ไข

จัดการเอกสาร

Submit Adjust

ยื่นเอกสารขอเพิ่มเวลาใหม่ (สูงสุด 4 รายการเวลาต่อเอกสาร)

Use Cases:

• พนักงานยื่นคำขอเพิ่มเวลา
• HR สร้างคำขอแทนพนักงาน

Update Adjust

แก้ไขเอกสารขอเพิ่มเวลาที่ยังไม่อนุมัติ

Use Cases:

• แก้ไขรายละเอียดเอกสาร
• เปลี่ยนประเภทหรือรายการเวลา

Delete Adjust

ลบเอกสารขอเพิ่มเวลา

Use Cases:

• ยกเลิกคำขอที่ยื่นผิดพลาด
• ลบเอกสารที่ไม่ต้องการ

อนุมัติ

Approve Adjust

อนุมัติหรือปฏิเสธเอกสารขอเพิ่มเวลา รองรับการอนุมัติแบบหลายขั้นตอน

Use Cases:

• หัวหน้าอนุมัติคำขอ
• HR อนุมัติหรือปฏิเสธเอกสาร
• อนุมัติแบบหลายขั้นตอน (Multi-level Approval)

นำเข้าข้อมูล

Import Adjust

นำเข้าเอกสารขอเพิ่มเวลาแบบกลุ่ม (Batch Import) รองรับสร้างและลบ

Use Cases:

• ย้ายข้อมูลจากระบบเดิม
• สร้างเอกสารจำนวนมากพร้อมกัน
• รับข้อมูลจากระบบภายนอก

Approve Status (สถานะการอนุมัติ)

Standard Response Format

Success Response

{
  "code": 200,
  "message": "สำเร็จ",
  "payload": { ... }
}

Error Response

{
  "code": 400,
  "message": "ไม่สำเร็จ",
  "error": "Error message"
}

Validation Error Response

{
  "code": 422,
  "message": "Validation failed",
  "errors": [
    "Missing required parameter: 'employee_code'",
    "'time_adjust_dt' must be in format YYYY-MM-DD"
  ]
}

หมายเหตุสำคัญ

1. Authentication Required - API เหล่านี้ต้องการ Ocp-Apim-Subscription-Key header

2. Finish Month Check - ไม่สามารถสร้าง/แก้ไข/ลบเอกสารในงวดเงินเดือนที่ปิดแล้ว

3. Cut-off Date - อาจมีการจำกัดวันสุดท้ายการส่งเอกสาร ขึ้นอยู่กับการตั้งค่าระบบ

4. Time List Limit - จำกัดรายการเวลาสูงสุด 4 รายการต่อเอกสาร

5. Approval Workflow - เอกสารต้องผ่านการอนุมัติตามลำดับขั้นที่กำหนด (รองรับ Multi-level Approval)

6. Employee Code - ใช้ employee_code แทน employee_id เพื่อความสะดวกในการเรียกใช้งาน

Related APIs

• Time Leave (การลา) - จัดการการลางาน
• Time Attendance (บันทึกเวลา) - จัดการบันทึกเวลา
• Overtime (ทำงานล่วงเวลา) - จัดการการทำงานล่วงเวลา