介绍
# Acuity Scheduling
使用托管的 OAuth 身份验证访问 Acuity Scheduling API。管理预约、日历、客户、可用时间等。
## 快速开始
```bash # List appointments python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/acuity-scheduling/api/v1/appointments?max=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## 基础 URL
``` https://gateway.maton.ai/acuity-scheduling/{native-api-path} ```
将 `{native-api-path}` 替换为实际的 Acuity API 端点路径。网关将请求代理到 `acuityscheduling.com` 并自动注入您的 OAuth 令牌。
## 身份验证
所有请求都需要在 Authorization 头中包含 Maton API 密钥：
``` Authorization: Bearer $MATON_API_KEY ```
**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### 获取您的 API 密钥
1. 登录或在 [maton.ai](https://maton.ai) 创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥
## 连接管理
在 `https://ctrl.maton.ai` 管理您的 Acuity Scheduling OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=acuity-scheduling&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 创建连接
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'acuity-scheduling'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 获取连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "acuity-scheduling", "metadata": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### 删除连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 指定连接
如果您有多个 Acuity Scheduling 连接，请使用 `Maton-Connection` 头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/acuity-scheduling/api/v1/appointments') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认的（最旧的）活动连接。
## API 参考
### 账户信息
#### 获取账户信息
```bash GET /acuity-scheduling/api/v1/me ```
返回账户信息，包括时区、调度页面 URL 和计划详情。
**响应：** ```json { "id": 12345, "email": "[email protected]", "timezone": "America/Los_Angeles", "name": "My Business", "schedulingPage": "https://app.acuityscheduling.com/schedule.php?owner=12345", "plan": "Professional", "currency": "USD" } ```
### 预约
#### 列出预约
```bash GET /acuity-scheduling/api/v1/appointments ```
**查询参数：** | 参数 | 类型 | 描述 | |-----------|------|-------------| | `max` | integer | 最大结果数（默认：100） | | `minDate` | date | 此日期及之后的预约 | | `maxDate` | date | 此日期及之前的预约 | | `calendarID` | integer | 按日历筛选 | | `appointmentTypeID` | integer | 按预约类型筛选 | | `canceled` | boolean | 包含已取消的预约（默认：false） | | `firstName` | string | 按客户名筛选 | | `lastName` | string | 按客户姓筛选 | | `email` | string | 按客户邮箱筛选 | | `excludeForms` | boolean | 省略咨询表单以加快响应速度 | | `direction` | string | 排序顺序：ASC 或 DESC（默认：DESC） |
**示例：** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/acuity-scheduling/api/v1/appointments?max=10&minDate=2026-02-01') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json [ { "id": 1630290133, "firstName": "Jane", "lastName": "McTest", "phone": "1235550101", "email": "[email protected]", "date": "February 4, 2026", "time": "9:30am", "endTime": "10:20am", "datetime": "2026-02-04T09:30:00-0800", "type": "Consultation", "appointmentTypeID": 88791369, "duration": "50", "calendar": "Chris", "calendarID": 13499175, "canceled": false, "confirmationPage": "https://app.acuityscheduling.com/schedule.php?..." } ] ```
#### 获取预约
```bash GET /acuity-scheduling/api/v1/appointments/{id} ```
#### 创建预约
```bash POST /acuity-scheduling/api/v1/appointments Content-Type: application/json
{ "datetime": "2026-02-15T09:00", "appointmentTypeID": 123, "firstName": "John", "lastName": "Doe", "email": "[email protected]", "phone": "555-123-4567", "timezone": "America/New_York" } ```
**必填字段：** - `datetime` - 日期和时间（可被 PHP 的 strtotime 解析） - `appointmentTypeID` - 预约类型 ID - `firstName` - 客户的名字 - `lastName` - 客户的姓氏 - `email` - 客户的邮箱
**可选字段：** - `phone` - 客户电话号码 - `calendarID` - 特定日历（如果省略则自动选择） - `timezone` - 客户的时区 - `certificate` - 套餐或优惠券代码 - `notes` - 管理员备注 - `addonIDs` - 附加项 ID 数组 - `fields` - 表单字段值数组
**示例：** ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({ 'datetime': '2026-02-15T09:00', 'appointmentTypeID': 123, 'firstName': 'John', 'lastName': 'Doe', 'email': '[email protected]' }).encode() req = urllib.request.Request('https://gateway.maton.ai/acuity-scheduling/api/v1/appointments', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 更新预约
```bash PUT /acuity-scheduling/api/v1/appointments/{id} Content-Type: application/json
{ "firstName": "Jane", "lastName": "Smith", "email": "[email protected]" } ```
#### 取消预约
```bash PUT /acuity-scheduling/api/v1/appointments/{id}/cancel ```
返回已取消的预约，其中 `canceled: true`。
#### 重新安排预约
```bash PUT /acuity-scheduling/api/v1/appointments/{id}/reschedule Content-Type: application/json
{ "datetime": "2026-02-20T10:00" } ```
**注意：** 新的日期时间必须是可用的时间段。
### 日历
#### 列出日历
```bash GET /acuity-scheduling/api/v1/calendars ```
**响应：** ```json [ { "id": 13499175, "name": "Chris", "email": "", "replyTo": "[email protected]", "description": "", "location": "", "timezone": "America/Los_Angeles" } ] ```
### 预约类型
#### 列出预约类型
```bash GET /acuity-scheduling/api/v1/appointment-types ```
**查询参数：** - `includeDeleted` (boolean) - 包含已删除的类型
**响应：** ```json [ { "id": 88791369, "name": "Consultation", "active": true, "description": "", "duration": 50, "price": "45.00", "category": "", "color": "#ED7087", "private": false, "type": "service", "calendarIDs": [13499175], "schedulingUrl": "https://app.acuityscheduling.com/schedule.php?..." } ] ```
### 可用时间
#### 获取可用日期
```bash GET /acuity-scheduling/api/v1/availability/dates?month=2026-02&appointmentTypeID=123 ```
**必填参数：** - `month` - 要检查的月份（例如，“2026-02”） - `appointmentTypeID` - 预约类型 ID
**可选参数：** - `calendarID` - 特定日历 - `timezone` - 结果的时区（例如，“America/New_York”）
**响应：** ```json [ {"date": "2026-02-09"}, {"date": "2026-02-10"}, {"date": "2026-02-11"} ] ```
#### 获取可用时间
```bash GET /acuity-scheduling/api/v1/availability/times?date=2026-02-10&appointmentTypeID=123 ```
**必填参数：** - `date` - 要检查的日期 - `appointmentTypeID` - 预约类型 ID
**可选参数：** - `calendarID` - 特定日历 - `timezone` - 结果的时区
**响应：** ```json [ {"time": "2026-02-10T09:00:00-0800", "slotsAvailable": 1}, {"time": "2026-02-10T09:50:00-0800", "slotsAvailable": 1}, {"time": "2026-02-10T10:40:00-0800", "slotsAvailable": 1} ] ```
### 客户
#### 列出客户
```bash GET /acuity-scheduling/api/v1/clients ```
**查询参数：** - `search` - 按名字、姓氏或电话筛选
**示例：** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/acuity-scheduling/api/v1/clients?search=John') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json [ { "firstName": "Jane", "lastName": "McTest", "email": "[email protected]", "phone": "(123) 555-0101", "notes": "" } ] ```
#### 创建客户
```bash POST /acuity-scheduling/api/v1/clients Content-Type: application/json
{ "firstName": "John", "lastName": "Doe", "email": "[email protected]", "phone": "555-123-4567" } ```
#### 更新客户
```bash PUT /acuity-scheduling/api/v1/clients Content-Type: application/json
{ "firstName": "John", "lastName": "Doe", "email": "[email protected]" } ```
**注意：** 客户更新/删除仅适用于已有预约的客户。
#### 删除客户
```bash DELETE /acuity-scheduling/api/v1/clients Content-Type: application/json
{ "firstName": "John", "lastName": "Doe" } ```
### 屏蔽时间段
#### 列出屏蔽时间段
```bash GET /acuity-scheduling/api/v1/blocks ```
**查询参数：** - `max` - 最大结果数（默认：100） - `minDate` - 此日期及之后的屏蔽 - `maxDate` - 此日期及之前的屏蔽 - `calendarID` - 按日历筛选
#### 获取屏蔽时间段
```bash GET /acuity-scheduling/api/v1/blocks/{id} ```
#### 创建屏蔽时间段
```bash POST /acuity-scheduling/api/v1/blocks Content-Type: application/json
{ "start": "2026-02-15T12:00", "end": "2026-02-15T13:00", "calendarID": 1234, "notes": "Lunch break" } ```
**响应：** ```json { "id": 9589304654, "calendarID": 13499175, "start": "2026-02-15T12:00:00-0800", "end": "2026-02-15T13:00:00-0800", "notes": "Lunch break", "description": "Sunday, February 15, 2026 12:00pm - 1:00pm" } ```
#### 删除屏蔽时间段
```bash DELETE /acuity-scheduling/api/v1/blocks/{id} ```
成功时返回 204 No Content。
### 表单
#### 列出表单
```bash GET /acuity-scheduling/api/v1/forms ```
**响应：** ```json [ { "id": 123, "name": "Client Intake Form", "appointmentTypeIDs": [456, 789], "fields": [ { "id": 1, "name": "How did you hear about us?", "type": "dropdown", "options": ["Google", "Friend", "Social Media"], "required": true } ] } ] ```
### 标签
#### 列出标签
```bash GET /acuity-scheduling/api/v1/labels ```
**响应：** ```json [ {"id": 23116714, "name": "Checked In", "color": "green"}, {"id": 23116715, "name": "Completed", "color": "pink"}, {"id": 23116713, "name": "Confirmed", "color": "yellow"} ] ```
## 分页
Acuity Scheduling 使用 `max` 参数来限制结果。使用 `minDate` 和 `maxDate` 来遍历日期范围：
```bash # First page GET /acuity-scheduling/api/v1/appointments?max=100&minDate=2026-01-01&maxDate=2026-01-31
# Next page GET /acuity-scheduling/api/v1/appointments?max=100&minDate=2026-02-01&maxDate=2026-02-28 ```
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/acuity-scheduling/api/v1/appointments?max=10', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const appointments = await response.json(); ```
### Python
```python import os import requests
response = requests.get( 'https://gateway.maton.ai/acuity-scheduling/api/v1/appointments', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'max': 10} ) appointments = response.json() ```
## 注意事项
- 日期时间值必须能被 PHP 的 `strtotime()` 函数解析 - 时区使用 IANA 格式（例如，“America/New_York”，“America/Los_Angeles”） - 客户更新/删除要求客户必须有现有预约 - 重新安排预约要求新的日期时间必须是可用的时间段 - 使用 `excludeForms=true` 可以更快地获取预约列表响应 - 重要：使用 curl 命令时，如果 URL 包含方括号，请使用 `curl -g` 以禁用 glob 解析 - 重要：将 curl 输出通过管道传递给 `jq` 或其他命令时，在某些 shell 环境中，像 `$MATON_API_KEY` 这样的环境变量可能无法正确展开。通过管道传输时，您可能会遇到“Invalid API key”错误。
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 请求无效（例如，时间不可用，未找到客户） | | 401 | Maton API 密钥无效或缺失 | | 404 | 未找到资源 | | 429 | 请求频率受限 | | 4xx/5xx | 来自 Acuity API 的透传错误 |
### 故障排除：API 密钥问题
1. 检查是否已设置 `MATON_API_KEY` 环境变量：
```bash echo $MATON_API_KEY ```
2. 通过列出连接来验证 API 密钥是否有效：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 故障排除：应用名称无效
1. 确保您的 URL 路径以 `acuity-scheduling` 开头。例如：
- 正确：`https://gateway.maton.ai/acuity-scheduling/api/v1/appointments` - 错误：`https://gateway.maton.ai/api/v1/appointments`
## 资源
- [Acuity Scheduling API 快速开始](https://developers.acuityscheduling.com/reference/quick-start) - [预约 API](https://developers.acuityscheduling.com/reference/get-appointments) - [可用时间 API](https://developers.acuityscheduling.com/reference/get-availability-dates) - [日历 API](https://developers.acuityscheduling.com/reference/get-calendars) - [客户 API](https://developers.acuityscheduling.com/reference/clients) - [OAuth2 文档](https://developers.acuityscheduling.com/docs/oauth2) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])