Warning Letter API Module

ภาพรวม (Overview)

โมดูล Warning Letter เป็น API สำหรับจัดการจดหมายเตือนพนักงาน ตรงกับเมนู ประเมินผล → จดหมายเตือน ในระบบ HumanSoft ครอบคลุมการสร้าง แก้ไข ค้นหา ดูรายละเอียด และลบจดหมายเตือน พร้อมแนบรูปภาพ (JPG/PNG) และเอกสาร PDF

สิทธิ์ที่ต้องการ: API Key ต้องมีสิทธิ์ ข้อมูลการยื่นเอกสาร (document:manage) จึงจะเรียกใช้ API ในโมดูลนี้ได้

ขั้นตอนการทำงาน (Workflow)

สร้างจดหมายเตือน - สร้างผ่าน Submit โดยแนบรูปภาพหรือ PDF ในคำขอเดียวกันได้ ใบที่สร้างจะมีสถานะ 01 (แจ้งพนักงานแล้ว) และระบบจะแจ้งเตือนพนักงานพร้อมแสดงการ์ดจดหมายเตือนใน News Feed ของพนักงาน
แก้ไขหรือจัดการไฟล์แนบ - ระหว่างที่ใบยังมีสถานะ 01 แก้ไขข้อมูลหรือแนบไฟล์เพิ่มได้ผ่าน Update ลบไฟล์แนบผ่าน Delete File หรือลบทั้งใบผ่าน Delete
พนักงานรับทราบ - เมื่อพนักงานกดรับทราบจดหมายเตือน สถานะจะเปลี่ยนเป็น 02 (พนักงานรับทราบแล้ว) และใบนั้นจะแก้ไข ลบ หรือลบไฟล์แนบไม่ได้อีก (HTTP 409)

สถานะ 02 เกิดเมื่อพนักงานกดรับทราบจดหมายเตือน — Open API ไม่มี Endpoint สำหรับเปลี่ยนสถานะการรับทราบ และไม่รับ approve_flag ในคำขอสร้างหรือแก้ไข

API Endpoints

Endpoint	Method	รายละเอียด
Get List	POST	ค้นหารายการจดหมายเตือนตามช่วงวันที่ พนักงาน ระดับ และสถานะ
Get Detail	POST	ดูรายละเอียดจดหมายเตือน 1 ใบ พร้อมไฟล์แนบ
Submit	POST	สร้างจดหมายเตือน พร้อมแนบรูปภาพและ PDF
Update	POST	แก้ไขจดหมายเตือน หรือแนบไฟล์เพิ่ม
Delete	POST	ลบจดหมายเตือนทั้งใบ พร้อมไฟล์แนบทั้งหมด
Delete File	POST	ลบไฟล์แนบ 1 ไฟล์

Warning Letter Levels

ค่าของ warning_letter_flag_lv (ระดับใบเตือน) ใช้ทั้งใน Request และ Response — Response จะคืนชื่อระดับทั้งภาษาไทย (warning_letter_flag_name) และภาษาอังกฤษ (warning_letter_flag_name_en) ให้ด้วย

ค่า	ความหมาย (EN)	ความหมาย (TH)
`01`	Work behavior	พฤติกรรมการทำงาน
`02`	Malfunction	ปฏิบัติงานผิดพลาด
`03`	Other	อื่นๆ
`04`	Letter of Verbal Reprimand	หนังสือตักเตือนด้วยวาจา
`05`	Written Warning Letter	หนังสือตักเตือนเป็นลายลักษณ์อักษร
`06`	Suspension Notice (Without Pay)	หนังสือพักงาน (โดยไม่ได้รับค่าจ้าง) ไม่เกิน 7 วัน
`07`	Notice of Summary Dismissal	หนังสือเลิกจ้าง (ความผิดร้ายแรง)
`08`	Notice of Termination (Repeated Misconduct)	หนังสือเลิกจ้าง (ผิดซ้ำคำเตือน)

Acknowledgement Status

ค่าของ approve_flag (สถานะการรับทราบ) — ระบบเป็นผู้กำหนด ใช้กรองข้อมูลใน Get List ได้

ค่า	ความหมาย (EN)	ความหมาย (TH)	แก้ไข / ลบได้
`01`	Informed	แจ้งพนักงานแล้ว — สถานะเริ่มต้นเมื่อสร้างใบ	ได้
`02`	Acknowledged	พนักงานรับทราบแล้ว	ไม่ได้ (HTTP `409`)

ไฟล์แนบ (Attachments)

แนบไฟล์ผ่าน Submit หรือ Update โดยส่งแบบ multipart/form-data — รูปภาพ JPG/PNG ใช้ field _image[] และเอกสาร PDF ใช้ field _doc[]
แต่ละใบมีรูปภาพได้ไม่เกิน 10 ไฟล์ รวมกันไม่เกิน 2,048 KB และมีเอกสารได้ไม่เกิน 10 ไฟล์ รวมกันไม่เกิน 2,048 KB (ดูเงื่อนไขทั้งหมดที่ File Attachment Rules)
Get Detail คืนรูปภาพใน images และเอกสารใน files พร้อม url สำหรับเปิดไฟล์

Warnings

Submit, Update, Delete และ Delete File อาจคืน HTTP 200 พร้อม array warnings เมื่อบันทึกหรือลบข้อมูลหลักสำเร็จแล้ว แต่งานต่อเนื่องบางส่วนไม่สำเร็จ เช่น แจ้งเตือนพนักงานไม่สำเร็จ — คำขอนั้นถือว่าสำเร็จแล้ว ไม่ควรส่งซ้ำ (การส่ง Submit ซ้ำจะได้ HTTP 409 เพราะข้อมูลซ้ำ)

Response Language

Parameter lang (TH ค่าเริ่มต้น หรือ EN) มีผลกับ message เท่านั้น — ข้อความใน errors และ warnings เป็นภาษาอังกฤษเสมอ ส่วนชื่อระดับใบเตือนและชื่อสถานะใน Response มีให้ทั้งภาษาไทยและภาษาอังกฤษทุกครั้ง

พารามิเตอร์ที่ลงท้ายด้วย _id (warning_letter_id, warning_letter_file_id) ต้องส่งเป็น Base64-encoded

Response จะ return raw string ID (เช่น 20251127D4573C421639)
เมื่อนำ ID จาก response ไปใช้ใน request ถัดไป ต้อง encode เป็น Base64 ก่อน

Assessment Overview - ภาพรวมโมดูลประเมินผล
API Permissions - สิทธิ์การเข้าถึงของ API Key