NVAT Month Report (ภงด.3)

ดึงรายงานภาษีเงินได้หัก ณ ที่จ่าย ประจำเดือน (ภงด.3) ตามงวดเดือนที่ระบุ ผลลัพธ์จัดเรียงตามบริษัท สาขา แผนก และสามารถส่งออกได้หลายรูปแบบ ทั้ง JSON, Excel, PDF และ Text

Endpoint


POST /api/v1/open-apis/report/nvat-month?path_action=nvat_month

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

Request Parameters

Required Parameters

Parameter	Type	Required	Description	Example
`authorize_id`	string	Yes	รหัสผู้เรียก API	`"EMP001"`
`year_month`	string	Yes	งวดเดือนที่ขอรายงาน (YYYY-MM)	`"2026-03"`

Optional Parameters — Output/Export

Parameter	Type	Default	Description	Example
`type`	string	`json`	รูปแบบผลลัพธ์: `json`, `excel`, `pdf1`, `pdf2`, `pdf3`, `text1`	`"json"`
`filename`	string	-	ชื่อไฟล์ที่ส่งออก (ใช้กับ `excel`, `pdf`, `text`)	`"รายงานภาษี ณ ที่จ่าย 03-2026"`
`sign_date`	string	-	วันที่ลงนาม/ออกเอกสาร (YYYY-MM-DD) ใช้กับ `pdf3`	`"2026-03-31"`
`employee_group`	string	-	ใช้กรองใน `text1`	`"01"`

Optional Parameters — Filter

Parameter	Type	Description	Example
`company_lists`	array	กรองตามบริษัท (id เป็น base64)	`[{"id":"MjAyNTExMjdENDU3M0M0MjE2Mzk="}]`
`branch_lists`	array	กรองตามสาขา (id เป็น base64)	`[{"id":"MjAyNTExMjdENDU3M0M0MjE2Mzk="}]`
`employee_lists`	array	กรองพนักงานรายบุคคล (id เป็น base64)	`[{"id":"MjAyNTExMjdENDU3M0M0MjE2Mzk="}]`
`lists_flag`	string	`FULL` = กรองเฉพาะงวดเต็ม	`"FULL"`
`payment_method`	string	กรองตามวิธีการจ่ายเงิน	`"01"`
`employee_type_group`	array	กลุ่มประเภทพนักงาน (array ของ base64 string)	`["MjAyNTExMjdENDU3M0M0MjE2Mzk="]`
`employee_type_code`	array	รหัสประเภทพนักงาน (plain string)	`["01"]`

ทุก ID ใน company_lists, branch_lists, employee_lists ต้อง encode เป็น base64 ก่อนส่ง
employee_type_group เป็น array ของ base64 string โดยตรง (ไม่ใช่ array of object)

`branch_lists` — โหมดการกรองตามสาขา

จำนวนสาขา	พฤติกรรม
ไม่ระบุ / ว่างเปล่า	ใช้ `company_id` จากบริษัทที่ resolve ได้ — ไม่กรองตามสาขา
1 สาขา	ดึง `company_id` และ `branch_id` จริงจาก master สาขา (โหมดสาขาเดี่ยว)
มากกว่า 1 สาขา	ใช้ `company_id` ระดับบริษัท + `branchList` สำหรับ query multi-branch

`employee_type_group` + `employee_type_code` — Logic การกรอง 3 กรณี

กรณี	เงื่อนไข	ผลลัพธ์
กลุ่ม + รหัส	มีทั้งสองอย่าง	merge แถวจากกลุ่ม + ต่อด้วยแถวที่ตรง `employee_type_code`
รหัสอย่างเดียว	มีเฉพาะ `employee_type_code`	กรองเฉพาะแถวที่ตรง `employee_type_code`
กลุ่มอย่างเดียว	มีเฉพาะ `employee_type_group`	ดึง master employee ของงวดนั้น แล้วกรองตาม `employee_type_group_id`

`text1` — เงื่อนไข Filter เพิ่มเติม

เมื่อใช้ type = text1 ระบบจะกรองพนักงานที่:

summary_before_rate > 0 (มีเงินได้ก่อนหักภาษี)
AND reference_code_1 = employee_group (parameter ที่ส่งมา)

ค่า `type` — รูปแบบผลลัพธ์

ค่า	ความหมาย	MIME Type
`json`	ข้อมูลตาราง JSON	`application/json`
`excel`	ไฟล์ Excel รูปแบบ ภงด.3	`application/vnd.ms-excel`
`pdf1`	PDF แบบฟอร์ม ภงด.3 หน้า 1+2	`application/pdf`
`pdf2`	PDF ใบแนบ ภงด.3 (รายชื่อ)	`application/pdf`
`pdf3`	PDF 50ทวิ รายบุคคล (ใช้ร่วมกับ `sign_date`)	`application/pdf`
`text1`	ไฟล์ Text รูปแบบสรรพากร (ใช้ร่วมกับ `employee_group`)	`text/plain`

