【freee人事労務】API仕様の変更について

【freee人事労務】API仕様の変更について

freee人事労務APIにおいて、以下の仕様変更があります。

変更内容①

  • 概要
    • 2024年6月にfreee人事労務でリリースされた複数回出退勤機能により、複数の出退勤時間が登録できることから勤務時間修正申請にも複数の出退勤時間登録するためのリクエストパラメーター「work_records」を対象エンドポイントに追加します。
    • 追加にあたり、現行の出退勤時間を登録するためのリクエストパラメーター「clock_in_at（勤務開始時間）」「clock_out_at（勤務終了時間）」項目を移行期間を設けた上で廃止します。
  • 移行期間
    • 2024/06/11 ~ 2025/01/31
  • 対象エンドポイント
    • 勤務時間修正申請の作成 (POST /api/v1/approval_requests/work_times)
    • 勤務時間修正申請の更新 (PUT /api/v1/approval_requests/work_times/{id})
  • 変更内容詳細

APIのリクエストの場合、以下のような変更内容となります。

現行移行期間中移行期間後

clock_in_at / clock_out_at を利用し、1件の勤務時間が設定可能。

{
  “company_id”: 1,
  “target_date”: “string”,
  “clear_work_time”: false,
  “clock_in_at”: “09:00”,
  “clock_out_at”: “18:00”,
  “lateness_mins”: 0,
  “early_leaving_mins”: 0,
  “break_records”: [
    {
      “clock_in_at”: “12:00”,
      “clock_out_at”: “13:00”
    }
  ],
  “comment”: “申請理由”,
  “approval_flow_route_id”: 1,
  “approver_id”: 1
}		clock_in_at / clock_out_at を利用し、1件の勤務時間が設定可能。

{
  “company_id”: 1,
  “target_date”: “string”,
  “clear_work_time”: false,
  “clock_in_at”: “09:00”,
  “clock_out_at”: “18:00”,
  “lateness_mins”: 0,
  “early_leaving_mins”: 0,
  “break_records”: [
    {
      “clock_in_at”: “12:00”,
      “clock_out_at”: “13:00”
    }
  ],
  “comment”: “申請理由”,
  “approval_flow_route_id”: 1,
  “approver_id”: 1
}

work_records を利用し、1件以上の勤務時間を設定可能。
{
  “company_id”: 1,
  “target_date”: “string”,
  “clear_work_time”: false,
  “work_records”: [
    {
      “clock_in_at”: “09:00”,
      “clock_out_at”: “18:00”
    },
    { 
      “clock_in_at”: “19:00”,
      “clock_out_at”: “21:00”
    }
  ],
  “lateness_mins”: 0,
  “early_leaving_mins”: 0,
  “break_records”: [
    {
      “clock_in_at”: “12:00”,
      “clock_out_at”: “13:00”
    }
  ],
  “comment”: “申請理由”,
  “approval_flow_route_id”: 1,
  “approver_id”: 1
}

work_records を利用し、1件以上の勤務時間を設定可能。
{
  “company_id”: 1,
  “target_date”: “string”,
  “clear_work_time”: false,
  “work_records”: [
    {
      “clock_in_at”: “09:00”,
      “clock_out_at”: “18:00”
    },
    { 
      “clock_in_at”: “19:00”,
      “clock_out_at”: “21:00”
    }
  ],
  “lateness_mins”: 0,
  “early_leaving_mins”: 0,
  “break_records”: [
    {
      “clock_in_at”: “12:00”,
      “clock_out_at”: “13:00”
    }
  ],
  “comment”: “申請理由”,
  “approval_flow_route_id”: 1,
  “approver_id”: 1
}

変更内容②

  • 概要
    • 2024年6月にfreee人事労務でリリースされた複数回出退勤機能に伴い、時間表記を48時間形式で返却するためのリクエストパラメーター「use_48h_time_notation」を対象エンドポイントに追加します。
    • 移行期間を設けた上で、「use_48h_time_notation」を廃止し、廃止後は時間表記が48時間形式固定になります。
  • 移行期間
    • 2024/06/11 ~ 2025/01/31
  • 対象エンドポイント
    • 勤務時間修正申請一覧の取得 (GET /api/v1/approval_requests/work_times)
    • 勤務時間修正申請の取得 (GET /api/v1/approval_requests/work_times/{id})
    • 勤務時間修正申請の作成 (POST /api/v1/approval_requests/work_times)
    • 勤務時間修正申請の承認操作 (POST /api/v1/approval_requests/work_times/{id}/actions)
    • 勤務時間修正申請の更新 (PUT /api/v1/approval_requests/work_times/{id})
  • 変更内容詳細
    • 勤務時間修正申請の取得 (GET /api/v1/approval_requests/work_times/{id}) のレスポンス例
      • 申請されている勤務時間修正申請内容
        • 勤務開始時間 21:00 / 勤務終了時間 08:00(翌日) / 休憩開始時間 01:00(翌日) / 休憩終了時間 02:00(翌日)


