Cuộc hẹn #

Appointments API cho phép bạn đặt lịch hẹn cho các liên hệ của mình dựa trên các loại sự kiện, sau đó lấy, liệt kê, cập nhật, hủy hoặc xóa chúng. API này cũng giải đáp câu hỏi xuất hiện đầu tiên trong hầu hết các quy trình đặt lịch — thời gian nào thực sự trống — và bao gồm cả khía cạnh lịch: liệt kê các Lịch Google bạn đã kết nối và nhập các sự kiện đã có sẵn trong đó. Khi kết nối Lịch Google đang hoạt động, sự kiện lịch tương ứng sẽ được tạo và tự động đồng bộ hóa ở chế độ nền. Các nhà hàng sử dụng Zenchef hoặc Formitable cho hệ thống đặt chỗ riêng của họ cũng có thể được xác minh và kết nối tại đây, để AI Agent đặt bàn thực tế thay vì các cuộc hẹn nội bộ.

Tất cả các đường dẫn trên trang này đều tương đối so với URL cơ sở https://api.youraiconnector.com/v1. Mọi yêu cầu đều cần khóa API của bạn — xem Xác thực để biết danh sách đầy đủ các cách gửi khóa. Các ví dụ bên dưới sử dụng tiêu đề X-API-Key, với một ví dụ cURL cũng hiển thị biểu mẫu truy vấn ?apiKey=.

Sự kiện so với cuộc hẹn: Loại sự kiện là định nghĩa về khung giờ có thể đặt lịch (loại cuộc họp, thời lượng, phòng họp). Cuộc hẹn là một phiên bản đã đặt của một loại sự kiện dành cho một liên hệ cụ thể. Bạn đặt một cuộc hẹn bằng cách tham chiếu đến liên hệ và loại sự kiện đó.

Đối tượng cuộc hẹn #

Mọi endpoint trả về một cuộc hẹn đều sử dụng cùng một cấu trúc:

Về đồng bộ hóa lịch: Ngay sau khi bạn đặt hoặc thay đổi một cuộc hẹn, google_calendar_event_id có thể vẫn là null và calendar_synced có thể là false vì quá trình đồng bộ hóa chạy ở chế độ nền ngay sau đó. Hãy lấy lại cuộc hẹn một lúc sau để xem các trường lịch đã được điền.

Tìm các khung giờ khả dụng #

GET /appointments/available-slots

Trả về các thời điểm thực sự trống trên một loại sự kiện giữa hai thời điểm. Đây thường là lệnh gọi đầu tiên trong quy trình đặt lịch: hiển thị các khung giờ này, để người dùng chọn một khung giờ, sau đó gửi thời gian đã chọn tới Đặt lịch hẹn.

Câu trả lời đã tính đến giờ mở cửa và thời lượng khung giờ của chính loại sự kiện đó, các phòng, các cuộc hẹn bạn đã đặt trên đó và mọi thứ bị chặn trên các Lịch Google được kết nối — vì vậy một khung giờ được trả về ở đây là khung giờ bạn có thể đặt.

Kết quả trả về được nhóm theo ngày — và khi loại sự kiện sử dụng phòng, mỗi nhóm sẽ tương ứng với một phòng mỗi ngày:

Mỗi mục trong available_slots có:

Thời gian là thời gian địa phương của loại sự kiện, không phải UTC. date, start_time và end_time là các giá trị đồng hồ thực tế theo múi giờ của chính loại sự kiện đó (múi giờ ghi đè của nó, hoặc múi giờ tài khoản của bạn nếu không có ghi đè). Đặt lịch hẹn yêu cầu một thời điểm UTC theo chuẩn ISO 8601, vì vậy hãy chuyển đổi khung giờ bạn đã chọn trước khi gửi đi.

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"])

Phản hồi (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 }
      ]
    }
  ]
}

Một ngày không có thời gian trống sẽ đơn giản là không xuất hiện. Thiếu event_id, start_time hoặc end_time sẽ trả về 400; một loại sự kiện không thuộc tài khoản của bạn sẽ trả về 404.

