シミュレーション

給与の一部の項目だけを試算したい場合(電卓的な利用)のために、月例給与・賞与の計算とは別に、3つの単独シミュレーションエンドポイントと、標準報酬月額の等級を解決する1つの lookup エンドポイントの計4つが用意されています。等級解決は金額の試算ではありません。4エンドポイントとも company_id と payment_date から設定バージョンを解決する点は月例給与・賞与と共通ですが、employee_ref や calculation_type のような明細情報は持ちません。

POST /v1/simulations/social-insurance:calculate

標準報酬月額から、健康保険・介護保険・子ども・子育て支援金・厚生年金保険の従業員負担額のみを試算します。

リクエストフィールド

フィールド	型	必須	説明
company_id	string(1〜128文字)	必須	試算対象の会社ID
calculation_date	string(ISO 8601日付)	必須	計算実行日。payment_date 以前でなければなりません
payment_date	string(ISO 8601日付)	必須	この日付を基準に社会保険料率表・厚生年金保険料率表のバージョンが解決されます
is_social_insurance_subject	boolean	必須	社会保険の対象かどうか
standard_monthly_remuneration	integer円(0以上)	必須	呼び出し側で報酬月額から決定した健康保険の標準報酬月額。is_social_insurance_subject が true の場合は 0 にできません。厚生年金保険料の計算では、エンジンが解決済みの厚生年金等級表の最小・最大へ自動クランプします
care_insurance_subject	boolean	必須	介護保険の対象かどうか。is_social_insurance_subject が false の場合は true にできません
settings_lock	object	任意	設定バージョンのロック。フィールドは月例給与の settings_lock と同じ6項目です
calculation_options.include_calculation_trace	boolean	任意(既定 true)	false にすると calculation_trace は空配列 [] になります

curl 実例

curl -X POST https://api.payroll.basee.io/v1/simulations/social-insurance:calculate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{
    "company_id": "cmp_docs_simulation_example",
    "calculation_date": "2026-07-27",
    "payment_date": "2026-07-27",
    "is_social_insurance_subject": true,
    "standard_monthly_remuneration": 300000,
    "care_insurance_subject": false
  }'

レスポンス実例

上記リクエストを2026年8月7日に dev API へ送信した実レスポンスです。資格情報と実会社IDは掲載せず、company_id はドキュメント用のダミー値へ置き換えています。

{
  "calculation_id": "calc_c06c4906-2a6b-43e2-9e8d-c43160ef53ed",
  "calculation_type": "social_insurance_simulation",
  "company_id": "cmp_docs_simulation_example",
  "calculated_at": "2026-08-07T05:10:16.757Z",
  "settings_snapshot": {
    "company_profile_version": "000001",
    "tax_table_version": "2026",
    "social_insurance_rate_version": "attack5-sv-0088a0d4",
    "employees_pension_rate_version": "fixture-employees-pension-2026-04-01",
    "employment_insurance_rate_version": "fixture-employment-insurance-2026-04-01",
    "rounding_rule_version": "fixture-round-half-up-v1"
  },
  "amounts": {
    "social_insurance_subject_amount": 300000,
    "employees_pension_standard_monthly_remuneration_used": 300000,
    "health_insurance": 14775,
    "care_insurance": 0,
    "childcare_support_contribution": 345,
    "employees_pension_insurance": 27450,
    "total": 42570
  },
  "calculation_trace": [
    "...",
    {
      "step": "social_insurance",
      "step_type": "statutory_deduction",
      "formula_code": "social_insurance.monthly.employee_contribution.v1",
      "output_key": "amounts.total",
      "input_refs": [
        "request.standard_monthly_remuneration",
        "settings_snapshot.social_insurance_rate_version",
        "settings_snapshot.employees_pension_rate_version"
      ],
      "formula": "standard_monthly_remuneration * health_care_childcare_rates + employees_pension_standard_monthly_remuneration_used * employees_pension_rate",
      "inputs": {
        "standard_monthly_remuneration": 300000,
        "employees_pension_standard_monthly_remuneration_used": 300000,
        "employees_pension_standard_monthly_remuneration_min": 88000,
        "employees_pension_standard_monthly_remuneration_max": 650000
      },
      "raw_amount": "42570",
      "rounding_rule": "round_50_sen_or_less_down_over_50_sen_up_to_yen",
      "rounded_amount": 42570,
      "master_refs": [
        {
          "type": "social_insurance_rate_table",
          "id": "attack5-social-0088a0d4",
          "version": "attack5-sv-0088a0d4",
          "effective_from": "2026-05-01",
          "effective_to": null
        },
        {
          "type": "employees_pension_rate_table",
          "id": "fixture-employees-pension",
          "version": "fixture-employees-pension-2026-04-01",
          "effective_from": "2026-04-01",
          "effective_to": null
        }
      ]
    }
  ]
}

