opencals-build-booking-site

Opencals の予約ストアフロントを構築する

Opencals のホスト型予約 API を利用して、実際に予約できるストアフロントを立ち上げるユーザーを支援します。予約エンジンを構築するわけではありません。空き状況の計算、タイムゾーン、二重予約への対処は API が担います。担当するのはフロントエンドです。テンプレートから始め、ユーザーのストアに接続し、スタイルを変更してデプロイします。

SDK の正確なメソッド名や引数の形式については、関連する opencals-storefront-api スキルを参照してください。空き状況、カート、予約、チェックアウト、割引、セルフサービス、ゲスト／参加者、カスタム所要時間、レート制限に関する信頼できる情報源です。このスキルでは、その周辺の構築ワークフローを扱います。

このスキルを使う場合

ユーザーが予約、アポイントメント、スケジュール管理のウェブサイトや「Opencals ストアフロント」を希望する場合、またはビジネスの説明と参考資料（スクリーンショット、競合サイトなど）を提示して予約サイトの構築を依頼する場合に使います。セルフホスト可能な予約エンジンやデータレジデンシーが必要な場合は、このツールは適していません。その旨を伝え、Cal.com または Easy!Appointments を案内してください。

主な進め方：アイデアと参考資料から公開サイトまで

1. ビジネスを理解します。 何の時間を販売するのでしょうか。人の時間（スタイリスト、臨床医、コーチ）、物（コート、部屋、レーン、機器）、それとも両方でしょうか。グループセッションはありますか。拠点は複数ですか。オンライン／配達に対応しますか。これらによってテンプレートとモデルの設計が決まります。
2. 最も近いテンプレートを選びます（以下を参照）。見た目よりも先に予約の形態を合わせます。スタイルの変更は簡単ですが、アーキテクチャの再設計は簡単ではありません。
3. ひな形の作成 → 設定 → 接続 → リブランド → デプロイ（以下のワークフローを参照）。
4. 参考資料からデザインのヒントを取り入れ、テンプレートのトークンやコンポーネントに反映します。接続済みの予約フローは維持してください。

新しいサイトを作るのではなく、既存のサイトに予約機能を追加する場合も、同じ SDK と API を使えます。opencals-storefront-api スキルを活用し、新しいテンプレートを作成する代わりに、予約フローを既存のアプリ（または iframe／ウィジェット）に埋め込んでください。

前提条件（まず確認してください）

1. どのようなビジネスか — 最も近い開始テンプレートを選んでください。
   • template-haar — サロン（サービス＋ギャラリー、温かみのあるエディトリアルな雰囲気）
   • template-frisor — 理容室（ダークでエディトリアルな雰囲気）
   • template-clarity — クリニック（落ち着きと温かみのある雰囲気。ニーズを優先する Care Finder、受診ごとの問診と写真アップロードに対応した1ページの予約フォーム、クリニックまたはビデオ診療、家族の診療記録、パスワードレスログイン）
   • template-volt（通称 padel template）— 複数のクラブにまたがるパデルとスカッシュのネットワーク（ダークでテクニカルな雰囲気）：予約可能なリソース（複数のクラブにあるコートを、ライブのホールマップまたはグリッドで表示）と、スタッフ主導のセッション（コーチング）を組み合わせたハイブリッド型で、クルーと用具のチェックアウト、試合チケットの確認に対応します。コート、レーン、部屋、ベイ、用具など、入れ替え可能な設備を貸し出す施設には、特にクラスやレッスンも提供している場合に、このテンプレートをお選びください。以下の「リソース予約型のビジネス」をご覧ください。
   • template-noir（NOIR Drive）— 高級車レンタル（黒を基調とした映画的な雰囲気で、アニメーションを多用）：日付範囲カレンダーを使った日単位の予約、配達場所と受け取り場所、日ごとの追加オプション、引き渡し時のデポジットに対応し、スタッフ付きの運転手サービスパッケージも提供します。1日以上のまとまった期間で貸し出すもの（車、ボート、用具など）には、このテンプレートをお選びください。以下の「日単位のレンタル予約」をご覧ください。
   • template-bali-villas（Bali Villa Rentals、デモブランド Lumbung Sidemen）— ヴィラのレンタル（温かみのある落ち着いた雰囲気、田園風景の写真）：チェックイン15:00からチェックアウト11:00までの宿泊単位の予約に対応し、稼働中の空室状況と清掃日のカレンダー、宿泊人数と到着情報、滞在ごとの追加オプション、アカウントからの日程変更やキャンセルが可能です。ヴィラ、キャビン、ゲストハウス、客室には、このテンプレートをお選びください。以下の「宿泊予約」をご覧ください。
   • template-fluently（Fluently）— 語学スクール（カラフルで遊び心のある雰囲気、3Dマスコット）：レベル別バリエーションとリアルタイムの「残席数」に対応したグループレッスン、プライベートのマンツーマンレッスン、無料体験、スタッフとして登録する教師、キャンパスに加えて「参加」ボタン付きのオンライン教室を備えています。語学、音楽、コーディング、個別指導、アートなど、あらゆるスクールやコース型のビジネスには、このテンプレートをお選びください。以下の「スクールとクラス」をご覧ください。
   • template-reformer（Tensile）— ベルリンのリフォーマー・ピラティススタジオ（テクニカルで温かみのある雰囲気。コンクリート、インク、スプリングの色使い）：3つのスタジオとオンラインにまたがる週間時間割で、各クラスにインストラクター名と残りのベッド数を表示します。満席クラスには「次に空きのあるクラス」を表示します。クラス詳細からチェックアウトに進めるほか、1対1およびデュエットのプライベートレッスン、日付指定のワークショップ、同意事項の質問、初回およびオフピーク割引、アカウントからの変更・キャンセルや参加申込にも対応しています。ピラティス、ヨガ、バレエフィットネス、スピン、またはクラス時間割のあるスタジオには、このテンプレートをお選びください。以下の「フィットネスとピラティスのスタジオ」をご覧ください。
