预约

Appointments API 允许您为联系人预约您的事件类型，然后获取、列出、更新、取消或删除这些预约。它还可以回答大多数预约流程中首先出现的问题——哪些时间段确实有空——并涵盖日历方面的内容：列出您已连接的 Google 日历并导入其中已有的事件。当 Google 日历连接处于活动状态时，相应的日历事件会在后台自动创建并保持同步。使用 Zenchef 或 Formitable 作为其自身预订系统的餐厅也可以在此处进行验证和连接，以便 AI 代理预订真实的餐桌，而不是内部预约。

本页面上的所有路径均相对于基础 URL https://api.youraiconnector.com/v1。每个请求都需要您的 API 密钥——请参阅身份验证以获取发送密钥的完整方式列表。以下示例使用了 X-API-Key 标头，其中一个 cURL 示例也展示了 ?apiKey= 查询形式。

事件与预约的区别： 事件类型 是可预订时段的定义（会议类型、时长、会议室）。预约是针对特定联系人的事件类型的已预订实例。您可以通过引用联系人和事件类型来预订预约。

预约对象

每个返回预约的端点都使用相同的结构：

字段	描述
`id`	预约的唯一 ID。
`contact_id`	预约联系人的 ID。
`event_id`	预订该预约的事件类型 ID。
`status`	`Confirmed` 或 `Canceled`。
`start_time`	预约开始时间，ISO 8601 UTC 格式。
`end_time`	预约结束时间，ISO 8601 UTC 格式。
`created_at`	预约创建时间。
`last_modified_at`	预约最后修改时间。
`room_name`	当事件类型使用会议室时，预订该预约的会议室或资源。
`description`	预约的自由格式描述。
`summary`	简短摘要或标题。
`cancelation_reason`	取消预约时提供的理由（如有）。
`google_calendar_event_id`	关联的 Google 日历事件 ID。在日历同步完成后设置；当未连接日历或同步仍在进行时为 `null`。
`calendar_synced`	当预约关联到日历事件时为 `true`。
`imported`	当预约是从外部日历导入而非直接预订时为 `true`。
`is_recurring`	当预约属于循环系列时为 `true`。
`recurrence_frequency`	循环预约的重复频率。
`recurring_event_id`	该预约所属的循环系列 ID。
`recurring_interval`	循环预约的重复间隔。
`recurring_sequence`	该预约在循环系列中的位置。
`end_after_x_occurrences`	循环系列结束前的发生次数。
`booking_provider`	当通过已连接的预订提供商预订时，预订来源系统。

关于日历同步： 在您预订或更改预约后，google_calendar_event_id 可能仍为 null，且 calendar_synced 可能为 false，因为同步是在稍后的后台运行的。请在稍后重新获取该预约以查看已填充的日历字段。

查找可用时段

GET /appointments/available-slots

返回在两个时间点之间，某个事件类型确实空闲的时间段。这通常是预约流程中的第一步调用：显示这些时段，让用户选择一个，然后将选定的时间发布到预约。

该结果已经考虑了事件类型本身的开放时间和时段长度、其房间、您已在该类型上预订的预约，以及连接的 Google 日历上所有被占用的时间——因此，此处返回的时段是您可以预订的时段。

查询参数	必填	描述
`event_id`	是	要检查的事件类型。必须属于您的账户。
`start_time`	是	您想要查询时段的时间窗口开始时间，ISO 8601 日期时间格式。
`end_time`	是	时间窗口的结束时间，ISO 8601 日期时间格式。包含整个结束日期。

结果按天分组返回——当事件类型使用房间时，按每天每个房间进行分组：

字段	描述
`date`	该组涵盖的日期，格式为 `DD/MM/YYYY`。
`day`	小写的星期几名称，例如 `monday`。
`room_name`	当事件类型使用房间时，该组所属的房间或资源。
`available_slots`	当天可预订的时间块，按时间先后顺序排列。

available_slots 中的每个条目包含：

字段	描述
`start_time`	时间块开始时间，格式为 `HH:mm`。
`end_time`	时间块结束时间，格式为 `HH:mm`。
`available`	`true` ——仅返回空闲时间。
`spots_left`	此时间块中还能容纳多少个预约。仅在每个时段接受多个预约的事件类型中出现。

