Taiwan Payroll

taiwan-payroll

オープンソースの台湾労働保険・健康保険・退職金の法定費用計算エンジンです。給与と身分を入力すると、労働保険（雇用保険を含む）、健康保険、退職金、労災、二代目健康保険の追加保険料について、各者の負担額を計算します。給与所得の源泉徴収、月途中の入社／退職による月単位未満の計算、健康保険追加保険料の申告用データファイル、労働保険の老齢給付の試算にも対応しています。

_{例：MCP 対応の AI アシスタント（Claude / Cursor など）から taiwan-payroll を呼び出す}

• 🧮 オンライン試算：https://taiwan-payroll.vercel.app（インストール不要、ブラウザー上で直接計算）
• 🔌 3種類のインターフェース：TypeScript（npm）、Python（PyPI、標準ライブラリのみ）、MCP サーバー（AI アシスタントから呼び出し）
• 📑 公式資料との照合：等級表と料率は管轄機関の公表資料から段階ごとに取得し、計算結果は公式サンプルのゴールデンベクトルとビット単位で検証済みです
• 🔁 言語間の一貫性：TS と Python は同じ data/ を読み込み、同じ testdata/ を実行するため、結果はビット単位で一致します
• 📦 実行時依存関係ゼロ：core はランタイムパッケージを一切含みません

位置付けは「計算エンジン」であり、「法令遵守の保証」ではありません。 民国 113～115（2024～2026）年度の公式パラメーターを内蔵しています。

インストール

npm install taiwan-payroll      # TypeScript / Node
pip install taiwan-payroll      # Python

クイックスタート

import { createPayrollEngine } from 'taiwan-payroll';

const engine = createPayrollEngine({ year: 2026 });
const r = engine.calculate({
  monthlySalary: 42000,
  identity: 'category1',
  dependents: 1,
  employmentInsurance: true,
  pensionSelfContribution: 0.06,
});

console.log(r.employee); // { labor: 1050, health: 1302, pensionSelf: 2520, total: 4872 }
console.log(r.employer.occupational); // 職災雇主負擔

二代目健康保険の追加保険料と月単位未満の計算

// 補充保費（六類所得：bonus/parttime/professional/dividend/interest/rent）
engine.calculateSupplementary({ type: 'bonus', amount: 200000, monthlyInsuredSalary: 42000 });
// → { type: 'bonus', chargeable: 32000, rate: '0.0211', premium: 675 }

// 月中到職／離職（勞保/職保/勞退按日；健保採官方「月底歸屬」原則）
engine.calculateProrated({ monthlySalary: 29500, startDate: '2026-03-08' });
// → { ..., days: { insured: 23 }, healthCharged: true }

健康保険の月単位未満の計算では「月末時点の所属先原則」を採用します：月末時点で所属する保険加入単位を基準に、1か月分を徴収します。入社月は1か月分を計算し、退職月は計算しません。これは健康保険署の実務規則であり、日割り計算ではなく、15日を境にする規則とも関係ありません。

申告用データファイル（健康保険の追加保険料）

申告データから健康保険署の「追加保険料明細申告ファイル」（CSV／Big5）を生成します。6種類の所得に対応しています：賞与(62)、兼業給与(63)、専門業務報酬(65)、配当(66)、利息(67)、賃貸料(68)。各ジェネレーターは健康保険署の公式サンプルとビット単位で検証済みで、TS と Python の結果は一致します。

import { generateSupplementaryBonusFiling } from 'taiwan-payroll';

const { filename, content } = generateSupplementaryBonusFiling({
  year: 2026,
  filingDate: '20260901', // 用於檔名
  unit: { taxId: '11111111', name: '甲公司', phone: '0227065866', email: '[email protected]', contactName: '王小明' },
  records: [
    { action: 'I', payDate: '20260615', payeeId: 'A123456789', payeeName: '李四',
      bonusAmount: 50000, insuredSalary: 31800, ytdBonusCumulative: 150000, unitCode: '123456789' },
  ],
});
// filename: 'DPR111111111150901001.csv'
// content : Unicode 字串；檔案實際為 Big5，存檔時請以 Big5 編碼寫出。

