opencals-storefront-api

Opencals Storefront API & SDK

実際に収益が発生する予約フローを、Opencals のホスト型 APIに接続します。空き状況の計算、タイムゾーン、競合の解決、料金設定、決済は実装しません。これらはすべて API が処理します。必要なのは、適切な順序で正しいエンドポイントを呼び出し、その結果を表示することです。

SDK は @opencals/storefront-sdk です（OpenAPI 仕様から生成されたクラスベースの SDK）。このスキルのリファレンスファイルに記載されている識別子は、すべてこの SDK から転記しています。**メソッド名、パラメーター、列挙値を決して独自に作らないでください。**必要な情報がここに記載されていない場合は、推測せずに node_modules/@opencals/storefront-sdk/dist の生成済み型（または github.com/letsopencals/storefront-sdk にあるソース src/client/*.gen.ts）を確認してください。

このスキルを使う場面

Opencals API／SDK に関する作業で使います。「予約をする」「空き枠を表示する」「割引コードを適用する」「顧客が予約を変更できるようにする」「予約にゲストを追加する」「チェックアウトで請求先住所を収集する」「なぜ 429 が返されるのか」「カスタム予約時間」「顧客ログイン」などが該当します。「テンプレートから予約サイト全体を作る」タスクの場合は、まず opencals-build-booking-site スキルを使い、正確な呼び出し形式を確認するためにここに戻ってください。

セットアップ（初回のみ）

副作用インポートを使って SDK を一度だけ初期化し、その後サービスクラスを直接インポートします。

// lib/opencals.ts — imported once at the top of every server file that calls the API
import { setupOpencals } from '@opencals/storefront-sdk';
import { nextBuyerIp } from '@opencals/storefront-sdk/next';

setupOpencals({
  baseUrl: process.env.OPENCALS_API_URL ?? 'https://api.opencals.com',
  apiKey: process.env.OPENCALS_API_KEY, // spk_… private storefront key, from the dashboard
  buyerIp: nextBuyerIp, // per-visitor rate limits (see references/setup.md)
  logging: process.env.NODE_ENV === 'development',
});

import { ProductService, CartService, AppointmentService } from '@opencals/storefront-sdk';

セットアップの詳細、サービスの全一覧、X-Api-Version、および throwOnError に関する注意点については、references/setup.md を参照してください。

予約フローの基本

1. 空き状況 → ProductService.getCurrentAvailabilities（正確な枠）または getCurrentAvailabilitiesMerged（カレンダー表示用の強調表示）。→ references/availability.md
2. カート → CartService.createOrGet を呼び出し、X-Cart-Id を保存します。→ references/cart-lifecycle.md
3. 予約 → AppointmentService.create（枠 + cartId + numberOfAttendees + 任意のゲスト／追加オプション）。→ references/guests-attendees.md
4. チェックアウト → CheckoutService.start → saveCustomer → saveAnswers → submit。→ references/checkout.md

リファレンスファイル（必要なものを読み込んでください）

ファイル	内容
references/setup.md	setupOpencals、サービスクラス、バージョンヘッダー、OpencalsApiError、throwOnError
references/products-variants.md	商品グループとバリエーション（バリエーションを参照）、デフォルトの image と順序未指定の images、ギャラリーの作成
references/availability.md	getCurrentAvailabilities と getCurrentAvailabilitiesMerged の違い、duration、excludeAppointmentId、枠の形式、グリッドへのリクエスト分割、複数日にわたる範囲とクライアント側での適合確認
references/custom-duration.md	allowCustomDuration／maxDuration、数量＝時間単位の料金ルール、複数日にわたる（1 日を基本単位とする）予約
references/guests-attendees.md	numberOfAttendees、maxAttendees／attendees、addGuest／removeGuest
references/cart-lifecycle.md	作成／取得、X-Cart-Id、expiresAt、extendExpiration、有効期限のカウントダウン
references/checkout.md	saveCustomer のタイミング、請求先住所と配送先住所、マーケティングへの同意、チェックアウト時の質問
references/auth-self-service.md	パスワード、パスワードレス、OAuth によるログイン、セッション、SelfService（プロフィール、予約、同意）
references/reschedule-cancel.md	reschedule／cancel、rescheduleGap／cancelGap、変更対象の予約を除外する方法
references/discounts.md	自動割引、コード（applyCode）、残高クレジット（valueType: 'time'）の違い、エラーコード
references/rate-limiting.md	429 の処理、withRateLimitRetry によるバックオフパターン、許可されたオリジン、キーごとのスロットリング
references/debugging.md	OpencalsApiError の読み方、よくある間違いとその見分け方

リソース

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

ガードレール

• SDK 名を決してでっち上げないでください。 メソッド、パラメーター、列挙値は生成された SDK と一致している必要があります。不明な場合は、references/* または SDK の .d.ts ファイルを 確認してください。
• サービス、料金、空き状況、スタッフ、場所を決してハードコードしないでください。 これらは API 経由でストアから取得され、Opencals ダッシュボードで設定されます。
• 商品データはグループではなくバリアントから取得してください。 images は順不同のため、 images[0] をメイン画像として使用しないでください。→ references/products-variants.md
• スロットの日付と時刻はすべて UTC です。 表示する場合のみ顧客のタイムゾーンに変換し、 スロットが現地の日付に合うよう、空き状況のクエリには timezone を指定してください。
• 実際のエラーを表面化させてください。 SDK はバックエンドのステータスコードとフィールド単位の 詳細を含む OpencalsApiError をスローします。汎用的な 500 エラーに握りつぶさないでください。
• SDK と公式テンプレートは MIT ライセンスですが、ホスト型 API はクローズドソースです。 Opencals への支払いは予約分のみです。