Petty Cash Report

ดึงรายงานการเบิกเงินสดย่อยของพนักงาน

ใช้ API นี้สำหรับเรียกรายงานรายการเบิกเงินสดย่อย กรองได้ตามช่วงปี/เดือน, ประเภทเงินสดย่อย, สถานะเอกสาร และโครงสร้างองค์กร เหมาะกับ Dashboard, รายงานรายเดือน หรือการตรวจสอบยอดเบิกของพนักงาน

Salary Masking: หากผู้เรียกไม่มีสิทธิ์ข้อมูลเงินเดือน ระบบจะ Mask ฟิลด์ request_amount และ total_amount ให้แสดงค่าเป็น null โดยอัตโนมัติ ระบบภายนอกไม่ต้องปิดบังยอดเงินเอง

Endpoint


POST /api/v1/open-apis/report/petty-cash

Authorization

ผู้เรียกต้องส่ง authorize_id และต้องมีสิทธิ์ document:manage จึงจะเรียกรายงานนี้ได้

Request Parameters

Required

Parameter	Type	Required	Description	Example
`authorize_id`	string	Yes	รหัสผู้เรียก API (Base64) ใช้สำหรับตรวจสิทธิ์และข้อมูลผู้ใช้งาน	`MjAyNjA0MzBVU0VSMDAwMDAx`
`search_year`	string (YYYY)	Yes	ปี ค.ศ. ที่ต้องการดึงข้อมูล	`2026`

หา authorize_id ได้อย่างไร: รับค่าจาก Get Employee Data Filter โดยใช้ path_action=get-user พร้อม employee_code ของผู้ทำรายการ — ใช้ค่า user_id ที่ได้กลับมาเป็น authorize_id

Output Parameters

Parameter	Type	Default	Description	Example
`search_month`	string (MM)	-	เดือนที่ต้องการดึงข้อมูล (`01`-`12`) — ไม่ระบุจะดึงทั้งปี	`05`
`type`	string	`json`	รูปแบบผลลัพธ์ — รองรับเฉพาะ `json`	`json`

Filter Parameters

Parameter	Type	Default	Description	Example
`search_status`	string	-	รหัสสถานะเอกสารเบิกเงินสดย่อย	`05`
`petty_cash_type_id`	string	-	รหัสประเภทเงินสดย่อย (Base64)	`MjAyNDExMjdENDU3M0M0MjE2Mzk=`
`company_lists`	array	`[]`	กรองตามบริษัท ใช้ object `{id: base64(company_id)}`	`[{"id":"Q09NUDAwMQ=="}]`
`branch_lists`	array	`[]`	กรองตามสาขา	`[{"id":"QlJBTkNIMDAx"}]`
`department_lists`	array	`[]`	กรองตามแผนก	`[{"id":"REVQMDAx"}]`
`division_lists`	array	`[]`	กรองตามฝ่าย	`[{"id":"RElWMDAx"}]`
`section_lists`	array	`[]`	กรองตามหน่วยงาน	`[{"id":"U0VDMDAx"}]`
`position_lists`	array	`[]`	กรองตามตำแหน่ง	`[{"id":"UE9TMDAx"}]`

Pagination & Language

Parameter	Type	Default	Description	Example
`_PAGE`	integer	`1`	หน้าที่ต้องการ (เริ่มที่ 1)	`1`
`_NUMBER_PER_PAGE`	integer	`10`	จำนวนรายการต่อหน้า (1-100)	`50`
`language_code`	string	`TH`	ภาษาของข้อมูลที่แปลได้ (`TH`, `EN`)	`TH`

โครงสร้าง List Parameters

*_lists ทุก parameter ใช้ array ของ object ที่มี id เป็น Base64 encoded:


[
  { "id": "Q09NUDAwMQ==" },
  { "id": "Q09NUDAwMg==" }
]

Validation Rules

กฎ	รายละเอียด
`authorize_id`	ต้องไม่ว่าง และต้องผ่านสิทธิ์ `document:manage`
`search_year`	ต้องตรงรูปแบบ `YYYY` (4 หลัก)
`search_month`	ถ้าระบุ ต้องเป็น `01`-`12`
`type`	ต้องเป็น `json` เท่านั้น
`_PAGE`	ต้องไม่ต่ำกว่า `1`
`_NUMBER_PER_PAGE`	ต้องอยู่ในช่วง `1`-`100`

Code Examples

cURL


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/report/petty-cash" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "authorize_id": "MjAyNjA0MzBVU0VSMDAwMDAx",
    "search_year": "2026",
    "search_month": "05",
    "_PAGE": 1,
    "_NUMBER_PER_PAGE": 10
  }'

JavaScript


const url = 'https://openapi.humansoft.co.th/api/v1/open-apis/report/petty-cash'
 
const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    authorize_id: 'MjAyNjA0MzBVU0VSMDAwMDAx',
    search_year: '2026',
    search_month: '05',
    _PAGE: 1,
    _NUMBER_PER_PAGE: 10
  })
})
 
const data = await response.json()
data.payload.forEach(r => {
  console.log(`${r.employee_code} - ${r.request_topic} - ${r.total_amount}`)
})
console.log(`Total: ${data._PAGINATION._TOTAL_RECORDS}`)

Python


import requests
 
url = "https://openapi.humansoft.co.th/api/v1/open-apis/report/petty-cash"
headers = {
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "authorize_id": "MjAyNjA0MzBVU0VSMDAwMDAx",
    "search_year": "2026",
    "search_month": "05",
    "_PAGE": 1,
    "_NUMBER_PER_PAGE": 10
}
 
response = requests.post(url, headers=headers, json=payload)
data = response.json()
 
for r in data["payload"]:
    print(f"{r['employee_code']} - {r['request_topic']} - {r['total_amount']}")