"..." は settings_resolution ステップの省略です。健康保険・介護保険・子ども・子育て支援金・厚生年金保険は social_insurance という1ステップにまとめて記録され、total に4つの合計額が入ります(内訳は amounts.health_insurance / amounts.care_insurance / amounts.childcare_support_contribution / amounts.employees_pension_insurance を参照)。amounts.employees_pension_standard_monthly_remuneration_used は常時出力され、解決済みの厚生年金等級表の最小・最大へクランプした後の標準報酬月額が入ります。社会保険の対象外の場合は 0 です。

POST /v1/simulations/employment-insurance:calculate

雇用保険の算定基礎額から、雇用保険料の従業員負担額のみを試算します。

リクエストフィールド

フィールド	型	必須	説明
company_id	string(1〜128文字)	必須	試算対象の会社ID
calculation_date	string(ISO 8601日付)	必須	計算実行日。payment_date 以前でなければなりません
payment_date	string(ISO 8601日付)	必須	この日付を基準に雇用保険料率表のバージョンが解決されます
is_employment_insurance_subject	boolean	必須	雇用保険の対象かどうか
subject_wage_total	integer円(0以上)	必須	雇用保険の算定基礎額。is_employment_insurance_subject が true の場合は 0 にできません
settings_lock	object	任意	設定バージョンのロック。フィールドは月例給与の settings_lock と同じ6項目です
calculation_options.include_calculation_trace	boolean	任意(既定 true)	false にすると calculation_trace は空配列 [] になります

curl 実例

curl -X POST https://api.payroll.basee.io/v1/simulations/employment-insurance:calculate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{
    "company_id": "cmp_4ba6c10e34004057b7353ea75f1c3e75",
    "calculation_date": "2026-07-20",
    "payment_date": "2026-07-25",
    "is_employment_insurance_subject": true,
    "subject_wage_total": 315000
  }'

レスポンス実例

{
  "calculation_id": "calc_0ca74ef8-4563-487f-8fb8-f3885d754e19",
  "calculation_type": "employment_insurance_simulation",
  "company_id": "cmp_4ba6c10e34004057b7353ea75f1c3e75",
  "calculated_at": "2026-07-24T12:36:06.082Z",
  "settings_snapshot": {
    "company_profile_version": "000001",
    "tax_table_version": "2026",
    "social_insurance_rate_version": "attack5-sv-0088a0d4",
    "employees_pension_rate_version": "attack2-pv-3c8a46f4",
    "employment_insurance_rate_version": "fixture-employment-insurance-2026-04-01",
    "rounding_rule_version": "fixture-round-half-up-v1"
  },
  "amounts": {
    "employment_insurance_subject_amount": 315000,
    "employment_insurance": 1732
  },
  "calculation_trace": [
    "...",
    {
      "step": "employment_insurance",
      "step_type": "statutory_deduction",
      "formula_code": "employment_insurance.employee_contribution.v1",
      "output_key": "amounts.employment_insurance",
      "input_refs": ["request.subject_wage_total", "settings_snapshot.employment_insurance_rate_version"],
      "formula": "subject_wage_total * employee_rate",
      "raw_amount": "1732.5",
      "rounding_rule": "round_50_sen_or_less_down_over_50_sen_up_to_yen",
      "rounded_amount": 1732,
      "master_refs": [
        {
          "type": "employment_insurance_rate_table",
          "id": "fixture-employment-insurance",
          "version": "fixture-employment-insurance-2026-04-01",
          "effective_from": "2026-04-01",
          "effective_to": null
        }
      ]
    }
  ]
}