Đặt một cuộc hẹn #

POST /appointments

Đặt một cuộc hẹn mới cho một liên hệ trên một trong các loại sự kiện của bạn. Thời gian kết thúc được tính toán tự động từ thời lượng khung giờ của loại sự kiện.

Việc đặt chỗ được kiểm tra xung đột: nếu khung giờ được yêu cầu trùng lặp với một cuộc hẹn đã xác nhận hiện có trên cùng một loại sự kiện, yêu cầu sẽ thất bại với mã 409 và không có gì được tạo.

cURL (sử dụng biểu mẫu truy vấn ?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"])

Phản hồi (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
  }
}

Lấy thông tin cuộc hẹn #

GET /appointments/{appointmentId}

Trả về một cuộc hẹn duy nhất theo ID của nó, bao gồm trạng thái đồng bộ hóa lịch của cuộc hẹn đó.

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"])

Phản hồi (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
  }
}

Liệt kê các cuộc hẹn #

GET /appointments

Liệt kê các cuộc hẹn cho tài khoản của bạn, hiển thị cuộc hẹn mới nhất trước, với tính năng phân trang dựa trên con trỏ.

Một vài quy tắc cần ghi nhớ:

• Không có bộ lọc, bạn sẽ nhận được mọi cuộc hẹn trên tài khoản, theo từng trang.
• Theo liên hệ — đặt contact_id để xem các cuộc hẹn đã xác nhận của một liên hệ. Bạn có thể thu hẹp phạm vi này xuống một ngày cụ thể bằng cách truyền thêm date.
• Theo trạng thái — đặt status (không có contact_id) để chỉ liệt kê các cuộc hẹn Confirmed hoặc chỉ Canceled trên toàn bộ tài khoản.
• Bộ lọc date khi không có contact_id, hoặc status=Canceled cùng với contact_id, sẽ trả về 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"])

Phản hồi (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
}

Để chuyển trang kết quả, hãy truyền next_cursor từ một phản hồi làm cursor cho yêu cầu tiếp theo. Tiếp tục cho đến khi next_cursor là null. Xem Lỗi & Phân trang để biết mẫu phân trang dùng chung.

Cập nhật cuộc hẹn #

PUT /appointments/{appointmentId}

Lên lịch lại cuộc hẹn hoặc thay đổi chi tiết cuộc hẹn. Chỉ gửi các trường bạn muốn thay đổi — bắt buộc phải có ít nhất một trường. Thời gian bắt đầu và kết thúc kết hợp phải theo đúng thứ tự thời gian (end_time phải sau start_time). Các thay đổi sẽ được tự động đồng bộ hóa với sự kiện lịch được liên kết.

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"])

Phản hồi (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
  }
}

Hủy cuộc hẹn #

POST /appointments/{appointmentId}/cancel

Hủy một cuộc hẹn đã xác nhận, tùy chọn ghi lại lý do. Cuộc hẹn vẫn nằm trong tài khoản của bạn với trạng thái Canceled, và sự kiện lịch được liên kết sẽ tự động bị xóa trong nền. Việc hủy một cuộc hẹn đã bị hủy sẽ trả về mã 400.

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"])

Phản hồi (200 OK):

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

Xóa cuộc hẹn #

DELETE /appointments/{appointmentId}

Xóa vĩnh viễn một cuộc hẹn và các tham chiếu của nó. Nếu bạn chỉ muốn hủy đặt chỗ trong khi vẫn giữ lại hồ sơ, hãy sử dụng hủy thay thế.

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"])

Phản hồi (200 OK):

{
  "success": true
}

Liệt kê các Lịch Google đã kết nối của bạn #

GET /appointments/google-calendars

Trả về các Lịch Google khả dụng trên tài khoản này, trực tiếp từ Google — hữu ích để hiển thị cho chủ tài khoản bộ chọn lịch để nhập từ bên dưới, hoặc chỉ để xác nhận kết nối đang hoạt động.

