Search Petty Cash List

API สำหรับ HR หรือหัวหน้างานเพื่อค้นหาและดึงรายการเอกสารคำขอเบิกเงินสดย่อยในระบบ รองรับการกรองข้อมูลอย่างละเอียดตามโครงสร้างองค์กร ช่วงวันที่ สถานะ และการแบ่งหน้า (Pagination) โดยผลลัพธ์จะจำกัดเฉพาะเอกสารที่ผู้ใช้ตาม authorize_id มีสิทธิ์เห็น

Endpoint


POST /api/v1/open-apis/petty-cash/get-list-search

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

Request Body

Required Parameters

Parameter	Type	Required	Description	Example
`req_year`	string	Yes	ปีที่ยื่นคำขอ (YYYY) — ต้องส่งเป็น string	`"2026"`
`approve_flag`	string	Yes	รหัสสถานะ หรือกลุ่มสถานะ (ดู Option Values) — ส่งเป็น string 2 หลัก	`"01"`
`authorize_id`	string	Yes	ID ของผู้ใช้ที่ทำการค้นหา (Base64) — ใช้กำหนดว่าเอกสารใดแสดงได้ (ดู Notes)	`"MjAyNTAzMDM1MUIwQTJDQ0JEOUM="`

Optional Parameters

Parameter	Type	Required	Description	Example
`authorize_line`	string	No	ส่งค่าที่ไม่ว่างและไม่ใช่ `"0"` (เช่น `"true"`) เพื่อดูเฉพาะเอกสารของพนักงานที่ผู้ใช้เป็นผู้อนุมัติตามสายบังคับบัญชา — ค่า `"false"` ก็ถือว่าส่ง หากไม่ต้องการให้ละ parameter นี้	`"true"`
`req_month`	string	No	เดือนที่ยื่นคำขอ (MM) — ต้องส่งเป็น string	`"03"`
`from_dt`	string	No	ค้นหาตั้งแต่วันที่ยื่น (YYYY-MM-DD) — ต้องส่งคู่กับ `to_dt`	`"2026-03-01"`
`to_dt`	string	No	ค้นหาถึงวันที่ยื่น (YYYY-MM-DD) — ต้องส่งคู่กับ `from_dt`	`"2026-03-31"`
`company_lists`	array	No	กรองตามบริษัท `[{ "id": "<Base64>" }]`	-
`branch_lists`	array	No	กรองตามสาขา `[{ "id": "<Base64>" }]`	-
`department_lists`	array	No	กรองตามแผนก `[{ "id": "<Base64>" }]`	`[{"id": "MjAyNTAxMTVCMkMzRDRFNUY2QTc="}]`
`division_lists`	array	No	กรองตามฝ่าย `[{ "id": "<Base64>" }]`	-
`section_lists`	array	No	กรองตามส่วน `[{ "id": "<Base64>" }]`	-
`section_lists_lv01` – `section_lists_lv05`	array	No	กรองตามส่วนย่อยระดับ 1–5 `[{ "id": "<Base64>" }]`	-
`position_lists`	array	No	กรองตามตำแหน่ง `[{ "id": "<Base64>" }]`	-
`employee_lists`	array	No	กรองเฉพาะเจาะจงรายพนักงาน `[{ "id": "<Base64>" }]`	`[{"id": "MjAyNjAzMDk0NjJGRUY2NUVGQ0E="}]`
`hashtags`	array	No	กรองพนักงานที่ hashtag มีคำใดคำหนึ่งในรายการ	`["ฝ่ายขาย"]`
`lang`	string	No	ภาษาของข้อความตอบกลับ ชื่อสถานะ และชื่อประเภทค่าใช้จ่าย: `TH` (ค่าเริ่มต้น) หรือ `EN`	`"EN"`
`_PAGE`	number	No	หน้าที่ต้องการดึง (default: 1)	`1`
`_NUMBER_PER_PAGE`	number	No	จำนวนรายการต่อหน้า (default: 10, สูงสุด 100)	`10`

Option Values: `approve_flag`

ค่า	ผลการกรอง
`01`	กลุ่มเอกสารที่ยังอยู่ระหว่างพิจารณา: สถานะ `01` (รออนุมัติ), `06` (ตรวจสอบอีกครั้ง) และ `07`–`11` (หัวหน้าอนุมัติแล้วบางขั้น รอขั้นถัดไป)
`02`–`12`	เฉพาะเอกสารที่มีสถานะ (`petty_cash_type_lv`) ตรงกับค่าที่ส่ง — ดูความหมายของแต่ละสถานะที่ Overview

Response Format

Success Response


