Payroll Events

Events ที่เกี่ยวข้องกับการจัดการงวดเงินเดือนและการคำนวณเงินเดือนพนักงาน

เปิดงวด / ปิดงวดเงินเดือน (Payroll Period)

การเปิดและปิดงวดเงินเดือนจะส่งผลให้ระบบส่ง Event แจ้งเตือนสถานะของงวดเงินเดือนนั้นๆ ทั้งแบบงวดปกติ (เดือนละครั้ง) และแบบแบ่งงวด (จ่ายหลายครั้งในหนึ่งเดือน)

payroll.month.unfinished

เกิดขึ้นเมื่อมีการปลดล็อคหรือเปิดงวดเงินเดือนเพื่อเริ่มการคำนวณเงินเดือน หรือแก้ไขข้อมูลใหม่

ตัวอย่าง Payload:


{
  "request_id": "req_py12345678",
  "event": "payroll.month.unfinished",
  "event_occurred_at": "2025-01-25 09:00:00",
  "body": {
    "master_salary_report_id": "REP2501001",
    "master_salary_month": "2025-01",
    "salary_report_start_dt": "2025-01-01",
    "salary_report_end_dt": "2025-01-31",
    "read_only_flag": "N",
    "publish_flag": "N",
    "total_employees": 150,
    "status": "unfinished",
    "unfinished_at": "2025-01-25 09:00:00"
  }
}

payroll.month.finished

เกิดขึ้นเมื่อยืนยันการคำนวณเงินเดือนเสร็จสิ้นและล็อคข้อมูลงวด

ตัวอย่าง Payload:


{
  "request_id": "req_py12345679",
  "event": "payroll.month.finished",
  "event_occurred_at": "2025-01-28 17:00:00",
  "body": {
    "master_salary_report_id": "REP2501001",
    "master_salary_month": "2025-01",
    "salary_report_start_dt": "2025-01-01",
    "salary_report_end_dt": "2025-01-31",
    "read_only_flag": "Y",
    "publish_flag": "Y",
    "total_employees": 150,
    "status": "finished",
    "finished_at": "2025-01-28 17:00:00"
  }
}

payroll.split_month.unfinished

เกิดขึ้นเมื่อเปิดงวดเงินเดือนย่อย สำหรับบริษัทที่จ่ายเงินเดือนหลายครั้งใน 1 เดือน

ตัวอย่าง Payload:


{
  "request_id": "req_py12345680",
  "event": "payroll.split_month.unfinished",
  "event_occurred_at": "2025-01-10 09:00:00",
  "body": {
    "master_salary_split_report_id": "SREP2501001-1",
    "master_salary_report_id": "REP2501001",
    "master_salary_month": "2025-01",
    "master_salary_split_seq": 1,
    "read_only_flag": "N",
    "publish_flag": "N",
    "total_employees": 150,
    "status": "unfinished",
    "unfinished_at": "2025-01-10 09:00:00"
  }
}

payroll.split_month.finished

เกิดขึ้นเมื่อปิดงวดเงินเดือนย่อย

ตัวอย่าง Payload:


{
  "request_id": "req_py12345681",
  "event": "payroll.split_month.finished",
  "event_occurred_at": "2025-01-14 17:00:00",
  "body": {
    "master_salary_split_report_id": "SREP2501001-1",
    "master_salary_report_id": "REP2501001",
    "master_salary_month": "2025-01",
    "master_salary_split_seq": 1,
    "read_only_flag": "Y",
    "publish_flag": "Y",
    "total_employees": 150,
    "status": "finished",
    "finished_at": "2025-01-14 17:00:00"
  }
}

การคำนวณเงินเดือนพนักงาน (Employee Payroll Calculation)

payroll.employee.calculated

เกิดขึ้นเมื่อการคำนวณเงินเดือนของพนักงานคนนั้นๆ เสร็จสิ้นสมบูรณ์

ตัวอย่าง Payload:


