有料向け開発者 API リファレンス

許容値

• 省略: 受理される（最新の挙動）。
• 指定する場合は "2026-04-01"（PUBLIC_SCHEDULE_API_VERSION）のみ。
• それ以外の文字列は拒否（TYPE_ERROR）。

挙動

• sanitizeApiVersion でサポート版と照合。

代表エラー

• TYPE_ERROR未サポートの apiVersion。

許容値

• JSON 上は 1 つの文字列。スキーマ上「許可値をすべて列挙した enum 型」としては提供していません（ゾーン数が多く、IANA の更新にも追随する必要があるため）。サーバー側で動的に妥当性を検証します。
• 実装はコードベースの `isValidIanaTimeZone` と同じで、Luxon の `DateTime.now().setZone(zone).isValid` が true になる必要があります。
• IANA タイムゾーンデータベースの正規の識別子を使ってください。例: `Asia/Tokyo`, `America/New_York`, `Europe/Berlin`, `UTC`。有効な集合は、デプロイ環境の Luxon が解釈できる IANA 名に依存します。
• `EST` や `JST` などの略称だけは IANA の安定したゾーン ID ではないため、避けてください（拒否されることがあります）。
• 一覧の参照先の例: IANA の配布物（https://www.iana.org/time-zones）や、利用言語・OS のタイムゾーン API。

挙動

• 日付・スロットの解釈に使用します。
• クライアント側で固定リストが必要な場合は、同じ前提（IANA の識別子）で自前の一覧を生成するのが適切で、サーバーが JSON Schema に enum を返す前提にはしないでください。

代表エラー

• INVALID_TIME_ZONE欠落・空・無効な IANA 名。

許容値

• /^\d{4}-\d{2}-\d{2}$/ に一致（トリム後）。
• 実在する暦日であり、enumerateDates で少なくとも 1 日が得られること。
• 期間の日数が maxScheduleDays 以下であること（有料 API では 2 週間詳細予測で最大 14 暦日が目安。実際はテナントのエンタイトルメント）。

挙動

• scheduleStartDate ≤ scheduleEndDate。

代表エラー

• INVALID_DATE_RANGE形式不正・無効な日付・空の範囲など。
• SCHEDULE_SPAN_TOO_LONGmaxScheduleDays を超える日数。

許容値

• 空でない文字列（トリム）。UI と同じ `enumerateSlotsByGranularity` で解釈。
• 組み合わせにより少なくとも 1 つのスロットが生成されること。

挙動

• slotGranularityMinutes と合わせて cellKey の slotId を決定。

代表エラー

• INVALID_TIME_RANGE欠落、またはスロット 0 本。

許容値

• 数値として正確に 60 または 15（文字列不可）。
• かつ allowedGranularities に含まれること。有料 API では通常 60 と 15 の両方が有効。テナントで 15 が無効な場合は INVALID_GRANULARITY。

挙動

• 時刻範囲と合わせてスロット本数を決定。

代表エラー

• INVALID_GRANULARITY60/15 以外、またはプラン不許可。

許容値

• プレーンな JSON オブジェクト（配列不可）。
• 各キーは（日付×slotId）で計算したグリッド上の cellKey であること。未知キーは UNKNOWN_CELL_KEY。
• 各値は JSON の number で整数かつ 0〜15。
• 省略セルは 0 相当。SHORTFALL 判定では必要人数が 1 以上のセルが対象。

挙動

• キーは sanitizeCellKey（trim）後に照合。

代表エラー

• INVALID_REQUIREMENTSオブジェクトでない、または数値が不正。
• UNKNOWN_CELL_KEYグリッド外のキー。

許容値

• 要素数は 1〜maxStaffPerSchedule（POST /v1/schedule 既定 500。POST /v1/staff の名簿上限とは別）。
• 各要素はプレーンオブジェクト。許可キーは厳格モードで staffId, displayName, availableCells のみ。
• staffId / displayName はサニタイズを通過する必要がある（サニタイズ節参照）。
• staffId は配列内で重複不可（DUPLICATE_STAFF_ID）。

挙動

• 並び順は保持され、可否集計に使われる。

代表エラー

• INVALID_STAFF空配列、超過、不正オブジェクト、サニタイズ失敗など。
• UNKNOWN_FIELD厳格モードで staff 行に未知キー。
• DUPLICATE_STAFF_IDstaffId の重複。

許容値

• 省略: そのスタッフはグリッド上の全セルで勤務可（内部では null 扱い）。
• 指定時: JSON 配列。各要素は空でない文字列であり、計算グリッド上の cellKey であること。
• 空文字列の要素は INVALID_AVAILABLE_CELL。

SHORTFALL 検証

• 必要人数が 1 以上の各セルで、そのセルに出勤可能と数えられるスタッフ数が必要人数以上であること。

代表エラー

• INVALID_AVAILABLE_CELL未知のセルキーまたは空要素。
• SHORTFALL_CELLS必要人数に対して勤務可能人数が不足。

親行に保存される内容（概要）

• トップレベルは ROOT_KEYS のみ、スタッフ行は STAFF_KEYS のみ。laborLawJurisdiction / usLaborStateCode / laborModelVersion / paidOptimization は送らない。
• 投入時、サーバーは親 SCHEDULE_CONDITION に共有既定を設定する。paidOptimization は DEFAULT_PAID_OPTIMIZATION — laborLawCompliance は false、balanceStaffLoad / honorShiftWishes / preferConsecutiveShifts は true（schedule-defaults-shared.ts および build-schedule-transact-items.ts）。laborLawJurisdiction は JP、usLaborStateCode は GENERIC、laborModelVersion は v1。
• オプティマイザの法令近似制約は親と各スタッフの laborLawCompliance がともに真のときに限る。本 API 経路では既定でオフのため、本文だけでは法令ベースの上限は有効にならない。
• モデルはスケジューリング用の近似であり法的助言ではない。カタログ: optimizer/config/labor_models.json。

ドキュメント

• 詳細: docs/data-and-api/PUBLIC_API_SCHEDULE_REQUEST_BODY.md の §2.1.1 と §3.1。

不許可キーを送った場合

• UNKNOWN_FIELD厳格モードでルートまたは staff 行の未知プロパティを拒否。