2026.10.28

新規機能・改善

【重要】[freee人事労務API] 勤怠APIでの休暇同日取得対応および勤怠API・勤怠情報月次サマリAPI・手当APIの旧パラメータ廃止（破壊的変更）のお知らせ【猶予期間：約半年】

いつもfreee人事労務APIをご利用いただきありがとうございます。

【破壊的変更を含むお知らせです】

休暇の同日複数取得への対応・パラメータ名の適正化に伴う機能追加（Non-Breaking Change）と、それに伴う勤怠API・勤怠情報月次サマリAPI・手当APIの旧パラメータの廃止予定（Breaking Change）をお知らせいたします。

旧パラメータは2027年4月頃に削除予定です。それまでの約半年間は、引き続き利用できます。

対象APIをご利用の方は、変更内容をご確認のうえ、移行期間中に新しいパラメータへの切り替えをお願いいたします。

■ 概要

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. 【`holidays` の追加】
勤怠APIに休暇の内訳を表す `holidays` を追加しました。これにより、年次有給休暇・特別休暇・代休を同じ日に複数取得した勤怠も、APIで参照・更新できます。

2025年12月22日のお知らせ「【重要】freee人事労務 API変更のお知らせ」でご案内した、特別休暇を同日に複数取得した勤怠の取得・更新時のエラーが、本変更により解消されます。

2. 【残業関連パラメータ名の変更】
勤怠API・勤怠情報月次サマリAPIに、法定内残業・時間外労働を表す新しい名前のパラメータを追加しました。パラメータ名と実際の意味（法定内残業）を一致させるための変更です
（従来名の「excess_statutory」は「法定超過」の意味）。

3. 【`formula_element_code`の追加】
手当APIに、計算に使う勤怠項目を新しい名前で返す `formula_element_code` を追加しました。

4. 【旧パラメータの廃止（破壊的変更）】
1〜3 で置き換えとなる旧パラメータは、約半年の猶予期間（移行期間）を設けたうえで、2027年4月頃に廃止（削除）する予定です。これは破壊的変更（Breaking Change）にあたります。

■ 変更内容① 休暇の内訳 `holidays` の追加

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

・変更対象API：
– 勤怠の取得 `GET /api/v1/employees/{emp_id}/work_records/{date}`
– 勤怠の更新 `PUT /api/v1/employees/{emp_id}/work_records/{date}`
– 勤怠情報月次サマリの取得 `GET /api/v1/employees/{emp_id}/work_record_summaries/{year}/{month}`（`work_records=true` を指定した場合の日次勤怠）

・変更種別：
Non-Breaking Change（新パラメータの追加）
Breaking Change（旧パラメータの廃止：2027年4月頃予定、猶予期間は約半年。詳細は「廃止予定のパラメータ」を参照）

・破壊的変更の影響：
旧パラメータは2027年4月頃にリクエスト・レスポンスから削除される予定です。削除後は旧パラメータを使った連携が正しく動作しなくなるおそれがあるため、猶予期間（約半年）のうちに新パラメータへ切り替えてください。

取得（レスポンス）

日次勤怠に `holidays` を追加しました。その日に取得したすべての年次有給休暇・特別休暇・代休が、1件ずつ配列で返ります。

要素	説明
`holiday_category`	休暇カテゴリ（`annual_paid_holiday`：年次有給休暇、`special_holiday`：特別休暇、`compensatory_holiday`：代休）
`holiday_type`	取得単位（`full`：全休、`half`：半休、`morning_off`：午前休、`afternoon_off`：午後休、`hourly`：時間休）
`mins`	取得時間（分）。半休・時間休の場合に返ります
`time_ranges`	取得時間帯（`start_at` / `end_at`）。時間帯を持つ休暇の場合に返ります
`special_holiday_setting_id`	特別休暇設定ID。特別休暇の場合に返ります
`source_date`	代休の元になった休日出勤日。代休の場合に返ります

レスポンス例（時間帯方式の時間休で年次有給休暇を2時間、午後休で特別休暇を同日に取得した場合）

{
  "date": "2026-11-02",
  "holidays": [
    {
      "holiday_category": "annual_paid_holiday",
      "holiday_type": "hourly",
      "mins": 120,
      "time_ranges": [
        { "start_at": "2026-11-02T09:00:00.000+09:00", "end_at": "2026-11-02T11:00:00.000+09:00" }
      ]
    },
    {
      "holiday_category": "special_holiday",
      "holiday_type": "afternoon_off",
      "special_holiday_setting_id": 1
    }
  ]
}