Example Request Body


{
  "authorize_id": "EMP001",
  "year_month": "2026-03",
  "type": "json",
  "branch_lists": [
    {"id": "MjAyNTExMjdENDU3M0M0MjE2Mzk="}
  ],
  "lists_flag": "FULL"
}

Response Format

Success Response (JSON type)


{
  "code": "200",
  "message": "Success",
  "payload": {
    "column": [
      "ลำดับ",
      "เลขประจำตัวประชาชน",
      "หนังสือเดินทาง/ใบอนุญาตทำงาน",
      "ชื่อ-นามสกุล",
      "วัน/เดือน/ปี",
      "เงินได้",
      "ภาษีที่หัก"
    ],
    "row": [
      [
        { "value": 1, "colspan": 1, "align": "center" },
        { "value": "1234567890123", "colspan": 1, "align": "center" },
        { "value": "", "colspan": 1, "align": "center" },
        { "value": "นายสมชาย ใจดี", "colspan": 1, "align": "left" },
        { "value": "31/03/2026", "colspan": 1, "align": "center" },
        { "value": "25,000.00", "colspan": 1, "align": "right" },
        { "value": "1,250.00", "colspan": 1, "align": "right" },
        {
          "value": "emp_id_here",
          "colspan": 1,
          "align": "center",
          "extra": {
            "employee_id": "emp_id_here",
            "tax_month_code": "03",
            "tax_year_code": "2026",
            "xtra_slip_lists": []
          }
        }
      ]
    ],
    "footer": [
      { "value": "รวม", "colspan": 5, "align": "center" },
      { "value": "25,000.00", "colspan": 1, "align": "right" },
      { "value": "1,250.00", "colspan": 1, "align": "right" }
    ]
  }
}

Response Fields

Field	Type	Description
`payload.column`	array<string>	ชื่อคอลัมน์ของตาราง
`payload.row`	array<array<Cell>>	แถวข้อมูลพนักงาน — Cell สุดท้ายมี `extra`
`payload.footer`	array<Cell>	แถวสรุปยอดรวม

`extra` Object (คอลัมน์สุดท้ายของแต่ละแถว)

Field	Type	Description
`employee_id`	string	รหัสพนักงาน (ใช้ส่งต่อไปยัง API อื่น)
`tax_month_code`	string	รหัสเดือนภาษี (MM)
`tax_year_code`	string	รหัสปีภาษี (YYYY)
`xtra_slip_lists`	array<string>	รายการ xtra slip ที่ผูกกับพนักงานในงวดนี้

Error Response

HTTP Status	Description
`400`	พารามิเตอร์ไม่ครบ / รูปแบบไม่ถูกต้อง / ไม่สามารถ resolve บริษัทได้
`401`	API Key ไม่ถูกต้องหรือไม่ได้ส่ง
`403`	ไม่มีสิทธิ์เรียก API นี้
`500`	เกิดข้อผิดพลาดที่เซิร์ฟเวอร์

หาก year_month ไม่มีข้อมูลงวดเงินเดือน ระบบจะ return payload ที่มี column และ footer แต่ row ว่างเปล่า โดยไม่ถือเป็น error

Code Examples

cURL


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

JavaScript


const response = await fetch(
  'https://openapi.humansoft.co.th/api/v1/open-apis/report/nvat-month?path_action=nvat_month',
  {
    method: 'POST',
    headers: {
      'Ocp-Apim-Subscription-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      authorize_id: 'EMP001',
      year_month: '2026-03',
      type: 'json'
    })
  }
)
const data = await response.json()
console.log(data.payload.row)

Python


import requests
 
url = "https://openapi.humansoft.co.th/api/v1/open-apis/report/nvat-month"
headers = {"Ocp-Apim-Subscription-Key": "YOUR_API_KEY"}
params = {"path_action": "nvat_month"}
payload = {
    "authorize_id": "EMP001",
    "year_month": "2026-03",
    "type": "json"
}
 
response = requests.post(url, headers=headers, params=params, json=payload)
data = response.json()
print(data["payload"]["row"])

PHP


<?php
$url = "https://openapi.humansoft.co.th/api/v1/open-apis/report/nvat-month?path_action=nvat_month";
$data = json_encode([
    "authorize_id" => "EMP001",
    "year_month" => "2026-03",
    "type" => "json"
]);
 
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Ocp-Apim-Subscription-Key: YOUR_API_KEY",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 
$response = curl_exec($ch);
curl_close($ch);
 
$result = json_decode($response, true);
print_r($result["payload"]["row"]);
?>

Delete Person Tax NVAT - ลบข้อมูลภาษี ณ ที่จ่ายรายบุคคลตามงวดเดือน