Acuity Scheduling

核心用法

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 泄露将导致账户完全暴露，建议配合密钥管理服务使用

核心用法

Acuity Scheduling Skill 是一个纯文档型 API 集成工具，通过 Maton 托管网关提供对 Acuity Scheduling 平台的完整访问能力。用户可通过标准化 REST API 实现预约的增删改查、客户管理、日历同步、可用时段查询等核心功能。

主要功能模块：

• 预约管理：创建、更新、取消、重新排程预约，支持按日期、日历、客户等多维度筛选
• 客户管理：客户信息的增删改查，支持按姓名、邮箱、电话搜索
• 日历与可用性：查询日历列表、获取可预约日期和时段、管理时间区块
• 表单与标签：获取客户 intake 表单、管理预约标签分类

认证方式：采用 Maton 托管 OAuth 2.0，用户需在 ctrl.maton.ai 完成授权流程，后续通过 MATON_API_KEY 环境变量进行 API 调用。

显著优点

1. 零代码基础设施：无需自建 OAuth 流程或处理令牌刷新，Maton 自动管理凭证生命周期
2. 完整 API 覆盖：支持 Acuity Scheduling 原生 API 的全部核心能力，包括预约类型、价格、时长等业务属性
3. 多连接管理：支持同一账号绑定多个 Acuity 账户，通过 Maton-Connection 头灵活切换
4. 安全传输保障：所有通信强制 HTTPS，符合 GDPR/CCPA 合规要求

潜在局限

• 网关依赖性：所有请求需经过 Maton 网关中转，存在单点故障风险和额外的网络延迟
• PHP 时间格式限制：datetime 字段需兼容 PHP strtotime() 解析，跨语言开发时需注意格式转换
• 客户操作限制：客户更新/删除仅对有历史预约的客户生效，无法直接管理潜客数据
• 无实时 Webhook：当前版本未提及 Webhook 支持，需轮询查询状态变更

适合人群

• 服务型企业：咨询、美容、医疗、教育等依赖预约制的行业
• 开发者/系统集成商：需要快速集成排程能力到现有 SaaS 产品的技术团队
• 自动化工作流用户：结合其他 Skill 实现"客户下单→自动预约→日历同步→提醒通知"的全链路自动化

常规风险

| 风险类型 | 等级 | 说明 |

|---------|------|------|

| 凭证泄露 | 中 | API 密钥通过环境变量管理，但用户可能误提交至版本控制 |

| 数据隐私 | 低 | 预约数据包含客户 PII，需确保 Maton 网关的数据处理协议符合业务合规要求 |

| 服务可用性 | 中 | 依赖 Maton 和 Acuity 双平台稳定性，建议实现重试和降级机制 |

| 权限边界 | 低 | OAuth 授权后 Maton 可访问完整账户数据，需定期审查授权范围 |