カスタム予約 UI
プロダクトに空き時間を表示し、バックエンドから予約を送信します。
Tenant API Keys をブラウザコードに置かないでください。
統合方法
Slotkit は Hosted Booking ページとバージョン付きサーバー側 API で同じスケジューリング機能を提供します。別エディションではなく、1 つのプロダクトへの 2 つの入口です。
既存アプリケーション
既存サービスに予約作成、変更、キャンセルを追加します。
Key scopes、idempotency、concurrency の要件に従ってください。
外部ワークフロー
ライフサイクル Webhook を受け取り、自社システムを更新します。
Slotkit は汎用ワークフロービルダーを提供しません。
Hosted と API
予約ページを使い、必要に応じて同じスケジューリング資源を統合します。
Hosted access と API 認可は別の境界です。
最小限の統合フロー
- 01
空き時間を検索
ある時点で Event Type に予約できる Slots を問い合わせます。
- 02
選択した予約を作成
一意の idempotency key とゲスト情報を添えて Slot を送信します。
- 03
ライフサイクルイベントを処理
署名付き Booking・Calendar ライフサイクル Webhook を受け取ります。
表示された Slot は保持されません。create call の確定前に利用できなくなる可能性があるため、競合応答を処理してください。
POST /v1/bookings
Authorization: Bearer sk_live_2f81c4…
Idempotency-Key: 0f4a9d12-6c33-4b7e-9a10-8ee2c5d17b40
{
"event_type_id": "evt_3n8xqk2r",
"start_at": "2026-09-14T02:00:00.000Z",
"guest": {
"name": "Mei Lin",
"email": "[email protected]",
"timezone": "Asia/Taipei"
}
}201 Created
{
"data": {
"id": "bkg_7pd4m1vs",
"status": "confirmed",
"version": 1,
"source": "api",
"start_at": "2026-09-14T02:00:00.000Z",
"end_at": "2026-09-14T02:30:00.000Z",
"calendar": { "status": "pending", "error_code": null },
"meeting": { "type": "google_meet", "join_url": null }
},
"meta": { "request_id": "req_a71c9f04" }
}同じ応答で Booking は confirmed、Calendar event は pending と報告されます。Booking の確定は Calendar event の書き込みを待ちません。
API に含まれる機能
- バージョン付き /v1 REST contract と固定 scope のサーバー側 API Keys。
- Availability の検索、予約の作成・変更・キャンセル。
- 招待限定ページの Booking Invitation の一覧、作成、取り消し、再発行。
- スケジューリングや認可の意味を持たない、アプリケーション用の限定 Metadata。
- 実装済み contract 向けのサーバー側 TypeScript SDK。
- 署名付き booking.created、booking.rescheduled、booking.cancelled、calendar.created、calendar.failed Webhook。
v1 contract は安定しており、API Reference から利用できます。TypeScript SDK は 1.0.0 で実装済みですが、まだ一般公開されていません。
統合時に考慮すること
- 安全なリクエスト再送
- Mutation idempotency により、受理済みの再送で別の予約が作られることを防ぎます。競合や内容が異なるリクエストは明示的に処理してください。
- 予約と副作用
- Calendar 同期と Webhook 配信は確定状態に続いて実行されます。遅延で予約が取り消されることはありません。
- Availability の依存関係
- Google カレンダーが利用できず有効な最近のスナップショットもない場合、Availability の確認は fail closed になることがあります。
- 同時予約
- 検索と送信の間に Slot が利用できなくなることがあります。統合側で応答を処理してください。
- 配信モデル
- Webhook は再試行され、複数回届くことがあります。署名を検証し、文書化された event identity で重複排除してください。
- 復旧
- 再試行回数には上限があります。同期や配信の失敗には認可された復旧操作が必要な場合があります。
認証情報と分離
- API keys はサーバー環境だけに置き、ブラウザコードには置きません。
- Scope は固定の最小権限です。統合で使うものだけを要求してください。
- Webhook 配信には署名があります。イベントを信頼する前に検証してください。
- 各ワークスペースは自身のデータだけを参照します。クロスワークスペースアクセスはサーバー側で再確認されます。
リソース
インタラクティブ API Reference または OpenAPI ドキュメントを使って v1 contract を確認できます。TypeScript SDK はまだ一般公開されていません。
よくある質問
統合する前に。
Hosted Booking ページなしで使えますか？
はい。Scope 付き API key で同じ Event Type と Availability をサーバー間で読み取り、予約できます。
API 認証情報はどこに置きますか？
サーバー側だけです。Tenant API keys をブラウザコードに埋め込まず、自分のバックエンド経由で呼び出してください。
API でも Google カレンダーは必要ですか？
はい。Availability の確認と予約イベントが Google カレンダーに依存するため、API のみの利用でも必要です。
Webhook は必ず一度だけ届きますか？
いいえ。再試行や重複配信があります。署名を検証し、event identity で重複排除してください。
ブラウザから API を直接呼べますか？
API keys を使ってはできません。認証情報を保持する自分のアプリケーションバックエンド経由で送信してください。
ゲストが Hosted ページを使いながら API 統合もできますか？
はい。Hosted access と API 認可は別ですが、同じスケジューリング資源を操作します。