月例給与の計算

POST /v1/payroll/monthly:calculate

月給制・時給制・日給制の月例給与を計算し、健康保険・介護保険・子ども・子育て支援金・厚生年金保険・雇用保険・源泉所得税(法定控除)と、任意控除・手取り額を返します。attendance_input を指定すると、勤怠実績から基本給・割増賃金・遅刻早退控除・欠勤控除を算出します(月給制では任意、時給制・日給制では必須)。従業員データ、勤怠実績、計算結果は保存されず、レスポンスに含まれる値がすべてです。

リクエストヘッダー

X-API-Key と Content-Type: application/json に加えて、任意で Idempotency-Key(1〜255文字)を送れます。前述のとおり、これは結果のキャッシュには使われないログ用のヘッダーです。

リクエストフィールド

フィールド	型	必須	説明
company_id	string(1〜128文字)	必須	計算対象の会社ID
calculation_date	string(ISO 8601日付、例: 2026-07-20)	必須	計算実行日。payment_date 以前でなければなりません
payment_date	string(ISO 8601日付)	必須	支払日。この日付を基準に会社プロファイル・税額表・料率表・端数処理ルールのバージョンが解決されます
period.payroll_month	string(YYYY-MM)	必須	対象の給与月
period.start_date	string(ISO 8601日付)	必須	対象期間の開始日
period.end_date	string(ISO 8601日付)	必須	対象期間の終了日。start_date 以降でなければなりません
employee_snapshot	object	必須	従業員の計算用スナップショット。全フィールドは下表
pay_type	"monthly" | "hourly" | "daily"	任意(既定 "monthly")	賃金形態。省略時は従来どおり月給制として計算します
base_pay	integer円(0以上)	monthly のみ必須	月給制の基本給。hourly / daily では指定できません
hourly_rate	integer円(0以上)	hourly のみ必須	時給。monthly / daily では指定できません
daily_rate	integer円(0以上)	daily のみ必須	日給。monthly / hourly では指定できません
overtime_pay	integer円(0以上)	任意(既定 0)	計算済みの残業代。attendance_input 指定時は非ゼロにできません
absence_deduction	integer円(0以上)	任意(既定 0)	計算済みの欠勤控除額。attendance_input 指定時は非ゼロにできません
late_early_leave_deduction	integer円(0以上)	任意(既定 0)	計算済みの遅刻早退控除額。attendance_input 指定時は非ゼロにできません
attendance_input	object	monthly は任意、hourly / daily は必須	勤怠実績。賃金形態ごとの制約と全フィールドは下表
allowances	array(既定 []、既定上限50件)	任意	手当の配列。各要素は下表
custom_deductions	array(既定 []、既定上限50件)	任意	任意控除(法定控除以外)の配列。各要素は下表
resident_tax_amount	integer円(0以上)	任意(既定 0)	住民税額。呼び出し側が確定させた額をそのまま控除します(本エンジンは住民税額を計算しません)
previous_adjustments	array(既定 []、既定上限20件)	任意	前月調整額の配列。各要素は下表
settings_lock	object	任意	再現性を保証する設定バージョンのロック。全フィールドは下表
calculation_options.include_calculation_trace	boolean	任意(既定 true)	false にすると calculation_trace は空配列 [] になります

employee_snapshot の全フィールド

フィールド	型	必須	説明
employee_ref	string(1〜128文字)	必須	呼び出し側が管理する相関ID。氏名・メールアドレス・社員番号などの直接識別子は避けてください
tax_dependent_count	integer(0〜7)	必須	源泉徴収税額表の扶養親族等の数の参照列。本エンジンは扶養該当性の判定は行いません
tax_table_type	"kou" | "otsu"	必須	源泉徴収税額表の甲欄・乙欄の区分
is_social_insurance_subject	boolean	必須	健康保険・介護保険・子ども・子育て支援金・厚生年金保険の対象かどうか
is_employment_insurance_subject	boolean	必須	雇用保険の対象かどうか
standard_monthly_remuneration	integer円(0以上)	必須	呼び出し側で報酬月額から決定した健康保険の標準報酬月額。is_social_insurance_subject が true の場合は 0 にできません。厚生年金保険料の計算では、エンジンが解決済みの厚生年金等級表の最小・最大へ自動クランプします(2026年度は88,000〜650,000円)。2027年9月以降の上限は68万円、71万円、75万円へ段階的に引き上げられ、マスタ更新により自動追従します。報酬月額から標準報酬月額・等級を決定する処理は呼び出し側の責務です。報酬月額からの等級解決には POST /v1/simulations/standard-monthly-remuneration:resolve が使えます(シミュレーション参照)
health_insurance_grade	integer(1以上)	任意	健康保険の等級(参照用)。計算そのものには使用されません(正は standard_monthly_remuneration)
employees_pension_insurance_grade	integer(1以上)	任意	厚生年金保険の等級(参照用)。同上、計算には使用されません
care_insurance_subject	boolean	必須	介護保険の対象かどうか。is_social_insurance_subject が false の場合は true にできません
monthly_standard_working_hours	decimal string(1〜744)	条件付き必須	月平均所定労働時間。monthly で attendance_input を指定する場合、または hourly / daily で overtime_base_included: true の手当がある場合に必須です
daily_standard_working_hours	decimal string(0より大きく24以下)	daily のみ必須	1日所定労働時間。日給制の割増・遅刻早退控除の時間単価の分母です。日によって異なる場合は1週間の1日平均所定労働時間を指定します。エンジンは平均値の妥当性を検証しません。monthly / hourly では指定できません

