Back to Details

opencals-storefront-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Opencals Storefront API & SDK

Opencals Storefront API & SDK

You are integrating a real, revenue-carrying booking flow against the Opencals hosted API. You do not implement availability maths, timezones, conflict resolution, pricing or payments — the API owns all of that. Your job is to call the right endpoints in the right order and render the results.
The SDK is 
@opencals/storefront-sdk
(class-based, generated from the OpenAPI spec). Every identifier in this skill's reference files is copied from that SDK — never invent method names, parameters or enum values. If something you need isn't documented here, read the generated types in 
node_modules/@opencals/storefront-sdk/dist
(or the source 
src/client/*.gen.ts
) rather than guessing.
你正在对接Opencals托管API的真实盈利性预订流程。你不需要实现可用性计算、时区处理、冲突解决、定价或支付——这些都由API负责。你的工作是按正确的顺序调用对应的端点并渲染结果。
SDK为
@opencals/storefront-sdk
（基于类实现，由OpenAPI规范生成）。本技能参考文件中的所有标识符均来自该SDK——绝对不要自行编造方法名、参数或枚举值。 如果你需要的内容没有在此处记录，请查阅
node_modules/@opencals/storefront-sdk/dist
中的生成类型（或源文件
src/client/*.gen.ts
），而不要猜测。

When to use this skill

何时使用本技能

Trigger on any Opencals API/SDK work: "book an appointment", "show available slots", "apply a discount code", "let customers reschedule", "add a guest to a booking", "collect a billing address at checkout", "why am I getting a 429", "custom booking length", "customer login". If the task is "build me a whole booking website from a template", start with the 
opencals-build-booking-site
 skill and come back here for the exact call shapes.
任何Opencals API/SDK相关工作都可触发：「预约预订」、「显示可用时段」、「应用优惠码」、「允许客户改期」、「向预订中添加访客」、「结账时收集账单地址」、「为什么我收到429错误」、「自定义预订时长」、「客户登录」。如果任务是「用模板搭建完整的预订网站」，请先使用**
opencals-build-booking-site
**技能，再回到此处查看具体的调用格式。

Setup (once)

配置（仅需一次）

Initialise the SDK a single time via a side-effect import, then import service classes directly:
ts
// lib/opencals.ts — imported once at the top of every server file that calls the API
import { setupOpencals } from '@opencals/storefront-sdk';

setupOpencals({
  baseUrl: process.env.OPENCALS_API_URL ?? 'https://api.opencals.com',
  apiKey: process.env.OPENCALS_API_KEY, // sfk_… storefront key, from the dashboard
  logging: process.env.NODE_ENV === 'development',
});
ts
import { ProductService, CartService, AppointmentService } from '@opencals/storefront-sdk';
Full setup details, the complete service list, 
X-Api-Version
, and the 
throwOnError
gotcha: 
references/setup.md
.
通过副作用导入单次初始化SDK，然后直接导入服务类：
ts
// lib/opencals.ts — imported once at the top of every server file that calls the API
import { setupOpencals } from '@opencals/storefront-sdk';

setupOpencals({
  baseUrl: process.env.OPENCALS_API_URL ?? 'https://api.opencals.com',
  apiKey: process.env.OPENCALS_API_KEY, // sfk_… storefront key, from the dashboard
  logging: process.env.NODE_ENV === 'development',
});
ts
import { ProductService, CartService, AppointmentService } from '@opencals/storefront-sdk';
完整的配置详情、完整的服务列表、
X-Api-Version
以及
throwOnError
注意事项，详见**
references/setup.md
**。

The core booking flow

核心预订流程

  1. Availability → 
    ProductService.getCurrentAvailabilities
    (exact slots) or 
    getCurrentAvailabilitiesMerged
    (calendar highlighting). → 
    references/availability.md
  2. Cart → 
    CartService.createOrGet
    , persist the 
    X-Cart-Id
    . → 
    references/cart-lifecycle.md
  3. Appointment → 
    AppointmentService.create
    (slot + 
    cartId
    + 
    numberOfAttendees
    + optional guests/add-ons). → 
    references/guests-attendees.md
  4. Checkout → 
    CheckoutService.start → saveCustomer → saveAnswers → submit
    . → 
    references/checkout.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

Reference files (load the one you need)

参考文件（按需加载）

FileCovers
references/setup.md
setupOpencals
, service classes, versioning header, 
OpencalsApiError
, 
throwOnError
references/availability.md
getCurrentAvailabilities
vs 
getCurrentAvailabilitiesMerged
, 
duration
, 
excludeAppointmentId
, slot shape, grid fan-out
references/custom-duration.md
allowCustomDuration
/ 
maxDuration
, quantity = duration-units pricing rule
references/guests-attendees.md
numberOfAttendees
, 
maxAttendees
/
attendees
, 
addGuest
/ 
removeGuest
references/cart-lifecycle.md
create/get, 
X-Cart-Id
, 
expiresAt
, 
extendExpiration
, expiry countdown
references/checkout.md
saveCustomer
timing, billing vs delivery address, marketing consent, checkout questions
references/auth-self-service.md
password + passwordless + OAuth login, sessions, 
SelfService
(profile, appointments, consent)
references/reschedule-cancel.md
reschedule
/ 
cancel
, 
rescheduleGap
/ 
cancelGap
, excluding the moved appointment
references/discounts.md
automatic vs code (
applyCode
) vs balance credit (
valueType: 'time'
), error codes
references/rate-limiting.md
429 handling, 
withRateLimitRetry
backoff pattern, allowed origins, per-key throttling
references/debugging.md
reading 
OpencalsApiError
, the top recurring mistakes and how to spot them
文件涵盖内容
references/setup.md
setupOpencals
、服务类、版本控制头、
OpencalsApiError
、
throwOnError
references/availability.md
getCurrentAvailabilities
与
getCurrentAvailabilitiesMerged
的区别、
duration
、
excludeAppointmentId
、时段格式、网格展开
references/custom-duration.md
allowCustomDuration
/ 
maxDuration
、按时长单位计费的定价规则（quantity = duration-units）
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
、最常见的错误及排查方法

Resources

资源

Guardrails

开发约束

  • Never invent SDK names. Methods, params and enums must match the generated SDK. When unsure, read 
    references/*
    or the SDK's 
    .d.ts
    files.
  • Never hard-code services, prices, availability, staff or locations. They come from the store via the API and are configured in the Opencals dashboard.
  • All slot dates/times are UTC. Convert to the customer's timezone for display only; send 
    timezone
    on availability queries so slots align to the local day.
  • Surface real errors. The SDK throws 
    OpencalsApiError
    with the backend status code and field-level detail — never swallow it into a generic 500.
  • The SDK and the official templates are MIT-licensed; the hosted API is closed-source. You pay Opencals only for bookings.
  • 绝对不要编造SDK名称。 方法、参数和枚举必须与生成的SDK一致。如有疑问，请查阅
    references/*
    或SDK的
    .d.ts
    文件。
  • 绝对不要硬编码服务、价格、可用性、员工或地点。 这些数据均通过API从店铺获取，并在Opencals管理后台中配置。
  • 所有时段的日期/时间均为UTC。 仅在显示时转换为客户的时区；在可用性查询中传入
    timezone
    参数，确保时段与当地日期对齐。
  • 透出真实错误。 SDK会抛出包含后端状态码和字段级详情的
    OpencalsApiError
    ——绝对不要将其捕获后返回通用的500错误。
  • SDK和官方模板采用MIT许可证；托管API为闭源。你仅需为成功的预订向Opencals付费。