{
  "request_id": "req_py12345682",
  "event": "payroll.employee.calculated",
  "event_occurred_at": "2025-01-26 23:45:10",
  "body": {
    "master_salary_report_id": "REP2501001",
    "master_salary_month": "2025-01",
    "employee_id": "20250101ABCD1234",
    "employee_code": "EMP001",
    "employee_title_lv": "1",
    "employee_title_name": "นาย",
    "employee_name": "สมชาย",
    "employee_last_name": "ใจดี",
    "employee_type_code": "01",
    "company_code": "COM001",
    "company_name": "บริษัท เอบีซี จำกัด",
    "company_name_en": "ABC Co., Ltd.",
    "branch_code": "BR001",
    "branch_name": "สำนักงานใหญ่",
    "department_code": "DEP001",
    "department_name": "ฝ่ายไอที",
    "position_code": "POS001",
    "position_name": "โปรแกรมเมอร์",
    "salary_amt": 30000.00,
    "sum_income": 5000.00,
    "sum_expense": 0.00,
    "total_income": 35000.00,
    "total_expense": 1250.00,
    "total_salary": 33750.00,
    "work_day": 22.00,
    "work_day_total": 22.00,
    "tax_amt": 500.00,
    "sso_amt": 750.00,
    "status": "success",
    "calculate_to": "NOW",
    "is_split": false,
    "split_seq": null,
    "master_salary_split_report_id": ""
  }
}

payroll.employee.calculate_failed

เกิดขึ้นเมื่อการคำนวณเงินเดือนของพนักงาน ล้มเหลว จากสาเหตุต่างๆ เช่น การตั้งค่าเงินเดือนผิดพลาด หรือข้อมูลไม่ครบถ้วน

ตัวอย่าง Payload:


{
  "request_id": "req_py12345683",
  "event": "payroll.employee.calculate_failed",
  "event_occurred_at": "2025-01-26 23:45:15",
  "body": {
    "employee_id": "20250102EFGH5678",
    "employee_code": "EMP001",
    "employee_title_lv": "2",
    "employee_title_name": "นางสาว",
    "employee_name": "สมหญิง",
    "employee_last_name": "รักงาน",
    "company_code": "COM001",
    "company_name": "บริษัท เอบีซี จำกัด",
    "company_name_en": "ABC Co., Ltd.",
    "branch_code": "BR001",
    "branch_name": "สำนักงานใหญ่",
    "department_code": "DEP001",
    "department_name": "ฝ่ายไอที",
    "position_code": "POS002",
    "position_name": "นักวิเคราะห์ระบบ",
    "year_month": "2025-01",
    "error_message": "ไม่พบการตั้งค่ารายได้พื้นฐาน (Base Salary) ของพนักงาน",
    "status": "failed",
    "is_split": false,
    "split_seq": null,
    "master_salary_split_report_id": ""
  }
}

Payroll Body Fields Reference

เพื่อให้เข้าใจความหมายของข้อมูลที่ส่งไปใน Payload มากขึ้น ด้านล่างนี้คือคำอธิบายของคีย์ (Key) ที่ปรากฏในแต่ละ Event

Period Finished / Unfinished Fields (คีย์สำหรับการเปิด/ปิดงวด)

Field	Type	Description
`master_salary_report_id`	string	รหัสอ้างอิงงวดเงินเดือนหลัก
`master_salary_month`	string	เดือนของงวดเงินเดือน (รูปแบบ YYYY-MM)
`salary_report_start_dt`	string	วันที่เริ่มต้นงวดเงินเดือน (YYYY-MM-DD)
`salary_report_end_dt`	string	วันที่สิ้นสุดงวดเงินเดือน (YYYY-MM-DD)
`master_salary_split_report_id`	string	รหัสอ้างอิงงวดเงินเดือนแบ่งงวด (กรณีเป็น Event แบ่งงวด)
`master_salary_split_seq`	integer	ลำดับการแบ่งงวด (เช่น งวดที่ 1, 2)
`read_only_flag`	string	สถานะปิดงวดบัญชี (`Y` = ปิดงวดบัญชี, `N` = เปิดงวดบัญชี)
`publish_flag`	string	สถานะการเผยแพร่สลิปเงินเดือน (`Y` = เผยแพร่แล้ว, `N` = ยังไม่เผยแพร่)
`total_employees`	integer	จำนวนพนักงานทั้งหมดที่ถูกคำนวณในงวดนี้
`status`	string	สถานะของการเปิด/ปิดงวด (`finished` หรือ `unfinished`)
`finished_at` / `unfinished_at`	string	วันที่และเวลาที่ทำรายการเปิดหรือปิดงวด