{
  "code": 200,
  "message": "ค้นหาเอกสารเงินสดย่อยสำเร็จ",
  "payload": [
    {
      "petty_cash_id": "20251127D4573C421639",
      "employee_id": "20260309462FEF65EFCA",
      "employee_code": "EMP001",
      "employee_name": "สมชาย",
      "employee_last_name": "ใจดี",
      "request_topic": "เบิกค่าเดินทางไปพบลูกค้า",
      "req_dt": "2026-03-25",
      "department_name": "ฝ่ายไอที",
      "department_name_en": "IT Support",
      "req_amt": 1500,
      "petty_cash_type_lv": "01",
      "petty_cash_type_name": "รออนุมัติ",
      "send_doc": true,
      "item_count": 1,
      "item_list": [
        {
          "petty_cash_item_id": "20260325A1B2C3D4E5F6",
          "petty_cash_id": "20251127D4573C421639",
          "petty_cash_item_name": "ค่าที่พักโรงแรม",
          "petty_cash_type_id": "20260303A1B2C3D4E5F6",
          "petty_cash_type_name": "ค่าที่พัก",
          "req_amt": "1500.00",
          "attach_file": [
            "https://cdn.humansoft.co.th/.../files/a1B2c3D4e5F6.jpg"
          ],
          "created": "2026-03-25 10:15:00"
        }
      ]
    }
  ],
  "_PAGINATION": {
    "_TOTAL_RECORDS": 1,
    "_PAGE": 1,
    "_NUMBER_PER_PAGE": 10
  }
}

Response Fields

Field	Type	Nullable	Description
`petty_cash_id`	string	No	รหัสเอกสาร
`employee_id`	string	No	ID ของพนักงาน
`employee_code`	string	No	รหัสพนักงาน
`employee_name`	string	No	ชื่อพนักงาน (ไม่รวมนามสกุล)
`employee_last_name`	string	No	นามสกุลพนักงาน
`request_topic`	string	No	หัวข้อการเบิก
`req_dt`	string	No	วันที่ยื่นคำขอ (YYYY-MM-DD)
`department_name`	string	No	ชื่อแผนก (ภาษาไทย)
`department_name_en`	string	No	ชื่อแผนก (ภาษาอังกฤษ)
`req_amt`	number	No	ยอดเงินรวมของเอกสาร (ผลรวม `req_amt` ของทุกรายการ)
`petty_cash_type_lv`	string	No	รหัสสถานะเอกสาร
`petty_cash_type_name`	string	No	ชื่อสถานะตามภาษา `lang`
`send_doc`	boolean	No	`true` เมื่อผู้ใช้ตาม `authorize_id` ตั้งเบิกเอกสารนี้ได้ (เปลี่ยนสถานะเป็น `04` ผ่าน Update Status) ได้แก่ ผู้ใช้กลุ่มฝ่าย HR/เงินเดือนหรือผู้ดูแลระบบ (กรณีไม่ส่ง `authorize_line`) หรือผู้อนุมัติลำดับสุดท้ายของเอกสาร เฉพาะเมื่อองค์กรตั้งค่าให้หัวหน้าลำดับสุดท้ายเป็นผู้อนุมัติขั้นสุดท้าย — ไม่ได้พิจารณาสถานะเอกสาร
`item_count`	number	No	จำนวนรายการค่าใช้จ่ายในเอกสาร
`item_list`	array	No	รายการค่าใช้จ่าย — โครงสร้างเดียวกับ `item_list` ใน Get Detail
`_PAGINATION`	object	No	ข้อมูลการแบ่งหน้า: `_TOTAL_RECORDS` (จำนวนเอกสารทั้งหมดที่ผู้ใช้เห็นได้หลังกรอง), `_PAGE`, `_NUMBER_PER_PAGE`

Error Response

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


{
  "code": 422,
  "message": "การตรวจสอบข้อมูลล้มเหลว",
  "errors": ["'req_year' is required"]
}

ข้อความใน `errors`	สาเหตุ
`'<parameter>' is required`	ไม่ได้ส่ง parameter บังคับ (`req_year`, `approve_flag`, `authorize_id`) เช่น `'req_year' is required`
`'req_year' must be YYYY`	`req_year` ไม่ใช่ตัวเลข 4 หลัก
`'req_month' must be MM`	`req_month` ไม่ใช่ตัวเลข 2 หลัก

เกิดข้อผิดพลาดระหว่างค้นหา (400)


{
  "code": 400,
  "message": "ล้มเหลว",
  "error": "รายละเอียดข้อผิดพลาด"
}

HTTP Status	Description
`400`	เกิดข้อผิดพลาดระหว่างค้นหา
`403`	API Key ไม่มีสิทธิ์ `document:manage`
`422`	ข้อมูลไม่ผ่านการตรวจสอบ
`500`	ส่ง `req_year` หรือ `req_month` เป็นตัวเลขแทน string

Code Examples

