Add Petty Cash Item

API สำหรับเพิ่มรายละเอียดค่าใช้จ่าย (เช่น ค่าเดินทาง, ค่าที่พัก, ค่าอุปกรณ์) เข้าไปในเอกสารเบิกเงินสดย่อยที่สร้างไว้แล้ว รองรับการระบุจำนวนเงิน หมวดหมู่การเบิก และการแนบไฟล์รูปภาพหลักฐาน (เช่น ใบเสร็จ)

Endpoint


POST /api/v1/open-apis/petty-cash/add-item

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

Request Body

ส่งแบบ multipart/form-data เมื่อต้องแนบไฟล์ (หากไม่แนบไฟล์ ส่งเป็น application/json ได้)

Required Parameters

Parameter	Type	Required	Description	Example
`petty_cash_id`	string	Yes	รหัสเอกสารหลักที่จะเพิ่มรายการเข้าไป (Base64)	`"MjAyNTExMjdENDU3M0M0MjE2Mzk="`
`petty_cash_item_name`	string	Yes	ชื่อรายการค่าใช้จ่าย	`"ค่าน้ำมันรถยนต์"`
`req_amt`	number	Yes	จำนวนเงินที่เบิก ต้องเป็นตัวเลขมากกว่า 0	`500.00`
`petty_cash_type_id`	string	Yes	รหัสประเภทรายการ (Base64) ดูได้จาก API List Types	`"MjAyNjAzMDNBMUIyQzNENEU1RjY="`

Optional Parameters

Parameter	Type	Required	Description	Example
`authorize_id`	string	No	ID ของผู้ใช้ที่ทำรายการ (Base64) — แนะนำให้ส่ง หากไม่ส่ง ผู้ทำรายการล่าสุดของเอกสารจะถูกบันทึกเป็นค่าว่าง	`"MjAyNTAzMDM1MUIwQTJDQ0JEOUM="`
`attach_files`	file	No	ไฟล์รูปภาพหลักฐาน — ส่งไฟล์เดียวด้วยชื่อ `attach_files` หรือหลายไฟล์ด้วย `attach_files[]` (ดูเงื่อนไขด้านล่าง)	`[Binary Data]`
`lang`	string	No	ภาษาของข้อความตอบกลับ: `TH` (ค่าเริ่มต้น) หรือ `EN`	`"EN"`

เงื่อนไขไฟล์แนบ

เงื่อนไข	รายละเอียด
ประเภทไฟล์	รูปภาพ JPG/JPEG, PNG, GIF, WEBP และ HEIC/HEIF เท่านั้น — ระบบตรวจจากเนื้อหาไฟล์จริง ไม่ได้ดูแค่นามสกุล
ขนาดไฟล์	ไม่เกิน 5MB ต่อไฟล์
จำนวนไฟล์	ส่งได้หลายไฟล์ในคำขอเดียวด้วย `attach_files[]`
เมื่อไฟล์ไม่ผ่าน	ระบบปฏิเสธคำขอทั้งหมดและไม่บันทึกรายการ โดยแจ้งชื่อไฟล์ที่ไม่ผ่านใน `errors`

ตัวอย่างการแนบหลายไฟล์:


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/petty-cash/add-item" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -F "petty_cash_id=MjAyNTExMjdENDU3M0M0MjE2Mzk=" \
  -F "petty_cash_item_name=ค่าที่พักโรงแรม" \
  -F "req_amt=1200.00" \
  -F "petty_cash_type_id=MjAyNjAzMDNBMUIyQzNENEU1RjY=" \
  -F "attach_files[]=@/path/to/receipt-1.jpg" \
  -F "attach_files[]=@/path/to/receipt-2.png"

Response Format

Success Response


