自訂預約介面
在你的產品中呈現可預約時間，再透過後端提交 Booking。
切勿把 Tenant API Keys 放進瀏覽器程式碼。
整合方式
Slotkit 透過 Hosted Booking 頁面與版本化伺服器端 API 提供相同的排程能力。這是同一個產品的兩種進入方式，不是兩個不同版本。
既有應用程式
將預約建立、改期與取消加入現有服務。
必須遵循 Key scopes、idempotency 與 concurrency 要求。
外部工作流程
接收生命週期 Webhooks，更新你自己的系統。
Slotkit 不提供通用工作流程建構器。
Hosted Booking 加 API
使用預約頁面，並在需要時整合相同的排程資源。
Hosted access 規則與 API 授權仍是不同邊界。
最小整合流程
- 01
查詢可預約時間
查詢某個 Event Type 在特定時間點有哪些可預約 Slots。
- 02
建立所選預約
使用唯一 idempotency key，提交所選時段與訪客資料。
- 03
處理生命週期事件
接收已簽署的 Booking 與 Calendar 生命週期 Webhooks。
畫面上顯示的 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 不會等待日曆活動寫入完成。
API 介面包含的能力
- 版本化 /v1 REST contract，以及具固定 scopes 的伺服器端 API Keys。
- Availability 查詢，以及 Booking 建立、改期與取消。
- 針對 invitation-only 頁面的 Booking Invitation 列表、建立、撤銷與重新發行。
- 供應用程式保存情境資料的有限 Metadata，不影響排程或授權語意。
- 依目前已實作 contract 建立的伺服器端 TypeScript SDK。
- 已簽署的 booking.created、booking.rescheduled、booking.cancelled、calendar.created 與 calendar.failed Webhooks。
v1 contract 已穩定，並可透過 API Reference 查看。TypeScript SDK 已實作至 1.0.0，但尚未公開發佈。
整合時必須考慮的情況
- 安全重送請求
- Mutation idempotency 可避免已接受的重試建立另一筆 Booking；衝突與內容不同的請求仍需明確處理。
- Booking 與後續副作用
- Calendar 同步與 Webhook 投遞會追隨已提交狀態；延遲不會撤銷 Booking。
- Availability 依賴
- Google 日曆不可用且沒有有效近期快照時，Availability 檢查可能 fail closed。
- 並行預約
- Slot 在查詢與提交之間可能變得無法預約，整合端必須處理該回應。
- 投遞模型
- Webhooks 可能重試並重複投遞。請驗證簽章，並使用文件中的 Event identity 去重。
- 復原
- 重試次數有限；同步或投遞失敗可能需要經授權的復原操作。
憑證與隔離
- API Keys 只能存在伺服器環境，絕不能放進瀏覽器程式碼。
- Scopes 固定且遵循最小權限；只申請整合實際使用的權限。
- Webhook 投遞具有簽章；信任事件前必須先驗證簽章。
- 每個工作區只能看到自己的資料；伺服器端會重新檢查跨工作區存取。
資源
使用互動式 API Reference 或下載 OpenAPI 文件來評估 v1 contract。TypeScript SDK 尚未公開發佈。
常見問題
整合之前。
可以不使用 Hosted Booking 頁面嗎？
可以。使用具適當 Scope 的 API Key，即可透過伺服器端讀取並預約相同的 Event Types 與 Availability。
API 憑證必須放在哪裡？
只能放在伺服器端。Tenant API Keys 絕不能嵌入瀏覽器程式碼；請由自己的後端發出請求。
使用 API 仍需要 Google 日曆嗎？
需要。包括 API-only 用法在內，Bookability 仍依賴 Google 日曆，因為 Availability 檢查與 Booking events 都會使用它。
Webhooks 只會投遞一次嗎？
不會。投遞可能重試，也可能重複到達。請驗證簽章，並使用 Event identity 去重。
瀏覽器可以直接呼叫 API 嗎？
不能使用 API Keys 直接呼叫。自訂預約 UI 應提交到持有憑證的自家應用程式後端。
訪客使用 Hosted Booking 時，我的整合還能使用 API 嗎？
可以。Hosted access 規則與 API 授權彼此獨立，但都操作相同的排程資源。