mcpField
O
opencals-storefront-api

opencals-storefront-api

github.com/letsopencals开发0208 次安装1 周前更新
代码仓库

关于 opencals-storefront-api

通过 `@opencals/storefront-sdk` 集成 Opencals 托管预约 API 的技能，指导开发者完成服务配置和预订流程。它强调使用生成 SDK 中确切的接口，并由 API 负责排期与定价逻辑。

主要功能

  1. 01SDK 初始化与服务配置
  2. 02查询可预约时段
  3. 03购物车与预约生命周期
  4. 04结账与客户自助服务
  5. 05折扣、改期和限流指引

适用场景

  1. 01在店面中展示预约时段
  2. 02实现购物车、预约与结账流程
  3. 03支持客户改期或使用折扣码

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/letsopencals/skills --skill opencals-storefront-api

安装后在 Claude Code 中输入/opencals-storefront-api确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
auth-self-service.md
availability.md
cart-lifecycle.md
checkout.md
custom-duration.md
debugging.md
discounts.md
guests-attendees.md
products-variants.md
rate-limiting.md
reschedule-cancel.md
setup.md

详细介绍

Opencals Storefront API 和 SDK

你正在将一个真正承载收入的预约流程接入 Opencals 托管 API。你无需实现可用时间计算、时区、冲突处理、定价或支付——这些都由 API 负责。你的任务是按正确顺序调用正确的端点并呈现结果。

SDK 为 @opencals/storefront-sdk（基于 OpenAPI 规范生成的类）。本技能参考文件中的每个标识符都摘自该 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.mdsetupOpencals、服务类、版本请求头、OpencalsApiError、throwOnError
references/products-variants.md商品组与变体（读取变体）、默认 image 与无序 images、构建图片库
references/availability.mdgetCurrentAvailabilities 与 getCurrentAvailabilitiesMerged、duration、excludeAppointmentId、时段结构、网格扇出、多日范围 + 客户端适配
references/custom-duration.mdallowCustomDuration / maxDuration、数量 = 时长单位定价规则、多日（以 1 天为基准）预约
references/guests-attendees.mdnumberOfAttendees、maxAttendees/attendees、addGuest / removeGuest
references/cart-lifecycle.md创建/获取、X-Cart-Id、expiresAt、extendExpiration、过期倒计时
references/checkout.mdsaveCustomer 时机、账单地址与配送地址、营销同意、结账问题
references/auth-self-service.md密码、免密码和 OAuth 登录、会话、SelfService（个人资料、预约、同意）
references/reschedule-cancel.mdreschedule / cancel、rescheduleGap / cancelGap、排除已移动的预约
references/discounts.md自动折扣与代码（applyCode）及余额抵扣（valueType: 'time'）、错误代码
references/rate-limiting.md429 处理、withRateLimitRetry 退避模式、允许的来源、按密钥限流
references/debugging.md如何读取 OpencalsApiError、最常见的错误及识别方法

资源

防护原则

  • 绝不臆造 SDK 名称。 方法、参数和枚举必须与生成的 SDK 一致。如不确定，请阅读 references/* 或 SDK 的 .d.ts 文件。
  • 绝不硬编码服务、价格、可用情况、员工或地点。 这些信息通过 API 从店铺获取，并在 Opencals 控制面板中配置。
  • 从变体而非分组读取产品数据。 images 中的顺序不固定，因此绝不可将 images[0] 用作主图。→ references/products-variants.md
  • 所有时段日期和时间均为 UTC。 仅在显示时转换为客户所在时区；查询可用情况时传入 timezone，以便时段与当地日期对齐。
  • 显示真实错误。 SDK 会抛出 OpencalsApiError，其中包含后端状态码和字段级详细信息——绝不要将其吞掉并转换成通用的 500 错误。
  • SDK 和官方模板采用 MIT 许可证；托管 API 为闭源。你只需向 Opencals 支付预订费用。

评论

支持 Markdown