{
  "code": 200,
  "message": "เพิ่มรายการเงินสดย่อยสำเร็จ",
  "payload": {
    "petty_cash_id": "20251127D4573C421639",
    "petty_cash_item_name": "ค่าที่พักโรงแรม",
    "req_amt": 1200,
    "attach_file": "[\"...\"]",
    "petty_cash_type_id": "20260303A1B2C3D4E5F6",
    "petty_cash_item_id": "20260325A1B2C3D4E5F6"
  }
}

Response Fields

Field	Type	Nullable	Description
`petty_cash_id`	string	No	รหัสเอกสารหลัก
`petty_cash_item_name`	string	No	ชื่อรายการค่าใช้จ่ายที่เพิ่ม
`req_amt`	number	No	จำนวนเงินที่เบิก
`attach_file`	string	No	JSON string ของรายการไฟล์แนบที่บันทึก (`"[]"` ถ้าไม่มีไฟล์) — ใช้ Get Detail เพื่อดู URL สำหรับเปิดไฟล์
`petty_cash_type_id`	string	No	รหัสประเภทรายการ
`petty_cash_item_id`	string	No	รหัสรายการย่อยที่ถูกสร้างขึ้น

Error Response

ข้อมูลไม่ผ่านการตรวจสอบ (422)


{
  "code": 422,
  "message": "การตรวจสอบข้อมูลล้มเหลว",
  "errors": ["'req_amt' must be greater than 0"]
}

ไฟล์แนบไม่ผ่านเงื่อนไข (422)


{
  "code": 422,
  "message": "การตรวจสอบข้อมูลล้มเหลว",
  "errors": ["receipt.pdf: รองรับเฉพาะไฟล์รูปภาพเท่านั้น (JPG, PNG, GIF, WEBP, HEIC)"]
}

ข้อความใน `errors`	สาเหตุ
`'<parameter>' is required`	ไม่ได้ส่ง parameter บังคับ เช่น `'req_amt' is required`
`'req_amt' must be numeric`	`req_amt` ไม่ใช่ตัวเลข
`'req_amt' must be greater than 0`	`req_amt` น้อยกว่าหรือเท่ากับ 0
`<ชื่อไฟล์>: รองรับเฉพาะไฟล์รูปภาพเท่านั้น (JPG, PNG, GIF, WEBP, HEIC)`	ไฟล์ไม่ใช่รูปภาพประเภทที่รองรับ
`<ชื่อไฟล์>: ขนาดไฟล์เกินกำหนด (สูงสุด 5MB ต่อไฟล์)`	ไฟล์มีขนาดเกิน 5MB
`<ชื่อไฟล์>: เกิดข้อผิดพลาดในการอัปโหลดไฟล์` (อาจมี `(code N)` ต่อท้าย)	ไฟล์อัปโหลดมาไม่สมบูรณ์
`cannot add item to petty cash that is not in draft state`	เอกสารไม่ได้อยู่ในสถานะ `01` (รออนุมัติ) จึงเพิ่มรายการไม่ได้

ไม่พบเอกสาร (404)


{
  "code": 404,
  "message": "ไม่พบรายการ"
}

HTTP Status	Description
`400`	เกิดข้อผิดพลาดระหว่างทำรายการ เช่น อัปโหลดไฟล์ไม่สำเร็จ
`403`	API Key ไม่มีสิทธิ์ `document:manage`
`404`	ไม่พบเอกสารตาม `petty_cash_id`
`422`	ข้อมูลหรือไฟล์แนบไม่ผ่านการตรวจสอบ หรือเอกสารไม่อยู่ในสถานะที่เพิ่มรายการได้

Code Examples

cURL


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/petty-cash/add-item" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -F "petty_cash_id=MjAyNTExMjdENDU3M0M0MjE2Mzk=" \
  -F "petty_cash_item_name=ค่าที่พักโรงแรม" \
  -F "req_amt=1200.00" \
  -F "petty_cash_type_id=MjAyNjAzMDNBMUIyQzNENEU1RjY=" \
  -F "authorize_id=MjAyNTAzMDM1MUIwQTJDQ0JEOUM=" \
  -F "attach_files=@/path/to/receipt.jpg"

