Acuity Scheduling

通过托管的 OAuth 认证访问 Acuity Scheduling API。管理预约、日历、客户、可用性等。

快速开始

# 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：

export MATON_API_KEY="YOUR_API_KEY"

获取您的 API 密钥

1. 请登录或前往maton.ai
2. 创建账户前往
3. maton.ai/settings

复制您的 API 密钥

在以下地址管理您的Acuity Scheduling OAuth连接https://ctrl.maton.ai。

列出连接

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

创建连接

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

获取连接

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

响应：

{
  "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": {}
  }
}

在浏览器中打开返回的网址以完成OAuth授权。

删除连接

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标头指定要使用的连接：

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参考

账户信息

获取账户信息

GET /acuity-scheduling/api/v1/me

返回账户信息，包括时区、预约页面URL和套餐详情。

响应：

{
  "id": 12345,
  "email": "user@example.com",
  "timezone": "America/Los_Angeles",
  "name": "My Business",
  "schedulingPage": "https://app.acuityscheduling.com/schedule.php?owner=12345",
  "plan": "Professional",
  "currency": "USD"
}

预约

列出预约

GET /acuity-scheduling/api/v1/appointments

查询参数：

示例：

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

响应：

[
  {
    "id": 1630290133,
    "firstName": "Jane",
    "lastName": "McTest",
    "phone": "1235550101",
    "email": "jane.mctest@example.com",
    "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?..."
  }
]

获取预约

GET /acuity-scheduling/api/v1/appointments/{id}

创建预约

POST /acuity-scheduling/api/v1/appointments
Content-Type: application/json

{
  "datetime": "2026-02-15T09:00",
  "appointmentTypeID": 123,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "555-123-4567",
  "timezone": "America/New_York"
}

必填字段：

• 日期时间- 日期和时间（可由 PHP 的 strtotime 解析）
• 预约类型ID- 预约类型 ID
• 名字- 客户的名字
• 姓氏- 客户姓氏
• 电子邮件- 客户电子邮件

可选字段：

• 电话- 客户电话号码
• 日历ID- 特定日历（若省略则自动选择）
• 时区- 客户时区
• 凭证- 套餐或优惠券代码
• 备注- 管理员备注
• 附加项ID- 附加项ID数组
• 字段- 表单字段值数组

示例：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    'datetime': '2026-02-15T09:00',
    'appointmentTypeID': 123,
    'firstName': 'John',
    'lastName': 'Doe',
    'email': 'john.doe@example.com'
}).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

更新预约

PUT /acuity-scheduling/api/v1/appointments/{id}
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane.smith@example.com"
}

取消预约

PUT /acuity-scheduling/api/v1/appointments/{id}/cancel

返回已取消的预约，其中包含canceled: true。

重新安排预约

PUT /acuity-scheduling/api/v1/appointments/{id}/reschedule
Content-Type: application/json

{
  "datetime": "2026-02-20T10:00"
}

注意：新的日期时间必须是一个可用的时间段。

日历

列出日历

GET /acuity-scheduling/api/v1/calendars

响应：

[
  {
    "id": 13499175,
    "name": "Chris",
    "email": "",
    "replyTo": "chris@example.com",
    "description": "",
    "location": "",
    "timezone": "America/Los_Angeles"
  }
]

预约类型

列出预约类型

GET /acuity-scheduling/api/v1/appointment-types

查询参数：

• includeDeleted（布尔值）- 包含已删除的类型

响应：

[
  {
    "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?..."
  }
]

可用性

获取可用日期

GET /acuity-scheduling/api/v1/availability/dates?month=2026-02&appointmentTypeID=123

必需参数：

• month- 要检查的月份（例如："2026-02"）
• appointmentTypeID- 预约类型ID

可选参数：

• calendarID- 特定日历
• timezone- 结果的时区（例如："America/New_York"）

响应：

[
  {"date": "2026-02-09"},
  {"date": "2026-02-10"},
  {"date": "2026-02-11"}
]

获取可用时间段

GET /acuity-scheduling/api/v1/availability/times?date=2026-02-10&appointmentTypeID=123

必需参数：

• date- 要查询的日期
• appointmentTypeID- 预约类型ID

可选参数：

• calendarID- 特定日历
• timezone- 返回结果使用的时区

响应：

[
  {"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}
]

客户

列出客户

GET /acuity-scheduling/api/v1/clients

查询参数：

• search- 按名、姓或电话筛选

示例：

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

响应：

[
  {
    "firstName": "Jane",
    "lastName": "McTest",
    "email": "jane.mctest@example.com",
    "phone": "(123) 555-0101",
    "notes": ""
  }
]

创建客户

POST /acuity-scheduling/api/v1/clients
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "phone": "555-123-4567"
}

更新客户

PUT /acuity-scheduling/api/v1/clients
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.updated@example.com"
}

注意：客户更新/删除仅适用于已有预约的客户。

删除客户

DELETE /acuity-scheduling/api/v1/clients
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Doe"
}

区块

列出日程块

GET /acuity-scheduling/api/v1/blocks

查询参数：

• max- 最大结果数量（默认值：100）
• minDate- 在此日期或之后的日程块
• maxDate- 在此日期或之前的日程块
• calendarID- 按日历筛选

获取日程块

GET /acuity-scheduling/api/v1/blocks/{id}

创建日程块

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"
}

响应：

{
  "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"
}

删除日程块

DELETE /acuity-scheduling/api/v1/blocks/{id}

成功时返回 204 No Content。

表单

列出表单

GET /acuity-scheduling/api/v1/forms

响应：

[
  {
    "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
      }
    ]
  }
]

标签

列出标签

GET /acuity-scheduling/api/v1/labels

响应：

[
  {"id": 23116714, "name": "Checked In", "color": "green"},
  {"id": 23116715, "name": "Completed", "color": "pink"},
  {"id": 23116713, "name": "Confirmed", "color": "yellow"}
]

分页

Acuity Scheduling 使用max参数来限制结果数量。使用minDate和maxDate用于对日期范围进行分页：

# 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

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

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以禁用通配符解析
• 重要提示：将 curl 输出通过管道传递给jq或其他命令时，在某些shell环境中，环境变量如$MATON_API_KEY可能无法正确展开。通过管道传输时，您可能会遇到"无效的API密钥"错误。

错误处理

故障排除：API密钥问题

1. 检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

2. 通过列出连接来验证API密钥是否有效：

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 快速入门
• 预约API
• 可用性API
• 日历API
• 客户API
• OAuth2 文档
• Maton 社区
• Maton 支持