"..." は settings_resolution ステップの省略です。raw_amount("1732.5")が50銭を超えているため、50銭ルールで 1732 に切り上げられています。

POST /v1/simulations/income-tax:calculate

課税支給額と社会保険料控除額から、源泉所得税額のみを試算します(月額表を使用。月例給与の income_tax ステップと同じロジックです)。月額表の row に加え、甲欄の課税基準額740,000円以上、乙欄の105,000円未満および740,000円以上では、本表ブラケットの「基準税額 + 超過額 × 税率」を自動適用し、1円未満を切り捨てます。扶養親族等の数は 0〜7 のみ対応し、8人以上は未対応です。

リクエストフィールド

フィールド	型	必須	説明
company_id	string(1〜128文字)	必須	試算対象の会社ID
calculation_date	string(ISO 8601日付)	必須	計算実行日。payment_date 以前でなければなりません
payment_date	string(ISO 8601日付)	必須	この日付を基準に所得税表のバージョンが解決されます
taxable_payment	integer円(0以上)	必須	課税支給額
social_insurance_deduction_amount	integer円(0以上)	必須	社会保険料控除額。taxable_payment から差し引いた額が所得税の課税基準額になります
tax_table_type	"kou" | "otsu"	必須	源泉徴収税額表の甲欄・乙欄の区分
tax_dependent_count	integer(0〜7)	必須	扶養親族等の数の参照列
settings_lock	object	任意	設定バージョンのロック。フィールドは月例給与の settings_lock と同じ6項目です
calculation_options.include_calculation_trace	boolean	任意(既定 true)	false にすると calculation_trace は空配列 [] になります

curl 実例

curl -X POST https://api.payroll.basee.io/v1/simulations/income-tax:calculate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{
    "company_id": "cmp_docs_simulation_example",
    "calculation_date": "2026-07-27",
    "payment_date": "2026-07-27",
    "taxable_payment": 80750,
    "social_insurance_deduction_amount": 0,
    "tax_table_type": "otsu",
    "tax_dependent_count": 0
  }'

レスポンス実例

上記リクエストを2026年8月7日に dev API へ送信した実レスポンスです。資格情報と実会社IDは掲載せず、company_id はドキュメント用のダミー値へ置き換えています。

{
  "calculation_id": "calc_cfb1dbeb-dc0a-48ee-8fbe-ab91609b4ecd",
  "calculation_type": "income_tax_simulation",
  "company_id": "cmp_docs_simulation_example",
  "calculated_at": "2026-08-07T05:10:16.777Z",
  "settings_snapshot": {
    "company_profile_version": "000001",
    "tax_table_version": "2026",
    "social_insurance_rate_version": "attack5-sv-0088a0d4",
    "employees_pension_rate_version": "fixture-employees-pension-2026-04-01",
    "employment_insurance_rate_version": "fixture-employment-insurance-2026-04-01",
    "rounding_rule_version": "fixture-round-half-up-v1"
  },
  "amounts": {
    "taxable_payment": 80750,
    "social_insurance_deduction_amount": 0,
    "income_tax_basis_amount": 80750,
    "income_tax": 2473
  },
  "calculation_trace": [
    "...",
    {
      "step": "income_tax",
      "step_type": "tax_calculation",
      "formula_code": "income_tax.monthly_bracket_lookup.v1",
      "output_key": "amounts.income_tax",
      "input_refs": [
        "request.taxable_payment",
        "request.social_insurance_deduction_amount",
        "request.tax_dependent_count",
        "settings_snapshot.tax_table_version"
      ],
      "formula": "base_tax_amount + (monthly_taxable_amount - taxable_from) * rate, floored to yen",
      "inputs": {
        "tax_table_type": "otsu",
        "monthly_taxable_amount": 80750,
        "dependent_count": null,
        "taxable_from": 0,
        "base_tax_amount": 0,
        "rate": "0.030630",
        "excess_amount": 80750,
        "row_index": 72
      },
      "raw_amount": "2473.3725",
      "rounding_rule": "floor_yen",
      "rounded_amount": 2473,
      "master_refs": [
        {
          "type": "income_tax_table",
          "id": "nta-income-tax-monthly-2026",
          "version": "2026",
          "effective_from": "2026-01-01",
          "effective_to": "2026-12-31"
        }
      ]
    }
  ]
}