Điều này chỉ hoạt động sau khi tài khoản đã kết nối Google Calendar (Cài đặt → Tích hợp) với ít nhất quyền truy cập đọc. Nếu chưa, hoặc quyền truy cập được cấp không còn bao gồm phạm vi đọc lịch, bạn sẽ nhận được một 400 yêu cầu bạn (kết nối lại) nó.

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"])

Phản hồi (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"
    }
  ]
}

Mỗi mục nhập là hình dạng CalendarListEntry của riêng Google, vì vậy tên trường tuân theo camelCase của Google, không phải snake_case thông thường của API này — đó là dữ liệu của Google được chuyển qua nguyên trạng, không phải của chúng tôi. Kết nối bị thiếu hoặc bị thu hồi sẽ trả về 400 kèm theo lỗi giải thích rằng Google Calendar cần được (kết nối lại).

Nhập sự kiện từ Google Calendar #

POST /appointments/import-calendar-events

Kéo các sự kiện đã có sẵn trong Google Calendar được kết nối của chiến dịch hoặc AI Agent và biến chúng thành các cuộc hẹn — hữu ích cho lần đầu tiên bạn kết nối một lịch đã có sẵn các đặt chỗ. Quá trình này có thể mất một chút thời gian (mỗi sự kiện đều trải qua quá trình trích xuất để xác định xem nó dành cho ai), vì vậy nó không bao giờ chạy trực tiếp: yêu cầu sẽ xếp hàng một tác vụ nền và trả lại cho bạn một job_id để thăm dò.

Gửi chính xác một trong campaign_id / agent_id, không bao giờ gửi cả hai và không bao giờ không gửi cái nào — bất kỳ sự kết hợp nào khác đều trả về 400. Bất kỳ cái nào bạn gửi đều phải thuộc về tài khoản của bạn, nếu không bạn sẽ nhận được 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"])

Phản hồi (202 Accepted):

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

campaign_id và agent_id phản hồi lại bất kỳ cái nào bạn đã gửi; cái còn lại luôn là null.

Thăm dò tác vụ nhập #

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

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

Phản hồi (200 OK):

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

GET trên một jobId không tồn tại (hoặc thuộc về một tài khoản khác) sẽ trả về 404.

Tích hợp đặt chỗ nhà hàng (Zenchef / Formitable) #

