Skip to Content
🚀 Welcome to Humansoft Open API Documentation

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

ParameterTypeRequiredDescriptionExample
employee_codestringYesรหัสพนักงานที่ได้รับจดหมายเตือน (ไม่เกิน 50 ตัวอักษร)"EMP001"
warning_letter_flag_lvstringYesระดับใบเตือน (ดู Warning Letter Levels)"04"
warning_letter_dtstringYesวันที่ของจดหมายเตือน รูปแบบ YYYY-MM-DD — ต้องไม่เป็นวันในอนาคต (เวลาประเทศไทย)"2026-10-15"

Optional Parameters

ParameterTypeRequiredDescriptionExample
warning_letter_descstringNoรายละเอียด / หมายเหตุ ไม่เกิน 5,000 ตัวอักษร ขึ้นบรรทัดใหม่ได้"มาสายเกิน 3 ครั้งในเดือน"
_image[]fileNoรูปภาพ JPG/PNG — ส่งได้หลายไฟล์โดยใช้ชื่อ field ซ้ำ[Binary Data]
_doc[]fileNoเอกสาร PDF — ส่งได้หลายไฟล์โดยใช้ชื่อ field ซ้ำ[Binary Data]
langstringNoภาษาของ 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 charactersemployee_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 allowedPDF มี 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 StatusDescription
400เกิดข้อผิดพลาดระหว่างบันทึก (message: กระบวนการล้มเหลว) — ระบบยกเลิกการบันทึกทั้งหมด รวมถึงไฟล์ที่อัปโหลดในคำขอนั้น
403API Key ไม่มีสิทธิ์ document:manage
409มีจดหมายเตือนของพนักงาน วันที่ และระดับเดียวกันอยู่แล้ว
422ข้อมูลหรือไฟล์แนบไม่ผ่านการตรวจสอบ หรือไม่พบพนักงานตาม employee_code
500เกิดข้อผิดพลาดที่เซิร์ฟเวอร์ (message: เกิดข้อผิดพลาดที่เซิร์ฟเวอร์) — ระบบยกเลิกการบันทึกทั้งหมด

Code Examples

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) จะไม่มีข้อมูลหรือไฟล์ใดถูกบันทึกจากคำขอนั้น ส่งคำขอใหม่ได้

  • Get Detail - ดูจดหมายเตือนที่สร้างด้วย warning_letter_id จาก Response (encode เป็น Base64 ก่อน)
  • Update - แก้ไขข้อมูลหรือแนบไฟล์เพิ่มภายหลัง
  • Get List - ค้นหารายการจดหมายเตือน
Last updated on