核心用法
Acuity Scheduling Skill 是 Maton 提供的托管式 OAuth 网关，允许用户通过统一的 API 接口操作 Acuity Scheduling 平台的核心功能。用户需先在 ctrl.maton.ai 完成 OAuth 授权，随后使用 Maton API Key 调用 gateway.maton.ai/acuity-scheduling 下的各类端点。
主要功能模块：
- 预约管理：创建、查询、更新、取消、改期预约，支持按日期范围、日历、客户信息筛选
- 可用时间查询：获取指定月份的可预约日期和具体时间段
- 客户管理：维护客户档案，支持按姓名/电话搜索（注意：仅支持已有预约的客户更新/删除）
- 日历与预约类型：管理多日历配置和服务类型
- 时间块管理：创建/删除不可用时段（如午休、休假）
- 表单与标签：读取客户 intake 表单和预约标签
认证流程：通过 ctrl.maton.ai/connections 创建连接 → 浏览器完成 OAuth → 使用 Authorization: Bearer $MATON_API_KEY 调用网关。多账户场景下可通过 Maton-Connection 头部指定特定连接。
显著优点
1. 托管OAuth简化集成：无需自行实现 OAuth 2.0 流程，Maton 自动处理 token 刷新和存储
2. 完整API覆盖：涵盖预约、客户、日历、可用性、表单等 Acuity 核心功能
3. 多语言示例：提供 Python、JavaScript、Bash 等现成代码片段
4. 灵活的时间查询：支持按月份批量获取可约日期，再细化到具体时间段
5. 批量操作支持：通过日期范围参数实现分页查询，适合数据同步场景
潜在缺点与局限性
1. 功能限制：客户更新/删除仅适用于已有预约的客户，无法直接管理潜在客户档案
2. 时间格式依赖：datetime 需符合 PHP strtotime() 解析规则，跨语言开发需注意格式兼容
3. 无实时推送：依赖轮询查询，无 webhook 支持，实时性受限
4. 改期约束：reschedule 操作要求目标时段必须可用，无法强制覆盖冲突
5. 网关依赖：服务稳定性受 Maton 网关影响，非直连 Acuity 官方 API
适合人群
- 中小型企业主或行政人员，需自动化预约管理流程
- 开发者构建预约相关的内部工具或集成工作流
- 服务行业的多日历管理团队（如诊所、咨询公司、美容工作室）
常规风险
- OAuth 会话过期：长期运行的自动化流程需监控连接状态，避免授权失效导致中断
- 时区处理复杂：需严格区分账户时区、客户时区和服务器时区，避免预约时间错位
- 速率限制：高频调用可能触发 429 限制，批量操作建议增加延迟
- 数据隐私：客户 PII（姓名、邮箱、电话）流经第三方网关，需评估合规要求
- API Key 安全：
MATON_API_KEY泄露将导致账户完全暴露，建议配合密钥管理服务使用