有料 API · 契約プラン

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

有料契約に紐づく API キーでスケジュール投入 API に連携します。テナントのスケジュール既定は PATCH /v1/schedule-defaults で保存でき、スタッフごとの週次希望は GET / PUT /v1/staff/{staffId}/weekly-shift-wish で取得・全置換更新できます。請求はサブスクリプションおよび契約プランに基づきます（API 呼び出し回数に応じた追加課金は行いません）。許容値・検証・エラーコードを掲載し、サイドバーの検索でフィールドへジャンプできます。

本ページが記載するのは、外部連携用の製品 REST API（API Gateway の {stage}/v1/*、認証は x-api-key）です。

スケジュール結果の完了通知 Webhook は、REST の CRUD ではなく、アカウントの API 管理画面で登録するアウトバウンド HTTP 通知です。ペイロードと署名の仕様は本ページの「完了通知 Webhook」を参照してください。

サイト内のブラウザ向けルート（例: 決済コールバックや計測用のパス）は、この製品 API の代替ではありません。外部システムからは本ページの /v1/* と完了通知 Webhook を利用してください。

本 HTTP API は有料プロダクトの一部です。利用には商用契約が有効であることと、オンボーディング後に組織向けにキーが発行されることを前提とします。

課金は契約プラン（サブスクリプション）に基づきます。有料プランの請求額は料金表に従い、登録スタッフ数（席）に比例する月額になり得ます。

プレイグラウンド／無料枠の制限は有料 API キーには適用されません。スケジュール日数・スタッフ数・15 分粒度の有効などは、有料エンタイトルメントで決まります。詳細は本ページの有料枠の上限を参照してください。

有料契約に基づき発行された API キーをリクエストに含めてください。キーの作成・ローテーション・失効はサインイン後のアカウント画面から行えます。

キーは x-api-key ヘッダで送ります。キーは組織に紐づき、契約プランに基づく利用上限が適用されます。

キーの管理: API 管理

スケジュール条件を JSON で投入する有料向け連携面です。ベース URL は API アクセスが付与されたあと、環境ごとに案内されます。

POST {baseUrl}/v1/schedule

ベース URL の具体値は、開通時または運用担当者から案内されたものを使用してください。

**BASE_URL** には、開通時に案内された API のベース URL（パスのプレフィックス）を入れてください。

API キーは **x-api-key** ヘッダで送ります。キーに紐づく組織（テナント）が自動的に識別されるため、別途テナント ID をクエリで渡す必要はありません。

有料機能（緊急シフト・労務詳細・一部のスケジュール既定など）は有効な有料契約が必要です。契約が未設定・無効な場合は **503**（code: **STRIPE_NOT_CONFIGURED** 等）になることがあります。会社情報・監査ログ・ユーザー管理は Web アプリ管轄のため公開 API には含めません。

curl の例（bash / macOS / Linux / WSL）

Windows PowerShell: 行末の \ は **行継続になりません**。1 行で書くか、行末を **バッククォート（`）** で続けてください。

curl -sS -D - \
  -H "x-api-key: YOUR_API_KEY" \
  "BASE_URL/v1/schedule-results?limit=10"

curl -sS -D - \
  -H "x-api-key: YOUR_API_KEY" \
  "BASE_URL/v1/staff"

POST /v1/schedule と同じベース URL・同じ x-api-key を使用します。クエリは任意: limit（1〜100、既定 50）、cursor（直前の応答の nextCursor をそのまま渡す不透明トークン）。

GET{baseUrl}/v1/schedule-results
SCHEDULE_RESULT 親行の一覧（conditionId、status、candidateCount、createdAt/updatedAt など）。DynamoDB 親行のページング用。
GET{baseUrl}/v1/schedule-results/history
スケジュール結果の履歴検索（ブラウザの履歴確認と同等）。from / to（ISO 8601、省略時はサービス開始日〜現在）、keyword、eventName（INSERT,MODIFY,REMOVE のカンマ区切り）、limit、cursor。直近とアーカイブを自動統合し items / nextCursor のみ返す。
GET{baseUrl}/v1/schedule-results/{conditionId}
conditionId で SCHEDULE_RESULT 親行を1件取得（PK/SK を除く属性を JSON で返す）。
GET{baseUrl}/v1/schedule-results/{conditionId}/resolution
最適化結果の解決済みペイロード（status、candidates、確定割当があれば含む）。status が completed で未確定のとき、この GET で rank1 が自動確定される場合があります（副作用あり）。手動確定は POST …/confirm-assignments を使用。
GET{baseUrl}/v1/schedule-results/{conditionId}/review
手動確定用レビューペイロード（候補・requiredByCellKey・スタッフの allowedCellKeys 等）。
GET{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift-context
緊急シフト用コンテキスト（暦日・スタッフ・スロット一覧）。有料契約が必要。条件が無いときは null。
GET{baseUrl}/v1/schedule-conditions
SCHEDULE_CONDITION 親行の一覧（conditionId・期間・取り消し時刻など）。
GET{baseUrl}/v1/schedule-conditions/{conditionId}
条件の親行＋ REQ 日次＋ STAFF スナップショット（PK/SK 除去）。
GET{baseUrl}/v1/schedule-defaults
テナントのスケジュール既定行（未保存なら null）。
GET{baseUrl}/v1/schedule-actual/{conditionId}
実績シフト（SCHEDULE_ACTUAL）行、無ければ null。
GET{baseUrl}/v1/staff/{staffId}/weekly-shift-wish
スタッフの週次希望シフト行、無ければ null。
GET{baseUrl}/v1/staff
テナントのアクティブなスタッフ一覧（表示名でソート）。
GET{baseUrl}/v1/staff/{staffId}
staffId で1件取得（laborLawCompliance、laborFlsaExempt、個人上限、laborConstraintMask 等の労務詳細を含む。論理削除済みは 404）。

メソッド	パス	説明
GET	{baseUrl}/v1/schedule-results	SCHEDULE_RESULT 親行の一覧（conditionId、status、candidateCount、createdAt/updatedAt など）。DynamoDB 親行のページング用。
GET	{baseUrl}/v1/schedule-results/history	スケジュール結果の履歴検索（ブラウザの履歴確認と同等）。from / to（ISO 8601、省略時はサービス開始日〜現在）、keyword、eventName（INSERT,MODIFY,REMOVE のカンマ区切り）、limit、cursor。直近とアーカイブを自動統合し items / nextCursor のみ返す。
GET	{baseUrl}/v1/schedule-results/{conditionId}	conditionId で SCHEDULE_RESULT 親行を1件取得（PK/SK を除く属性を JSON で返す）。
GET	{baseUrl}/v1/schedule-results/{conditionId}/resolution	最適化結果の解決済みペイロード（status、candidates、確定割当があれば含む）。status が completed で未確定のとき、この GET で rank1 が自動確定される場合があります（副作用あり）。手動確定は POST …/confirm-assignments を使用。
GET	{baseUrl}/v1/schedule-results/{conditionId}/review	手動確定用レビューペイロード（候補・requiredByCellKey・スタッフの allowedCellKeys 等）。
GET	{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift-context	緊急シフト用コンテキスト（暦日・スタッフ・スロット一覧）。有料契約が必要。条件が無いときは null。
GET	{baseUrl}/v1/schedule-conditions	SCHEDULE_CONDITION 親行の一覧（conditionId・期間・取り消し時刻など）。
GET	{baseUrl}/v1/schedule-conditions/{conditionId}	条件の親行＋ REQ 日次＋ STAFF スナップショット（PK/SK 除去）。
GET	{baseUrl}/v1/schedule-defaults	テナントのスケジュール既定行（未保存なら null）。
GET	{baseUrl}/v1/schedule-actual/{conditionId}	実績シフト（SCHEDULE_ACTUAL）行、無ければ null。
GET	{baseUrl}/v1/staff/{staffId}/weekly-shift-wish	スタッフの週次希望シフト行、無ければ null。
GET	{baseUrl}/v1/staff	テナントのアクティブなスタッフ一覧（表示名でソート）。
GET	{baseUrl}/v1/staff/{staffId}	staffId で1件取得（laborLawCompliance、laborFlsaExempt、個人上限、laborConstraintMask 等の労務詳細を含む。論理削除済みは 404）。

同じ API キーで JSON ボディを送ります。PATCH /v1/schedule-defaults はテナント全体の営業既定（requirementsByCellKey・計画ホライズン等）を保存します。有料項目は契約プランに応じて反映されます。PUT /v1/staff/{staffId}/weekly-shift-wish は当該スタッフの週次希望を全置換します（検証の注意は下記）。POST /v1/staff は、契約人数上限を超える場合 409（STAFF_LIMIT）を返します。ユーザー（アカウント）・会社情報・監査ログは Web アプリ管轄のため公開 API には含めません。

POST /v1/staff は JSON { "displayName": "..." } のみ。PATCH /v1/staff/{staffId} は displayName、laborLawCompliance、laborFlsaExempt、personalMaxWeeklyMinutes / personalMaxMonthlyMinutes / personalMaxThreeMonthMinutes（整数または null でクリア）、laborConstraintMask（オブジェクトまたは null、laborLawCompliance が true のときのみ）を任意組み合わせで送信（労務項目は有料契約が必要）。POST /v1/schedule-results/{conditionId}/emergency-shift は absentStaffIds・absentDatesYmd および/または absentSlots（有料・参照シフト完了済みが前提）。POST …/confirm-assignments は assignments 配列と任意の relaxAvailability。PATCH /v1/schedule-defaults のボディは docs/data-and-api/PUBLIC_API_SCHEDULE_REQUEST_BODY.md §12。PUT /v1/staff/{staffId}/weekly-shift-wish は scheduleStartDate, scheduleEndDate, timeRangeStart, timeRangeEnd, wishByCellKey を送ります。

PATCH{baseUrl}/v1/schedule-defaults
テナントのスケジュール既定を保存（ボディは schedule-defaults-actions の saveSchema と同一）。有料項目は契約プランに応じて反映されます。
POST{baseUrl}/v1/staff
スタッフを作成（displayName）。201 と staff JSON。
POST{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift
完了済み参照シフトを複製し欠勤を反映した新 condition を作成（201 と conditionId）。有料契約が必要。
POST{baseUrl}/v1/schedule-results/{conditionId}/confirm-assignments
最適化候補の手動編集結果を検証し確定割当を保存（200 と { ok: true }）。
PATCH{baseUrl}/v1/staff/{staffId}
スタッフの表示名・労務詳細（laborLawCompliance、laborFlsaExempt、個人上限、laborConstraintMask）を更新。
DELETE{baseUrl}/v1/staff/{staffId}
スタッフを論理削除（deletedAt を設定）。
DELETE{baseUrl}/v1/schedule-conditions/{conditionId}
条件を取り消し（publicApiCancelledAt）。子行は削除しない。
PUT{baseUrl}/v1/schedule-actual/{conditionId}
実績割当を保存 JSON { "assignments": [ ... ] }。
PUT{baseUrl}/v1/staff/{staffId}/weekly-shift-wish
週次希望を全置換（1〜7 日のフルグリッド、wishByCellKey。粒度はテナント既定に追随）。

メソッド	パス	説明
PATCH	{baseUrl}/v1/schedule-defaults	テナントのスケジュール既定を保存（ボディは schedule-defaults-actions の saveSchema と同一）。有料項目は契約プランに応じて反映されます。
POST	{baseUrl}/v1/staff	スタッフを作成（displayName）。201 と staff JSON。
POST	{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift	完了済み参照シフトを複製し欠勤を反映した新 condition を作成（201 と conditionId）。有料契約が必要。
POST	{baseUrl}/v1/schedule-results/{conditionId}/confirm-assignments	最適化候補の手動編集結果を検証し確定割当を保存（200 と { ok: true }）。
PATCH	{baseUrl}/v1/staff/{staffId}	スタッフの表示名・労務詳細（laborLawCompliance、laborFlsaExempt、個人上限、laborConstraintMask）を更新。
DELETE	{baseUrl}/v1/staff/{staffId}	スタッフを論理削除（deletedAt を設定）。
DELETE	{baseUrl}/v1/schedule-conditions/{conditionId}	条件を取り消し（publicApiCancelledAt）。子行は削除しない。
PUT	{baseUrl}/v1/schedule-actual/{conditionId}	実績割当を保存 JSON { "assignments": [ ... ] }。
PUT	{baseUrl}/v1/staff/{staffId}/weekly-shift-wish	週次希望を全置換（1〜7 日のフルグリッド、wishByCellKey。粒度はテナント既定に追随）。

最適化（スケジュール結果）が終端状態になったとき、登録した HTTPS URL へ署名付き JSON を POST します。結果本文は含めません。詳細は公開 API（GET /v1/schedule-results/{conditionId}）で取得してください。

プレイグラウンドの結果は対象外です。通知が無効、または URL 未設定のときは送信しません。

設定手順

サインイン後、API 管理で HTTPS の通知先 URL を保存する。
「通知を有効にする」をオンにする。
表示された署名シークレットを控える（再表示不可。紛失時は再生成）。
受信側で署名を検証し、必要なら links.result を API キー付きで GET する。

イベント

送信される type とタイミングです。

schedule.result.terminal
スケジュール結果が completed / no_solution / failed / error / canceled などに更新されたとき

type	タイミング
schedule.result.terminal	スケジュール結果が completed / no_solution / failed / error / canceled などに更新されたとき

リクエストボディ

status は終端値のみ。customerId はボディに含めません。

{
  "type": "schedule.result.terminal",
  "conditionId": "019ee481-e855-7000-abd8-977cbfd64ffc",
  "status": "completed",
  "occurredAt": "2026-07-16T13:00:54.694Z",
  "links": {
    "result": "{baseUrl}/v1/schedule-results/019ee481-e855-7000-abd8-977cbfd64ffc"
  }
}

リクエストヘッダ

Content-Type
application/json
User-Agent
AutoScheduler-Webhook/1.0
X-AutoScheduler-Timestamp
Unix 秒（文字列）
X-AutoScheduler-Signature
v1=<hex>（下記の署名）

ヘッダ	説明
Content-Type	application/json
User-Agent	AutoScheduler-Webhook/1.0
X-AutoScheduler-Timestamp	Unix 秒（文字列）
X-AutoScheduler-Signature	v1=<hex>（下記の署名）

署名検証

受信した生ボディ（パース前）と Timestamp からダイジェストを計算し、Signature と比較します。|現在時刻 − timestamp| が 300 秒（5 分）を超えるリクエストは拒否してください（より広いずれが必要な場合を除く）。

HMAC-SHA256(signingSecret, `${timestamp}.${rawBody}`) → hex。ヘッダ値は v1=<hex>

リトライ

5xx やタイムアウト時は自動で再送します。繰り返し失敗すると配信は停止し、運用側のデッドレターに残ります。ブラウザ向けの完了通知とは別経路です。

登録・有効化: API 管理

x-api-key
有料契約に紐づく API キー（テナントと利用上限の識別に使用）。
Content-Type
application/json

ヘッダ	説明
x-api-key	有料契約に紐づく API キー（テナントと利用上限の識別に使用）。
Content-Type	application/json

応答ヘッダについて

リクエスト ID など、一部の応答ヘッダはトレース用のメタデータです。API キーそのものではありません。機密性の高いのは主に JSON **ボディ**（会社・ユーザー情報など）です。

契約プランに応じた検証上限の目安です（15 分粒度・期間・登録スタッフ数など）。

課金モデル
Stripe サブスクリプション。プロダクトの請求は料金表に従い、登録スタッフ数（席）に比例する月額になり得ます（API 呼び出し回数に応じた追加課金は行いません）。
maxScheduleDays
標準の有料 2 週間詳細予測では、1 リクエストあたり最大 14 暦日（契約でさらに広げる場合のみ）。
maxStaffPerSchedule
POST /v1/schedule の staff 配列は最大 500 行（PUBLIC_SCHEDULE_MAX_STAFF。リクエスト本文のインライン staffId）。
maxRosterStaff
POST /v1/staff の名簿登録は現行アプリ既定で最大 30 名（STAFF_ROSTER_MAX_PAID）。超過時は 409 STAFF_LIMIT。
allowedGranularities
[60, 15] — 15 分は有料機能。60 分（時刻単位）も利用可能。
maxPayloadBytes
524288（512 KiB）、特別な上限がない限り UTF-8 バイト長で計測。
strictUnknownRootKeys
true — 未知のトップレベルまたは staff 内のキーは拒否

項目	有料 API（目安）
課金モデル	Stripe サブスクリプション。プロダクトの請求は料金表に従い、登録スタッフ数（席）に比例する月額になり得ます（API 呼び出し回数に応じた追加課金は行いません）。
maxScheduleDays	標準の有料 2 週間詳細予測では、1 リクエストあたり最大 14 暦日（契約でさらに広げる場合のみ）。
maxStaffPerSchedule	POST /v1/schedule の staff 配列は最大 500 行（PUBLIC_SCHEDULE_MAX_STAFF。リクエスト本文のインライン staffId）。
maxRosterStaff	POST /v1/staff の名簿登録は現行アプリ既定で最大 30 名（STAFF_ROSTER_MAX_PAID）。超過時は 409 STAFF_LIMIT。
allowedGranularities	[60, 15] — 15 分は有料機能。60 分（時刻単位）も利用可能。
maxPayloadBytes	524288（512 KiB）、特別な上限がない限り UTF-8 バイト長で計測。
strictUnknownRootKeys	true — 未知のトップレベルまたは staff 内のキーは拒否

セルごとの必要人数は 0 以上 15 以下の整数です。リクエスト頻度の上限を超えた場合はエラーが返ることがあります。

厳格モードでは次のトップレベルキーのみ受理されます。それ以外は UNKNOWN_FIELD になります。

apiVersion
timeZone
scheduleStartDate
scheduleEndDate
timeRangeStart
timeRangeEnd
slotGranularityMinutes
requirementsByCell
staff

有料向けの公開スケジュール投入モデルに従います。暦日・タイムゾーン・スロット列（有料 API では 60 分または 15 分）・セルごとの必要人数・スタッフの可否を含みます。労働法管轄・有料オプション・スタッフ行の労働フラグは JSON には含めず、サーバーが既定値を適用します（「労働法・有料フラグ（サーバー既定）」を参照）。内部向けの識別子や未公開フィールドを本文に含めないでください。

apiVersion — 任意。指定する場合はサポートされているスキーマのバージョン文字列のみ。
cellKey の形式 — requirementsByCell と availableCells のキーは、対象期間の日付と、時刻範囲・粒度から列挙された slotId を使った `${date}__${slotId}` と一致している必要があります（playground の `cellKey` と同じ規約）。

timeZone
型
string
必須
はい
日付・スロット解釈に使う IANA タイムゾーン。
scheduleStartDate / scheduleEndDate
型
string (YYYY-MM-DD)
必須
はい
対象期間（暦日）。開始 ≤ 終了。
timeRangeStart / timeRangeEnd
型
string (HH:mm)
必須
はい
スロット列を定義する壁時計の範囲。1 本以上のスロットが生成されること。
slotGranularityMinutes
型
60 | 15
必須
はい
有料 API: 60（時単位）または 15（15 分）。allowedGranularities に含まれること。
requirementsByCell
型
object
必須
はい
キーは計算されたグリッド上の cellKey。値は 0〜15 の整数。
staff
型
array
必須
はい
空でない配列。上限は limits 参照。各要素: staffId, displayName, 任意の availableCells。

フィールド	型	必須	備考
timeZone	string	はい	日付・スロット解釈に使う IANA タイムゾーン。
scheduleStartDate / scheduleEndDate	string (YYYY-MM-DD)	はい	対象期間（暦日）。開始 ≤ 終了。
timeRangeStart / timeRangeEnd	string (HH:mm)	はい	スロット列を定義する壁時計の範囲。1 本以上のスロットが生成されること。
slotGranularityMinutes	60 \| 15	はい	有料 API: 60（時単位）または 15（15 分）。allowedGranularities に含まれること。
requirementsByCell	object	はい	キーは計算されたグリッド上の cellKey。値は 0〜15 の整数。
staff	array	はい	空でない配列。上限は limits 参照。各要素: staffId, displayName, 任意の availableCells。

フィールドリファレンス（許容値）

以下は `app/lib/public-schedule-api/validate.ts` の検証および `sanitize.ts` の処理に沿った説明です。既定は `PUBLIC_SCHEDULE_SUBMIT_DEFAULTS`（有料版）です。数値は JSON の number 型で送ってください（文字列の "60" 等は型エラーになります）。検証後、`build-schedule-transact-items.ts` がリクエストキーではない親行フィールド（有料オプションのコピー・労働法管轄・モデル版など）を付与します。詳細は「労働法・有料フラグ（サーバー既定）」を参照。

許容値

省略: 受理される（最新の挙動）。
指定する場合は "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 行の未知プロパティを拒否。

`sanitize.ts` で実装されているとおり、検証前後で適用されます。INVALID_STAFF の原因の多くはここに該当します。

staffId

トリム。長さ 1〜128。
許容文字: /^[a-zA-Z0-9._-]+$/（スラッシュ・バックスラッシュ不可）。

displayName

制御文字・ゼロ幅除去、空白の圧縮、トリム。
山括弧 < > は不可。
最大 128 文字。空になったら不正。

セルキー（requirements / availableCells）

キーは trim 後、計算されたグリッドの cellKey と完全一致する必要がある。

202 Accepted

本文が検証を通過し条件の書き込みが行われた状態。以降の最適化は非同期で継続する場合があります。本文に conditionId 等が含まれる場合があります。

検証エラーは安定した `code` を返します。検証前に JSON パースが走ります（INVALID_JSON, PAYLOAD_TOO_LARGE）。永続化失敗は DYNAMODB_ERROR などハンドラ依存で返る場合があります。スケジュール既定の PATCH は Zod や業務ルール失敗時に HTTP 400 と SCHEDULE_DEFAULTS_SAVE_FAILED（details に内訳）を返すことがあります。

INVALID_JSON
JSON として解析できない。
PAYLOAD_TOO_LARGE
UTF-8 バイト長が maxPayloadBytes（既定 512 KiB）超過。
TYPE_ERROR
JSON 型が不正、または未サポートの apiVersion 文字列。
UNKNOWN_FIELD
厳格モード: ルートまたは staff 行に不許可のプロパティ。
INVALID_TIME_ZONE
timeZone 欠落または IANA として無効。
INVALID_DATE_RANGE
日付形式不正、範囲不正、列挙が空。
SCHEDULE_SPAN_TOO_LONG
開始〜終了の日数が maxScheduleDays を超過。
INVALID_TIME_RANGE
時刻範囲欠落、またはスロット 0 本。
INVALID_GRANULARITY
60/15 以外、またはプラン不許可。
INVALID_REQUIREMENTS
requirementsByCell がオブジェクトでない、または 0〜15 以外の数値。
UNKNOWN_CELL_KEY
計算されたスケジュールグリッドにないキー。
INVALID_STAFF
staff が空・超過・行不正・サニタイズ失敗など。
DUPLICATE_STAFF_ID
staffId の重複。
INVALID_AVAILABLE_CELL
availableCells の空要素または未知キー。
SHORTFALL_CELLS
必要人数に対して勤務可能人数が不足。
DYNAMODB_ERROR
検証後の永続化などで失敗（ハンドラ依存）。
SCHEDULE_DEFAULTS_SAVE_FAILED
PATCH /v1/schedule-defaults：検証または業務ルール失敗（error.details 参照）。
LABOR_COMPLIANCE_REQUIRED
PATCH /v1/staff/{staffId}：laborLawCompliance が false のとき laborConstraintMask を送信した。

コード	意味
INVALID_JSON	JSON として解析できない。
PAYLOAD_TOO_LARGE	UTF-8 バイト長が maxPayloadBytes（既定 512 KiB）超過。
TYPE_ERROR	JSON 型が不正、または未サポートの apiVersion 文字列。
UNKNOWN_FIELD	厳格モード: ルートまたは staff 行に不許可のプロパティ。
INVALID_TIME_ZONE	timeZone 欠落または IANA として無効。
INVALID_DATE_RANGE	日付形式不正、範囲不正、列挙が空。
SCHEDULE_SPAN_TOO_LONG	開始〜終了の日数が maxScheduleDays を超過。
INVALID_TIME_RANGE	時刻範囲欠落、またはスロット 0 本。
INVALID_GRANULARITY	60/15 以外、またはプラン不許可。
INVALID_REQUIREMENTS	requirementsByCell がオブジェクトでない、または 0〜15 以外の数値。
UNKNOWN_CELL_KEY	計算されたスケジュールグリッドにないキー。
INVALID_STAFF	staff が空・超過・行不正・サニタイズ失敗など。
DUPLICATE_STAFF_ID	staffId の重複。
INVALID_AVAILABLE_CELL	availableCells の空要素または未知キー。
SHORTFALL_CELLS	必要人数に対して勤務可能人数が不足。
DYNAMODB_ERROR	検証後の永続化などで失敗（ハンドラ依存）。
SCHEDULE_DEFAULTS_SAVE_FAILED	PATCH /v1/schedule-defaults：検証または業務ルール失敗（error.details 参照）。
LABOR_COMPLIANCE_REQUIRED	PATCH /v1/staff/{staffId}：laborLawCompliance が false のとき laborConstraintMask を送信した。

{
  "apiVersion": "2026-04-01",
  "timeZone": "Asia/Tokyo",
  "scheduleStartDate": "2026-04-07",
  "scheduleEndDate": "2026-04-13",
  "timeRangeStart": "08:00",
  "timeRangeEnd": "20:00",
  "slotGranularityMinutes": 60,
  "requirementsByCell": {
    "2026-04-07__slot-0": 2
  },
  "staff": [
    {
      "staffId": "550e8400-e29b-41d4-a716-446655440000",
      "displayName": "Example",
      "availableCells": ["2026-04-07__slot-0"]
    }
  ]
}

参照. リクエスト本文の詳細は docs/data-and-api/PUBLIC_API_SCHEDULE_REQUEST_BODY.md を参照してください（POST /v1/schedule §1–§11、テナント既定 PATCH §12、スタッフ労務 PATCH §13、履歴 GET §14）。

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

メソッド

パス

説明

GET

{baseUrl}/v1/schedule-results

SCHEDULE_RESULT 親行の一覧（conditionId、status、candidateCount、createdAt/updatedAt など）。DynamoDB 親行のページング用。

GET

{baseUrl}/v1/schedule-results/history

スケジュール結果の履歴検索（ブラウザの履歴確認と同等）。from / to（ISO 8601、省略時はサービス開始日〜現在）、keyword、eventName（INSERT,MODIFY,REMOVE のカンマ区切り）、limit、cursor。直近とアーカイブを自動統合し items / nextCursor のみ返す。

GET

{baseUrl}/v1/schedule-results/{conditionId}

conditionId で SCHEDULE_RESULT 親行を1件取得（PK/SK を除く属性を JSON で返す）。

GET

{baseUrl}/v1/schedule-results/{conditionId}/resolution

最適化結果の解決済みペイロード（status、candidates、確定割当があれば含む）。status が completed で未確定のとき、この GET で rank1 が自動確定される場合があります（副作用あり）。手動確定は POST …/confirm-assignments を使用。

GET

{baseUrl}/v1/schedule-results/{conditionId}/review

手動確定用レビューペイロード（候補・requiredByCellKey・スタッフの allowedCellKeys 等）。

GET

{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift-context

緊急シフト用コンテキスト（暦日・スタッフ・スロット一覧）。有料契約が必要。条件が無いときは null。

GET

{baseUrl}/v1/schedule-conditions

SCHEDULE_CONDITION 親行の一覧（conditionId・期間・取り消し時刻など）。

GET

{baseUrl}/v1/schedule-conditions/{conditionId}

条件の親行＋ REQ 日次＋ STAFF スナップショット（PK/SK 除去）。

GET

{baseUrl}/v1/schedule-defaults

テナントのスケジュール既定行（未保存なら null）。

GET

{baseUrl}/v1/schedule-actual/{conditionId}

実績シフト（SCHEDULE_ACTUAL）行、無ければ null。

GET

{baseUrl}/v1/staff/{staffId}/weekly-shift-wish

スタッフの週次希望シフト行、無ければ null。

GET

{baseUrl}/v1/staff

テナントのアクティブなスタッフ一覧（表示名でソート）。

GET

{baseUrl}/v1/staff/{staffId}

staffId で1件取得（laborLawCompliance、laborFlsaExempt、個人上限、laborConstraintMask 等の労務詳細を含む。論理削除済みは 404）。

メソッド

パス

説明

PATCH

{baseUrl}/v1/schedule-defaults

テナントのスケジュール既定を保存（ボディは schedule-defaults-actions の saveSchema と同一）。有料項目は契約プランに応じて反映されます。

POST

{baseUrl}/v1/staff

スタッフを作成（displayName）。201 と staff JSON。

POST

{baseUrl}/v1/schedule-results/{conditionId}/emergency-shift

完了済み参照シフトを複製し欠勤を反映した新 condition を作成（201 と conditionId）。有料契約が必要。

POST

{baseUrl}/v1/schedule-results/{conditionId}/confirm-assignments

最適化候補の手動編集結果を検証し確定割当を保存（200 と { ok: true }）。

PATCH

{baseUrl}/v1/staff/{staffId}

スタッフの表示名・労務詳細（laborLawCompliance、laborFlsaExempt、個人上限、laborConstraintMask）を更新。

DELETE

{baseUrl}/v1/staff/{staffId}

スタッフを論理削除（deletedAt を設定）。

DELETE

{baseUrl}/v1/schedule-conditions/{conditionId}

条件を取り消し（publicApiCancelledAt）。子行は削除しない。

PUT

{baseUrl}/v1/schedule-actual/{conditionId}

実績割当を保存 JSON { "assignments": [ ... ] }。

PUT

{baseUrl}/v1/staff/{staffId}/weekly-shift-wish

週次希望を全置換（1〜7 日のフルグリッド、wishByCellKey。粒度はテナント既定に追随）。

type

タイミング

schedule.result.terminal

スケジュール結果が completed / no_solution / failed / error / canceled などに更新されたとき

{ "type": "schedule.result.terminal", "conditionId": "019ee481-e855-7000-abd8-977cbfd64ffc", "status": "completed", "occurredAt": "2026-07-16T13:00:54.694Z", "links": { "result": "{baseUrl}/v1/schedule-results/019ee481-e855-7000-abd8-977cbfd64ffc" } }

ヘッダ

説明

Content-Type

application/json

User-Agent

AutoScheduler-Webhook/1.0

X-AutoScheduler-Timestamp

Unix 秒（文字列）

X-AutoScheduler-Signature

v1=<hex>（下記の署名）

ヘッダ

説明

x-api-key

有料契約に紐づく API キー（テナントと利用上限の識別に使用）。

Content-Type

application/json

項目

有料 API（目安）

課金モデル

Stripe サブスクリプション。プロダクトの請求は料金表に従い、登録スタッフ数（席）に比例する月額になり得ます（API 呼び出し回数に応じた追加課金は行いません）。

maxScheduleDays

標準の有料 2 週間詳細予測では、1 リクエストあたり最大 14 暦日（契約でさらに広げる場合のみ）。

maxStaffPerSchedule

POST /v1/schedule の staff 配列は最大 500 行（PUBLIC_SCHEDULE_MAX_STAFF。リクエスト本文のインライン staffId）。

maxRosterStaff

POST /v1/staff の名簿登録は現行アプリ既定で最大 30 名（STAFF_ROSTER_MAX_PAID）。超過時は 409 STAFF_LIMIT。

allowedGranularities

[60, 15] — 15 分は有料機能。60 分（時刻単位）も利用可能。

maxPayloadBytes

524288（512 KiB）、特別な上限がない限り UTF-8 バイト長で計測。

strictUnknownRootKeys

true — 未知のトップレベルまたは staff 内のキーは拒否

フィールド

型

必須

備考

timeZone

string

はい

日付・スロット解釈に使う IANA タイムゾーン。

scheduleStartDate / scheduleEndDate

string (YYYY-MM-DD)

はい

対象期間（暦日）。開始 ≤ 終了。

timeRangeStart / timeRangeEnd

string (HH:mm)

はい

スロット列を定義する壁時計の範囲。1 本以上のスロットが生成されること。

slotGranularityMinutes

60 | 15

はい

有料 API: 60（時単位）または 15（15 分）。allowedGranularities に含まれること。

requirementsByCell

object

はい

キーは計算されたグリッド上の cellKey。値は 0〜15 の整数。

staff

array

はい

空でない配列。上限は limits 参照。各要素: staffId, displayName, 任意の availableCells。

フィールドリファレンス（許容値）

コード

意味

INVALID_JSON

JSON として解析できない。

PAYLOAD_TOO_LARGE

UTF-8 バイト長が maxPayloadBytes（既定 512 KiB）超過。

TYPE_ERROR

JSON 型が不正、または未サポートの apiVersion 文字列。

UNKNOWN_FIELD

厳格モード: ルートまたは staff 行に不許可のプロパティ。

INVALID_TIME_ZONE

timeZone 欠落または IANA として無効。

INVALID_DATE_RANGE

日付形式不正、範囲不正、列挙が空。

SCHEDULE_SPAN_TOO_LONG

開始〜終了の日数が maxScheduleDays を超過。

INVALID_TIME_RANGE

時刻範囲欠落、またはスロット 0 本。

INVALID_GRANULARITY

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

INVALID_REQUIREMENTS

requirementsByCell がオブジェクトでない、または 0〜15 以外の数値。

UNKNOWN_CELL_KEY

計算されたスケジュールグリッドにないキー。

INVALID_STAFF

staff が空・超過・行不正・サニタイズ失敗など。

DUPLICATE_STAFF_ID

staffId の重複。

INVALID_AVAILABLE_CELL

availableCells の空要素または未知キー。

SHORTFALL_CELLS

必要人数に対して勤務可能人数が不足。

DYNAMODB_ERROR

検証後の永続化などで失敗（ハンドラ依存）。

SCHEDULE_DEFAULTS_SAVE_FAILED

PATCH /v1/schedule-defaults：検証または業務ルール失敗（error.details 参照）。

LABOR_COMPLIANCE_REQUIRED

PATCH /v1/staff/{staffId}：laborLawCompliance が false のとき laborConstraintMask を送信した。

{ "apiVersion": "2026-04-01", "timeZone": "Asia/Tokyo", "scheduleStartDate": "2026-04-07", "scheduleEndDate": "2026-04-13", "timeRangeStart": "08:00", "timeRangeEnd": "20:00", "slotGranularityMinutes": 60, "requirementsByCell": { "2026-04-07__slot-0": 2 }, "staff": [ { "staffId": "550e8400-e29b-41d4-a716-446655440000", "displayName": "Example", "availableCells": ["2026-04-07__slot-0"] } ] }

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

このドキュメントの対象範囲

契約プランとアクセス

認証

エンドポイント

使い方（クイックスタート）

curl の例（bash / macOS / Linux / WSL）

取得 API（GET）

更新 API（PATCH / POST / PUT / DELETE）

完了通知 Webhook

設定手順

イベント

リクエストボディ

リクエストヘッダ

署名検証

リトライ

ヘッダ

応答ヘッダについて

有料枠の上限（エンタイトルメント）

ルートで許可されるキー（厳格モード）

リクエストボディ（概要）

クイックリファレンス表

フィールドリファレンス（許容値）

apiVersion

timeZone

scheduleStartDate, scheduleEndDate

timeRangeStart, timeRangeEnd

slotGranularityMinutes

requirementsByCell

staff

staff[].availableCells

労働法・有料オプション（JSON 本文には含めない）

サニタイズのルール

成功レスポンス

エラーコード一覧

JSON の最小例

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

このドキュメントの対象範囲

契約プランとアクセス

認証

エンドポイント

使い方（クイックスタート）

curl の例（bash / macOS / Linux / WSL）

取得 API（GET）

更新 API（PATCH / POST / PUT / DELETE）

完了通知 Webhook

設定手順

イベント

リクエストボディ

リクエストヘッダ

署名検証

リトライ

ヘッダ

応答ヘッダについて

有料枠の上限（エンタイトルメント）

ルートで許可されるキー（厳格モード）

リクエストボディ（概要）

クイックリファレンス表

フィールドリファレンス（許容値）

apiVersion

timeZone

scheduleStartDate, scheduleEndDate

timeRangeStart, timeRangeEnd

slotGranularityMinutes

requirementsByCell

staff

staff[].availableCells

労働法・有料オプション（JSON 本文には含めない）

サニタイズのルール

成功レスポンス

エラーコード一覧

JSON の最小例