时间是事件类型的本地时间，而非 UTC 时间。 date、start_time 和 end_time 是事件类型所在时区（其覆盖设置，或在没有覆盖设置时为您账户的时区）的挂钟时间值。预约需要一个 ISO 8601 UTC 即时时间，因此请在发布之前转换您选择的时段。

cURL

curl "https://api.youraiconnector.com/v1/appointments/available-slots?event_id=event_xyz789&start_time=2026-06-15T00:00:00.000Z&end_time=2026-06-19T00:00:00.000Z" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  event_id: "event_xyz789",
  start_time: "2026-06-15T00:00:00.000Z",
  end_time: "2026-06-19T00:00:00.000Z",
});
const res = await fetch(
  `https://api.youraiconnector.com/v1/appointments/available-slots?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.data);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments/available-slots",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "event_id": "event_xyz789",
        "start_time": "2026-06-15T00:00:00.000Z",
        "end_time": "2026-06-19T00:00:00.000Z",
    },
)
print(res.json()["data"])

响应 (200 OK)：

{
  "success": true,
  "data": [
    {
      "date": "15/06/2026",
      "day": "monday",
      "room_name": "Room A",
      "available_slots": [
        { "start_time": "10:00", "end_time": "10:30", "available": true },
        { "start_time": "10:30", "end_time": "11:00", "available": true }
      ]
    },
    {
      "date": "16/06/2026",
      "day": "tuesday",
      "room_name": "Room A",
      "available_slots": [
        { "start_time": "09:00", "end_time": "09:30", "available": true, "spots_left": 2 }
      ]
    }
  ]
}

没有空闲时间的一天将不会显示。缺少 event_id、start_time 或 end_time 会返回 400；不属于您账户的事件类型会返回 404。

预订预约

POST /appointments

为联系人预订特定事件类型的新预约。结束时间会根据事件类型的时段时长自动计算。

预订会进行冲突检查：如果请求的时段与同一事件类型上现有的已确认预约重叠，请求将失败并返回 409，且不会创建任何内容。

字段	必填	描述
`contact_id`	是	预订联系人的 ID。必须属于您的账户。
`event_id`	是	预订的事件类型 ID。必须属于您的账户。
`start_time`	是	所需的开始时间，ISO 8601 日期时间格式。
`room_name`	否	当事件类型使用会议室时，会议室或资源名称。

cURL（使用 ?apiKey= 查询表单）

curl -X POST "https://api.youraiconnector.com/v1/appointments?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "start_time": "2026-06-15T10:00:00.000Z",
    "room_name": "Room A"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/appointments", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contact_id: "contact_abc123",
    event_id: "event_xyz789",
    start_time: "2026-06-15T10:00:00.000Z",
    room_name: "Room A",
  }),
});
const data = await res.json();
console.log(data.appointment_id);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "contact_id": "contact_abc123",
        "event_id": "event_xyz789",
        "start_time": "2026-06-15T10:00:00.000Z",
        "room_name": "Room A",
    },
)
print(res.json()["appointment_id"])

响应 (201 Created)：

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678",
  "appointment": {
    "id": "aBcD1234eFgH5678",
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "status": "Confirmed",
    "start_time": "2026-06-15T10:00:00.000Z",
    "end_time": "2026-06-15T10:30:00.000Z",
    "created_at": "2026-06-10T09:00:00.000Z",
    "last_modified_at": "2026-06-10T09:00:00.000Z",
    "room_name": "Room A",
    "google_calendar_event_id": null,
    "calendar_synced": false
  }
}

获取预约

GET /appointments/{appointmentId}

根据 ID 返回单个预约，包括其日历同步状态。

cURL

curl "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.appointment);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["appointment"])

响应 (200 OK)：

{
  "success": true,
  "appointment": {
    "id": "aBcD1234eFgH5678",
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "status": "Confirmed",
    "start_time": "2026-06-15T10:00:00.000Z",
    "end_time": "2026-06-15T10:30:00.000Z",
    "room_name": "Room A",
    "google_calendar_event_id": "abc123googleevent",
    "calendar_synced": true
  }
}

列出预约

GET /appointments

列出您账户下的预约，按最新时间排序，并使用基于游标的分页。

查询参数	必填	描述
`contact_id`	否	仅返回此联系人的预约。按联系人筛选的列表仅包含已确认的预约。
`date`	否	仅返回此日历日的预约 (`YYYY-MM-DD`)。需要 `contact_id`。
`status`	否	按 `Confirmed` 或 `Canceled` 筛选。仅在没有 `contact_id` 时可用。
`limit`	否	每页大小，1 到 100 之间的整数。默认为 `50`。
`cursor`	否	上次响应中的 `next_cursor` 值。

需要注意的几条规则：

无筛选条件时，您将逐页获取账户下的所有预约。
按联系人 — 设置 contact_id 以查看某位联系人的已确认预约。您也可以通过同时传递 date 将范围缩小到特定的一天。
按状态 — 设置 status（不带 contact_id）以列出账户中仅 Confirmed 或仅 Canceled 的预约。
在没有 contact_id 的情况下使用 date 筛选，或将 status=Canceled 与 contact_id 一起使用，将返回 400。

cURL

curl "https://api.youraiconnector.com/v1/appointments?contact_id=contact_abc123&date=2026-06-15" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  contact_id: "contact_abc123",
  date: "2026-06-15",
});
const res = await fetch(
  `https://api.youraiconnector.com/v1/appointments?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.appointments, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"contact_id": "contact_abc123", "date": "2026-06-15"},
)
data = res.json()
print(data["appointments"], data["next_cursor"])