attendance_input の全フィールド

分数フィールドは 0〜44,640 の整数分で、省略時は 0 です。44,640分は31日 × 24時間 × 60分です。base_work_minutes と attendance_days は賃金形態に応じて必須になり、省略時 0 にはなりません。

フィールド	型	必須	説明
overtime_minutes	integer(0〜44640)	任意(既定 0)	時間外労働の分数
late_night_minutes	integer(0〜44640)	任意(既定 0)	深夜労働の分数。深夜加算率のみを適用し、他の支給区分と重複できます
legal_holiday_minutes	integer(0〜44640)	任意(既定 0)	法定休日労働の分数
non_legal_holiday_minutes	integer(0〜44640)	任意(既定 0)	所定(法定外)休日労働の分数
late_early_leave_minutes	integer(0〜44640)	任意(既定 0)	遅刻・早退控除の対象分数
absence_minutes	integer(0〜44640)	任意(既定 0)	欠勤控除の対象分数。日数入力ではなく、呼び出し側で分へ換算します
base_work_minutes	integer(0〜44640)	hourly のみ必須	基本給(1.0倍)で支給する実労働分数。monthly / daily では指定できません。予定シフトを基準に控除する方式には対応していません
attendance_days	integer(0〜31)	daily のみ必須	対象期間の出勤日数。monthly / hourly では指定できません

最重要: 二重支給を防ぐ排他セマンティクス

base_work_minutes は、基本給として 1.0倍で支給される分数です。overtime_minutes・legal_holiday_minutes・non_legal_holiday_minutes に計上した分数はフル率で別払いされるため、base_work_minutes に含めないでください。含めると二重支給になります。

深夜労働は例外です。late_night_minutes は0.25の加算率だけを表すため、深夜分は base_work_minutes に含めた上で late_night_minutes にも計上します。

日給制の attendance_days にも、終日を法定休日労働または法定外休日労働として分数計上した日は含めないでください。

overtime_minutes・legal_holiday_minutes・non_legal_holiday_minutes は互いに排他的な区分です。同じ1分を複数区分へ入れないでください。late_night_minutes は加算区分のため、これらのいずれかと重複できます。

allowances の各要素

フィールド	型	必須	説明
code	string(1〜64文字)	必須	手当の識別コード。同一配列内で重複不可
name	string(1〜128文字)	必須	手当名
amount	integer円(0以上)	必須	金額
taxable	boolean	必須	課税対象かどうか
social_insurance_included	boolean	必須	社会保険の算定基礎に含めるかどうか
employment_insurance_included	boolean	必須	雇用保険の算定基礎に含めるかどうか
fixed	boolean	任意	固定的な手当かどうかを示すフラグ。呼び出し側の記録用で、計算には使用されません
overtime_base_included	boolean	任意(既定 false)	true の場合、この手当を勤怠計算の時間単価の分子へ算入します。allowances でのみ使用されます
metadata	record(string → string | number | boolean | null)	任意	呼び出し側の任意メタデータ。既定上限は20キー・キー名128文字・文字列値256文字

custom_deductions の各要素

フィールド	型	必須	説明
code	string(1〜64文字)	必須	控除の識別コード。同一配列内で重複不可
name	string(1〜128文字)	必須	控除名
amount	integer円(0以上)	必須	金額
metadata	record(string → string | number | boolean | null)	任意	allowances と同じ上限

previous_adjustments の各要素

フィールド	型	必須	説明
code	string(1〜64文字)	必須	調整項目の識別コード。同一配列内で重複不可
name	string(1〜128文字)	必須	調整項目名
amount	integer円(符号あり、マイナス可)	必須	金額。前月分の追加・減額調整のためマイナスも許容
taxable	boolean	必須	課税対象かどうか
social_insurance_included	boolean	必須	社会保険の算定基礎に含めるかどうか
employment_insurance_included	boolean	必須	雇用保険の算定基礎に含めるかどうか
metadata	record(string → string | number | boolean | null)	任意	allowances と同じ上限

settings_lock の全フィールド

settings_lock オブジェクト自体は任意ですが、指定する場合は次の6フィールドすべてが必須です。前回レスポンスの settings_snapshot から、次の6つのバージョンフィールドを渡してください。解決結果と完全一致しない場合は 409 settings_lock_conflict が返ります。詳細は マスタとバージョン解決 を参照してください。

フィールド	型	必須	説明
company_profile_version	string(1文字以上)	必須	会社計算プロファイルのバージョン
tax_table_version	string(1文字以上)	必須	所得税表のバージョン
social_insurance_rate_version	string(1文字以上)	必須	社会保険料率表のバージョン
employees_pension_rate_version	string(1文字以上)	必須	厚生年金保険料率表のバージョン
employment_insurance_rate_version	string(1文字以上)	必須	雇用保険料率表のバージョン
rounding_rule_version	string(1文字以上)	必須	端数処理ルールのバージョン

settings_snapshot の割増端数処理フィールド

レスポンスの settings_snapshot には、上の6つのバージョンに加えて、解決された会社プロファイルの割増端数処理方式が常に含まれます。この2フィールドは計算条件の確認用で、settings_lock には指定しません。