2. Opencals の非公開ストアフロントキー（spk_...）— Opencals ダッシュボード（Users → your user → API Keys）から取得します。テンプレートはサーバーから API を呼び出すため、キーは秘密に保たれ、訪問者ごとに個別のレート制限が適用されます。キーを持っていない場合は、デプロイ前にストアと非公開ストアフロントキーを作成するよう案内してください（キーがなくてもサイトはビルドできますが、ライブデータは返されません）。
3. Node.js 20+ と、デプロイ用の Vercel アカウント（無料プランで問題ありません）。

ワークフロー

1. 最も近いテンプレートからひな形を作成する

npx create-next-app -e https://github.com/letsopencals/template-haar my-booking-site
cd my-booking-site
npm install

必要に応じて、リポジトリを template-frisor、template-clarity、template-volt、template-noir、template-bali-villas、template-fluently、または template-reformer に置き換えてください。これらは完成済みのアプリです。サービスカタログ、リアルタイムの空き状況、カート、チェックアウト、Stripe 決済、顧客アカウントはすでに接続されています。作り直さないでください。

2. 環境を設定する

.env.example を .env.local にコピーし、次の項目を設定してください。

OPENCALS_API_KEY=spk_your_key_here          # Required — the private storefront key
AUTH_SECRET=<random string>                 # Required — session encryption
# OPENCALS_API_URL=https://api.opencals.com # Optional — defaults to this
# NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_...  # Optional — for payments

openssl rand -base64 32 を使って AUTH_SECRET を生成してください。

3. SDK の配線を理解する（独自に作り直さないでください）

SDK は lib/opencals.ts の副作用インポートによって一度だけ初期化され、すべての API ルートがファイルの先頭でこれをインポートします。サービスはクラスベースです （ProductService、CartService、AppointmentService、CheckoutService、 AuthService、SelfService、…）。ビルドレベルの概要は references/booking-flow.md を、正確な呼び出し形式は opencals-storefront-api スキルを参照してください。既存の形式を使い、メソッド名を独自に作らないでください。

4. ブランドと設定をカスタマイズする

主にデザインの変更であり、配線の変更ではありません。色やフォントのトークンは app/globals.css に、 コピーや事業情報は lib/site-config.ts にあります。サービス、スタッフ、ロケーションは API 経由でストアから取得します。references/customizing.md を参照してください。

5. ローカルで検証する

npm run dev

サービスが読み込まれること、空き状況から予約枠が返されること、テスト予約が完了することを確認してください。 API ルートは handleApiError を通じて実際のエラーを表示します。エラーを確認し、握りつぶさないでください。

6. Vercel にデプロイする

npx vercel

Vercel プロジェクトの設定にも同じ環境変数を追加してから、npx vercel --prod を実行します。 ローンチ時は無料プランで問題ありません。ユーザーが Opencals に支払うのは予約分のみです。

リソース予約型の事業（コート、レーン、部屋、設備）

施設によっては、スタッフ主導のクラスと並行して、さまざまな交換可能な設備を予約することがあります。 padel/volt テンプレートが実例です。それぞれに適した競合ルールを設定し、すべてを「スタッフ」経由にしないでください。 カスタム所要時間には、所要時間バリアントの商品ではなく allowCustomDuration を使用します。詳細、 3 つのルールの判断表、複数クラブのモデル化、クラブごとの空き状況戦略については references/resource-booking.md を参照してください（API の形式については opencals-storefront-api スキルの custom-duration.md／availability.md を参照してください）。