※ 休暇がない日は空の配列 `[]` が返ります。
※ 特別休暇を同日に複数取得した勤怠は、これまでエラーになっていましたが、今回の変更以降は取得できます。
ただし、旧パラメータ（`special_holiday`、`special_holiday_setting_id` など）は、1日1件の休暇しか表せません。
複数の休暇がある場合は、`holidays` を参照してください。

更新（リクエスト）

`holidays`を指定して休暇を登録できるようになりました。年次有給休暇と特別休暇、特別休暇同士など、同じ日に複数の休暇を登録できます。

リクエスト例

{
  "company_id": 1,
  "holidays": [
    {
      "holiday_category": "annual_paid_holiday",
      "holiday_type": "hourly",
      "time_ranges": [
        { "start_at": "2026-11-02 09:00:00", "end_at": "2026-11-02 11:00:00" }
      ]
    },
    {
      "holiday_category": "special_holiday",
      "holiday_type": "afternoon_off",
      "special_holiday_setting_id": 1
    }
  ]
}

指定のルール

– 特別休暇では `special_holiday_setting_id`、代休では `source_date` が必須です。

– `full`、`morning_off`、`afternoon_off` では `mins` と `time_ranges` を指定しません。

– 年次有給休暇と有給の特別休暇の `half` では `mins` を指定します。

– 時間休（`hourly`）の指定方法は、対象日に適用される勤務賃金設定の時間休の入力方式に従います。

・時間数方式の場合：`mins`（60分単位）を指定

・時間帯方式の場合：`time_ranges` を指定

※ `mins` と `time_ranges` は同時に指定できません。

– `time_ranges` の `start_at` / `end_at` は `YYYY-MM-DD HH:MM:SS` 形式で、対象日の日付で指定します。

– 代休は1件のみ指定でき、年次有給休暇・特別休暇と同時には指定できません。

※ `holidays` と旧休暇パラメータ（`paid_holidays`、`special_holiday` など）は同時に指定できません。同時に指定した場合は 400 エラーになります。

旧形式のみ、または `holidays` のみのどちらか一方でリクエストしてください。

{
  "status_code": 400,
  "errors": [
    {
      "type": "bad_request",
      "messages": ["holidays と旧休暇キーは同時に利用できません。どちらか一方の形式で指定してください。"]
    }
  ]
}

※ 特別休暇を同日に複数取得している勤怠を旧休暇パラメータで更新した場合は、従来どおり 400 エラーになります。
`holidays` を使用して更新してください。

APIリファレンス

・勤怠の取得：
https://developer.freee.co.jp/reference/hr#/%E5%8B%A4%E6%80%A0/get_employee_work_record

・勤怠の更新：
https://developer.freee.co.jp/reference/hr#/%E5%8B%A4%E6%80%A0/update_employee_work_record

■ 変更内容② 法定内残業・時間外労働の新しいパラメータ名の追加

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

変更対象API：
– 勤怠の取得・更新 `GET / PUT /api/v1/employees/{emp_id}/work_records/{date}`

– 勤怠情報月次サマリの取得・更新 `GET / PUT /api/v1/employees/{emp_id}/work_record_summaries/{year}/{month}`

・変更理由：
従来のパラメータ名に含まれる「excess_statutory」は「法定を超える」という意味ですが、実際に入っている値は法定内残業でした。名前と意味を一致させるため、新しい名前のパラメータを追加します。値の計算方法は変わりません。

API	旧パラメータ（廃止予定）	新パラメータ	意味
勤怠（取得・更新のレスポンス）	`total_excess_statutory_work_mins`	`total_overtime_within_statutory_work_mins`	法定内残業時間（分）
〃	`total_latenight_excess_statutory_work_mins`	`total_latenight_overtime_within_statutory_work_mins`	深夜の法定内残業時間（分）
勤怠情報月次サマリ（取得・更新）	`total_excess_statutory_work_mins`	`total_overtime_within_statutory_work_mins`	給与計算に用いられる法定内残業時間（分）
〃（取得・更新）	`total_deemed_paid_excess_statutory_work_mins`	`total_deemed_paid_overtime_within_statutory_work_mins`	みなし外の法定内残業時間（分）（裁量労働制）
〃（更新のリクエストのみ）	`total_actual_excess_statutory_work_mins`	`total_actual_overtime_within_statutory_work_mins`	実労働時間ベースの法定内残業時間（分）
〃（更新のリクエストのみ）	`total_overtime_work_mins`	`total_overtime_excess_statutory_work_mins`	時間外労働時間（分）