"..." は settings_resolution ステップの省略です。income_tax_basis_amount(80750)は taxable_payment - social_insurance_deduction_amount(80750 - 0)です。乙欄の105,000円未満はブラケットの加算式を使い、2473.3725 円の1円未満を floor_yen で切り捨てて2,473円を返します。

POST /v1/simulations/standard-monthly-remuneration:resolve

呼び出し側で算定した月平均報酬である報酬月額から、健康保険と厚生年金保険それぞれの等級・標準報酬月額を解決する純粋な等級 lookup です。保険料は計算しません。算定基礎届・随時改定の要否判定や、4〜6月の報酬平均の算出も行わず、これらは従来どおり呼び出し側の責務です。

リクエストフィールド

フィールド	型	必須	説明
company_id	string(1〜128文字)	必須	等級解決対象の会社ID
calculation_date	string(ISO 8601日付)	必須	計算実行日。payment_date 以前でなければなりません
payment_date	string(ISO 8601日付)	必須	この日付を基準に社会保険料率表・厚生年金保険料率表のバージョンが解決されます
monthly_remuneration	integer円(0以上1,000,000,000未満)	必須	呼び出し側で算定した報酬月額
settings_lock	object	任意	設定バージョンのロック。フィールドは月例給与の settings_lock と同じ6項目です
calculation_options.include_calculation_trace	boolean	任意(既定 false)	true にすると calculation_trace が出力されます。このエンドポイントのみ既定値は false で、他の3つのシミュレーションは既定 true です

curl 実例

curl -X POST https://api.payroll.basee.io/v1/simulations/standard-monthly-remuneration:resolve \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{
    "company_id": "cmp_docs_simulation_example",
    "calculation_date": "2026-08-07",
    "payment_date": "2026-08-25",
    "monthly_remuneration": 1800000,
    "calculation_options": {
      "include_calculation_trace": true
    }
  }'

レスポンス実例

上記リクエストを2026年8月7日に本番 API へ送信した実レスポンスです。資格情報と実会社IDは掲載せず、company_id はドキュメント用のダミー値へ置き換えています。