Employee Calculate Fields (คีย์สำหรับการคำนวณเงินเดือนรายบุคคล)

Field	Type	Description
`master_salary_report_id`	string	รหัสอ้างอิงงวดเงินเดือนหลัก (เฉพาะกรณีสำเร็จ)
`master_salary_month`	string	เดือนของงวดเงินเดือน (เฉพาะกรณีสำเร็จ)
`year_month`	string	เดือนของงวดเงินเดือน (เฉพาะกรณีล้มเหลว)
`employee_id`	string	รหัสพนักงานในระบบ (Internal ID)
`employee_code`	string	รหัสพนักงาน
`employee_title_lv`	string	รหัสคำนำหน้าชื่อพนักงาน
`employee_title_name`	string	คำนำหน้าชื่อพนักงาน (ภาษาไทย)
`employee_name`	string	ชื่อพนักงาน (ภาษาไทย)
`employee_last_name`	string	นามสกุลพนักงาน (ภาษาไทย)
`employee_type_code`	string	รหัสประเภทพนักงาน (เช่น รายเดือน, รายวัน)
`company_code`	string	รหัสบริษัท
`company_name`	string	ชื่อบริษัท (ภาษาไทย)
`company_name_en`	string	ชื่อบริษัท (English)
`branch_code`	string	รหัสสาขา
`branch_name`	string	ชื่อสาขา (ภาษาไทย)
`department_code`	string	รหัสแผนก
`department_name`	string	ชื่อแผนก (ภาษาไทย)
`position_code`	string	รหัสตำแหน่ง
`position_name`	string	ชื่อตำแหน่ง (ภาษาไทย)
`salary_amt`	number (float)	เงินเดือนพื้นฐาน (Base Salary)
`sum_income`	number (float)	ยอดรวมรายได้อื่นๆ นอกเหนือจากเงินเดือน (เช่น OT, เบี้ยขยัน)
`sum_expense`	number (float)	ยอดรวมรายการหักอื่นๆ (ไม่รวมภาษีและประกันสังคม)
`total_income`	number (float)	ยอดรายรับรวมทั้งหมด (`salary_amt` + `sum_income`)
`total_expense`	number (float)	ยอดรายการหักรวมทั้งหมด (รวมภาษีและประกันสังคมแล้ว)
`total_salary`	number (float)	รายได้สุทธิที่พนักงานได้รับหลังหักทุกอย่าง (Net Income)
`tax_amt`	number (float)	ยอดหักภาษี ณ ที่จ่าย
`sso_amt`	number (float)	ยอดหักประกันสังคม
`work_day`	number (float)	จำนวนวันทำงานที่คำวณค่าจ้าง
`work_day_total`	number (float)	จำนวนวันทำงานตามรอบการคำนวณทั้งหมด
`status`	string	สถานะการคำนวณ (`success` หรือ `failed`)
`is_split`	boolean	เป็นการคำนวณแบบแบ่งงวดหรือไม่ (`true` / `false`)
`split_seq`	integer	ลำดับการแบ่งงวด (ถ้ามี)
`master_salary_split_report_id`	string	รหัสอ้างอิงงวดเงินเดือนแบ่งงวด (ถ้ามี)
`calculate_to`	string	ระยะเวลาหรือขอบเขตของการคำนวณ
`error_message`	string	สาเหตุที่ทำให้คำนวณไม่ได้ (เฉพาะกรณีล้มเหลว)

สรุป Payroll Events

Event Code	คำอธิบาย
`payroll.month.unfinished`	เปิดงวดเงินเดือนปกติ (ปลดล็อคเพื่อแก้ไข/คำนวณใหม่)
`payroll.month.finished`	ปิดงวดเงินเดือนปกติ (ล็อคงวด)
`payroll.split_month.unfinished`	เปิดงวดเงินเดือนแบบแบ่งงวด
`payroll.split_month.finished`	ปิดงวดเงินเดือนแบบแบ่งงวด
`payroll.employee.calculated`	คำนวณเงินเดือนพนักงานสำเร็จ
`payroll.employee.calculate_failed`	คำนวณเงินเดือนพนักงานล้มเหลว