响应 (200 OK)：

{
  "success": true,
  "appointments": [
    {
      "id": "aBcD1234eFgH5678",
      "contact_id": "contact_abc123",
      "event_id": "event_xyz789",
      "status": "Confirmed",
      "start_time": "2026-06-15T10:00:00.000Z",
      "end_time": "2026-06-15T10:30:00.000Z",
      "calendar_synced": true
    }
  ],
  "next_cursor": null
}

要翻阅结果，请将上一次响应中的 next_cursor 作为下一次请求的 cursor 传递。持续此操作直到 next_cursor 为 null。请参阅错误与分页以了解共享的分页模式。

更新预约

PUT /appointments/{appointmentId}

重新安排预约或更改其详细信息。仅发送您想要更改的字段 — 至少需要一个字段。合并后的开始和结束时间必须保持时间顺序（end_time 必须在 start_time 之后）。更改会自动同步到关联的日历事件。

字段	描述
`start_time`	新的开始时间，ISO 8601 日期时间格式。
`end_time`	新的结束时间，ISO 8601 日期时间格式。必须晚于开始时间。
`room_name`	新的房间或资源名称。
`description`	新的描述，或使用 `null` 清除它。
`summary`	新的摘要，或使用 `null` 清除它。

cURL

curl -X PUT "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": "2026-06-16T10:00:00.000Z",
    "end_time": "2026-06-16T10:30:00.000Z"
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      start_time: "2026-06-16T10:00:00.000Z",
      end_time: "2026-06-16T10:30:00.000Z",
    }),
  }
);
const data = await res.json();
console.log(data.appointment);

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "start_time": "2026-06-16T10:00:00.000Z",
        "end_time": "2026-06-16T10:30:00.000Z",
    },
)
print(res.json()["appointment"])

响应 (200 OK)：

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678",
  "appointment": {
    "id": "aBcD1234eFgH5678",
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "status": "Confirmed",
    "start_time": "2026-06-16T10:00:00.000Z",
    "end_time": "2026-06-16T10:30:00.000Z",
    "calendar_synced": true
  }
}

取消预约

POST /appointments/{appointmentId}/cancel

取消已确认的预约，并可选择记录原因。预约将保留在您的账户中，状态为 Canceled，关联的日历事件会在后台自动移除。取消一个已取消的预约将返回 400。

字段	必填	描述
`cancellation_reason`	否	取消原因，将存储在预约记录中。

cURL

curl -X POST "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/cancel" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cancellation_reason": "Client asked to reschedule next month"
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/cancel",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      cancellation_reason: "Client asked to reschedule next month",
    }),
  }
);
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/cancel",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"cancellation_reason": "Client asked to reschedule next month"},
)
print(res.json()["success"])

响应 (200 OK)：

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678"
}

删除预约

DELETE /appointments/{appointmentId}