フィールド	値	説明
overtime_premium_rounding_method	none / hourly_rate_half_up / unit_price_half_up / hourly_rate_ceil	割増賃金に使う時間単価・割増単価の処理方式
overtime_premium_monthly_total_rounding	none / half_up_100_yen	割増賃金の月合計に対する追加処理

各方式の意味は端数処理の規則を参照してください。

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

• calculation_date は payment_date 以前でなければなりません。 賃金形態ごとの入力条件は次のとおりです。禁止フィールドは黙って無視されず、指定すると 422 validation_error になります。

フィールド	monthly	hourly	daily
pay_type	省略可(既定値)	"hourly" 必須	"daily" 必須
base_pay	必須	禁止	禁止
hourly_rate	禁止	必須	禁止
daily_rate	禁止	禁止	必須
employee_snapshot.daily_standard_working_hours	禁止	禁止	必須
attendance_input	任意	必須	必須
attendance_input.base_work_minutes	禁止	必須(0〜44640)	禁止
attendance_input.attendance_days	禁止	禁止	必須(0〜31)
attendance_input.absence_minutes	許可	0 のみ	0 のみ
attendance_input.late_early_leave_minutes	許可	0 のみ	許可
employee_snapshot.monthly_standard_working_hours	attendance_input 指定時必須	算入手当がある場合のみ必須	算入手当がある場合のみ必須

• base_pay またはエンジンが導出した基本給に、overtime_pay・手当・前月調整を加え、欠勤・遅刻早退控除を引いた支給合計の候補値はマイナスにできません。
• attendance_input と、非ゼロの overtime_pay・absence_deduction・late_early_leave_deduction は併用できません。
• base_work_minutes / attendance_days と対象期間の実日数との整合は呼び出し側の責務です。エンジンは上限(44640分 / 31日)だけを検証します。
• allowances / custom_deductions / previous_adjustments それぞれの配列内で code は重複できません。
• リクエストボディはスキーマに定義のないフィールドを含むと 422 になります(未知フィールド拒否)。
• 賃金形態別の必須・禁止条件を含む cross-field 違反に新しいエラーコードはありません。すべて 422 validation_error で、具体的な理由は error.details[].message を確認してください。

標準報酬月額のレスポンスフィールド

amounts には次の2フィールドが常時出力されます。社会保険の対象外の場合はいずれも 0 です。

フィールド	型	説明
standard_monthly_remuneration_used	integer円(0以上)	月次の健康保険・介護保険・子ども・子育て支援金の計算に使用した標準報酬月額
employees_pension_standard_monthly_remuneration_used	integer円(0以上)	解決済みの厚生年金等級表の最小・最大へクランプした後の標準報酬月額。社会保険の対象外の場合は 0

源泉所得税の適用範囲

源泉所得税は、income_tax_basis_amount を月額表の row から表引きします。row の範囲外となる甲欄の740,000円以上、乙欄の105,000円未満および740,000円以上では、月額表本表のブラケットに定められた「基準税額 + 超過額 × 税率」を自動適用し、1円未満を切り捨てます。そのため、高額給与・役員報酬も同じエンドポイントで計算できます。

扶養親族等の数は row・ブラケットのどちらも 0〜7 のみ対応しています。8人以上に対する1人あたり1,610円の追加控除は未対応です。

計算方式

源泉所得税の計算方式は、既定の 月額表(税額表) と 電算機計算の特例 の2方式です。会社計算プロファイルの income_tax_withholding_method を、ダッシュボードまたは PUT /cp/v1/companies/{company_id}/calculation-profile で設定します。

• monthly_table(既定) — 月額表の row または本表ブラケットで計算します。
• computer_special — 月次給与の甲欄だけに電算機計算の特例を適用します。乙欄はこの設定にかかわらず月額表で計算され、賞与は対象外です。

電算機計算の特例では、給与所得控除の1円未満を切り上げて課税給与所得を算出し、税額を10円未満四捨五入します。calculation_trace には income_tax_salary_deduction、income_tax_taxable_income、income_tax_computer_special の3ステップが記録されます。

次は、特例を設定した会社について、月給1,820,000円・甲欄・扶養0人で2026年8月12日に dev API から採取した実レスポンスです。資格情報と実会社IDは掲載せず、company_id と会社プロファイルの id はドキュメント用のダミー値へ置き換えています。calculation_trace は源泉所得税の3ステップを抜粋しています。