※ 移行期間中、レスポンスには新旧両方のパラメータが同じ値で返ります。

※ 勤怠情報月次サマリの更新で、同じ項目の新旧パラメータを両方指定した場合は 400 エラーになります。

旧パラメータのみ、または新パラメータのみで指定してください。

エラーメッセージ例：「total_excess_statutory_work_mins と total_overtime_within_statutory_work_mins は同時に指定できません。total_overtime_within_statutory_work_mins のみを指定してください。」

【重要】日次勤怠の `total_overtime_work_mins` は、今回の変更・廃止の対象外です。名称変更の対象は、勤怠情報月次サマリの更新リクエストの `total_overtime_work_mins` のみです。

■ 変更内容③ 手当API `formula_element_code`の追加

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

・変更対象API：
– 手当一覧の取得 `GET /api/v1/allowances`
– 手当の取得 `GET /api/v1/allowances/{id}`

計算に使う勤怠項目を、変更内容②の新しいパラメータ名で返す `formula_element_code` を追加しました。

下表以外の値は `formula_element` と同じ値が返ります。

`formula_element`（廃止予定）の値	`formula_element_code` の値
`total_excess_statutory_work_mins`	`total_overtime_within_statutory_work_mins`
`total_overtime_work_mins`	`total_overtime_excess_statutory_work_mins`
`attendance_tag_total_excess_statutory_work_mins`	`attendance_tag_total_overtime_within_statutory_work_mins`
`attendance_tag_total_overtime_work_mins`	`attendance_tag_total_overtime_excess_statutory_work_mins`

■廃止予定のパラメータ

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

以下のパラメータは、2027年4月頃にリクエスト・レスポンスの両方から削除する予定です（Breaking Change）。

削除日は移行状況を踏まえて確定し、あらためてお知らせいたします。

API	廃止予定のパラメータ	移行先
勤怠の取得・更新	`paid_holiday`、`paid_holidays`、`half_paid_holiday_mins`、`hourly_paid_holiday_mins`、`half_holiday_type`、`special_holiday`、`special_holiday_setting_id`、`half_special_holiday_mins`、`hourly_special_holiday_mins`、`use_half_compensatory_holiday`（レスポンスのみ）	`holidays`
勤怠の取得・更新	`total_excess_statutory_work_mins`、`total_latenight_excess_statutory_work_mins`	変更内容②の表を参照
勤怠情報月次サマリの取得・更新	`total_excess_statutory_work_mins`、`total_deemed_paid_excess_statutory_work_mins`、`total_actual_excess_statutory_work_mins`、`total_overtime_work_mins`（更新のリクエスト）	変更内容②の表を参照
手当の取得	`formula_element`	`formula_element_code`

※ 2024年10月30日のお知らせ「半日単位と時間単位の年次有給休暇を同日に日次勤怠として登録することができるようになります。」で非推奨としていた以下も、今回あわせて削除します。

– `paid_holiday`、`half_paid_holiday_mins`、`hourly_paid_holiday_mins`、`half_holiday_type`

【過去に `paid_holidays` へ移行された方へのご注意】

2024/10/30 のお知らせで移行先としてご案内した `paid_holidays` も、`holidays` の導入に伴い廃止されます。

`paid_holidays` をご利用中の場合も、`holidays` への切り替えが必要です。

■ 対応方法

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

移行期間中は旧パラメータもこれまでどおり利用できます。
2027年4月頃の削除までに、以下の改修をお願いいたします。

1. リクエスト（入力）の改修

・新しいパラメータを使うよう、連携アプリを改修してください。
・リクエスト単位で段階的に移行できます。

・【注意】1つのリクエスト内で新旧のパラメータを混在させると 400 エラーになります。必ずリクエスト単位で、新形式または旧形式のいずれかに統一してください。

2. レスポンス（出力）の改修

・レスポンスの参照先を、旧パラメータから新パラメータ（`holidays`、法定内残業・時間外労働の新パラメータ、`formula_element_code`）へ切り替えてください。

■ 変更スケジュール

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

– 新パラメータの提供開始：2026/10/26（提供済み）

– アナウンス日：2026/10/28

– 移行期間（猶予期間）：2026/10/26 〜 2027年4月頃（予定・約半年）

– 旧パラメータの削除：2027年4月頃（予定）
※ 確定次第、あらためてお知らせいたします

引き続きfreee人事労務APIをご利用いただけますと幸いです。