Net Total Month Report

ดึงรายงานผลการคำนวณเงินเดือนสุทธิประจำเดือนจากงวดเงินเดือนหลัก รองรับ JSON, Excel, PDF และ Text

ใช้ API นี้สำหรับเรียกรายงานเงินเดือนสุทธิของพนักงานตาม year_month ที่ระบุ เหมาะสำหรับแสดงผลรายงานบนระบบ ส่งออก Excel/PDF/Text หรือใช้ตรวจสอบยอดรายรับ รายจ่าย เงินเบิกล่วงหน้า และยอดสุทธิหลังคำนวณเงินเดือนประจำเดือน

Endpoint


POST /api/v1/open-apis/report/net-total-month

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

Authorization

ผู้เรียกต้องส่ง authorize_id จึงจะเรียกรายงานนี้ได้

Request Parameters

Required

Parameter	Type	Required	Description	Example
`authorize_id`	string	Yes	รหัสผู้เรียก API ใช้สำหรับตรวจสิทธิ์และข้อมูลผู้ใช้งาน	`EMP001`
`year_month`	string (YYYY-MM)	Yes	งวดเดือนเงินเดือนที่ต้องการดึงรายงาน	`2026-03`

Output / Export Parameters

Parameter	Type	Default	Description	Example
`type`	string	`json`	รูปแบบผลลัพธ์ (ดูค่าที่อนุญาตด้านล่าง)	`json`
`filename`	string	ชื่อรายงานตามงวด	ชื่อไฟล์สำหรับ export PDF/Excel/Text (ไม่ต้องใส่นามสกุล)	`net_salary_2026_03`
`skip_queue`	string	`Y`	ใช้กับ report export เพื่อส่งออกทันที	`Y`

Filter & Scope Parameters

Parameter	Type	Default	Description	Example
`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"}]`
`section_lists_lv01`	array	`[]`	กรองตามหน่วยงานย่อยระดับ 1	`[{"id":"U0VDTFYwMQ=="}]`
`section_lists_lv02`	array	`[]`	กรองตามหน่วยงานย่อยระดับ 2	`[{"id":"U0VDTFYwMg=="}]`
`section_lists_lv03`	array	`[]`	กรองตามหน่วยงานย่อยระดับ 3	`[{"id":"U0VDTFYwMw=="}]`
`section_lists_lv04`	array	`[]`	กรองตามหน่วยงานย่อยระดับ 4	`[{"id":"U0VDTFYwNA=="}]`
`section_lists_lv05`	array	`[]`	กรองตามหน่วยงานย่อยระดับ 5	`[{"id":"U0VDTFYwNQ=="}]`
`employee_lists`	array	`[]`	กรองพนักงานรายบุคคล	`[{"id":"RU1QMDAx"}]`
`employee_type`	array	`[]`	กรองตามรอบคำนวณเงินเดือน เช่น `Full`	`["Full"]`
`employee_type_group`	array	`[]`	กลุ่มประเภทพนักงาน (array ของ base64 string)	`["R1JPVVAxMDE="]`
`employee_type_code`	array	`[]`	รหัสประเภทพนักงาน (plain string)	`["01"]`
`lists_flag`	string	`""`	ถ้าเป็น `FULL` จะกรองเฉพาะพนักงานงวดเต็ม	`FULL`
`payment_method`	string	`""`	กรองตามวิธีจ่ายเงินของ slip	`01`

Limit & Performance Parameters

Parameter	Type	Default	Description	Example
`check_count_of_employee`	boolean / string	`true`	เปิด/ปิดการตรวจจำนวนพนักงานก่อนสร้างรายงาน รองรับ `true`, `false`, `1`, `0`, `Y`, `N`	`true`
`count_of_employee_limit`	integer	`2000`	จำนวนพนักงานสูงสุดที่อนุญาตก่อนตอบ `413 Payload Too Large`	`2000`

โครงสร้าง List Parameters

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


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

employee_type_group ใช้ array ของ base64 string:


["R1JPVVAxMDE=", "R1JPVVAxMDI="]

employee_type_code และ employee_type ใช้ array ของ string ปกติ:


{
  "employee_type_code": ["01", "02"],
  "employee_type": ["Full"]
}

Output Types

`type` — ค่าที่อนุญาต

ค่า	คำอธิบาย	MIME
`json`	JSON ตารางรายงาน	`application/json`
`excel`	Excel รายงานหลัก	`application/vnd.ms-excel`
`excel1` – `excel6`	Excel รูปแบบย่อย 1–6	`application/vnd.ms-excel`
`pdf`	PDF รายงานหลัก	`application/pdf`
`pdf2` – `pdf7`	PDF รูปแบบย่อย 2–7	`application/pdf`
`text`	Text export	`text/plain`

ค่าที่อนุญาตทั้งหมด:


json, excel, excel1, excel2, excel3, excel4, excel5, excel6,
pdf, pdf2, pdf3, pdf4, pdf5, pdf6, pdf7, text

`filename` — ชื่อไฟล์ export

