コンテンツにスキップ

API リファレンス

賞与の計算

POST /v1/payroll/bonus:calculate

Section titled “POST /v1/payroll/bonus:calculate”

賞与を計算し、標準賞与額に基づく健康保険・介護保険・子ども・子育て支援金・厚生年金保険、雇用保険、賞与用の源泉所得税(法定控除)と、任意控除・手取り額を返します。月例給与と同様にステートレスで、計算結果は保存されません。

リクエストヘッダー

Section titled “リクエストヘッダー”

X-API-Key と Content-Type: application/json に加えて、任意で Idempotency-Key(1〜255文字、ログ記録のみで結果キャッシュには使われません)を送れます。

リクエストフィールド

Section titled “リクエストフィールド”
フィールド型必須説明
company_idstring(1〜128文字)必須計算対象の会社ID
calculation_datestring(ISO 8601日付)必須計算実行日。payment_date 以前でなければなりません
payment_datestring(ISO 8601日付)必須支払日。この日付を基準に設定バージョンが解決されます(賞与用の所得税表が使われます)
employee_snapshotobject必須従業員の計算用スナップショット。全フィールドは下表(月例給与と同じ構造です)
bonus_gross_amountinteger円(0以上)必須賞与の支給総額
bonus_itemsarray(既定 []、既定上限50件)任意賞与項目の配列。各要素は下表
custom_deductionsarray(既定 []、既定上限50件)任意任意控除の配列。フィールドは月例給与と同じ構造です
previous_month_taxable_payroll_amountinteger円(0以上)必須前月の課税支給額。previous_month_social_insurance_amount と合わせて賞与源泉徴収税額表の参照額(前月給与額)を算出します
previous_month_social_insurance_amountinteger円(0以上)必須前月の社会保険料控除額
bonus_tax_contextobject任意(既定 { "calculation_method": "standard" })賞与源泉税率の決定方法。全フィールドは下表
bonus_social_insurance_contextobject必須標準賞与額の年度内上限計算に使う、これまでの累計額。全フィールドは下表
settings_lockobject任意再現性を保証する設定バージョンのロック。フィールドは月例給与と同じ構造です
calculation_options.include_calculation_traceboolean任意(既定 true)false にすると calculation_trace は空配列 [] になります

employee_snapshot の全フィールド

Section titled “employee_snapshot の全フィールド”
フィールド型必須説明
employee_refstring(1〜128文字)必須呼び出し側が管理する相関ID。直接識別子は避けてください
tax_dependent_countinteger(0〜7)必須賞与源泉徴収税額表の扶養親族等の数の参照列
tax_table_type"kou" | "otsu"必須甲欄・乙欄の区分
is_social_insurance_subjectboolean必須健康保険・介護保険・子ども・子育て支援金・厚生年金保険の対象かどうか
is_employment_insurance_subjectboolean必須雇用保険の対象かどうか
standard_monthly_remunerationinteger円(0以上)必須健康保険の標準報酬月額。賞与計算では健康保険・厚生年金の保険料計算には使われません(標準賞与額は bonus_gross_amount 等から別途算出されます)
health_insurance_gradeinteger(1以上)任意健康保険の等級(参照用。計算には使用されません)
employees_pension_insurance_gradeinteger(1以上)任意厚生年金保険の等級(参照用。計算には使用されません)
care_insurance_subjectboolean必須介護保険の対象かどうか。is_social_insurance_subject が false の場合は true にできません

bonus_items の各要素

Section titled “bonus_items の各要素”
フィールド型必須説明
codestring(1〜64文字)必須賞与項目の識別コード。同一配列内で重複不可
namestring(1〜128文字)必須項目名
amountinteger円(0以上)必須金額
taxableboolean必須課税対象かどうか
social_insurance_includedboolean必須社会保険の算定基礎に含めるかどうか
employment_insurance_includedboolean必須雇用保険の算定基礎に含めるかどうか
metadatarecord(string → string | number | boolean | null)任意呼び出し側の任意メタデータ。既定上限は20キー・キー名128文字・文字列値256文字

bonus_tax_context の全フィールド

Section titled “bonus_tax_context の全フィールド”
フィールド型必須説明
calculation_method"standard" | "no_previous_month_payroll"必須(オブジェクト自体は既定 "standard")standard は前月給与額を賞与源泉徴収税額表で参照します。no_previous_month_payroll は前月給与がない従業員向けに、v1固定の税率を使います
withholding_rate_overridestring(小数、例: "0.04084")任意呼び出し側が指定する源泉税率。会社プロファイルで allow_withholding_rate_override が有効な場合のみ適用されます。無効な会社プロファイルで指定すると 422 withholding_rate_override_not_allowed になります。適用された場合、レスポンスの warnings に WITHHOLDING_RATE_OVERRIDDEN_BY_CALLER が入ります

bonus_social_insurance_context の全フィールド

Section titled “bonus_social_insurance_context の全フィールド”
フィールド型必須説明
health_insurance_standard_bonus_ytd_before_this_paymentinteger円(0以上)必須健康保険の標準賞与額の年度累計上限判定に使う、この支給より前の累計額
employees_pension_standard_bonus_same_month_before_this_paymentinteger円(0以上)必須厚生年金の標準賞与額の同月上限判定に使う、この支給より前の同月累計額

バリデーションルール(補足)

Section titled “バリデーションルール(補足)”
  • calculation_date は payment_date 以前でなければなりません。
  • bonus_gross_amount が 0 かつ bonus_items が空の場合はエラーになります(賞与支給額は0より大きい必要があります)。
  • bonus_items / custom_deductions それぞれの配列内で code は重複できません。
  • 標準賞与額は1,000円未満切り捨て後、健康保険・厚生年金それぞれの上限が適用されます(詳細はマスタとバージョン解決)。