JavaScript


const formData = new FormData()
formData.append('petty_cash_id', 'MjAyNTExMjdENDU3M0M0MjE2Mzk=')
formData.append('petty_cash_item_name', 'ค่าที่พักโรงแรม')
formData.append('req_amt', '1200.00')
formData.append('petty_cash_type_id', 'MjAyNjAzMDNBMUIyQzNENEU1RjY=')
formData.append('authorize_id', 'MjAyNTAzMDM1MUIwQTJDQ0JEOUM=')
// แนบได้หลายไฟล์ด้วย attach_files[]
for (const file of fileInput.files) {
  formData.append('attach_files[]', file)
}
 
const response = await fetch(
  'https://openapi.humansoft.co.th/api/v1/open-apis/petty-cash/add-item',
  {
    method: 'POST',
    headers: {
      'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY'
    },
    body: formData
  }
)
const data = await response.json()

Python


import requests
 
url = "https://openapi.humansoft.co.th/api/v1/open-apis/petty-cash/add-item"
headers = {
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "petty_cash_id": "MjAyNTExMjdENDU3M0M0MjE2Mzk=",
    "petty_cash_item_name": "ค่าที่พักโรงแรม",
    "req_amt": "1200.00",
    "petty_cash_type_id": "MjAyNjAzMDNBMUIyQzNENEU1RjY=",
    "authorize_id": "MjAyNTAzMDM1MUIwQTJDQ0JEOUM="
}
files = {
    "attach_files": open("/path/to/receipt.jpg", "rb")
}
 
response = requests.post(url, headers=headers, data=data, files=files)
result = response.json()

PHP


<?php
$url = "https://openapi.humansoft.co.th/api/v1/open-apis/petty-cash/add-item";
$headers = [
    "Ocp-Apim-Subscription-Key: YOUR_API_KEY"
];
$postFields = [
    "petty_cash_id" => "MjAyNTExMjdENDU3M0M0MjE2Mzk=",
    "petty_cash_item_name" => "ค่าที่พักโรงแรม",
    "req_amt" => "1200.00",
    "petty_cash_type_id" => "MjAyNjAzMDNBMUIyQzNENEU1RjY=",
    "authorize_id" => "MjAyNTAzMDM1MUIwQTJDQ0JEOUM=",
    "attach_files" => new CURLFile("/path/to/receipt.jpg")
];
 
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postFields);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 
$response = curl_exec($ch);
curl_close($ch);
 
$result = json_decode($response, true);
?>

Notes

เพิ่มรายการได้เฉพาะเอกสารที่มีสถานะ 01 (รออนุมัติ) เท่านั้น
รองรับไฟล์แนบเฉพาะรูปภาพ (JPG/JPEG, PNG, GIF, WEBP, HEIC/HEIF) ขนาดไม่เกิน 5MB ต่อไฟล์ ไฟล์ประเภทอื่น เช่น PDF จะถูกปฏิเสธ
ข้อความ message และข้อความเรื่องไฟล์แนบใน errors เป็นภาษาตาม parameter lang (ค่าเริ่มต้น TH) — API นี้ไม่ได้ใช้ language_code
การเพิ่มรายการอาจส่งแจ้งเตือนถึงผู้อนุมัติ หรือฝ่าย HR (เมื่อองค์กรตั้งค่าให้ฝ่ายบุคคลอนุมัติ หรือพนักงานไม่มีหัวหน้าในสายอนุมัติ) ตามการตั้งค่าการแจ้งเตือนเอกสารและสายอนุมัติขององค์กร

พารามิเตอร์ petty_cash_id, petty_cash_type_id และ authorize_id ต้องส่งเป็น Base64-encoded

Submit - สร้างเอกสารคำขอเบิกเงินสดย่อย
List Types - ดูรายการประเภทค่าใช้จ่าย
Delete Item - ลบรายการค่าใช้จ่าย
Get Detail - ดูรายละเอียดเอกสาร