ใช้กับ excel*, pdf*, text
ส่งเป็นชื่อไฟล์โดยไม่ต้องใส่นามสกุล
ถ้าไม่ส่ง ระบบจะใช้ชื่อรายงานตามงวดเดือน

`lists_flag`

ค่า	ผลลัพธ์
`FULL`	แสดงเฉพาะพนักงานที่ `round_month_config = Full`
`""` หรือไม่ส่ง	ไม่กรองด้วย `round_month_config` เพิ่ม

`check_count_of_employee`

ค่า input	ผลลัพธ์
`true`, `"true"`, `"1"`, `"Y"`, `"y"`	เปิดตรวจ limit
`false`, `"false"`, `"0"`, `"N"`, `"n"`	ปิดตรวจ limit
ไม่ส่งค่า	ใช้ default `true`

`employee_type_group` + `employee_type_code`

กรณี	เงื่อนไข	ผลลัพธ์
ส่งทั้ง group และ code	ทั้งสองค่าไม่ว่าง	รวมรายการที่ตรง group และที่ตรง `employee_type_code`
ส่งเฉพาะ code	group ว่าง / code ไม่ว่าง	กรองจาก field `employee_type_code` ใน slip
ส่งเฉพาะ group	group ไม่ว่าง / code ว่าง	กรองตาม `employee_type_group_id`
ไม่ส่งทั้งสองค่า	ทั้งสองค่าเป็น array ว่าง	ไม่กรองประเภทพนักงานเพิ่มเติม

employee_type_group ต้องส่งเป็น base64 string ส่วน employee_type_code ส่งเป็น plain string

Validation Rules

กฎ	รายละเอียด
`authorize_id`	ต้องไม่ว่าง และต้องผ่านสิทธิ์ `document:manage`
`year_month`	ต้องตรงรูปแบบ `YYYY-MM` และเดือนต้องอยู่ในช่วง `01` ถึง `12`
`type`	ถ้าไม่ส่งจะ default เป็น `json`; ถ้าส่งต้องอยู่ใน allowlist
`master payroll`	ต้องพบงวดเงินเดือนของ `year_month`; ถ้าไม่พบตอบ `406`
`employee limit`	ถ้าเปิด `check_count_of_employee` และจำนวนพนักงานเกิน `count_of_employee_limit` จะตอบ `413`
`*_lists`	ต้องเป็น array; ถ้าไม่ส่ง ระบบ normalize เป็น array ว่าง

Code Examples

ตัวอย่างพื้นฐาน (JSON)


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/report/net-total-month" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "authorize_id": "EMP001",
    "year_month": "2026-03",
    "type": "json"
  }'

กรองบริษัท/สาขา


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/report/net-total-month" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "authorize_id": "EMP001",
    "year_month": "2026-03",
    "type": "json",
    "company_lists": [{"id": "Q09NUDAwMQ=="}],
    "branch_lists": [{"id": "QlJBTkNIMDAx"}],
    "department_lists": [{"id": "REVQMDAx"}],
    "payment_method": "01"
  }'

งวดเต็ม + ประเภทพนักงาน


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/report/net-total-month" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "authorize_id": "EMP001",
    "year_month": "2026-03",
    "type": "json",
    "lists_flag": "FULL",
    "employee_type_group": ["R1JPVVAxMDE="],
    "employee_type_code": ["01"]
  }'

พนักงานรายบุคคล


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/report/net-total-month" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "authorize_id": "EMP001",
    "year_month": "2026-03",
    "type": "json",
    "employee_lists": [{"id": "RU1QMDAx"}]
  }'

Excel


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/report/net-total-month" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "authorize_id": "EMP001",
    "year_month": "2026-03",
    "type": "excel",
    "filename": "net_salary_2026_03"
  }' \
  --output net_salary_2026_03.xlsx

PDF


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/report/net-total-month" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "authorize_id": "EMP001",
    "year_month": "2026-03",
    "type": "pdf",
    "filename": "net_salary_2026_03",
    "check_count_of_employee": false
  }' \
  --output net_salary_2026_03.pdf

Text


curl -X POST "https://openapi.humansoft.co.th/api/v1/open-apis/report/net-total-month" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "authorize_id": "EMP001",
    "year_month": "2026-03",
    "type": "text",
    "filename": "net_salary_2026_03"
  }' \
  --output net_salary_2026_03.txt

Response Format

Response Structure ตามประเภท

`type`	Response
`json`	JSON object ที่มี `payload.column` และ `payload.row`
`excel*`	Binary/download stream จาก template Excel
`pdf*`	Binary/download stream จาก template PDF
`text`	Text/download stream จาก template text

Success Response — `type: json`