cURL


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/petty-cash/get-list-search" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -d '{
    "req_year": "2026",
    "approve_flag": "01",
    "authorize_id": "MjAyNTAzMDM1MUIwQTJDQ0JEOUM=",
    "department_lists": [
      { "id": "MjAyNTAxMTVCMkMzRDRFNUY2QTc=" }
    ],
    "_PAGE": 1,
    "_NUMBER_PER_PAGE": 10
  }'

JavaScript


const response = await fetch(
  'https://openapi.humansoft.co.th/api/v1/open-apis/petty-cash/get-list-search',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      req_year: '2026',
      approve_flag: '01',
      authorize_id: 'MjAyNTAzMDM1MUIwQTJDQ0JEOUM=',
      department_lists: [
        { id: 'MjAyNTAxMTVCMkMzRDRFNUY2QTc=' }
      ],
      _PAGE: 1,
      _NUMBER_PER_PAGE: 10
    })
  }
)
const data = await response.json()

Python


import requests
 
url = "https://openapi.humansoft.co.th/api/v1/open-apis/petty-cash/get-list-search"
headers = {
    "Content-Type": "application/json",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
payload = {
    "req_year": "2026",
    "approve_flag": "01",
    "authorize_id": "MjAyNTAzMDM1MUIwQTJDQ0JEOUM=",
    "department_lists": [
        {"id": "MjAyNTAxMTVCMkMzRDRFNUY2QTc="}
    ],
    "_PAGE": 1,
    "_NUMBER_PER_PAGE": 10
}
 
response = requests.post(url, headers=headers, json=payload)
data = response.json()

PHP


<?php
$url = "https://openapi.humansoft.co.th/api/v1/open-apis/petty-cash/get-list-search";
$headers = [
    "Content-Type: application/json",
    "Ocp-Apim-Subscription-Key: YOUR_API_KEY"
];
$data = [
    "req_year" => "2026",
    "approve_flag" => "01",
    "authorize_id" => "MjAyNTAzMDM1MUIwQTJDQ0JEOUM=",
    "department_lists" => [
        ["id" => "MjAyNTAxMTVCMkMzRDRFNUY2QTc="]
    ],
    "_PAGE" => 1,
    "_NUMBER_PER_PAGE" => 10
];
 
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
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

ผู้ใช้ในกลุ่มผู้ใช้ฝ่าย HR/เงินเดือน เห็นเอกสารของพนักงานทั้งหมด หรือเฉพาะพนักงานในขอบเขตที่กำหนดให้ดูแล (หากมีการตั้งค่าไว้)
ผู้ใช้อื่นเห็นเอกสารของพนักงานที่ตนอยู่ในสายอนุมัติ ตามขั้นและสถานะของเอกสาร และการตั้งค่าการมองเห็นขององค์กร
เอกสารของผู้ใช้เองอาจไม่แสดงในผลค้นหา (ขึ้นกับกลุ่มผู้ใช้) — ใช้ Get List สำหรับเอกสารของตนเอง
เมื่อส่ง authorize_line ระบบใช้เฉพาะสิทธิ์ผู้อนุมัติตามสายบังคับบัญชา (ไม่ใช้สิทธิ์ HR/เงินเดือน) พิจารณาเอกสารสูงสุด 300 ฉบับที่ยื่นก่อนสุด และไม่รวมเอกสารที่ยังไม่มีรายการค่าใช้จ่าย
หาก authorize_id ไม่ได้ผูกกับข้อมูลพนักงาน โดยทั่วไปจะไม่พบเอกสาร

approve_flag = "01" จะรวมเอกสารที่ยังอยู่ระหว่างพิจารณาทุกระดับ (สถานะ 01, 06 และ 07–11)
from_dt/to_dt จะกรองก็ต่อเมื่อส่งครบทั้งคู่ และใช้ร่วมกับเงื่อนไข req_year/req_month เสมอ ช่วงวันที่จึงต้องอยู่ในปีที่ระบุ
ตัวกรองหน่วยงาน branch_lists, department_lists, division_lists, section_lists และ section_lists_lv01–section_lists_lv05 ใช้แบบตรงอย่างใดอย่างหนึ่ง (OR) แล้วจึงใช้ร่วมกับ company_lists, position_lists, employee_lists และ hashtags แบบต้องตรงทั้งหมด (AND)
ผลลัพธ์เรียงตามวันที่ยื่น (req_dt) จากเก่าไปใหม่ และแบ่งหน้าหลังจากกรองสิทธิ์แล้ว

authorize_id และ id ในตัวกรองแบบ array เช่น company_lists, department_lists, employee_lists ต้องส่งเป็น Base64-encoded ส่วน ID ใน response เป็นค่า raw

Get List - ดูรายการเอกสารของพนักงาน
Get Detail - ดูรายละเอียดเอกสาร
Approve - อนุมัติเอกสาร