{
  "calculation_id": "calc_12ee946d-ff5c-4175-be3a-91542b67022b",
  "calculation_type": "monthly_payroll",
  "company_id": "cmp_docs_income_tax_computer_special",
  "employee_ref": "emp_docs_income_tax_computer_special_001",
  "calculated_at": "2026-08-12T03:06:25.601Z",
  "settings_snapshot": {
    "company_profile_version": "000001",
    "tax_table_version": "2026",
    "social_insurance_rate_version": "2026-04",
    "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": {
    "gross_payment": 1820000,
    "taxable_payment": 1820000,
    "social_insurance_subject_amount": 1820000,
    "standard_monthly_remuneration_used": 980000,
    "employees_pension_standard_monthly_remuneration_used": 650000,
    "employment_insurance_subject_amount": 1820000,
    "income_tax_basis_amount": 1701123,
    "statutory_deductions": {
      "health_insurance": 48265,
      "care_insurance": 0,
      "childcare_support_contribution": 1127,
      "employees_pension_insurance": 59475,
      "employment_insurance": 10010,
      "income_tax": 371440,
      "resident_tax": 0,
      "total": 490317
    },
    "custom_deductions": {
      "items": [],
      "total": 0
    },
    "total_deductions": 490317,
    "net_payment": 1329683
  },
  "calculation_trace": [
    {
      "step": "income_tax_salary_deduction",
      "step_type": "tax_calculation",
      "formula_code": "income_tax.computer_special_salary_deduction.v1",
      "output_key": "trace.income_tax_salary_deduction",
      "input_refs": [
        "amounts.income_tax_basis_amount",
        "settings_snapshot.tax_table_version"
      ],
      "formula": "salary income deduction by table 1, ceiled to yen",
      "inputs": {
        "monthly_taxable_amount": 1701123,
        "rate": null,
        "addition_amount": null,
        "fixed_amount": 162500
      },
      "raw_amount": "162500",
      "rounding_rule": "ceil_yen",
      "rounded_amount": 162500,
      "master_refs": [
        {
          "type": "income_tax_table",
          "id": "nta-income-tax-monthly-2026",
          "version": "2026",
          "effective_from": "2026-01-01",
          "effective_to": "2026-12-31"
        }
      ]
    },
    {
      "step": "income_tax_taxable_income",
      "step_type": "tax_calculation",
      "formula_code": "income_tax.computer_special_taxable_income.v1",
      "output_key": "trace.income_tax_taxable_income",
      "input_refs": [
        "amounts.income_tax_basis_amount",
        "trace.income_tax_salary_deduction",
        "request.employee_snapshot.tax_dependent_count"
      ],
      "formula": "monthly_taxable_amount - salary_deduction - basic_deduction - dependent_deduction, clamped to zero",
      "inputs": {
        "salary_deduction": 162500,
        "basic_deduction": 48334,
        "dependent_deduction": 0,
        "dependent_count": 0
      },
      "raw_amount": "1490289",
      "rounding_rule": null,
      "rounded_amount": 1490289,
      "master_refs": [
        {
          "type": "income_tax_table",
          "id": "nta-income-tax-monthly-2026",
          "version": "2026",
          "effective_from": "2026-01-01",
          "effective_to": "2026-12-31"
        }
      ]
    },
    {
      "step": "income_tax_computer_special",
      "step_type": "tax_calculation",
      "formula_code": "income_tax.computer_special_tax.v1",
      "output_key": "amounts.statutory_deductions.income_tax",
      "input_refs": [
        "amounts.income_tax_basis_amount",
        "settings_snapshot.tax_table_version",
        "trace.income_tax_salary_deduction",
        "trace.income_tax_taxable_income"
      ],
      "formula": "taxable_income * rate - deduction_amount, rounded half up to 10 yen",
      "inputs": {
        "taxable_income": 1490289,
        "rate": "0.336930",
        "deduction_amount": 130688
      },
      "raw_amount": "371435.07277",
      "rounding_rule": "round_half_up_to_10_yen",
      "rounded_amount": 371440,
      "master_refs": [
        {
          "type": "income_tax_table",
          "id": "nta-income-tax-monthly-2026",
          "version": "2026",
          "effective_from": "2026-01-01",
          "effective_to": "2026-12-31"
        }
      ]
    }
  ]
}

curl 実例(月給制)

curl -X POST https://api.payroll.basee.io/v1/payroll/monthly:calculate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -d '{
    "company_id": "cmp_docs_attendance_example",
    "calculation_date": "2026-07-27",
    "payment_date": "2026-07-27",
    "period": {
      "payroll_month": "2026-07",
      "start_date": "2026-07-01",
      "end_date": "2026-07-31"
    },
    "employee_snapshot": {
      "employee_ref": "emp_docs_attendance_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,
      "monthly_standard_working_hours": "160"
    },
    "base_pay": 300000,
    "attendance_input": {
      "overtime_minutes": 600,
      "late_night_minutes": 120,
      "legal_holiday_minutes": 60,
      "non_legal_holiday_minutes": 60,
      "late_early_leave_minutes": 30,
      "absence_minutes": 480
    },
    "allowances": [
      {
        "code": "position_allowance",
        "name": "役職手当",
        "amount": 20000,
        "taxable": true,
        "social_insurance_included": true,
        "employment_insurance_included": true,
        "overtime_base_included": true
      }
    ],
    "custom_deductions": [],
    "resident_tax_amount": 0
  }'

レスポンス実例

上記リクエストを2026年8月7日に dev API へ送信した実レスポンスです。資格情報と実会社IDは掲載せず、company_id と会社プロファイルの id はドキュメント用のダミー値へ置き換えています。calculation_trace は勤怠計算の4ステップを抜粋しています。