• 賞与／兼業／専門業務報酬／利息／賃貸料：行ごとの追加保険料はエンジンが計算します。配当（generateSupplementaryDividendFiling）は株式配当／雇用主控除などのケースが含まれるため、行ごとの保険料は呼び出し側が指定します（便利関数 calcDividendPremium も用意しています）。
• 出力は公式ポータルにアップロードする「データファイル」です。Big5 エンコード：TS では呼び出し側でエンコードし、Python では to_big5_bytes() を提供します（core は依存関係ゼロを維持します）。
• API の詳細はドキュメントサイト /docs/api をご覧ください。

労働保険の老齢給付試算

労働保険局の公式計算式に基づき、3種類の老齢給付を試算します（すべて公式の数値／計算式と照合済み、TS≡Python）。

import { calcOldAgePension, calcOldAgeLumpSum, calcOldAgeSinglePayment, getYearData } from 'taiwan-payroll';
const d = getYearData(2026);
calcOldAgePension(d, { avgInsuredSalary: 32000, years: 35, months: 6 });     // 月領年金（擇優兩式，可提前/延後）
calcOldAgeLumpSum(d, { avgInsuredSalary: 30000, years: 10 });                // 老年一次金
calcOldAgeSinglePayment(d, { avgInsuredSalary: 30000, preSixtyYears: 20 });  // 一次請領（舊制基數）

• 老齢年金：2つの計算式を比較して有利な方を選択します（平均×年数×0.775%+3000 と ×1.55%）。繰上げ／繰下げは claimOffsetMonths で指定（年あたり±4%、上限は±5年（±20%））。averageHighestInsuredSalary、statutoryClaimAge も付属します。
• 老齢一時金：加入期間が1年満了するごとに1か月分を支給し、60歳以降の加入期間は最大5年分までです。
• 一括請求：基数方式（最初の15年は1年につき1基数、それを超える部分は1年につき2基数、最初の60歳までの上限は45、合算上限は50）。平均額は脱退前36か月分を使用します。
• 試算は参考情報です。実際の金額は労働保険局の認定結果が基準となります。

アーキテクチャ

• data/{year}.json — 唯一の信頼できる情報源となる、年度ごとの法規パラメーター（等級表、料率）。JSON Schema で検証します。
• testdata/ — 言語に依存しないゴールデンテストベクトル（出典を示す source を含む）。言語間で動作の一貫性を保つ基盤です。
• packages/core — 実行時依存関係ゼロの TypeScript エンジンです。

その他の言語とインターフェース

• Python：pip install taiwan-payroll。標準ライブラリのみを使用し、API は TS 版に対応しています（PyPI）。
• MCP サーバー：Claude などの AI アシスタントから直接試算を呼び出せます。インストール不要のリモートエンドポイント https://taiwan-payroll.simoko.workers.dev/mcp（Streamable HTTP）、またはローカルで実行する npx taiwan-payroll-mcp（stdio、npm）。
  • 公式 MCP Registry（io.github.supra126/taiwan-payroll）、Smithery（ワンクリックインストール）、Glama に掲載されています。
• オンライン計算機と完全な API：https://taiwan-payroll.vercel.app

データソース（2026 / 民国115年）

項目	管轄機関	文書番号
労働保険の加入給与等級表（11級、上限45,800）	労働部労働保険局	労動保2字第1140091863号令
労働者退職金の月額拠出等級表（62級、上限150,000）	労働部労働保険局	労動福3字第1140153598号令
労災保険の加入給与等級表（21級、上限72,800）	労働部労災保険法§17
健康保険の加入金額等級表（58級、上限313,000）	衛生福利部健康保険署	衛部保字第1140153424号令

料率：労働保険 12.5%（雇用保険 1% を含む）、健康保険 5.17%、退職金の雇用主負担 6%、労災保険の平均 0.21%、二代目健康保険の追加保険料 2.11%。

現在、民国 113／114／115（2024／2025／2026） の3年度分を内蔵しています。各年度の等級表と文書番号は data/{year}.json の sources をご覧ください。createPayrollEngine({ year }) で年度を指定でき、利用可能な年度は getAvailableYears() で取得できます。

開発

pnpm install
pnpm validate:data   # 驗證 data schema、級距連續性、向量格式
pnpm -r test         # 跑全部黃金測試向量
pnpm typecheck

免責事項

本パッケージは公開法規と管轄機関の公表資料に基づいて実装されています。計算結果は参考情報であり、実際の納付額は労働保険局および健康保険署が発行する納付書を基準とします。本パッケージは法律または会計に関する助言を構成するものではありません。

ライセンス

MIT