Net Total Split Month Report

ดึงรายงานผลการคำนวณเงินเดือนสุทธิแบบแบ่งงวดจ่ายตาม master_salary_split_seq ที่ระบุ รองรับ JSON, Excel และ PDF

ใช้ API นี้สำหรับเรียกรายงานเงินเดือนสุทธิของงวดจ่ายย่อยภายในเดือนเดียวกัน เช่น งวดที่ 1 หรือ งวดที่ 2 ระบบจะดึงงวดเงินเดือนหลักจาก year_month และดึงงวดจ่ายย่อยจาก year_month + master_salary_split_seq เพื่อเตรียมยอดรายรับ รายจ่าย เบิกล่วงหน้า และยอดสุทธิของพนักงานในงวดจ่ายนั้น

Endpoint


POST /api/v1/open-apis/report/net-total-split-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`
`master_salary_split_seq`	string / integer	Yes	ลำดับงวดจ่ายย่อยของเดือนนั้น	`1`

Output / Export Parameters

Parameter	Type	Default	Description	Example
`type`	string	`json`	รูปแบบผลลัพธ์ (ดูค่าที่อนุญาตด้านล่าง)	`json`
`filename`	string	ชื่อรายงานตามงวด	ชื่อไฟล์สำหรับ export PDF/Excel (ไม่ต้องใส่นามสกุล)	`net_salary_split_2026_03_1`
`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	`""`	กรองตามวิธีจ่ายเงินของ split 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 รายงาน split หลัก	`application/vnd.ms-excel`
`excel2`	Excel split รูปแบบย่อย	`application/vnd.ms-excel`
`pdf`	PDF รายงาน split หลัก	`application/pdf`
`pdf2`	PDF split รูปแบบย่อย 2	`application/pdf`
`pdf3`	PDF split รูปแบบย่อย 3	`application/pdf`

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


json, excel, excel2, pdf, pdf2, pdf3

`master_salary_split_seq`

ใช้ระบุรอบแบ่งจ่ายของ year_month นั้น:

ค่า	ความหมาย
`1`	งวดจ่ายย่อยที่ 1
`2`	งวดจ่ายย่อยที่ 2
`3` ขึ้นไป	รองรับตามจำนวน split round ที่ตั้งค่าในงวดเงินเดือนหลัก

ถ้าไม่พบงวดจ่ายย่อยของ year_month และ master_salary_split_seq ที่ส่งมา ระบบจะตอบ 406

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

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

`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	ทั้งสองค่าไม่ว่าง	merge group เข้ารายการ split slip แล้วเก็บรายการที่ตรง group หรือ code
ส่งเฉพาะ code	group ว่าง / code ไม่ว่าง	กรองจาก field `employee_type_code` ใน split slip
ส่งเฉพาะ group	group ไม่ว่าง / code ว่าง	merge group แล้วกรองตาม `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`
`master_salary_split_seq`	ต้องไม่ว่าง และต้องพบ split report ของงวดนั้น
`type`	ถ้าไม่ส่งจะ default เป็น `json`; ถ้าส่งต้องอยู่ใน allowlist
`master split payroll`	ต้องพบงวดจ่ายย่อย; ถ้าไม่พบตอบ `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-split-month" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "authorize_id": "EMP001",
    "year_month": "2026-03",
    "master_salary_split_seq": "1",
    "type": "json"
  }'

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


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

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


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

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


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

Excel


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

PDF


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

Response Format

Response Structure ตามประเภท

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

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",
                    10,
                    15,
                    15000,
                    "... amount columns ..."
                  ]
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Response Fields

Field	Type	Description
`payload.column`	`array<string>`	รายชื่อ column ของรายงาน split สร้างจาก 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	เงินเดือนหรือเงินเดือนตามงวด split
Income config	รายรับจาก config เช่น OT, เบี้ยขยัน, รายได้อื่น
Dynamic income	รายรับตาม salary type ของงวด split
Total income	รายรับรวม
Expense config	รายจ่ายจาก config เช่น มาสาย, ขาดงาน, หักอื่น
Dynamic expense	รายจ่ายตาม salary type ของงวด split
Total expense	รายจ่ายรวม
Net	ยอดรวม, เบิกล่วงหน้า, คงเหลือ

Error Response

Validation Error (HTTP 400)


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

Invalid Type (HTTP 400)


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

No Master Split 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` + `master_salary_split_seq`
`413`	จำนวนพนักงานเกิน `count_of_employee_limit`
`500`	เกิด error ระหว่างสร้างรายงาน

Notes & Best Practices

ใช้ json ก่อน export เพื่อยืนยันว่าพบงวด split และยอดเงินถูกต้อง
master_salary_split_seq ต้องตรงกับรอบแบ่งจ่ายที่ระบบ payroll สร้างไว้จริง
ใช้ employee_lists เมื่อต้องตรวจพนักงานเฉพาะราย จะช่วยลดจำนวนข้อมูลและเวลา query
employee_type_group ต้อง encode เป็น base64 ก่อนส่ง ส่วน employee_type_code ไม่ต้อง encode
ถ้าต้องการเฉพาะพนักงานงวดเต็ม ให้ใช้ lists_flag = FULL
รายงาน split มี logic เบิกล่วงหน้าต่างจากรายงานปกติ เพราะต้องอิงช่วงวันที่ของงวดจ่ายย่อย
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`
split หลายงวดในเดือนเดียวกัน	ระบุ `master_salary_split_seq` ให้ชัดเจนทุกครั้ง
filter แล้วไม่มีพนักงาน	ผลลัพธ์ JSON จะมี `row` ว่าง ควรตรวจ payload ก่อนใช้งานต่อ

Net Total Month - รายงานเงินเดือนสุทธิประจำเดือนหลัก
Tax Month - รายงานภาษีรายเดือน ภงด.1