永久删除预约及其引用。如果您只想取消预订但保留记录，请改用取消。

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["success"])

响应 (200 OK)：

{
  "success": true
}

列出您已连接的 Google 日历

GET /appointments/google-calendars

直接从 Google 返回此账户上可用的 Google 日历——这对于向账户所有者显示一个选择器以决定从下方导入哪个日历，或者仅仅是为了确认连接是否处于活动状态非常有用。

只有在账户连接了 Google 日历（设置 → 集成）且至少拥有读取权限后，此功能才有效。如果尚未连接，或者授予的权限不再包含日历读取范围，您将收到一个 400，提示您（重新）连接它。

cURL

curl "https://api.youraiconnector.com/v1/appointments/google-calendars" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/appointments/google-calendars", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.data);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments/google-calendars",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["data"])

响应 (200 OK)：

{
  "success": true,
  "data": [
    {
      "id": "primary",
      "summary": "jane@example.com",
      "timeZone": "America/New_York",
      "accessRole": "owner",
      "primary": true
    },
    {
      "id": "abcdefg1234567890@group.calendar.google.com",
      "summary": "Bookings",
      "timeZone": "America/New_York",
      "accessRole": "writer"
    }
  ]
}

每个条目都是 Google 自己的 CalendarListEntry 格式，因此字段名称遵循 Google 的 camelCase，而不是本 API 通常使用的 snake_case —— 这是原样传递的 Google 数据，而非我们的数据。如果连接缺失或已撤销，将返回 400，并附带说明需要（重新）连接 Google 日历的错误信息。

从 Google 日历导入事件

POST /appointments/import-calendar-events

拉取已存在于营销活动或 AI 代理关联的 Google 日历中的事件，并将其转换为预约 —— 这在您首次连接已有预订的日历时非常有用。此过程可能需要一些时间（每个事件都会经过提取以确定其归属），因此它从不内联运行：请求会将任务放入后台队列，并返回一个 job_id 供您轮询。

字段	必填	描述
`campaign_id`	二选一	要从中导入关联日历的营销活动。
`agent_id`	二选一	要从中导入关联日历的 AI 代理。
`identifier`	是	`"EMAIL"` 或 `"PHONE_NUMBER"` —— 从每个日历事件中提取哪种联系信息，以匹配或创建其所属的联系人。

发送 campaign_id / agent_id 中的且仅限其中一个，不能两个都发，也不能一个都不发 —— 任何其他组合都会返回 400。您发送的任何一个都必须属于您的账户，否则您将收到 404。

cURL

curl -X POST "https://api.youraiconnector.com/v1/appointments/import-calendar-events?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "identifier": "EMAIL"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/appointments/import-calendar-events", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_id: "agent_abc123",
    identifier: "EMAIL",
  }),
});
const data = await res.json();
console.log(data.job_id);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments/import-calendar-events",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"agent_id": "agent_abc123", "identifier": "EMAIL"},
)
print(res.json()["job_id"])

响应 (202 Accepted)：

{
  "success": true,
  "job_id": "jK9mQ2xR7pL4wN1t",
  "status": "queued",
  "campaign_id": null,
  "agent_id": "agent_abc123"
}

campaign_id 和 agent_id 会回显您发送的那个字段；另一个始终为 null。

轮询导入任务

GET /appointments/import-calendar-events/{jobId}

curl "https://api.youraiconnector.com/v1/appointments/import-calendar-events/jK9mQ2xR7pL4wN1t" \
  -H "X-API-Key: YOUR_API_KEY"

响应 (200 OK)：

{
  "success": true,
  "job_id": "jK9mQ2xR7pL4wN1t",
  "status": "completed",
  "message": "Imported 12 events as appointments.",
  "error": null
}

`status`	含义
`queued`	尚未处理。请继续轮询。
`processing`	导入正在运行。请继续轮询。
`completed`	已完成 —— `message` 包含简短的人类可读摘要。
`failed`	出错了 —— `error` 包含原因。

对不存在（或属于其他账户）的 jobId 执行 GET 会返回 404。

餐厅预订集成（Zenchef / Formitable）

