如何调用wix-bookings API getServiceAvailability()获取服务可用性支撑外部预约创建

前置准备（无需编写复杂代码即可完成） #

• 在Wix站点后台定位到Wix Bookings应用的API权限配置页，生成对应访问密钥：确保密钥勾选了“读取服务可用性”的权限范围，不要使用默认的访客只读密钥，否则调用会触发权限报错
• 从你之前导出的全量预约JSON文件中，逐服务提取对应的serviceId值留存——这是调用接口的必填参数，没有有效serviceId的请求都会失败，不要手动编造该值
• 提前明确需要查询的时间区间范围（例如未来7天、14天的可约时段），将区间的开始、结束时间统一准备为Wix要求的ISO 8601格式（例如2024-10-01T00:00:00Z）

最简化可运行的调用实现 #

不需要搭建外部服务器、不需要编写复杂后端代码，所有操作都可以在Wix后台自带的API调试面板内完成

• 调用时仅需传入三个核心必填参数，无额外复杂逻辑：
  • serviceId：直接粘贴从导出JSON中复制的对应服务ID
  • startTime：查询区间的起始时间，严格按照ISO 8601格式填写
  • endTime：查询区间的截止时间，同样采用ISO 8601格式
• 可直接复用的调用代码片段，替换占位值即可跑通：

// 替换三个引号内的占位值即可
const availabilityQuery = {
  serviceId: "粘贴从导出JSON复制的服务ID",
  startTime: "2024-10-01T00:00:00Z",
  endTime: "2024-10-15T00:00:00Z"
}

// 发起接口调用
wixBookings.getServiceAvailability(availabilityQuery)
  .then(result => {
    // 接口返回的result.slots即为所有开放可约的时段列表，后续创建预约可直接复用这里拿到的slotID
    console.log(result.slots)
  })

新手高频踩坑点排查 #

• 不要手动编造serviceId：90%的调用失败都是因为使用了自定义ID值，Wix仅识别系统正式生成的服务ID，必须从导出的JSON文件中提取
• 不要用Unix时间戳传值：Wix接口不支持秒级/毫秒级的数字时间戳，必须传递带时区标识的ISO格式字符串，否则会返回空的可用性结果
• 不要遗漏权限配置：如果API密钥没有勾选对应服务的读取权限，会直接返回403错误，无法获取任何可用性数据

后续衔接外部应用创建预约的逻辑 #

• 从getServiceAvailability()返回的可约时段列表中，选定对应要创建预约的slot值
• 将选中的slotID、预约人基础联系信息（姓名、手机号、邮箱）组装为入参，直接调用createBooking方法即可完成预约创建——无需重复校验时段有效性，因为前面的可用性查询已经确认过该时段为开放可约状态

内容的提问来源于stack exchange，提问作者Miguel Gomez