← 回快速上手

API 參考

TypeScript（npm taiwan-payroll）與 Python（PyPI taiwan-payroll）為同一套引擎的鏡像實作，讀同一份分級表、跑通同一套黃金測試向量，結果逐位元一致。差別僅命名慣例：TS 用 camelCase、Python 用 snake_case；下方參數表並列兩者。金額一律為整數新台幣元。

建立引擎

createPayrollEngine / create_payroll_engine：傳入年度，回傳引擎物件。內建 2024–2026；年度不存在會丟錯。

// TypeScript
import { createPayrollEngine } from 'taiwan-payroll';
const engine = createPayrollEngine({ year: 2026 });

# Python
from taiwan_payroll import create_payroll_engine, CalculateInput
engine = create_payroll_engine(year=2026)

calculate — 勞保＋健保＋勞退＋職災

當月各方法定負擔。輸入 CalculateInput，回傳 CalculateResult。

// TS
engine.calculate({ monthlySalary: 42000, dependents: 1, pensionSelfContribution: 0.06 });
# Python
engine.calculate(CalculateInput(monthly_salary=42000, dependents=1, pension_self_contribution=0.06))

回傳 CalculateResult： brackets（各保險採用的投保級距金額）、employee（員工負擔 labor／health／pensionSelf／total）、employer（雇主負擔 labor／health／pension／occupational／total）、government（政府負擔 labor／health）、meta（year、dataVersion）。

calculateSupplementary — 二代健保補充保費

六類所得的補充保費。輸入 SupplementaryInput，回傳 SupplementaryResult。

回傳 SupplementaryResult： type、chargeable（計費金額）、rate（費率字串）、premium（補充保費）。

calculateEmployerSupplementary — 雇主端補充保費

投保單位（雇主）二代健保補充保費：(每月支付薪資總額 − 受僱者當月健保投保金額總額) × 2.11%，無上限。輸入 EmployerSupplementaryInput，回傳 EmployerSupplementaryResult。

回傳 EmployerSupplementaryResult： base（差額 max(0, A−B)）、rate（費率字串）、premium（補充保費）。

calculateProrated — 月中到職／離職破月

破月當月的各方負擔。輸入 ProratedInput（＝ CalculateInput 全部欄位，再加下列兩個），回傳 ProratedResult。勞保／職保／勞退按日（30 日基準），健保採官方月底歸屬原則。

回傳 ProratedResult： 同 CalculateResult，再加 days.insured（投保天數）與 healthCharged / health_charged（健保當月是否計費）。

calculateWithholding — 薪資所得扣繳

薪資所得稅代扣，三條路徑以 type 區分。輸入 WithholdingInput，回傳 WithholdingResult（withholding 應扣繳稅額、rate 適用稅率、taxableAnnual 僅居住者）。

居住者公式法：免稅額 101,000×(本人＋扶養)＋標準扣除 272,000＋薪資特別扣除 227,000，依級距稅率減累進差額、兩步四捨五入至元。獎金按 5%（單次未達 90,501 免扣）。非居住者月薪 ≤ 1.5× 基本工資為 6%、否則 18%。僅內建 2026；其餘年度未提供時丟錯。

calculateOldAgePension — 勞保老年年金（月領）試算

勞保老年年金月領金額試算，採法定擇優兩式取高者。TS calculateOldAgePension（函式 calcOldAgePension）／Python calculate_old_age_pension（函式 calc_old_age_pension）。輸入 OldAgePensionInput，回傳 OldAgePensionResult。僅內建 2026；其餘年度未提供時丟錯。

// TS
engine.calculateOldAgePension({ avgInsuredSalary: 32000, years: 35, months: 6 });
# Python
engine.calculate_old_age_pension(OldAgePensionInput(avg_insured_salary=32000, years=35, months=6))

擇優兩式：式一 平均 × 年資 × 0.775% + 3,000、式二 平均 × 年資 × 1.55%，取高者為月領金額（角以下四捨五入）。 提前／延後：依 claimOffsetMonths 增減給，每年 ±4%（每月按比例 ±4%÷12），上限 ±20%（即 ±5 年）；超過上限自動夾限。 年資未滿 15 年：eligible:false（未達年金請領資格，公式數值仍計算供參考）。