print(f"Total: {data['_PAGINATION']['_TOTAL_RECORDS']}")

PHP


<?php
$url = "https://openapi.humansoft.co.th/api/v1/open-apis/report/petty-cash";
 
$payload = [
    "authorize_id" => "MjAyNjA0MzBVU0VSMDAwMDAx",
    "search_year" => "2026",
    "search_month" => "05",
    "_PAGE" => 1,
    "_NUMBER_PER_PAGE" => 10
];
 
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Ocp-Apim-Subscription-Key: YOUR_API_KEY",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
 
$response = curl_exec($ch);
$data = json_decode($response, true);
 
foreach ($data["payload"] as $r) {
    echo "{$r['employee_code']} - {$r['request_topic']} - {$r['total_amount']}\n";
}
echo "Total: {$data['_PAGINATION']['_TOTAL_RECORDS']}\n";
 
curl_close($ch);
?>

Response Format

Success Response (HTTP 200)


{
  "code": 200,
  "message": "Success",
  "payload": [
    {
      "employee_code": "EMP001",
      "employee_name": "สมชาย ใจดี (ชาย)",
      "department_name": "ฝ่ายไอที",
      "position_name": "Software Engineer",
      "request_topic": "เบิกค่าเดินทางไปพบลูกค้า",
      "petty_cash_type": "ค่าเดินทาง",
      "spending_name": "ค่าน้ำมันรถยนต์",
      "request_amount": 1500.00,
      "total_amount": 1500.00,
      "request_date": "2026-05-15",
      "approve_date": "2026-05-16",
      "paid_date": "2026-05-18",
      "received_date": "2026-05-18",
      "status": "ได้รับเงินแล้ว",
      "remark": "อนุมัติจ่ายค่าน้ำมัน",
      "payment_method": "จ่ายนอกเงินเดือน"
    }
  ],
  "_PAGINATION": {
    "_TOTAL_RECORDS": 1,
    "_PAGE": 1,
    "_NUMBER_PER_PAGE": 10
  }
}

Response Fields

Field	Type	Description
`employee_code`	string	รหัสพนักงาน
`employee_name`	string	ชื่อ-นามสกุล (ชื่อเล่น) ตาม `language_code`
`department_name`	string	ชื่อแผนกของพนักงาน
`position_name`	string	ชื่อตำแหน่งงาน
`request_topic`	string	หัวข้อ/จุดประสงค์ในการขอเบิก
`petty_cash_type`	string	ประเภทของวงเงินสดย่อย เช่น ค่าเดินทาง, ค่าอุปกรณ์
`spending_name`	string	ชื่อของรายการใช้จ่ายย่อย
`request_amount`	number	จำนวนเงินของรายการย่อย (`null` หากผู้เรียกไม่มีสิทธิ์เงินเดือน)
`total_amount`	number	จำนวนเงินรวมของเอกสารเบิกใบนั้น (`null` หากไม่มีสิทธิ์เงินเดือน)
`request_date`	string (YYYY-MM-DD)	วันที่ยื่นคำขอเบิกเงิน
`approve_date`	string (YYYY-MM-DD)	วันที่เอกสารได้รับการอนุมัติ
`paid_date`	string (YYYY-MM-DD)	วันที่ทำการจ่ายเงินจริง
`received_date`	string (YYYY-MM-DD)	วันที่พนักงานได้รับเงิน
`status`	string	สถานะของเอกสาร เช่น รออนุมัติ, อนุมัติแล้ว, ได้รับเงินแล้ว
`remark`	string	หมายเหตุ ความเห็น หรือเหตุผลการปฏิเสธ/อนุมัติ
`payment_method`	string	ช่องทางการจ่ายเงิน เช่น จ่ายนอกเงินเดือน, จ่ายในระบบคำนวณ

Pagination Fields

Field	Type	Description
`_PAGINATION._TOTAL_RECORDS`	integer	จำนวนรายการทั้งหมดหลังกรอง
`_PAGINATION._PAGE`	integer	หน้าปัจจุบัน
`_PAGINATION._NUMBER_PER_PAGE`	integer	จำนวนรายการต่อหน้า

Error Responses

Validation Error (HTTP 400)


{
  "code": 400,
  "message": "Validation failed",
  "errors": [
    "'type' must be one of: json"
  ]
}

Permission Denied (HTTP 403)


{
  "code": 403,
  "message": "Permission denied",
  "errors": ["User does not have 'document:manage' permission"]
}

Status Codes

Code	ความหมาย
`200`	สำเร็จ
`400`	Validation ไม่ผ่าน เช่น parameter หาย, format ผิด, `type` ไม่อยู่ใน allowlist
`403`	ไม่มีสิทธิ์ `document:manage` หรือ API key ไม่ถูกต้อง
`500`	เกิด error ระหว่างประมวลผลบนเซิร์ฟเวอร์

Notes & Best Practices

API นี้รองรับเฉพาะ type: json เท่านั้น ไม่รองรับ Excel หรือ PDF เพื่อประสิทธิภาพการประมวลผลและการรักษาความปลอดภัยระดับเงินเดือน
Salary Masking ทำที่ฝั่ง Server-side ผ่านสิทธิ์ส่วนบุคคล — ระบบภายนอกไม่ต้องปิดบังยอดเงินเอง
ID ใน *_lists ต้องเข้ารหัส Base64 และใช้รูปแบบ {id: "..."}
ถ้าไม่ระบุ search_month ระบบจะดึงข้อมูลสรุปของทั้งปี

Resigned Employee Report - รายงานพนักงานลาออก
Submit Petty Cash Request - ยื่นเอกสารเบิกเงินสดย่อย
Get Petty Cash Detail - ดูรายละเอียดเอกสารใบเดียว