{
  "calculation_id": "calc_46b9144c-b3c6-406f-aeab-bf254c43b586",
  "calculation_type": "monthly_payroll",
  "company_id": "cmp_docs_attendance_example",
  "employee_ref": "emp_docs_attendance_001",
  "calculated_at": "2026-08-07T05:08:09.126Z",
  "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": {
    "gross_payment": 334200,
    "taxable_payment": 334200,
    "social_insurance_subject_amount": 334200,
    "standard_monthly_remuneration_used": 300000,
    "employees_pension_standard_monthly_remuneration_used": 300000,
    "employment_insurance_subject_amount": 334200,
    "income_tax_basis_amount": 289792,
    "statutory_deductions": {
      "health_insurance": 14775,
      "care_insurance": 0,
      "childcare_support_contribution": 345,
      "employees_pension_insurance": 27450,
      "employment_insurance": 1838,
      "income_tax": 5880,
      "resident_tax": 0,
      "total": 50288
    },
    "custom_deductions": {
      "items": [],
      "total": 0
    },
    "attendance": {
      "hourly_base": "2000",
      "overtime_pay": 31200,
      "late_early_leave_deduction": 1000,
      "absence_deduction": 16000
    },
    "total_deductions": 50288,
    "net_payment": 283912
  },
  "calculation_trace": [
    {
      "step": "attendance_hourly_base",
      "step_type": "payment_aggregation",
      "formula_code": "attendance.hourly_base.v1",
      "output_key": "amounts.attendance.hourly_base",
      "input_refs": [
        "request.base_pay",
        "request.allowances",
        "request.employee_snapshot.monthly_standard_working_hours"
      ],
      "formula": "(base_pay + overtime_base_included allowance total) / monthly_standard_working_hours",
      "inputs": {
        "base_pay": 300000,
        "overtime_base_allowance_total": "20000",
        "monthly_standard_working_hours": "160"
      },
      "raw_amount": "2000",
      "rounding_rule": null,
      "rounded_amount": "2000",
      "master_refs": []
    },
    {
      "step": "attendance_overtime_pay",
      "step_type": "payment_aggregation",
      "formula_code": "attendance.overtime_pay.v1",
      "output_key": "amounts.attendance.overtime_pay",
      "input_refs": [
        "amounts.attendance.hourly_base",
        "request.attendance_input",
        "settings_snapshot.company_profile_version"
      ],
      "formula": "hourly_base * (overtime_rate * overtime_minutes + late_night_additional_rate * late_night_minutes + legal_holiday_rate * legal_holiday_minutes + non_legal_holiday_rate * non_legal_holiday_minutes) / 60",
      "inputs": {
        "overtime": { "minutes": 600, "rate": "1.25000000", "raw": "25000" },
        "late_night": { "minutes": 120, "rate": "0.25000000", "raw": "1000" },
        "legal_holiday": { "minutes": 60, "rate": "1.35000000", "raw": "2700" },
        "non_legal_holiday": { "minutes": 60, "rate": "1.25000000", "raw": "2500" }
      },
      "raw_amount": "31200",
      "rounding_rule": "ceil_yen",
      "rounded_amount": 31200,
      "master_refs": [
        {
          "type": "company_calculation_profile",
          "id": "prof_docs_attendance_example",
          "version": "000001",
          "effective_from": "2026-07-27",
          "effective_to": null
        }
      ],
      "notes": "Late-night minutes are additive and may overlap another premium category."
    },
    {
      "step": "attendance_late_early_leave_deduction",
      "step_type": "deduction_aggregation",
      "formula_code": "attendance.late_early_leave_deduction.v1",
      "output_key": "amounts.attendance.late_early_leave_deduction",
      "input_refs": [
        "amounts.attendance.hourly_base",
        "request.attendance_input.late_early_leave_minutes",
        "settings_snapshot.company_profile_version"
      ],
      "formula": "hourly_base * late_early_leave_minutes / 60",
      "inputs": { "hourly_base": "2000", "minutes": 30 },
      "raw_amount": "1000",
      "rounding_rule": "floor_yen",
      "rounded_amount": 1000,
      "master_refs": [
        {
          "type": "company_calculation_profile",
          "id": "prof_docs_attendance_example",
          "version": "000001",
          "effective_from": "2026-07-27",
          "effective_to": null
        }
      ]
    },
    {
      "step": "attendance_absence_deduction",
      "step_type": "deduction_aggregation",
      "formula_code": "attendance.absence_deduction.v1",
      "output_key": "amounts.attendance.absence_deduction",
      "input_refs": [
        "amounts.attendance.hourly_base",
        "request.attendance_input.absence_minutes",
        "settings_snapshot.company_profile_version"
      ],
      "formula": "hourly_base * absence_minutes / 60",
      "inputs": { "hourly_base": "2000", "minutes": 480 },
      "raw_amount": "16000",
      "rounding_rule": "floor_yen",
      "rounded_amount": 16000,
      "master_refs": [
        {
          "type": "company_calculation_profile",
          "id": "prof_docs_attendance_example",
          "version": "000001",
          "effective_from": "2026-07-27",
          "effective_to": null
        }
      ]
    }
  ]
}

実レスポンスでは settings_resolution の直後に上記4ステップが入り、その後に payment_aggregation と既存の法定控除・net_payment ステップが続きます。勤怠以外のステップは例から省略しています。

割増端数処理の実API例

unit_price_half_up と half_up_100_yen を設定した会社について、基本給22,254円・月平均所定労働時間10時間・時間外60分・深夜60分として、2026年8月25日にdev APIから採取した実レスポンスの抜粋です。資格情報と実会社IDは掲載せず、会社プロファイルの id はドキュメント用のダミー値へ置き換えています。