Zenchef 和 Formitable 是餐厅预订系统，您的 AI 代理可以通过它们预订真实的餐位。每个系统都有一个公开、无需身份验证的预订小部件（https://api.youraiconnector.com/v1/zenchef-widget/... 和 https://api.youraiconnector.com/v1/formitable-widget/...），可在聊天中为用餐者呈现 —— 这些小部件路由是旨在浏览器中打开的纯 HTML 页面，而非 JSON API 端点，因此此处不予记录。以下是账户管理端点：验证餐厅 ID 是否属于账户持有者，然后对其进行添加、更新或移除。

Zenchef

连接 Zenchef 餐厅需要进行两步验证，以确保账户持有人在将其接入机器人之前证明他们确实经营该餐厅：首先检查 ID 是否存在（不显示名称），然后让他们自行输入餐厅名称并验证其是否匹配。

第 1 步 — 检查餐厅 ID 是否存在

POST /appointments/zenchef-restaurants/check

字段	必填	描述
`restaurant_id`	是	要检查的 Zenchef 餐厅 ID。

curl -X POST "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/check?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "12345" }'

响应 (200 OK)：

{
  "success": true,
  "data": { "exists": true, "requiresNameVerification": true }
}

exists: false 表示没有 Zenchef 餐厅拥有该 ID — 无需进行其他操作。每个账户每 5 分钟限额 10 次检查；超出限制将返回 429。

第 2 步 — 验证餐厅名称

POST /appointments/zenchef-restaurants/verify-name

字段	必填	描述
`restaurant_id`	是	来自第 1 步的 Zenchef 餐厅 ID。
`user_input_name`	是	账户持有人输入的名称 — 与 Zenchef 上餐厅的真实名称进行比对（忽略大小写/空格）。

curl -X POST "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/verify-name?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "12345", "user_input_name": "The Blue Door Bistro" }'

响应 (200 OK)：

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "id": "12345",
      "name": "The Blue Door Bistro",
      "address": "1 Rue de Rivoli, Paris",
      "status": "active"
    }
  }
}

verified: false 表示名称不匹配 — restaurantDetails 被省略，请要求账户持有人重试。每 5 分钟限额 3 次尝试（比存在性检查更严格，因为这是实际的验证步骤）。如果 restaurant_id 在 Zenchef 上不再解析，则返回 404。

第 3 步 — 保存餐厅

POST /appointments/zenchef-restaurants

字段	必填	描述
`restaurant_id`	是	1–64 个字符，字母/数字/下划线/连字符。
`restaurant_name`	是	来自第 2 步的已验证餐厅名称。

curl -X POST "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "12345", "restaurant_name": "The Blue Door Bistro" }'

响应 (201 Created)：

{ "success": true, "data": { "restaurantId": "12345" } }

更新已保存的 Zenchef 餐厅

PUT /appointments/zenchef-restaurants/{restaurantId}

字段	必填	说明
`restaurant_name`	否	新的显示名称。
`is_active`	否	设置 `false` 以阻止机器人预订该餐厅，而无需将其删除。

curl -X PUT "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/12345" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

响应 (200 OK)：与上述保存响应的格式相同。

移除 Zenchef 餐厅

DELETE /appointments/zenchef-restaurants/{restaurantId}

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/12345" \
  -H "X-API-Key: YOUR_API_KEY"

响应 (200 OK)：{ "success": true, "data": { "restaurantId": "12345" } }

如果 restaurantId 当前不在账户中，更新或删除时将返回 404。

Formitable

Formitable 不需要像 Zenchef 那样进行两步名称验证——它的餐厅 ID 已经在每个企业范围内确定，因此一次验证调用就足够了。它还有一个详细信息查询功能，用于在设置期间缓存餐厅的网站 URL。

验证餐厅 ID

POST /appointments/formitable-restaurants/verify

字段	必填	说明
`restaurant_id`	是	Formitable 餐厅 ID。
`language`	否	探测请求的语言标签。默认为 `"nl"`。

curl -X POST "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/verify?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "the-blue-door", "language": "en" }'

响应 (200 OK)：

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "restaurantId": "the-blue-door",
      "productCount": 4,
      "sampleProductTitle": "Dinner for two",
      "language": "en"
    }
  }
}

如果 Formitable 无法识别 restaurant_id，则返回 404。每个账户每 5 分钟限流 10 次尝试。

获取餐厅详细信息

GET /appointments/formitable-restaurants/{restaurantId}/details?language=en

