Submit Warning Letter
API สำหรับสร้างจดหมายเตือนให้พนักงาน พร้อมแนบรูปภาพและเอกสาร PDF ได้ในคำขอเดียว เมื่อสร้างสำเร็จ ระบบจะแจ้งเตือนพนักงาน และสร้างการ์ดจดหมายเตือนใน News Feed ของพนักงาน
Endpoint
POST /api/v1/open-apis/warning-letter/submitสิทธิ์ที่ต้องการ: API Key ต้องมีสิทธิ์ ข้อมูลการยื่นเอกสาร (document:manage)
Request Body
ส่งแบบ multipart/form-data (ใช้ได้ทั้งกรณีแนบและไม่แนบไฟล์)
Required Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
employee_code | string | Yes | รหัสพนักงานที่ได้รับจดหมายเตือน (ไม่เกิน 50 ตัวอักษร) | "EMP001" |
warning_letter_flag_lv | string | Yes | ระดับใบเตือน (ดู Warning Letter Levels) | "04" |
warning_letter_dt | string | Yes | วันที่ของจดหมายเตือน รูปแบบ YYYY-MM-DD — ต้องไม่เป็นวันในอนาคต (เวลาประเทศไทย) | "2026-10-15" |
Optional Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
warning_letter_desc | string | No | รายละเอียด / หมายเหตุ ไม่เกิน 5,000 ตัวอักษร ขึ้นบรรทัดใหม่ได้ | "มาสายเกิน 3 ครั้งในเดือน" |
_image[] | file | No | รูปภาพ JPG/PNG — ส่งได้หลายไฟล์โดยใช้ชื่อ field ซ้ำ | [Binary Data] |
_doc[] | file | No | เอกสาร PDF — ส่งได้หลายไฟล์โดยใช้ชื่อ field ซ้ำ | [Binary Data] |
lang | string | No | ภาษาของ message: TH (ค่าเริ่มต้น) หรือ EN | "EN" |
สถานะการรับทราบ วันเวลาที่สร้าง/แก้ไข และข้อมูลอื่นที่ระบบกำหนดเอง ห้ามส่งมา เช่น employee_id, approve_flag, created, last_upd — หากส่งมาจะได้ HTTP 422 พร้อมข้อความ '<field>' is not allowed ให้ระบุพนักงานด้วย employee_code เท่านั้น
File Attachment Rules
ระบบตรวจชนิดไฟล์จาก เนื้อหาไฟล์จริง ไม่ได้ดูจาก Content-Type ที่ส่งมา และตรวจไฟล์ทุกไฟล์ก่อนบันทึก — หากมีไฟล์ใดไม่ผ่าน คำขอทั้งหมดจะถูกปฏิเสธและไม่มีการบันทึกข้อมูล
| เงื่อนไข | รายละเอียด |
|---|---|
| ชื่อ field | รับเฉพาะ _image[] และ _doc[] — ไฟล์ที่ส่งด้วยชื่อ field อื่นจะถูกปฏิเสธ |
รูปภาพ (_image[]) | ต้องเป็น JPEG หรือ PNG ที่เปิดอ่านได้จริง นามสกุลต้องตรงกับเนื้อหาไฟล์ (.jpg / .jpeg สำหรับ JPEG, .png สำหรับ PNG) และกว้าง/สูงไม่เกิน 10,000 pixels |
เอกสาร (_doc[]) | ต้องเป็น PDF ที่สมบูรณ์ (ไม่ใช่ไฟล์ที่อัปโหลดมาไม่ครบ) นามสกุล .pdf และต้องไม่มี JavaScript, คำสั่งเปิดโปรแกรม (launch action), rich media หรือไฟล์ฝัง (PDF ที่แนบไฟล์อื่นไว้ภายในจะถูกปฏิเสธ) |
| ขนาดรวม | รูปภาพรวมกันไม่เกิน 2,048 KB และเอกสารรวมกันไม่เกิน 2,048 KB ต่อจดหมายเตือน 1 ใบ |
| จำนวนไฟล์ | รูปภาพไม่เกิน 10 ไฟล์ และเอกสารไม่เกิน 10 ไฟล์ ต่อจดหมายเตือน 1 ใบ |
| ไฟล์ว่าง | ไฟล์ขนาด 0 bytes หรืออัปโหลดมาไม่สำเร็จจะถูกปฏิเสธ |
| ชื่อไฟล์ | ใช้เฉพาะชื่อไฟล์ (ตัด path ออก) ต้องไม่มี emoji หรืออักขระควบคุม และยาวไม่เกิน 255 ตัวอักษร — ชื่อนี้จะแสดงใน file_name ส่วน URL ของไฟล์ระบบตั้งชื่อใหม่ให้ |
Response Format
Success Response
คืนข้อมูลของจดหมายเตือนที่สร้าง ในรูปแบบเดียวกับ Get Detail
{
"code": 200,
"message": "สร้างจดหมายเตือนสำเร็จ",
"payload": {
"warning_letter_id": "20251127D4573C421639",
"employee_code": "EMP001",
"employee_name": "สมชาย ใจดี",
"employee_name_en": "Somchai Jaidee",
"warning_letter_dt": "2026-10-15",
"warning_letter_flag_lv": "05",
"warning_letter_flag_name": "หนังสือตักเตือนเป็นลายลักษณ์อักษร",
"warning_letter_flag_name_en": "Written Warning Letter",
"warning_letter_desc": "ทำงานผิดพลาดซ้ำ",
"approve_flag": "01",
"approve_flag_name": "แจ้งพนักงานแล้ว",
"approve_flag_name_en": "Informed",
"created": "2026-10-15 10:01:12",
"last_upd": "2026-10-15 10:01:12",
"images": [
{
"warning_letter_file_id": "20251127A1B2C3D4E5F6",
"file_name": "evidence.jpg",
"mime_type": "image/jpeg",
"file_size": 183402,
"url": "https://cdn.humansoft.co.th/.../file/3fa1c2d4e5b6a7f8.jpg"
}
],
"files": [
{
"warning_letter_file_id": "20251127F6E5D4C3B2A1",
"file_name": "letter.pdf",
"mime_type": "application/pdf",
"file_size": 92311,
"url": "https://cdn.humansoft.co.th/.../file/9b8c7d6e5f4a3b2c.pdf"
}
]
}
}Success Response with Warnings
จดหมายเตือนถูกบันทึกแล้ว แต่งานต่อเนื่องบางส่วนไม่สำเร็จ — ระบบคืน HTTP 200 พร้อม warnings (ไม่ต้องส่งคำขอซ้ำ)
{
"code": 200,
"message": "สร้างจดหมายเตือนสำเร็จ",
"payload": {
"warning_letter_id": "20251127D4573C421639",
"...": "..."
},
"warnings": [
"employee notification could not be sent"
]
}ข้อความใน warnings | ความหมาย |
|---|---|
employee notification could not be sent | ส่งแจ้งเตือนถึงพนักงานไม่สำเร็จ |
news feed could not be updated | สร้างการ์ดจดหมายเตือนใน News Feed ไม่สำเร็จ |
Error Response
ข้อมูลไม่ผ่านการตรวจสอบ (422) — ระบบรวมข้อผิดพลาดของทุก parameter และทุกไฟล์มาในคำตอบเดียว
{
"code": 422,
"message": "การตรวจสอบข้อมูลล้มเหลว",
"errors": [
"'warning_letter_dt' must not be in the future",
"'_image[0]' extension '.png' does not match its content (image/jpeg)",
"total document size must not exceed 2048 KB (including files already attached)"
]
}ข้อความใน errors | สาเหตุ |
|---|---|
'<parameter>' is required | ไม่ได้ส่ง parameter บังคับ |
'<parameter>' must be a string | ส่งค่าเป็น array, object หรือ boolean |
'<field>' is not allowed | ส่ง field ที่ระบบกำหนดเองมา เช่น employee_id, approve_flag |
'employee_code' must be at most 50 characters without control characters | employee_code ยาวเกิน 50 ตัวอักษร หรือมีอักขระควบคุม |
'warning_letter_flag_lv' must be one of: 01, 02, ... | ระดับใบเตือนไม่มีอยู่ในระบบ |
'warning_letter_dt' must be a valid date (YYYY-MM-DD) | วันที่ผิดรูปแบบหรือไม่มีอยู่จริง |
'warning_letter_dt' must not be in the future | วันที่เป็นวันในอนาคต |
'warning_letter_desc' must not exceed 5000 characters | รายละเอียดยาวเกิน 5,000 ตัวอักษร |
'warning_letter_desc' must not contain emoji or other 4-byte characters | รายละเอียดมี emoji หรืออักขระพิเศษที่ไม่รองรับ |
'warning_letter_desc' must not contain control characters / must be valid UTF-8 | รายละเอียดมีอักขระควบคุม (ยกเว้น tab และขึ้นบรรทัดใหม่) หรือไม่ใช่ UTF-8 |
'<field>' is not an accepted file field (use _image[] or _doc[]) | ส่งไฟล์ด้วยชื่อ field อื่น |
'_image[n]' must be a JPG or PNG image / is not a readable JPG or PNG image | ไฟล์ใน _image[] ไม่ใช่รูป JPEG/PNG หรือเปิดอ่านไม่ได้ |
'_image[n]' must be at most 10000 pixels wide and high | รูปกว้างหรือสูงเกิน 10,000 pixels |
'_doc[n]' must be a PDF file / is an incomplete or damaged PDF | ไฟล์ใน _doc[] ไม่ใช่ PDF หรือไฟล์ไม่สมบูรณ์ |
'_doc[n]' contains active content (JavaScript, launch actions or embedded files), which is not allowed | PDF มี JavaScript, launch action หรือไฟล์ฝัง |
'<file>' extension '.xxx' does not match its content (...) | นามสกุลไฟล์ไม่ตรงกับเนื้อหาไฟล์ |
'<file>' is empty / '<file>' upload failed: ... | ไฟล์ขนาด 0 bytes หรืออัปโหลดไม่สำเร็จ |
'<file>' file name must ... / '<file>' must have a file name | ชื่อไฟล์ไม่ผ่านเงื่อนไข |
at most 10 image files are allowed per warning letter (including files already attached) | รูปภาพเกิน 10 ไฟล์ (ข้อความสำหรับเอกสารใช้คำว่า document) |
total image size must not exceed 2048 KB (including files already attached) | รูปภาพรวมกันเกิน 2,048 KB (ข้อความสำหรับเอกสารใช้คำว่า document) |
'employee_code' not found | ไม่พบพนักงานรหัสนี้ในองค์กร (ตรวจหลังจาก parameter และไฟล์ผ่านทั้งหมดแล้ว) |
จดหมายเตือนซ้ำ (409) — มีจดหมายเตือนของพนักงาน วันที่ และระดับใบเตือนเดียวกันอยู่แล้ว
{
"code": 409,
"message": "มีจดหมายเตือนของพนักงาน วันที่ และระดับเดียวกันอยู่แล้ว"
}| HTTP Status | Description |
|---|---|
400 | เกิดข้อผิดพลาดระหว่างบันทึก (message: กระบวนการล้มเหลว) — ระบบยกเลิกการบันทึกทั้งหมด รวมถึงไฟล์ที่อัปโหลดในคำขอนั้น |
403 | API Key ไม่มีสิทธิ์ document:manage |
409 | มีจดหมายเตือนของพนักงาน วันที่ และระดับเดียวกันอยู่แล้ว |
422 | ข้อมูลหรือไฟล์แนบไม่ผ่านการตรวจสอบ หรือไม่พบพนักงานตาม employee_code |
500 | เกิดข้อผิดพลาดที่เซิร์ฟเวอร์ (message: เกิดข้อผิดพลาดที่เซิร์ฟเวอร์) — ระบบยกเลิกการบันทึกทั้งหมด |
Code Examples
cURL
curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/warning-letter/submit" \
-H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
-F "employee_code=EMP001" \
-F "warning_letter_flag_lv=05" \
-F "warning_letter_dt=2026-10-15" \
-F "warning_letter_desc=ทำงานผิดพลาดซ้ำ" \
-F "_image[]=@/path/to/evidence.jpg" \
-F "_doc[]=@/path/to/letter.pdf"Notes
- จดหมายเตือนที่สร้างจะมีสถานะ
01(แจ้งพนักงานแล้ว) เสมอ ระบบจะแจ้งเตือนพนักงาน (เฉพาะพนักงานที่มีบัญชีผู้ใช้ในระบบ — หากไม่มี จะไม่มีการแจ้งเตือนและไม่มีwarnings) และสร้างการ์ดจดหมายเตือนใน News Feed ของพนักงาน - ห้ามมีจดหมายเตือนของพนักงาน วันที่ และระดับใบเตือนเดียวกันซ้ำกัน — หากส่งคำขอที่มีข้อมูลชุดเดียวกันพร้อมกันหลายคำขอ ระบบอาจรับไว้มากกว่า 1 ใบ จึงควรส่งทีละคำขอ
- สร้างจดหมายเตือนให้พนักงานที่ลาออกแล้วได้
- หากบันทึกไม่สำเร็จ (HTTP
400) จะไม่มีข้อมูลหรือไฟล์ใดถูกบันทึกจากคำขอนั้น ส่งคำขอใหม่ได้
Related APIs
- Get Detail - ดูจดหมายเตือนที่สร้างด้วย
warning_letter_idจาก Response (encode เป็น Base64 ก่อน) - Update - แก้ไขข้อมูลหรือแนบไฟล์เพิ่มภายหลัง
- Get List - ค้นหารายการจดหมายเตือน