{
  "code": 200,
  "message": "Success",
  "payload": {
    "column": [
      "รหัสพนักงาน",
      "ชื่อพนักงาน",
      "มาทำงาน",
      "วันทำงาน",
      "อัตราเงินเดือน",
      "เงินเดือน",
      "... dynamic income/expense columns ..."
    ],
    "row": [
      {
        "id": "COMPANY_ID",
        "code": "COMPANY_CODE",
        "name": "Company Name",
        "child": [
          {
            "id": "BRANCH_ID",
            "code": "BRANCH_CODE",
            "name": "Branch Name",
            "child": [
              {
                "id": "DEPARTMENT_OR_SECTION_ID",
                "code": "ORG_CODE",
                "name": "Org Name",
                "structure": "REP_DEPARTMENT",
                "child": [
                  [
                    "EMP001",
                    "Employee Name",
                    22,
                    30,
                    30000,
                    30000,
                    "... amount columns ..."
                  ]
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Response Fields

Field	Type	Description
`payload.column`	`array<string>`	รายชื่อ column ของรายงาน สร้างจาก config, salary type และ field มาตรฐาน
`payload.row`	`array<object>`	รายการข้อมูลแบบ tree เรียงตามบริษัท สาขา และ node องค์กร
`row[].child[]`	`array<object>`	node ย่อย เช่น branch, department, division, section หรือ section_lv
`structure`	string	รหัสโครงสร้าง เช่น `REP_DEPARTMENT`, `REP_DIVISION`, `REP_SECTION`, `REP_SECTION_LV01`
employee row	`array`	ค่าแต่ละ column ของพนักงานตามลำดับใน `payload.column`

Column สำคัญใน JSON

กลุ่ม column	รายละเอียด
Employee	รหัสพนักงาน, ชื่อพนักงาน
Work	มาทำงาน, วันทำงาน
Salary	อัตราเงินเดือน, เงินเดือน
Income config	รายรับจาก config เช่น OT, เบี้ยขยัน, รายได้อื่น
Dynamic income	รายรับตาม salary type ของงวด
Total income	รายรับรวม
Expense config	รายจ่ายจาก config เช่น มาสาย, ขาดงาน, หักอื่น
Dynamic expense	รายจ่ายตาม salary type ของงวด
Total expense	รายจ่ายรวม
Net	ยอดรวม, เบิกล่วงหน้า, คงเหลือ

Error Response

Validation Error (HTTP 400)


{
  "code": 400,
  "message": "Validation failed",
  "errors": [
    "Missing required parameter: 'year_month'"
  ]
}

Invalid Type (HTTP 400)


{
  "code": 400,
  "message": "Validation failed",
  "errors": [
    "'type' must be one of: json, excel, excel1, excel2, excel3, excel4, excel5, excel6, pdf, pdf2, pdf3, pdf4, pdf5, pdf6, pdf7, text"
  ]
}

No Master Payroll (HTTP 406)


{
  "code": "406",
  "payload": "Error: no master salary report id"
}

Employee Over Limit (HTTP 413)


{
  "code": "413",
  "payload": "Payload Too Large"
}

Server Error (HTTP 500)


{
  "code": "500",
  "payload": "undefined",
  "message": "error message"
}

Status Codes

Code	ความหมาย
`200`	สำเร็จ
`400`	validation ไม่ผ่าน เช่น parameter หาย, format ผิด, type ไม่อยู่ใน allowlist
`403`	ไม่มีสิทธิ์ `document:manage` หรือ API key ไม่ผ่าน
`406`	ไม่พบงวดเงินเดือนของ `year_month` ที่ระบุ
`413`	จำนวนพนักงานเกิน `count_of_employee_limit`
`500`	เกิด error ระหว่างสร้างรายงาน

Notes & Best Practices

ใช้ json ในการตรวจสอบข้อมูลก่อน export เป็น excel หรือ pdf
หากต้อง export รายงานขนาดใหญ่ ควรกำหนด count_of_employee_limit ให้เหมาะกับระบบปลายทาง
ใช้ employee_lists เมื่อต้องการตรวจรายบุคคล จะช่วยลดจำนวนข้อมูลและเวลา query
employee_type_group ต้อง encode เป็น base64 ก่อนส่ง ส่วน employee_type_code ไม่ต้อง encode
ถ้าต้องการเฉพาะพนักงานงวดเต็ม ให้ใช้ lists_flag = FULL
column บางส่วนเป็น dynamic ตาม config และ salary type ของงวดเงินเดือน

Performance Considerations

กรณี	คำแนะนำ
พนักงานจำนวนมาก	เปิด `check_count_of_employee` และกำหนด limit ให้เหมาะสม
ต้องการแค่บางส่วนขององค์กร	ส่ง `company_lists`, `branch_lists`, `department_lists` หรือ `employee_lists`
ต้องตรวจผลลัพธ์ก่อน export	เรียก `type=json` ก่อน แล้วค่อยเรียก `excel`/`pdf`
filter แล้วไม่มีพนักงาน	ผลลัพธ์ JSON จะมี `row` ว่าง ควรตรวจ payload ก่อนใช้งานต่อ

Net Total Split Month - รายงานเงินเดือนสุทธิแบบแบ่งงวดจ่าย
Tax Month - รายงานภาษีรายเดือน ภงด.1