自订预约界面
在你的产品中呈现可预约时间，再透过后端提交 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 授权彼此独立，但都操作相同的日程安排资源。