맞춤 예약 UI
제품에 가능한 시간을 표시하고 backend를 통해 예약을 제출합니다.
Tenant API Key를 브라우저 코드에 넣지 마세요.
통합 방법
Slotkit은 Hosted Booking 페이지와 버전 서버 API를 통해 같은 scheduling 기능을 제공합니다. 별도 에디션이 아니라 하나의 제품으로 들어가는 두 경로입니다.
기존 애플리케이션
기존 서비스에 예약 생성, 일정 변경, 취소를 추가합니다.
key scopes, idempotency, concurrency 요구사항을 따르세요.
외부 워크플로
lifecycle Webhook을 받아 자체 시스템을 업데이트합니다.
Slotkit은 일반적인 workflow builder를 제공하지 않습니다.
Hosted와 API
예약 페이지를 사용하고 같은 scheduling 리소스를 필요한 곳에 통합합니다.
Hosted access와 API authorization은 별도 경계입니다.
최소 통합 흐름
- 01
가능한 시간 조회
특정 시점에 Event Type에서 예약 가능한 Slot을 요청합니다.
- 02
선택한 예약 생성
고유 idempotency key와 방문자 정보를 포함해 선택한 Slot을 제출합니다.
- 03
lifecycle 이벤트 처리
서명된 Booking 및 Calendar lifecycle Webhook을 받습니다.
표시된 Slot은 확보되지 않습니다. create call 확정 전에 unavailable이 될 수 있으므로 conflict response를 처리해야 합니다.
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" }
}같은 response에서 Booking은 confirmed, Calendar event는 pending으로 보고됩니다. Booking 확정은 Calendar event 기록을 기다리지 않습니다.
API가 제공하는 기능
- 버전 /v1 REST contract와 고정 scope 서버 API key
- Availability 조회 및 예약 생성·변경·취소
- 초대 전용 페이지의 Booking Invitation 조회·생성·취소·재발급
- scheduling이나 authorization 의미가 없는 애플리케이션 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 Calendar가 unavailable이고 유효한 최신 snapshot이 없으면 Availability 확인이 fail closed가 될 수 있습니다.
- 동시 예약
- 조회와 제출 사이에 Slot이 unavailable이 될 수 있으므로 응답을 처리해야 합니다.
- 전달 모델
- Webhook은 재시도되거나 여러 번 도착할 수 있습니다. 서명을 확인하고 event identity로 중복 제거하세요.
- 복구
- 재시도에는 제한이 있으며 동기화나 전달 실패에는 권한 있는 복구 작업이 필요할 수 있습니다.
인증 정보와 격리
- API key는 서버 환경에만 두고 브라우저 코드에는 넣지 않습니다.
- Scope는 고정된 최소 권한입니다. 통합에 필요한 것만 요청하세요.
- Webhook 전달에는 서명이 있으므로 이벤트를 신뢰하기 전에 확인합니다.
- 각 workspace는 자신의 데이터만 봅니다. 교차 workspace 접근은 서버에서 다시 확인합니다.
리소스
대화형 API reference나 OpenAPI 문서로 v1 contract를 확인하세요. TypeScript SDK의 공개 배포는 아직 없습니다.
질문
통합 전에.
Hosted Booking 없이 사용할 수 있나요?
예. scope가 있는 API key로 같은 Event Type과 Availability를 서버 간에 읽고 예약할 수 있습니다.
API 인증 정보는 어디에 둬야 하나요?
서버에만 둡니다. Tenant API key를 브라우저 코드에 넣지 말고 자체 backend를 통해 호출하세요.
API도 Google Calendar가 필요한가요?
예. Availability 확인과 예약 이벤트가 Google Calendar에 의존하므로 API만 사용해도 필요합니다.
Webhook은 정확히 한 번 전달되나요?
아니요. 재시도와 중복 전달이 가능합니다. 서명을 확인하고 event identity로 중복 제거하세요.
브라우저가 API를 직접 호출할 수 있나요?
API key로는 불가능합니다. 인증 정보를 보유한 자체 backend를 통해 제출하세요.
방문자가 Hosted 페이지를 쓰면서 API 통합도 사용할 수 있나요?
예. Hosted access와 API authorization은 별개지만 같은 scheduling 리소스를 사용합니다.