予約 API

確定した面接の一覧・詳細・キャンセル。共通規約は API 共通仕様を参照。

ベースパス: /api/v1/projects/{projectId}/reservations

メソッド	パス	概要	必要ロール
GET	`/`	予約一覧取得	viewer
GET	`/{reservationId}`	予約詳細取得	viewer
PATCH	`/{reservationId}/cancel`	予約キャンセル	member

全エンドポイントで Authorization: Bearer <access_token> が必要。PATCH / PUT / DELETE は member 以上。

予約の作成はこのルータにはない

予約は日程確定によって作られる。候補者側からは POST /api/v1/scheduling/{token}/submit-availability → 管理者側の POST /api/v1/projects/{id}/candidates/{cid}/confirm-schedule という流れ。

Reservation オブジェクト

フィールド	型	説明
`id`	integer	予約 ID
`projectId`	integer	プロジェクト ID
`projectCandidateId`	integer	プロジェクト候補者 ID
`interviewerId`	integer	担当面接官のユーザー ID
`scheduledAt`	string(date-time)	面接開始日時
`durationMinutes`	integer	所要時間（分）
`interviewType`	enum	`online_meet` / `online_zoom` / `offline` / `any`
`meetingUrl`	string \| null	会議 URL
`status`	enum	`confirmed` / `cancelled`
`candidate`	object	候補者情報（`id` / `externalUserId` / `email` / `phone` / `name`）
`interviewer`	object	面接官情報（`User`）
`createdAt` / `updatedAt`	string(date-time)	作成／更新日時

予約一覧取得

URI

GET /api/v1/projects/{projectId}/reservations

クエリパラメータ

フィールド	型	必須	既定値	ルール	説明
`page`	integer	-	`1`	正の整数	ページ番号
`limit`	integer	-	`20`	1〜100	件数
`sort`	string	-	-	-	並び順
`status`	enum	-	-	`confirmed` / `cancelled`	ステータスで絞り込み
`startDate`	string	-	-	`YYYY-MM-DD`	この日以降の予約
`endDate`	string	-	-	`YYYY-MM-DD`	この日以前の予約

リクエスト例

GET /api/v1/projects/1/reservations?status=confirmed&startDate=2026-02-01&endDate=2026-02-28

レスポンス（200 OK）

data が Reservation の配列、pagination 付き。

{
  "success": true,
  "status": "success",
  "statusCode": 200,
  "data": [
    {
      "id": 7,
      "projectId": 1,
      "projectCandidateId": 12,
      "interviewerId": 5,
      "scheduledAt": "2026-02-03T01:00:00Z",
      "durationMinutes": 60,
      "interviewType": "online_meet",
      "meetingUrl": "https://meet.google.com/xxx-yyyy-zzz",
      "status": "confirmed",
      "candidate": {
        "id": 100,
        "externalUserId": "1001",
        "email": "yamada@example.com",
        "phone": "090-1234-5678",
        "name": "山田太郎"
      },
      "interviewer": {
        "id": 5,
        "email": "interviewer@example.com",
        "name": "末成",
        "picture": null,
        "role": "member",
        "createdAt": "2026-01-10T09:00:00Z"
      },
      "createdAt": "2026-01-20T09:00:00Z",
      "updatedAt": "2026-01-20T09:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "totalCount": 8, "totalPages": 1, "hasNext": false, "hasPrevious": false },
  "path": "/api/v1/projects/1/reservations",
  "method": "GET"
}

例外処理

説明	ステータスコード	ステータス名
クエリの形式不正	400	Bad Request
トークンが欠落または無効	401	Unauthorized
プロジェクトが存在しない	404	Not Found
サーバ内部エラー	500	Internal Server Error

予約詳細取得

URI

GET /api/v1/projects/{projectId}/reservations/{reservationId}

パスパラメータ

フィールド	ルール
`projectId`	必須。正の整数
`reservationId`	必須。正の整数

レスポンス（200 OK）

data に Reservation。

例外処理

説明	ステータスコード	ステータス名
トークンが欠落または無効	401	Unauthorized
予約が存在しない	404	Not Found
サーバ内部エラー	500	Internal Server Error

予約キャンセル

レコードは削除せず、status を cancelled に更新する。

URI

PATCH /api/v1/projects/{projectId}/reservations/{reservationId}/cancel

リクエスト

ボディなし。

レスポンス（200 OK）

data にキャンセル後の Reservation（status が cancelled）。

例外処理

説明	ステータスコード	ステータス名
トークンが欠落または無効	401	Unauthorized
ロール不足	403	Forbidden
予約が存在しない	404	Not Found
Google Calendar エラー	502	Bad Gateway

副作用

Google Calendar の確定イベントがキャンセルされる
候補者ステータスは cancelled に遷移しうる（scheduled / interviewed からの遷移が許可されている）

PROTOTYPE_MODE

PROTOTYPE_MODE=true の間はカレンダー操作とメール送信がスキップされ、DB の更新のみが行われる。

再確定するには

reservations.project_candidate_id は UNIQUE のため、キャンセル済みの予約が残っている候補者に対して新しい予約を作る際は、既存レコードの扱いに注意が必要になる。