日単位で予約するレンタル（車、ボート、設備、ヴィラ）

複数日のレンタルでは時間枠を使用しません。各ユニットは、1 日を基本とするスタッフなしの商品です （duration: 86400、allowCustomDuration、maxDuration）。スケジュールは 連続した 24 時間 7 日間（またはスケジュールなし）にします。UI は統合された空き状況の 範囲（getCurrentAvailabilitiesMerged、duration なし）を読み込み、 クライアント側で受け取りから返却までが 1 つの範囲内に収まることを確認してから、 ストアのタイムゾーンで受け取り 00:00 から返却 00:00 までの予約枠を作成し、UTC に変換します。 受け渡し時間帯とフライト番号は予約の customAttributes に保存します。デポジットは必須のチェックボックスで同意を求め、 受け渡し時に預かります。template-noir が実例です。詳しいパターンについては references/rentals-multi-day.md を参照してください。

宿泊（ヴィラ、キャビン、ゲストハウス、部屋）

日単位のレンタルと同じモデルに加え、fixedStartTime（チェックイン、 例：15:00）と fixedEndTime（チェックアウト、例：11:00）を含む fixedTimes を設定します。 時間枠はスケジュールのタイムゾーンで、チェックイン日の fixedStartTime から チェックアウト日の fixedEndTime までとし、UTC に変換します。商品固有の固定時間を使って サーバー側で作成してください。API は顧客の予約と日時変更に対してこれを強制します （それ以外は 400。加盟店による予約は対象外）。また ceil(booked / base) で料金を計算するため、 N 泊なら料金は N × 価格になります。チェックアウト日を次のチェックイン日にすることもできます。 最低宿泊数はサイトコンテンツで設定し、宿泊人数、到着時刻、フライト番号は customAttributes に保存します。template-bali-villas が実例です。詳しいパターンについては references/rentals-multi-day.md §11 を参照してください。

学校とクラス（語学、音楽、コーディング、個別指導）

特別なエンジン機能は不要です。科目はコレクション、クラスは、バリアントがレベルとなる商品 （グループ形式、maxAttendees > 1）、または時間が長さとなる商品（プライベート形式、1 席）です。 価格 0 ドルの 1 席商品は無料体験レッスンで、教師は各クラスに割り当てられるスタッフです。 形式（オンラインか、キャンパスでのグループ形式か）はクラスのロケーションタイプから導き出すため、 スラッグを基準にした分岐はありません。リアルタイムの「残り席数」は時間枠の空き状況から取得します。 Online ロケーションの link は教室の URL で、予約済みの予約のロケーションに含まれて返されます。 これを「レッスンに参加」ボタンに利用できます。template-fluently が実例です。詳しいパターンについては references/classes-and-lessons.md を参照してください。

フィットネス・ピラティススタジオ（リフォーマー、ヨガ、バレエ、スピン）

同じクラスのモデルを、もう一段深く適用します。クラス × スタジオ × インストラクターごとに1つのバリアント（flow-mitte-lena）を作成し、それぞれに独自の週間スケジュール、唯一のロケーションとしてそのスタジオ、唯一のスタッフとしてそのインストラクターを設定し、maxAttendees は部屋のベッド数にします。部屋とベッドの配置はテンプレートコンテンツです。空き状況 API は満席になると枠を返さなくなるため、時間割では各シリーズの週間パターンを学習し、枠が表示されない週を満席として表示して、「次に空きがある枠」へのリンクを設けます。日付指定のワークショップは、満席になると表示されなくなります。プライベートレッスン（1:1 とデュエット）はそれぞれ1席で、スタジオごとの商品プールを共有します。デュエットは、カスタム属性 people: "2" を持つ1件の予約です。template-reformer が実例です。完全なパターンは references/classes-and-lessons.md §6 を参照してください。

リソース

• Opencals — メインサイト
• ドキュメントと API リファレンス
• npm の @opencals/storefront-sdk
• ダッシュボード — ストアの作成、ストアフロント API キーの管理

ガードレール

• サービス、料金、空き状況をフロントエンドにハードコードしないでください。これらは API から取得します。
• SDK のメソッド名を推測して作らないでください。opencals-storefront-api スキルまたはテンプレートに既存の app/api/ ルートを使用してください。
• フロントエンドは MIT ライセンスです。UI から Opencals のブランディングをすべて削除しても問題ありません。API 自体はオープンソースではなく、納品物にも含まれません。