概念ガイド

trace の読み方

計算APIのレスポンスには、amounts に加えて calculation_trace という配列が含まれます。ここには、計算のステップごとに「何を」「どう計算し」「どのマスタを参照して」「どう丸めたか」が記録されています。値の検算や監査の根拠として使えます。

実例(月次給与計算)

POST /v1/payroll/monthly:calculate のレスポンスから、健康保険の計算ステップを抜粋します。

{
  "step": "health_insurance",
  "step_type": "statutory_deduction",
  "formula_code": "health_insurance.monthly.employee_contribution.v1",
  "output_key": "amounts.statutory_deductions.health_insurance",
  "input_refs": [
    "amounts.standard_monthly_remuneration_used",
    "settings_snapshot.social_insurance_rate_version"
  ],
  "formula": "standard_monthly_remuneration * health_insurance_employee_rate",
  "raw_amount": "14775",
  "rounding_rule": "round_50_sen_or_less_down_over_50_sen_up_to_yen",
  "rounded_amount": 14775,
  "master_refs": [
    {
      "type": "social_insurance_rate_table",
      "id": "attack5-social-0088a0d4",
      "version": "attack5-sv-0088a0d4",
      "effective_from": "2026-05-01",
      "effective_to": null
    }
  ]
}

各フィールドの意味

step / step_type — ステップの名前(health_insurance)と種別(statutory_deduction = 法定控除)です。
formula_code — 適用した計算式を一意に識別するコードです。バージョン管理されており(末尾の .v1)、計算式そのものが変わった場合は別のコードになります。
output_key — このステップの結果がレスポンスのどのフィールドに対応するか(amounts.statutory_deductions.health_insurance)を示します。
input_refs — このステップの計算に使った値の参照元です。この例では、標準報酬月額(amounts.standard_monthly_remuneration_used)と、適用した社会保険料率表のバージョン(settings_snapshot.social_insurance_rate_version)を参照しています。
formula — 適用した計算式の説明(standard_monthly_remuneration * health_insurance_employee_rate)です。
raw_amount — 丸める前の生の計算結果です。文字列("14775")で表現され、decimal.js による中間値をそのまま保持します。
rounding_rule — 適用した端数処理ルールです。この例では round_50_sen_or_less_down_over_50_sen_up_to_yen(50銭ルール)が使われています。規則の詳細は端数処理の規則を参照してください。
rounded_amount — 端数処理後の整数円の値です。レスポンスの amounts.statutory_deductions.health_insurance と一致します。
master_refs — このステップで参照した法令マスタです。type(マスタの種別)・id・version・有効期間(effective_from / effective_to)が記録されます。この例では、適用された社会保険料率表(id: attack5-social-0088a0d4、version: attack5-sv-0088a0d4)が参照されています。

一部のステップには inputs という追加フィールドも含まれ、参照した値そのものが記録されます。たとえば雇用保険のステップでは次のようになります。

{
  "step": "employment_insurance",
  "inputs": {
    "subject_wage_total": 315000,
    "employee_rate": "0.00550000"
  },
  "raw_amount": "1732.5",
  "rounding_rule": "round_50_sen_or_less_down_over_50_sen_up_to_yen",
  "rounded_amount": 1732
}

ステップの並び

月次給与計算の calculation_trace は、次の順番でステップが並びます。

settings_resolution — 設定解決。会社プロファイル・税額表・料率表・端数処理ルールの、解決されたバージョン一覧を master_refs に記録します。
pay_type_base_pay — 時給制・日給制だけに現れ、賃金形態別の基本給を算出します。月給制には現れません。
attendance_hourly_base から attendance_absence_deduction — attendance_input 指定時だけに現れる勤怠計算のステップ群です。
payment_aggregation — 支給合計(gross_payment)の算出。
monthly_social_insurance_basis — 社会保険料の算定基礎(標準報酬月額)の確認。
health_insurance — 健康保険料。
care_insurance — 介護保険料(care_insurance_subject が false の場合は 0)。
childcare_support_contribution — 子ども・子育て支援金。
employees_pension_standard_monthly_remuneration — 厚生年金保険料に使用する標準報酬月額を、解決済みの厚生年金等級表の最小・最大へクランプします。社会保険の対象外では 0 です。
employees_pension_insurance — 厚生年金保険料。input_refs はクランプ後の amounts.employees_pension_standard_monthly_remuneration_used を参照します。
employment_insurance — 雇用保険料。
源泉所得税 — 月額表方式では income_tax で row 表引きまたは本表ブラケットの加算式を適用します。電算機計算の特例では income_tax_salary_deduction、income_tax_taxable_income、income_tax_computer_special の3ステップがこの位置に並びます。
net_payment — 手取り額(gross_payment - total_deductions)。

厚年クランプと所得税の `formula_code`

employees_pension_standard_monthly_remuneration は常時出力され、formula_code は social_insurance.monthly.employees_pension_smr_clamp.v1、output_key は amounts.employees_pension_standard_monthly_remuneration_used です。入力値が等級表の範囲外で実際にクランプされた場合だけ notes が付きます。
income_tax が月額表の row を表引きした場合、formula_code は income_tax.monthly_table_lookup.v1 で、追加の端数処理がないため rounding_rule は null です。
甲欄の課税基準額740,000円以上、乙欄の105,000円未満または740,000円以上で本表ブラケットを使った場合、formula_code は income_tax.monthly_bracket_lookup.v1、rounding_rule は floor_yen です。
電算機計算の特例では、給与所得控除の income_tax_salary_deduction に income_tax.computer_special_salary_deduction.v1(ceil_yen)、課税給与所得の income_tax_taxable_income に income_tax.computer_special_taxable_income.v1(丸めなし)、最終税額の income_tax_computer_special に income_tax.computer_special_tax.v1(round_half_up_to_10_yen)を使います。

賞与計算(POST /v1/payroll/bonus:calculate)は賃金形態・勤怠のステップを持たず、settings_resolution の後に bonus_payment_aggregation と法定控除の各ステップが続きます。bonus_care_insurance の次に bonus_childcare_support_contribution が入ります。全ステップの実例は賞与の計算を参照してください。

一方、社会保険料シミュレーション(POST /v1/simulations/social-insurance:calculate)の calculation_trace は、健康保険・介護保険・子ども・子育て支援金・厚生年金保険をまとめた単一の social_insurance ステップのままで、total にはこれら4項目(子ども・子育て支援金を含む)の合計額が入ります。詳しくは社会保険料シミュレーションを参照してください。

独自料率を使っている場合の `master_refs`

会社が協会けんぽプリセットではなく独自の社会保険料率を登録している場合、健康保険・介護保険ステップの master_refs には、協会けんぽの料率表ではなく company_self_declared_social_insurance という参照が記録されます。これにより、その会社がどの時点でどの独自料率を自己申告していたかを、trace から監査できます。詳しくはマスタとバージョン解決を参照してください。

次のステップ

端数処理の規則そのものは端数処理の規則へ。
設定バージョンの解決方法や再現性の保証はマスタとバージョン解決へ。