Zenchef và Formitable là các hệ thống đặt chỗ nhà hàng mà AI Agent của bạn có thể sử dụng để đặt bàn thực tế. Mỗi hệ thống đều có một tiện ích đặt chỗ công khai, không cần xác thực (https://api.youraiconnector.com/v1/zenchef-widget/... và https://api.youraiconnector.com/v1/formitable-widget/...) hiển thị trong cuộc trò chuyện cho thực khách — các đường dẫn tiện ích đó là các trang HTML thuần túy dành cho trình duyệt, không phải điểm cuối API JSON, vì vậy chúng không được ghi lại ở đây. Những gì theo sau là các điểm cuối quản lý tài khoản: xác minh ID nhà hàng thuộc về chủ tài khoản, sau đó thêm, cập nhật hoặc xóa nó.

Zenchef #

Việc kết nối nhà hàng Zenchef là quy trình xác minh hai bước, để chủ tài khoản chứng minh rằng họ thực sự điều hành nhà hàng đó trước khi nó được liên kết vào bot: trước tiên hãy kiểm tra xem ID có tồn tại hay không (mà không tiết lộ tên), sau đó yêu cầu họ tự nhập tên nhà hàng và xác minh xem nó có khớp hay không.

Bước 1 — Kiểm tra xem ID nhà hàng có tồn tại không

POST /appointments/zenchef-restaurants/check

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

Phản hồi (200 OK):

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

exists: false nghĩa là không có nhà hàng Zenchef nào có ID đó — không cần làm gì thêm. Giới hạn tốc độ là 10 lần kiểm tra mỗi 5 phút cho mỗi tài khoản; nếu vượt quá sẽ trả về 429.

Bước 2 — Xác minh tên nhà hàng

POST /appointments/zenchef-restaurants/verify-name

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

Phản hồi (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 nghĩa là tên không khớp — restaurantDetails bị bỏ qua, hãy yêu cầu chủ tài khoản thử lại. Giới hạn tốc độ là 3 lần thử mỗi 5 phút (chặt chẽ hơn so với kiểm tra sự tồn tại, vì đây là bước chứng minh thực tế). Một restaurant_id không còn tồn tại trên Zenchef sẽ trả về 404.

Bước 3 — Lưu nhà hàng

POST /appointments/zenchef-restaurants

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

Phản hồi (201 Created):

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

Cập nhật nhà hàng Zenchef đã lưu

PUT /appointments/zenchef-restaurants/{restaurantId}

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

Phản hồi (200 OK): có cùng cấu trúc với phản hồi lưu ở trên.

Xóa một nhà hàng 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"

Phản hồi (200 OK): { "success": true, "data": { "restaurantId": "12345" } }

Một restaurantId hiện không có trong tài khoản sẽ trả về 404 khi cập nhật hoặc xóa.

Formitable #

Formitable không cần xác minh tên hai bước như Zenchef — ID nhà hàng của nó đã được phân định theo doanh nghiệp, vì vậy chỉ cần một cuộc gọi xác minh là đủ. Nó cũng có tính năng tra cứu chi tiết được sử dụng để lưu vào bộ nhớ đệm URL trang web của nhà hàng trong quá trình thiết lập.

Xác minh ID nhà hàng

POST /appointments/formitable-restaurants/verify

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

Phản hồi (200 OK):

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

Một restaurant_id mà Formitable không nhận dạng được sẽ trả về 404. Giới hạn tốc độ là 10 lần thử mỗi 5 phút cho mỗi tài khoản.

Lấy chi tiết nhà hàng

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

Tìm nạp hồ sơ công khai của nhà hàng từ Formitable, bao gồm cả trang web của nó — được sử dụng để lưu vào bộ nhớ đệm URL trang web trong khi thiết lập nhà hàng. language là tham số truy vấn tùy chọn, mặc định là "en".

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

Phản hồi (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"
  }
}

Lưu nhà hàng

POST /appointments/formitable-restaurants

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

Phản hồi (201 Created): { "success": true, "data": { "restaurantId": "the-blue-door" } }

Cập nhật nhà hàng Formitable đã lưu

PUT /appointments/formitable-restaurants/{restaurantId}

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

Phản hồi (200 OK): có cùng cấu trúc với phản hồi lưu ở trên.

Xóa nhà hàng 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"

Phản hồi (200 OK): { "success": true, "data": { "restaurantId": "the-blue-door" } }

Một restaurantId hiện không có trong tài khoản sẽ trả về 404 khi cập nhật hoặc xóa.

Cấu trúc lỗi trên tất cả các endpoint Zenchef/Formitable: không giống như phần còn lại của trang này, các lỗi ở đây mang trạng thái của chúng hai lần — một lần là trạng thái HTTP và một lần là error_code trong phần thân — ví dụ: { "success": false, "error": "Restaurant not found", "error_code": 404 }. Hãy xử lý theo cách tương tự như bất kỳ lỗi nào khác: kiểm tra success, đọc error để biết thông báo lỗi.

Các lỗi của Appointments API #

Các điểm cuối (endpoint) của cuộc hẹn trả về phong bì lỗi tiêu chuẩn:

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

Các mã chung mà mọi điểm cuối có thể trả về — 401, 403 (gói của bạn không bao gồm quyền truy cập API), 429 (giới hạn tốc độ) và 500 — được liệt kê cùng với hướng dẫn thử lại trong Lỗi & Phân trang.

Các bước tiếp theo #

• Danh bạ — tạo và tra cứu các liên hệ mà bạn đặt lịch.
• Tin nhắn & Cuộc hội thoại — gửi xác nhận hoặc lời nhắc cho liên hệ.
• Webhook — nhận thông báo khi các cuộc hẹn thay đổi.