{
  "settings_snapshot": {
    "company_profile_version": "000002",
    "tax_table_version": "2026",
    "social_insurance_rate_version": "2026-04",
    "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",
    "overtime_premium_rounding_method": "unit_price_half_up",
    "overtime_premium_monthly_total_rounding": "half_up_100_yen"
  },
  "amounts": {
    "attendance": {
      "hourly_base": "2225.4",
      "overtime_pay": 3300,
      "late_early_leave_deduction": 0,
      "absence_deduction": 0
    }
  },
  "calculation_trace": [
    {
      "step": "attendance_premium_rounding",
      "step_type": "payment_aggregation",
      "formula_code": "attendance.premium_rounding.v1",
      "output_key": "trace.attendance_premium_rounding",
      "input_refs": [
        "amounts.attendance.hourly_base",
        "settings_snapshot.company_profile_version"
      ],
      "formula": "rounded_hourly_base = round_half_up(hourly_base); unit_price_i = round_half_up(rounded_hourly_base * rate_i)",
      "inputs": {
        "method": "unit_price_half_up",
        "hourly_base": "2225.4",
        "rounded_hourly_base": "2225",
        "unit_prices": {
          "overtime": "2781",
          "late_night": "556",
          "legal_holiday": "3004",
          "non_legal_holiday": "2781"
        }
      },
      "raw_amount": "2225.4",
      "rounding_rule": "round_half_up_to_yen",
      "rounded_amount": 2225,
      "master_refs": [
        {
          "type": "company_calculation_profile",
          "id": "prof_docs_premium_rounding",
          "version": "000002",
          "effective_from": "2026-08-25",
          "effective_to": null
        }
      ],
      "notes": "The hourly base and each premium unit price are rounded independently."
    },
    {
      "step": "attendance_overtime_monthly_total_rounding",
      "step_type": "payment_aggregation",
      "formula_code": "attendance.overtime_monthly_total_rounding.v1",
      "output_key": "amounts.attendance.overtime_pay",
      "input_refs": [
        "trace.attendance_overtime_pay.rounded_amount",
        "settings_snapshot.company_profile_version"
      ],
      "formula": "round_half_up(overtime_pay / 100) * 100",
      "inputs": {
        "overtime_pay_before_monthly_total_rounding": 3337
      },
      "raw_amount": "3337",
      "rounding_rule": "round_half_up_to_100_yen",
      "rounded_amount": 3300,
      "master_refs": [
        {
          "type": "company_calculation_profile",
          "id": "prof_docs_premium_rounding",
          "version": "000002",
          "effective_from": "2026-08-25",
          "effective_to": null
        }
      ]
    }
  ]
}

検算すると、時間単価は 22,254 ÷ 10 = 2,225.4円、50銭四捨五入後は2,225円です。時間外単価は 2,225 × 1.25 = 2,781.25 → 2,781円、深夜単価は 2,225 × 0.25 = 556.25 → 556円 となります。各60分なので合計は 2,781 + 556 = 3,337円、これを100円単位で四捨五入した最終割増賃金は3,300円で、レスポンスと一致します。

厚年クランプ・高額給与の実API例

健保の標準報酬月額1,390,000円、基本給1,800,000円、甲欄・扶養親族等0人として、2026年8月7日に同じ dev API へ送信しました。リクエストの主要部分は次のとおりです。

{
  "employee_snapshot": {
    "tax_dependent_count": 0,
    "tax_table_type": "kou",
    "is_social_insurance_subject": true,
    "is_employment_insurance_subject": true,
    "standard_monthly_remuneration": 1390000,
    "care_insurance_subject": false
  },
  "base_pay": 1800000
}

実レスポンスから amounts と厚年クランプ・所得税の trace を抜粋すると次のとおりです。健保・子ども子育て支援金は入力した1,390,000円、厚生年金は上限へクランプした650,000円を基数にしています。所得税はブラケットの加算式を適用し、raw金額 357863.0501 の1円未満を切り捨てています。