curl 実例

Section titled “curl 実例”
Terminal window
curl -X POST https://api.payroll.basee.io/v1/payroll/bonus: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",
    "employee_snapshot": {
      "employee_ref": "emp_docs_example_001",
      "tax_dependent_count": 1,
      "tax_table_type": "kou",
      "is_social_insurance_subject": true,
      "is_employment_insurance_subject": true,
      "standard_monthly_remuneration": 300000,
      "care_insurance_subject": false
    },
    "bonus_gross_amount": 500000,
    "bonus_items": [],
    "custom_deductions": [],
    "previous_month_taxable_payroll_amount": 315000,
    "previous_month_social_insurance_amount": 45450,
    "bonus_social_insurance_context": {
      "health_insurance_standard_bonus_ytd_before_this_payment": 0,
      "employees_pension_standard_bonus_same_month_before_this_payment": 0
    }
  }'

レスポンス実例

Section titled “レスポンス実例”

amounts.statutory_deductions の全項目・net_payment、および calculation_trace は主要ステップを抜粋しています。

{
  "calculation_id": "calc_2e01fc89-ad53-46c9-b311-ecd7b1759ea6",
  "calculation_type": "bonus",
  "company_id": "cmp_4ba6c10e34004057b7353ea75f1c3e75",
  "employee_ref": "emp_docs_example_001",
  "calculated_at": "2026-07-24T12:33:55.630Z",
  "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": {
    "gross_payment": 500000,
    "taxable_payment": 500000,
    "social_insurance_subject_amount": 500000,
    "employment_insurance_subject_amount": 500000,
    "standard_bonus_amounts": {
      "health_insurance": 500000,
      "employees_pension_insurance": 500000
    },
    "income_tax_basis_amount": 426300,
    "statutory_deductions": {
      "health_insurance": 24625,
      "care_insurance": 0,
      "childcare_support_contribution": 575,
      "employees_pension_insurance": 45750,
      "employment_insurance": 2750,
      "income_tax": 17410,
      "total": 91110
    },
    "custom_deductions": {
      "items": [],
      "total": 0
    },
    "total_deductions": 91110,
    "net_payment": 408890
  },
  "calculation_trace": [
    "...",
    {
      "step": "bonus_income_tax",
      "step_type": "tax_calculation",
      "formula_code": "income_tax.bonus_table_lookup.v1",
      "output_key": "amounts.statutory_deductions.income_tax",
      "input_refs": [
        "amounts.income_tax_basis_amount",
        "request.previous_month_taxable_payroll_amount",
        "request.previous_month_social_insurance_amount",
        "settings_snapshot.tax_table_version"
      ],
      "formula": "lookup bonus withholding rate from income_tax_bonus_rows",
      "inputs": {
        "tax_table_type": "kou",
        "previous_month_taxable_amount": 269550,
        "dependent_count": 1,
        "row_index": 17,
        "withholding_rate": "0.04084",
        "calculation_method": "standard"
      },
      "raw_amount": "17410.092",
      "rounding_rule": "floor_yen",
      "rounded_amount": 17410,
      "master_refs": [
        {
          "type": "income_tax_table",
          "id": "nta-income-tax-bonus-2026",
          "version": "2026",
          "effective_from": "2026-01-01",
          "effective_to": "2026-12-31"
        }
      ]
    },
    "..."
  ],
  "warnings": []
}

"..." の部分は省略です。実際のレスポンスには settings_resolution・bonus_payment_aggregation・bonus_health_insurance・bonus_care_insurance・bonus_childcare_support_contribution・bonus_employees_pension_insurance・bonus_employment_insurance・bonus_income_tax・bonus_net_payment の9ステップが順に含まれます。賞与所得税は floor_yen(切り捨て)で丸められます。月例給与は row 表引きなら追加の丸めなし、本表ブラケットなら floor_yen です。全ステップの詳細は trace の読み方 を参照してください。

子ども・子育て支援金は、健康保険と同じ標準賞与額(年度累計573万円上限適用後)に料率を乗じて算出されます。

warnings は既定で空配列です。withholding_rate_override を使った場合など、呼び出し側の指定が計算に影響した場合にのみ要素が入ります(例: WITHHOLDING_RATE_OVERRIDDEN_BY_CALLER)。

主要エラー

Section titled “主要エラー”
ステータスerror.code説明
401unauthorizedX-API-Key ヘッダーが未指定、または無効です
402quota_exceeded無料プランの当月の計算回数の上限に達しました(アカウント単位)
404company_not_found会社がこのアカウントに存在しません
409settings_lock_conflictsettings_lock が実際に解決された設定バージョンと一致しません
422validation_errorリクエストボディがスキーマ検証に失敗しました
422settings_not_resolvedcompany_id と payment_date の組み合わせで、有効な会社計算プロファイルが解決できません
422income_tax_lookup_failed解決された法令マスタ(賞与源泉徴収税額表)に必要な行がない場合に発生します。通常の運用では発生しません
422withholding_rate_override_not_allowed会社プロファイルで allow_withholding_rate_override が有効になっていないのに bonus_tax_context.withholding_rate_override を指定しました
429rate_limit_exceededレート制限超過。Retry-After ヘッダーの秒数だけ待ってから再試行してください
500(エンジン内部エラー)サーバー側の内部エラー

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

関連リンク

Section titled “関連リンク”