acuity-scheduling

核心用法

Acuity Scheduling Skill 是一个 API 集成型技能，通过 Maton 网关代理访问 Acuity Scheduling 平台的完整 API 能力。用户需先在 maton.ai 注册获取 API 密钥，并通过 OAuth 流程授权 Acuity 账户访问权限。核心操作包括：预约查询与创建（支持按日期、日历、客户等多维度筛选）、实时可用性检查（获取可预约日期和时间段）、客户信息管理（增删改查）、日历与预约类型配置，以及时间块管理（设置不可预约时段）。所有请求通过 gateway.maton.ai 代理转发，自动注入 OAuth Token，无需直接处理 Acuity 的认证细节。

显著优点

托管式 OAuth 简化集成：用户无需自行实现复杂的 OAuth 2.0 流程，Maton 提供统一的连接管理界面（ctrl.maton.ai），支持多账户切换和连接状态监控。功能覆盖全面：完整支持 Acuity Scheduling 的核心业务能力，包括预约的创建、修改、取消、改期，以及客户信息、表单、标签等元数据管理。多语言示例丰富：提供 Python、JavaScript、Bash 等语言的完整代码示例，降低接入门槛。灵活的可用性查询：支持按月份获取可预约日期、按日期获取具体时间段，便于构建自定义预约界面。多连接管理：通过 Maton-Connection 头部可指定使用哪个 OAuth 连接，适合代理多个商家账户的场景。

潜在缺点与局限性

第三方网关依赖：所有 API 请求必须经过 Maton 网关，存在单点故障风险，且服务可用性完全依赖 Maton 的运维能力。数据隐私顾虑：客户姓名、邮箱、电话等 PII 数据需经过 Maton 服务器中转，对数据合规要求严格的场景需谨慎评估。功能边界限制：作为代理层，新上线的 Acuity API 功能可能存在延迟支持，且部分高级功能（如自定义支付流程）可能未完全暴露。时区处理复杂：Datetime 格式依赖 PHP strtotime 解析，跨时区场景需要额外注意格式转换。错误信息透传：4xx/5xx 错误直接透传 Acuity 原生错误，调试时可能需要对照双方文档。

适合的目标群体

服务型中小企业：咨询、美容、健身、医疗预约等需要在线预约系统的行业。SaaS 集成开发者：正在构建需要嵌入预约功能的垂直行业软件，如 CRM、ERP、客户门户等。自动化工作流搭建者：使用 n8n、Make 等工具连接 Acuity 与其他业务系统（如 Slack 通知、Google Calendar 同步）。多门店管理方：需要集中管理多个 Acuity 账户的连锁品牌或代运营服务商。

使用风险

API 密钥泄露风险：MATON_API_KEY 是访问所有连接的统一凭证，一旦泄露可能导致所有关联 Acuity 账户被非法访问。OAuth 连接失效：Acuity 端的授权过期或用户主动撤销，会导致连接状态变为 INACTIVE，需人工重新授权。速率限制：Acuity API 本身存在调用频率限制，高频场景（如实时日历同步）可能触发 429 错误。数据同步延迟：网关层的缓存策略可能导致可用性数据与 Acuity 实际状态存在短暂不一致。供应商锁定：深度使用 Maton 网关后，迁移至直接调用 Acuity API 需要重新实现 OAuth 和连接管理逻辑。