※ 移行期間を過ぎると24時間形式での表記はできなくなりますのでご注意ください。

現行移行期間中移行期間後
24時間形式のレスポンスを返却
{
  “work_time”: {
    “id”: 1,
    — 中略 —
    “clock_in_at”: “21:00”,
    “clock_out_at”: “08:00”,
    “break_records”: [
      {
        “clock_in_at”: “01:00”,
        “clock_out_at”: “02:00”
      }
    ],
    — 中略 —
  }
}

use_48h_time_notationがtrueの場合は48時間形式のレスポンスを返却
{
  “work_time”: {
    “id”: 1,
    — 中略 —
    “clock_in_at”: “21:00”,
    “clock_out_at”: “32:00”,
    “break_records”: [
      {
        “clock_in_at”: “25:00”,
        “clock_out_at”: “26:00”
      }
    ],
    — 中略 —
  }
}

use_48h_time_notationがfalseの場合は24時間形式のレスポンスを返却
{
  “work_time”: {
    “id”: 1,
    — 中略 —
    “clock_in_at”: “21:00”,
    “clock_out_at”: “32:00”,
    “break_records”: [
      {
        “clock_in_at”: “25:00”,
        “clock_out_at”: “26:00”
      }
    ],
    — 中略 —
  }
}		48時間形式のレスポンスを返却
{
  “work_time”: {
    “id”: 1,
    — 中略 —
    “clock_in_at”: “21:00”,
    “clock_out_at”: “32:00”,
    “break_records”: [
      {
        “clock_in_at”: “25:00”,
        “clock_out_at”: “26:00”
      }
    ],
    — 中略 —
  }
}

変更内容③

  • 概要
    • 2024年6月にfreee人事労務でリリースされた複数回出退勤機能に伴い、複数の出退勤時刻が登録できるリクエストパラメーター「work_record_segments」を対象エンドポイントに追加します。
  • 対象エンドポイント
    • 勤怠の更新（PUT /api/v1/employees/{employee_id}/work_records/{date}）
  • リクエスト例
    • 2024年6月1日に 09:00 ~ 18:00 / 21:00 ~ 22:00 の出退勤で更新する場合


work_record_segments を利用し、1件以上の勤務時間を更新可能。

{
  “company_id”: 1,
  “work_record_segments”: [
    {
      “clock_in_at”: “2024-06-01 09:00:00”,
      “clock_out_at”: “2024-06-01 18:00:00”
    },
    {
      “clock_in_at”: “2024-06-01 21:00:00”,
      “clock_out_at”: “2024-06-01 22:00:00”
    },
  ]
}

※ 既存のclock_in_at / clock_out_at でも勤怠更新は可能です

変更内容④

  • 概要
    • 2024年6月にfreee人事労務でリリースされた複数回出退勤機能に伴い、複数の出退勤時刻情報を返却するためのレスポンスパラメーター「work_records_segsments」を対象エンドポイントに追加します。
  • 対象エンドポイント
    • 勤怠の取得（GET /api/v1/employees/{employee_id}/work_records/{date}）
    • 勤怠の更新（PUT /api/v1/employees/{employee_id}/work_records/{date}）
  • レスポンス例
    • 2024年6月1日に 09:00 ~ 18:00 / 21:00 ~ 22:00 の出退勤が登録されている場合
※ 複数の出退勤が登録されている時、clock_in_at には最初の出勤時刻が入りclock_out_at には最後の退勤時刻が入る。

{
  “company_id”: 1,
  “clock_in_at”: “2024-06-01 09:00:00”,
  “clock_out_at”: “2024-06-01 22:00:00”
  “work_record_segments”: [
    {
      “clock_in_at”: “2024-06-01 09:00:00”,
      “clock_out_at”: “2024-06-01 18:00:00”
    },
    {
      “clock_in_at”: “2024-06-01 21:00:00”,
      “clock_out_at”: “2024-06-01 22:00:00”
    },
  ]
}