{
  "amounts": {
    "gross_payment": 1800000,
    "taxable_payment": 1800000,
    "social_insurance_subject_amount": 1800000,
    "standard_monthly_remuneration_used": 1390000,
    "employees_pension_standard_monthly_remuneration_used": 650000,
    "employment_insurance_subject_amount": 1800000,
    "income_tax_basis_amount": 1660570,
    "statutory_deductions": {
      "health_insurance": 68457,
      "care_insurance": 0,
      "childcare_support_contribution": 1598,
      "employees_pension_insurance": 59475,
      "employment_insurance": 9900,
      "income_tax": 357863,
      "resident_tax": 0,
      "total": 497293
    },
    "custom_deductions": {
      "items": [],
      "total": 0
    },
    "total_deductions": 497293,
    "net_payment": 1302707
  },
  "calculation_trace": [
    {
      "step": "employees_pension_standard_monthly_remuneration",
      "step_type": "statutory_deduction",
      "formula_code": "social_insurance.monthly.employees_pension_smr_clamp.v1",
      "output_key": "amounts.employees_pension_standard_monthly_remuneration_used",
      "input_refs": [
        "request.employee_snapshot.standard_monthly_remuneration",
        "request.employee_snapshot.is_social_insurance_subject",
        "settings_snapshot.employees_pension_rate_version"
      ],
      "formula": "is_social_insurance_subject ? clamp(standard_monthly_remuneration, grade_min, grade_max) : 0",
      "inputs": {
        "standard_monthly_remuneration": 1390000,
        "is_social_insurance_subject": true,
        "employees_pension_standard_monthly_remuneration_min": 88000,
        "employees_pension_standard_monthly_remuneration_max": 650000
      },
      "raw_amount": "650000",
      "rounding_rule": null,
      "rounded_amount": 650000,
      "master_refs": [
        {
          "type": "employees_pension_rate_table",
          "id": "fixture-employees-pension",
          "version": "fixture-employees-pension-2026-04-01",
          "effective_from": "2026-04-01",
          "effective_to": null
        }
      ],
      "notes": "Employees pension basis is clamped to the resolved standard monthly remuneration grade bounds."
    },
    {
      "step": "income_tax",
      "step_type": "tax_calculation",
      "formula_code": "income_tax.monthly_bracket_lookup.v1",
      "output_key": "amounts.statutory_deductions.income_tax",
      "input_refs": [
        "amounts.income_tax_basis_amount",
        "settings_snapshot.tax_table_version"
      ],
      "formula": "base_tax_amount + (monthly_taxable_amount - taxable_from) * rate, floored to yen",
      "inputs": {
        "tax_table_type": "kou",
        "monthly_taxable_amount": 1660570,
        "dependent_count": 0,
        "taxable_from": 960000,
        "base_tax_amount": 121820,
        "rate": "0.336930",
        "excess_amount": 700570,
        "row_index": 16
      },
      "raw_amount": "357863.0501",
      "rounding_rule": "floor_yen",
      "rounded_amount": 357863,
      "master_refs": [
        {
          "type": "income_tax_table",
          "id": "nta-income-tax-monthly-2026",
          "version": "2026",
          "effective_from": "2026-01-01",
          "effective_to": "2026-12-31"
        }
      ]
    }
  ]
}

勤怠金額の計算・レスポンス・丸め

基本給と割増・控除の時間単価(hourly_base)は賃金形態ごとに次の式で算出します。overtime_base_included: true の手当だけが時間単価へ算入されます。

monthly hourly_base =
  (base_pay + Σ allowances[overtime_base_included=true].amount)
  / employee_snapshot.monthly_standard_working_hours

hourly base_pay raw = hourly_rate * base_work_minutes / 60
hourly base_pay = ceil_yen(hourly base_pay raw)
hourly hourly_base =
  hourly_rate
  + Σ allowances[overtime_base_included=true].amount
    / employee_snapshot.monthly_standard_working_hours

daily base_pay = daily_rate * attendance_days
daily hourly_base =
  daily_rate / employee_snapshot.daily_standard_working_hours
  + Σ allowances[overtime_base_included=true].amount
    / employee_snapshot.monthly_standard_working_hours

overtime_pay raw =
  hourly_base
  * (
      overtime_rate * overtime_minutes
    + late_night_additional_rate * late_night_minutes
    + legal_holiday_rate * legal_holiday_minutes
    + non_legal_holiday_rate * non_legal_holiday_minutes
  )
  / 60

late_early_leave_deduction raw =
  hourly_base * late_early_leave_minutes / 60

absence_deduction raw =
  hourly_base * absence_minutes / 60

時給制の基本給は円未満を ceil_yen で切り上げます。日給制の基本給は daily_rate × attendance_days で、丸めはありません。手当時間割がない時給制・日給制では monthly_standard_working_hours は不要です。時間単価そのものは丸めません。

attendance_input を指定した場合だけ、レスポンスの amounts.attendance が現れます。

フィールド	型	説明
base_pay	integer円	エンジンが導出した基本給。hourly / daily の場合のみ返ります
hourly_base	decimal string	丸め前の時間単価
overtime_pay	integer円	時間外・深夜加算・法定休日・所定休日の割増賃金合計
late_early_leave_deduction	integer円	遅刻早退控除
absence_deduction	integer円	欠勤控除

割増賃金は4区分のraw金額を合算してから、ceil_yen で1回だけ円単位へ切り上げます。区分ごとには丸めません。遅刻早退控除と欠勤控除はそれぞれのraw金額へ floor_yen(円未満切り捨て) を適用します。

時給制・日給制では settings_resolution の直後に基本給導出の pay_type_base_pay ステップが追加され、その後に次の勤怠ステップが続きます。

1. pay_type_base_pay — 時給制は pay_type.hourly.base_pay.v1、日給制は pay_type.daily.base_pay.v1 で amounts.attendance.base_pay を算出します。月給制にはこのステップはありません。
2. attendance_hourly_base — hourly_base を算出。rounding_rule は null で、rounded_amount もdecimal stringです。
3. attendance_overtime_pay — 4区分の分数・率・raw金額を inputs に記録し、合算後に ceil_yen を適用します。
4. attendance_late_early_leave_deduction — 遅刻早退控除へ floor_yen を適用します。
5. attendance_absence_deduction — 欠勤控除へ floor_yen を適用します。

月60時間を超える時間外労働

現行バージョンは overtime_minutes 全量へ単一の overtime_rate を適用し、労働基準法37条1項但書の月60時間超に対する割増率引き上げ(1.5倍以上)を自動適用しません。月60時間超が発生し得る場合は、会社の率設定または呼び出し側で対応してください。

時給制の実API例

本番反映済みAPIへ送信したリクエストの賃金・勤怠部分です。base_work_minutes: 6543 には基本給として支給する分だけを入れ、別払いの時間外90分は含めていません。深夜20分は base_work_minutes に含めた上で late_night_minutes にも計上しています。