从 Formitable 获取餐厅的公开资料，包括其网站——用于在设置餐厅时缓存网站 URL。language 是一个可选的查询参数，默认为 "en"。

curl "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/the-blue-door/details?language=en" \
  -H "X-API-Key: YOUR_API_KEY"

响应 (200 OK)：

{
  "success": true,
  "data": {
    "uid": "the-blue-door",
    "name": "The Blue Door Bistro",
    "website": "https://thebluedoorbistro.com",
    "email": "info@thebluedoorbistro.com",
    "telephone": "+31201234567",
    "streetAddress": "Prinsengracht 1",
    "zipcode": "1015 AB",
    "city": "Amsterdam",
    "country": "Netherlands",
    "countryCode": "NL",
    "currency": "EUR"
  }
}

保存餐厅

POST /appointments/formitable-restaurants

字段	必填	描述
`restaurant_id`	是	1–64 个字符，包含字母/数字/下划线/连字符。
`restaurant_name`	是	显示名称。
`language`	是	ISO 语言标签，例如 `"en"` 或 `"en-GB"`。
`website_url`	否	餐厅网站，来自上述详情查询。必须是 `http(s)://`。

curl -X POST "https://api.youraiconnector.com/v1/appointments/formitable-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "restaurant_id": "the-blue-door",
    "restaurant_name": "The Blue Door Bistro",
    "language": "en",
    "website_url": "https://thebluedoorbistro.com"
  }'

响应 (201 Created)：{ "success": true, "data": { "restaurantId": "the-blue-door" } }

更新已保存的 Formitable 餐厅

PUT /appointments/formitable-restaurants/{restaurantId}

字段	必填	描述
`restaurant_name`	否	新的显示名称。
`language`	否	新的 ISO 语言标签。
`is_active`	否	设置为 `false` 可阻止机器人预订该餐厅，而无需将其移除。
`website_url`	否	新的网站 URL。

curl -X PUT "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/the-blue-door" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

响应 (200 OK)：与上述保存响应的格式相同。

移除 Formitable 餐厅

DELETE /appointments/formitable-restaurants/{restaurantId}

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/the-blue-door" \
  -H "X-API-Key: YOUR_API_KEY"

响应 (200 OK)：{ "success": true, "data": { "restaurantId": "the-blue-door" } }

如果 restaurantId 当前不在账户中，更新或删除时将返回 404。

所有 Zenchef/Formitable 端点的错误格式： 与本页其余部分不同，此处的错误状态会携带两次——一次作为 HTTP 状态，另一次作为主体中的 error_code——例如 { "success": false, "error": "Restaurant not found", "error_code": 404 }。处理方式与其他错误相同：检查 success，读取 error 以获取消息。

预约 API 错误

预约端点返回标准的错误封装：

{
  "success": false,
  "error": "Appointment not found"
}

状态码	在预约端点上发生的情况
`400`	缺少必填字段或字段无效 —— 例如错误的 `start_time`、`end_time` 不在 `start_time` 之后、无效的筛选器组合、没有要更新的字段，或预约已取消。
`404`	未找到预约、联系人或事件类型。
`409`	请求的时间段已被占用（预订冲突）。

每个端点都可能返回的共享代码 — 401, 403（您的套餐不包含 API 访问权限）, 429（速率限制）和 500 — 及其重试指南列在错误与分页中。

后续步骤

联系人 — 创建并查找您为其预订的联系人。
消息与对话 — 向联系人发送确认或提醒。
Webhooks — 在预约发生变更时获取通知。

预约 #

预约对象 #

查找可用时段 #

预订预约 #

获取预约 #

列出预约 #

更新预约 #

取消预约 #

删除预约 #

列出您已连接的 Google 日历 #

从 Google 日历导入事件 #

轮询导入任务 #

餐厅预订集成（Zenchef / Formitable） #

Zenchef #

Formitable #

预约 API 错误 #

后续步骤 #

预约

预约对象

查找可用时段

预订预约

获取预约

列出预约

更新预约

取消预约

删除预约

列出您已连接的 Google 日历

从 Google 日历导入事件

轮询导入任务

餐厅预订集成（Zenchef / Formitable）

Zenchef

Formitable

预约 API 错误

后续步骤