回傳 OldAgePensionResult： formulaA（式一）、formulaB（式二）、monthly（擇優月領）、adjustmentMonths（實際採用的增減給月數，已夾限）、eligible（是否達 15 年年資門檻）。

便利函式：averageHighestInsuredSalary（TS）/ average_highest_insured_salary（Python）取投保薪資序列中最高 60 個月平均（四捨五入）；statutoryClaimAge（TS）/ statutory_claim_age（Python）依出生民國年回法定請領年齡。

免責：試算結果僅供參考，實際請領金額以勞保局核定為準。

calculateOldAgeLumpSum — 勞保老年一次金試算

勞保老年一次金給付試算（適用年資未滿 15 年、不請領年金者）。TS calculateOldAgeLumpSum（函式 calcOldAgeLumpSum）／Python calculate_old_age_lump_sum（函式 calc_old_age_lump_sum）。輸入 OldAgeLumpSumInput，回傳 OldAgeLumpSumResult。僅內建 2026；其餘年度未提供時丟錯。

// TS
engine.calculateOldAgeLumpSum({ avgInsuredSalary: 30000, years: 10 });
# Python
engine.calculate_old_age_lump_sum(OldAgeLumpSumInput(avg_insured_salary=30000, years=10))

計算公式：給付 = 平均月投保薪資 × 給付月數。給付月數＝保險年資每滿 1 年發給 1 個月； 逾 60 歲上限：逾 60 歲以後的年資最多計 5 年（60 個月），以 postSixtyMonths 指定逾 60 歲的月數，超過部分不計入。 適用對象：年資未滿 15 年、不請領老年年金者。

回傳 OldAgeLumpSumResult： payment（一次金給付金額）、insuredMonthsCounted（實際計入的給付月數）。

免責：試算結果僅供參考，實際請領金額以勞保局核定為準。

calculateOldAgeSinglePayment — 勞保一次請領老年給付試算

勞保一次請領老年給付試算（基數制，適用 98 年前有保險年資、選擇一次請領者）。TS calculateOldAgeSinglePayment（函式 calcOldAgeSinglePayment）／Python calculate_old_age_single_payment（函式 calc_old_age_single_payment）。輸入 OldAgeSinglePaymentInput，回傳 OldAgeSinglePaymentResult。僅內建 2026；其餘年度未提供時丟錯。

// TS
engine.calculateOldAgeSinglePayment({ avgInsuredSalary: 32000, preSixtyYears: 20, preSixtyMonths: 6, postSixtyYears: 5 });
# Python
engine.calculate_old_age_single_payment(OldAgeSinglePaymentInput(avg_insured_salary=32000, pre_sixty_years=20, pre_sixty_months=6, post_sixty_years=5))

基數制：保險年資前 15 年每滿 1 年給 1 個基數、超過 15 年的部分每滿 1 年給 2 個基數； 滿 60 歲前上限：最高 45 個基數。 逾 60 歲後：逾 60 歲以後的年資最多計 5 年（每滿 1 年 2 個基數），與滿 60 歲前合併計算最高 50 個基數。 給付公式：給付 = 平均月投保薪資 × 基數。

回傳 OldAgeSinglePaymentResult： payment（一次請領給付金額）、basisTwelfths（基數 × 12；基數＝basisTwelfths / 12，以 12 倍整數空間表示避免分數浮點誤差）。

免責：試算結果僅供參考，實際請領金額以勞保局核定為準。

generateSupplementaryBonusFiling — 補充保費獎金申報檔（CSV）

產生健保署「補充保險費明細申報檔（獎金，所得類別 62）」CSV。輸入扣費單位 metadata 與獎金給付明細；逐列補充保費由 calculateSupplementary(bonus) 計算，回傳 { filename, content }。檔案為 Big5 編碼：content 為 Unicode 字串，存檔時須以 Big5 編碼（Python 可用 to_big5_bytes()；TS 端請自行以 Big5 寫出）。