{
  "calculation_id": "calc_b5891431-9a00-4df9-afd2-904c5d90ba72",
  "calculation_type": "standard_monthly_remuneration_resolution",
  "company_id": "cmp_docs_simulation_example",
  "calculated_at": "2026-08-07T07:31:48.846Z",
  "settings_snapshot": {
    "company_profile_version": "000002",
    "tax_table_version": "2026",
    "social_insurance_rate_version": "2026-04",
    "employees_pension_rate_version": "2026-04",
    "employment_insurance_rate_version": "2026-04",
    "rounding_rule_version": "round-half-up-2026-01-01"
  },
  "amounts": {
    "monthly_remuneration": 1800000,
    "health_insurance_grade": 50,
    "health_insurance_standard_monthly_remuneration": 1390000,
    "employees_pension_insurance_grade": 32,
    "employees_pension_standard_monthly_remuneration": 650000
  },
  "calculation_trace": [
    "...",
    {
      "step": "standard_monthly_remuneration_resolution",
      "step_type": "settings_resolution",
      "formula_code": "masters.standard_monthly_remuneration.resolve.v1",
      "output_key": "amounts.monthly_remuneration",
      "input_refs": [
        "request.monthly_remuneration",
        "settings_snapshot.social_insurance_rate_version",
        "settings_snapshot.employees_pension_rate_version"
      ],
      "formula": "lookup grade where monthly_remuneration_from <= monthly_remuneration < monthly_remuneration_to",
      "inputs": {
        "monthly_remuneration": 1800000,
        "health_insurance_grade": 50,
        "health_insurance_standard_monthly_remuneration": 1390000,
        "health_insurance_monthly_remuneration_from": 1355000,
        "health_insurance_monthly_remuneration_to": null,
        "employees_pension_insurance_grade": 32,
        "employees_pension_standard_monthly_remuneration": 650000,
        "employees_pension_monthly_remuneration_from": 635000,
        "employees_pension_monthly_remuneration_to": null
      },
      "raw_amount": "1800000",
      "rounding_rule": null,
      "rounded_amount": 1800000,
      "master_refs": [
        {
          "type": "social_insurance_rate_table",
          "id": "kyoukaikenpo-tokyo-social-insurance-2026-04",
          "version": "2026-04",
          "effective_from": "2026-04-01",
          "effective_to": null
        },
        {
          "type": "employees_pension_rate_table",
          "id": "jps-employees-pension-2026-04",
          "version": "2026-04",
          "effective_from": "2026-04-01",
          "effective_to": "2027-03-31"
        }
      ]
    }
  ]
}

"..." は settings_resolution ステップの省略です。amounts には monthly_remuneration / health_insurance_grade / health_insurance_standard_monthly_remuneration / employees_pension_insurance_grade / employees_pension_standard_monthly_remuneration が入ります。等級レンジは monthly_remuneration_from 以上、monthly_remuneration_to 未満として判定します。最下限レンジ未満または最上限レンジ以上でも open-ended 行により第1級または最上級に解決され、エラーにはなりません。たとえば報酬月額1,800,000円は健康保険50級・標準報酬月額1,390,000円、厚生年金保険32級・標準報酬月額650,000円に解決されます。中間レンジでは、報酬月額300,000円は健康保険22級・標準報酬月額300,000円、厚生年金保険19級・標準報酬月額300,000円に解決されます。

独自料率(custom)の会社は自社プロファイルに等級表を持たないため、payment_date で解決できる協会けんぽの等級表を法定参照として決定的に代用します。健康保険の等級レンジは全国共通であり、採用したテーブルは calculation_trace の master_refs に明示されます。この代用等級表は settings_lock の対象外であるため、同じ lock を指定しても等級表の改定により結果が変わることがあります。

このエンドポイントは月次クォータ(Free プランの月10件)の対象外です。月次クォータの対象は /v1/payroll/* のみです。解決結果は月例給与・賞与・社会保険シミュレーションの standard_monthly_remuneration に渡して利用します。月例給与での指定方法は 月例給与の計算 を参照してください。

主要エラー

4エンドポイントとも同じエラー形式・ステータスコード体系です。

ステータス	error.code	説明
401	unauthorized	X-API-Key ヘッダーが未指定、または無効です
404	company_not_found	会社がこのアカウントに存在しません
409	settings_lock_conflict	settings_lock が実際に解決された設定バージョンと一致しません
422	validation_error	リクエストボディがスキーマ検証に失敗しました
422	settings_not_resolved	company_id と payment_date の組み合わせで、有効な設定が解決できません。等級解決では、解決された社会保険料率表・厚生年金保険料率表に等級行が1件もない場合にも発生します
422	income_tax_lookup_failed	(源泉所得税シミュレーションのみ)解決された法令マスタ(月額表)に必要な row・ブラケットがない場合に発生します。通常の運用では発生しません
429	rate_limit_exceeded	レート制限超過。Retry-After ヘッダーの秒数だけ待ってから再試行してください
500	(エンジン内部エラー)	サーバー側の内部エラー

エラーコード一覧とレート制限の詳細は エラーとレート制限 を参照してください。

関連リンク

• 月例給与の計算
• マスタとバージョン解決
• 端数処理の規則
• trace の読み方