{
  "pay_type": "hourly",
  "hourly_rate": 1130,
  "attendance_input": {
    "base_work_minutes": 6543,
    "overtime_minutes": 90,
    "late_night_minutes": 20,
    "late_early_leave_minutes": 0,
    "absence_minutes": 0
  }
}

実レスポンスから amounts と基本給導出 trace を抜粋すると次のとおりです。

{
  "amounts": {
    "gross_payment": 125440,
    "attendance": {
      "base_pay": 123227,
      "hourly_base": "1130",
      "overtime_pay": 2213,
      "late_early_leave_deduction": 0,
      "absence_deduction": 0
    },
    "total_deductions": 1780,
    "net_payment": 123660
  },
  "calculation_trace": [
    "...",
    {
      "step": "pay_type_base_pay",
      "step_type": "payment_aggregation",
      "formula_code": "pay_type.hourly.base_pay.v1",
      "output_key": "amounts.attendance.base_pay",
      "input_refs": [
        "request.hourly_rate",
        "request.attendance_input.base_work_minutes"
      ],
      "formula": "hourly_rate * base_work_minutes / 60",
      "inputs": {
        "hourly_rate": 1130,
        "base_work_minutes": 6543
      },
      "raw_amount": "123226.5",
      "rounding_rule": "ceil_yen",
      "rounded_amount": 123227,
      "master_refs": []
    },
    "..."
  ]
}

日給制の実API例

同じAPIへ送信した日給制リクエストの賃金・勤怠部分です。日給 10500 円、1日所定労働時間 7.75 時間、出勤17日で、時間外60分と遅刻早退100分を指定しています。

{
  "employee_snapshot": {
    "daily_standard_working_hours": "7.75"
  },
  "pay_type": "daily",
  "daily_rate": 10500,
  "attendance_input": {
    "attendance_days": 17,
    "overtime_minutes": 60,
    "late_early_leave_minutes": 100,
    "absence_minutes": 0
  }
}

実レスポンスから amounts と基本給導出 trace を抜粋すると次のとおりです。

{
  "amounts": {
    "gross_payment": 177936,
    "attendance": {
      "base_pay": 178500,
      "hourly_base": "1354.8387096774193548",
      "overtime_pay": 1694,
      "late_early_leave_deduction": 2258,
      "absence_deduction": 0
    },
    "total_deductions": 4459,
    "net_payment": 173477
  },
  "calculation_trace": [
    "...",
    {
      "step": "pay_type_base_pay",
      "step_type": "payment_aggregation",
      "formula_code": "pay_type.daily.base_pay.v1",
      "output_key": "amounts.attendance.base_pay",
      "input_refs": [
        "request.daily_rate",
        "request.attendance_input.attendance_days"
      ],
      "formula": "daily_rate * attendance_days",
      "inputs": {
        "daily_rate": 10500,
        "attendance_days": 17
      },
      "raw_amount": "178500",
      "rounding_rule": null,
      "rounded_amount": 178500,
      "master_refs": []
    },
    "..."
  ]
}

"..." は他の trace ステップの省略です。どちらも pay_type_base_pay の直後に賃金形態別の attendance_hourly_base が続き、割増賃金・控除・法定控除が計算されます。

主要エラー

ステータス	error.code	説明
401	unauthorized	X-API-Key ヘッダーが未指定、または無効です
402	quota_exceeded	無料プランの当月の計算回数の上限に達しました(アカウント単位)
404	company_not_found	会社がこのアカウントに存在しません
409	settings_lock_conflict	settings_lock が実際に解決された設定バージョンと一致しません
422	validation_error	リクエストボディがスキーマ検証に失敗しました(details に対象フィールドの一覧が入ります)
422	settings_not_resolved	指定した company_id と payment_date の組み合わせで、有効な会社計算プロファイルが解決できません(会社に社会保険が未設定の場合を含みます)
422	income_tax_lookup_failed	解決された法令マスタ(月額表)に必要な row・ブラケットがない場合に発生します。通常の運用では発生しません
422	attendance_input_conflict	attendance_input と非ゼロの計算済み勤怠金額を併用しています
422	attendance_rates_not_configured	解決された会社プロファイルに勤怠割増率4種が設定されていません
422	negative_gross_payment	勤怠由来の控除によって gross_payment が負になります
429	rate_limit_exceeded	レート制限超過。Retry-After ヘッダーの秒数だけ待ってから再試行してください
500	(エンジン内部エラー)	サーバー側の内部エラー

422 validation_error の実例(空ボディを送った場合):

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "request_id": "075cbd87-37ea-48eb-9850-56fc4684bb5f",
    "details": [
      { "path": ["company_id"], "code": "invalid_type" },
      { "path": ["calculation_date"], "code": "invalid_type" },
      { "path": ["payment_date"], "code": "invalid_type" },
      { "path": ["period"], "code": "invalid_type" },
      { "path": ["employee_snapshot"], "code": "invalid_type" },
      { "path": ["base_pay"], "code": "invalid_type" }
    ]
  }
}

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

関連リンク

• trace の読み方 — calculation_trace の全ステップの解説
• マスタとバージョン解決 — settings_snapshot / settings_lock の仕組み
• 端数処理の規則 — rounding_rule の値の意味
• 賞与の計算