定期予約・出欠・キャンセル待ちAPI の使い方

予約そのものの操作は 予約管理API をご覧ください。

定期予約（Series）

「毎週火曜19時」のような繰り返しの予約です。定期予約は予定を保持するだけで、予約そのものは持ちません。実際の予約は、すでに存在する予約枠に対して生成されます。店舗が用意していないクラスの予約が勝手に作られることはありません。

登録と生成

POST /api/v1/reservations/series
Authorization: Bearer {token}
Content-Type: application/json

{
  "storeId": "store-001",
  "customerName": "山田 花子",
  "dayOfWeek": "Tuesday",
  "startTime": "19:00",
  "startDate": "2026-09-01",
  "skipDates": "2026-09-22,2026-12-29"
}

dayOfWeek は英語の曜日名、startTime は HH:mm です。skipDates にはお休みの日を yyyy-MM-dd 形式でカンマ区切りに並べます。

登録しただけでは予約は作られません。generate に throughDate を指定して、どこまで先の予約を作るかを決めてください。

{
  "seriesId": "series-001",
  "created": 8,
  "skipped": 2,
  "unavailable": 1,
  "reservationIds": ["res-001", "res-002"]
}

作れなかった週は理由ごとに分けて数えます。skipped はお休み指定や作成済みなど意図的に飛ばした週、unavailable は予約枠がない、または満席だった週です。後者は店舗側の対応が必要なので、区別して扱ってください。

繰り返し実行しても、すでに予約のある週が二重に予約されることはありません。

終了

cancelFuture=true を付けると、生成済みでまだ来ていない予約もキャンセルします。過去の予約は変更しません。

出欠と振替（Attendance）

出欠はクラス単位で記録します。1人ずつではなく、10人のクラスを1回の呼び出しでまとめて記録できます。

POST /api/v1/reservations/attendance/record
Authorization: Bearer {token}
Content-Type: application/json

{
  "storeId": "store-001",
  "entries": [
    { "reservationId": "res-001", "outcome": "Attended" },
    { "reservationId": "res-002", "outcome": "Excused" },
    { "reservationId": "res-003", "outcome": "NoShow" }
  ]
}

outcome は Attended（出席）、Excused（欠席・振替対象）、NoShow（無断欠席）のいずれかです。記録し直しても構いません。間違いの訂正に別のエンドポイントを使わせないためです。レスポンスの changed は実際に変わった件数で、同じ内容を再送すると 0 になります。

出欠の読み取りについての注意

出席簿の attendance は保存された値をそのまま返しているわけではありません。出席は「来店済み」の予約として、欠席と無断欠席はどちらも「無断キャンセル」の予約として保存され、両者は振替が付与されたかどうかでしか区別されません。

そのため振替制度を使っていない店舗では、欠席と無断欠席が同じ形で記録され、あとから区別できません。その場合は NoShow として返します。推測した値を返すより、保存されている事実を返すほうが確実だからです。

集計

attendanceRate は実際に行われたクラスだけを対象にします。これから先の予約を欠席として数えると、入会したばかりのお客様が一律に低い出席率になってしまうためです。対象がない場合は null を返します。

キャンセル待ち（Waitlist）

キャンセル待ちは予約ではなく、席を確保しません。空きが出たときに順番にご案内するための記録です。

予約枠ごとの応答には waiting（待機中の組数）、offered（ご案内済みで返答待ちの組数）、waitingCovers（待機中の人数合計）が含まれます。もう一回転増やすかどうかを判断するのは人数のほうなので、組数と分けて返しています。

空席のご案内について

空席が出たときのご案内は、APIからは実行できません。予約がキャンセルされた時点で自動的に行われます。

ご案内には、店舗がキャンセル待ちを有効にしていること、そしてその予約枠が休講・貸切でないことという条件があります。この確認を経ずにご案内を送ると、荒天で一括キャンセルした日に待機列の全員へ「空きが出ました」と通知してしまい、予約画面では受け付けられない、という事態になります。そのため手動で実行する口は用意していません。

OpenAPI定義

リクエスト・レスポンスの詳細は APIリファレンス と /openapi/v1.json をご覧ください。

関連ガイド

• 予約管理API（Reservations API）の使い方
• 通い放題プラン・回数券API の使い方
• 在庫・リソース・予約分析API の使い方