generateSupplementaryParttimeFiling — 補充保費兼職薪資申報檔（CSV，類別63）

產生健保署「補充保險費明細申報檔（兼職薪資，所得類別 63）」CSV。輸入扣費單位 metadata 與兼職薪資給付明細；逐列補充保費由 calculateSupplementary(parttime) 計算（兼職薪資：單次達基本工資者全額×費率），回傳 { filename, content }。檔案為 Big5 編碼：content 為 Unicode 字串，存檔時須以 Big5 編碼（Python 可用 to_big5_bytes()；TS 端請自行以 Big5 寫出）。

generateSupplementaryProfessionalFiling — 補充保費執行業務申報檔（CSV，類別65）

產生健保署「補充保險費明細申報檔（執行業務所得，所得類別 65）」CSV。輸入扣費單位 metadata 與執行業務所得給付明細；逐列補充保費由 calculateSupplementary(professional) 計算（執行業務：單次達 20,000 起扣，全額×費率），回傳 { filename, content }。檔案為 Big5 編碼：content 為 Unicode 字串，存檔時須以 Big5 編碼（Python 可用 to_big5_bytes()；TS 端請自行以 Big5 寫出）。

generateSupplementaryInterestFiling — 補充保費利息申報檔（CSV，類別67）

產生健保署「補充保險費明細申報檔（利息所得，所得類別 67）」CSV。輸入扣費單位 metadata 與利息所得給付明細；逐列補充保費由 calculateSupplementary(interest) 計算（利息：單次達 20,000 起扣，全額×費率），回傳 { filename, content }。檔案為 Big5 編碼：content 為 Unicode 字串，存檔時須以 Big5 編碼（Python 可用 to_big5_bytes()；TS 端請自行以 Big5 寫出）。

generateSupplementaryRentFiling — 補充保費租金申報檔（CSV，類別68）

產生健保署「補充保險費明細申報檔（租金所得，所得類別 68）」CSV。輸入扣費單位 metadata 與租金所得給付明細；逐列補充保費由 calculateSupplementary(rent) 計算（租金：單次達 20,000 起扣，全額×費率），回傳 { filename, content }。檔案為 Big5 編碼：content 為 Unicode 字串，存檔時須以 Big5 編碼（Python 可用 to_big5_bytes()；TS 端請自行以 Big5 寫出）。

generateSupplementaryDividendFiling — 補充保費股利申報檔（CSV，類別66）

產生健保署「補充保險費明細申報檔（股利所得，所得類別 66）」CSV，回傳 { filename, content }。本類別欄位最多（明細列 17 欄），且與其他類別最大的差異是：逐列補充保費由呼叫端提供（record.premium），不由引擎硬算。原因是官方申報流程即由申報人自行填「扣繳補充保險費金額」，且股票股利、特殊情形（如官方範例中股票股利保費為 0）公式無法涵蓋，故交由呼叫端判定。檔案為 Big5 編碼：content 為 Unicode 字串，存檔時須以 Big5 編碼（Python 可用 to_big5_bytes()；TS 端請自行以 Big5 寫出）。

便利函式 calculateDividendPremium（TS calcDividendPremium / Python calc_dividend_premium）：協助計算「一般股東／雇主」常見情況的補充保費供呼叫端取用——一般股東 amount × 費率、雇主 (amount − 投保額總額) × 費率，單次達 20,000 起扣（未達門檻回 0）。股票股利、特殊註記等情形不在涵蓋範圍，請呼叫端自行判定後以 record.premium 提供。

年度資料

getAvailableYears() / get_available_years() 回傳可用年度陣列；getYearData(year) / get_year_data(year) 回傳該年度的完整分級表與費率原始資料（含 sources 文號）。

列舉值

輸入驗證

monthlySalary 須為有限非負數、pensionSelfContribution 與 dependents 須為有限數、occupationalRate 須落在 [0, 0.02)、identity 須為合法值——否則丟出 Error（Python 為 ValueError）。

計算結果僅供參考，實際應繳金額以勞保局、健保署核發之繳款單為準。本套件不構成法律或會計建議。