פגישות #

ממשק ה-API של פגישות (Appointments API) מאפשר לך לקבוע פגישות עבור אנשי הקשר שלך בסוגי האירועים שלך, ולאחר מכן לאחזר, להציג, לעדכן, לבטל או למחוק אותן. הוא גם עונה על השאלה שעולה ראשונה ברוב תהליכי ההזמנה — אילו זמנים הם אכן פנויים — ומכסה את הצד של היומן: הצגת יומני Google שחיברת וייבוא אירועים שכבר קיימים בהם. כאשר חיבור ליומן Google פעיל, אירוע היומן התואם נוצר ומסונכרן באופן אוטומטי ברקע. מסעדות המשתמשות ב-Zenchef, Formitable, OpenTable או TheFork עבור מערכת ההזמנות שלהן יכולות גם הן לעבור אימות וחיבור כאן, כך שהסוכן הבינה המלאכותית (AI Agent) יזמין שולחנות אמיתיים במקום פגישות פנימיות — ועסקים מבוססי פגישות שמנהלים את לוח הזמנים שלהם ב-Trafft יכולים להתחבר באותה דרך.

כל הנתיבים בדף זה הם יחסיים לכתובת ה-URL הבסיסית https://api.youraiconnector.com/v1. כל בקשה דורשת את מפתח ה-API שלך — ראה אימות לרשימה המלאה של הדרכים לשליחתו. הדוגמאות להלן משתמשות בכותרת X-API-Key, כאשר דוגמת cURL אחת מציגה גם את טופס השאילתה ?apiKey=.

אירועים לעומת פגישות: סוג אירוע הוא הגדרה של משבצת זמן שניתן להזמין (סוג הפגישה, משכה, החדרים שלה). פגישה היא מופע אחד מוזמן של סוג אירוע עבור איש קשר ספציפי. אתה קובע פגישה על ידי הפניה לאיש הקשר ולסוג האירוע.

אובייקט הפגישה #

כל נקודת קצה (endpoint) שמחזירה פגישה משתמשת באותו מבנה:

אודות סנכרון יומן: מיד לאחר שאתה קובע או משנה פגישה, google_calendar_event_id עשוי עדיין להיות null ו-calendar_synced עשוי להיות false מכיוון שהסנכרון פועל ברקע רגע לאחר מכן. אחזר את הפגישה שוב זמן קצר לאחר מכן כדי לראות את שדות היומן המאוכלסים.

מציאת משבצות פנויות #

GET /appointments/available-slots

מחזיר את הזמנים הפנויים באמת עבור סוג אירוע מסוים בין שתי נקודות זמן. זוהי בדרך כלל הקריאה הראשונה בתהליך הזמנה: הצג משבצות אלו, תן לאדם לבחור אחת, ולאחר מכן שלח (post) את הזמן שנבחר אל קביעת פגישה.

התשובה כבר לוקחת בחשבון את שעות הפתיחה ואורך המשבצת של סוג האירוע עצמו, את החדרים שלו, פגישות שכבר קבעת בו, וכל מה שחסום ביומני Google המחוברים — כך שמשבצת שמוחזרת כאן היא משבצת שניתן להזמין.

התוצאות מוחזרות כשהן מקובצות לפי יום — וכאשר סוג האירוע משתמש בחדרים, קבוצה אחת לכל חדר בכל יום:

לכל רשומה ב-available_slots יש:

הזמנים הם מקומיים לסוג האירוע, לא לפי UTC. date, start_time, ו-end_time הם ערכי שעון קיר באזור הזמן של סוג האירוע עצמו (ההגדרה העוקפת שלו, או אזור הזמן של החשבון שלך כשאין כזו). קביעת פגישה מצפה לזמן UTC בתבנית ISO 8601, לכן המר את המשבצת שבחרת לפני שליחתה.

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

יוצר פגישה עבור אחד מאנשי הקשר שלך. ישנן שתי דרכים להשתמש בזה:

• על אחד מסוגי האירועים שלך — שלח event_id, וההזמנה תעבוד בדיוק כפי שעבדה תמיד: זמינות ותפוסה נשמרות, זמן הסיום מחושב לפי משך המשבצת של סוג האירוע, והפגישה מסתנכרנת ל-Google Calendar שלך כאשר הוא מחובר.
• כהזמנה חיצונית — השאר את event_id ריק ושלח title במקום. זה רושם הזמנה שבוצעה במקום אחר (מערכת ה-CRM שלך, לוח זמנים של שיעורים, כלי הזמנות אחר) כך שהיא תופיע בדף הפגישות לצד השאר.

הזמנה לסוג אירוע עם חדרים חייבת להתבצע בזמן ש-מצא משבצות זמינות יציע: בתוך שעות הפעילות של החדר, מחוץ לתקופת ההתראה, בטווח הזמן שבו ניתן להזמין את סוג האירוע, על רשת המשבצות, לא בעבר, ולא חסום ביומן מקושר. כל זמן אחר יידחה עם 400 ולא ייווצר דבר. כך גם לגבי room_name שאינו תואם לאף אחד מהחדרים של סוג האירוע (ההודעה מפרטת את השמות התקינים). זמני חיץ המוגדרים בסוג האירוע (חיץ לפני ו-חיץ אחרי בעורך סוג האירוע, buffer_before ו-buffer_after בדקות) נשמרים פנויים סביב כל הזמנה.

הזמנה לסוג אירוע עוברת גם בדיקת התנגשות: אם המשבצת כבר מלאה, הבקשה תיכשל עם 409 ושום דבר לא ייווצר. להזמנה חיצונית אין סוג אירוע מאחוריה, לכן שום דבר לא נבדק מול הזמינות או הקיבולת שלך ושום דבר לא מסתנכרן ליומן.

ניסיון חוזר הוא בטוח. אם לאותו איש קשר כבר יש הזמנה מאושרת לאותו סוג אירוע באותה שעת התחלה (באותו חדר, כאשר מציינים אחד), למשל בגלל שהבקשה הראשונה שלך פגה לאחר שהיא עברה, תקבל את אותה הזמנה בחזרה עם 200 ו-"replayed": true במקום הזמנה שנייה או 409.

ה-external_reference משמש כמפתח אידמפוטנטיות (idempotency key). הוא ייחודי לחשבון שלך: אם פגישה כבר נושאת את המזהה ששלחת, פגישה זו תוחזר עם 200 ו-"replayed": true ולא ייווצר דבר חדש, גם אם הניסיון החוזר מציין זמן או איש קשר שונים, וללא קשר לסטטוס של אותה פגישה. השתמש בו עבור הזמנות בתשלום (שלח את מזהה התשלום או ההזמנה שלך), ושלח מזהה חדש עבור הזמנה חדשה באמת.

שלח event_id ו-title יחד, או אף אחד מהשניים, והבקשה תחזיר 400 — כפי שקורה בשליחת גם end_time וגם duration_minutes.

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

רישום הזמנה שבוצעה במקום אחר #

אותו נקודת קצה (endpoint), ללא סוג אירוע: title ו-start_time מספיקים, ו-duration_minutes קובע כמה זמן היא נמשכת.

cURL

curl -X POST "https://api.youraiconnector.com/v1/appointments" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "contact_abc123",
    "title": "Beginner guitar class",
    "start_time": "2026-06-15T10:00:00.000Z",
    "duration_minutes": 90,
    "external_reference": "class-slot-4812"
  }'

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",
    title: "Beginner guitar class",
    start_time: "2026-06-15T10:00:00.000Z",
    duration_minutes: 90,
  }),
});
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",
        "title": "Beginner guitar class",
        "start_time": "2026-06-15T10:00:00.000Z",
        "duration_minutes": 90,
    },
)
print(res.json()["appointment_id"])

תגובה (201 Created):

{
  "success": true,
  "appointment_id": "eFgH5678aBcD1234",
  "appointment": {
    "id": "eFgH5678aBcD1234",
    "contact_id": "contact_abc123",
    "event_id": null,
    "status": "Confirmed",
    "start_time": "2026-06-15T10:00:00.000Z",
    "end_time": "2026-06-15T11:30:00.000Z",
    "created_at": "2026-06-10T09:00:00.000Z",
    "last_modified_at": "2026-06-10T09:00:00.000Z",
    "summary": "Beginner guitar class",
    "google_calendar_event_id": null,
    "calendar_synced": false
  }
}

הזמנות חיצוניות הן פגישות רגילות מרגע זה ואילך: הן מופיעות בדף הפגישות וב-רשימת פגישות, ניתן לתזמן אותן מחדש, לבטל או למחוק אותן באפליקציה או דרך API זה, אימייל אישור ההזמנה נשלח כרגיל, וטריגר האוטומציה פגישה נקבעה (Appointment booked) ו-webhook מופעלים עבורן כמו עבור כל הזמנה אחרת שבוצעה דרך ה-API. ההבדלים היחידים הם אלו שלעיל — ללא בדיקת זמינות או תפוסה, ללא סנכרון יומן, ו-event_id נשאר null.

קבלת פגישה #

GET /appointments/{appointmentId}

מחזיר פגישה בודדת לפי המזהה שלה, כולל מצב הסנכרון שלה עם היומן.

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

מציג רשימת פגישות עבור החשבון שלך, מהחדשה לישנה, עם דפדוף מבוסס סמן (cursor-based pagination).

כמה כללים שכדאי לזכור:

• ללא מסננים, תקבל את כל הפגישות בחשבון, דף אחר דף.
• לפי איש קשר — הגדר את contact_id כדי לראות את הפגישות המאושרות של איש קשר אחד. ניתן לצמצם זאת ליום בודד על ידי העברת date גם כן.
• לפי סטטוס — הגדר את status (ללא contact_id) כדי להציג רק פגישות Confirmed או רק פגישות Canceled בכל החשבון.
• המסנן date ללא contact_id, או 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 או room_name חדש) עוברת בדיקת התנגשות כמו הזמנה חדשה: משבצת שכבר מלאה תענה ב-409 ושום דבר לא ישתנה, ו-room_name שאינו תואם לאף אחד מהחדרים של סוג האירוע יענה ב-400. שלח רק את start_time וההזמנה תשמור על אורכה. שעות הפתיחה ותקופת ההתראה שלך לא מיושמות כאן, כך שעדיין ניתן להעביר הזמנה לכל זמן פנוי.

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.

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

שליחה מחדש של אישור ההזמנה #

POST /appointments/{appointmentId}/resend-confirmation

שולח לאיש הקשר את אישור ההזמנה שלו שוב, למשל כאשר הוא טוען שהוא מעולם לא הגיע או הגיע לתיקיית הספאם. מורכב משני חלקים, שניהם נשלחים אלא אם תכבה אחד מהם: אימייל האישור (אותו אימייל שאיש הקשר קיבל בעת ביצוע ההזמנה) וכאשר הפגישה מופיעה ביומן Google שלך, הזמנת יומן Google. שניהם נשלחים לכתובת האימייל של איש הקשר.

כל חלק חוזר עם תוצאה משלו: sent, not_requested, no_contact_email, turned_off_for_event_type (המתג שלח אימייל פגישה לאיש הקשר של סוג האירוע כבוי), not_on_google_calendar, imported (פגישות שיובאו מהיומן שלך לא מקבלות אימייל אישור) או failed.

• 200 כאשר לפחות חלק אחד נשלח. recipient היא הכתובת אליה הוא נשלח.
• 409 עבור פגישה שבוטלה, פגישה שכבר הסתיימה, או הזמנה שבוצעה דרך Zenchef, Formitable, OpenTable, TheFork או Trafft (מערכת זו שולחת אישור משלה). code הוא appointment_canceled, appointment_in_past או managed_by_provider.
• 422 כאשר לא ניתן היה לשלוח דבר, עם הסיבה ב-error.

cURL

curl -X POST "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/resend-confirmation" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/resend-confirmation",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ calendar_invite: false }),
  }
);
const data = await res.json();
console.log(data.email, data.recipient);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/resend-confirmation",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={},
)
print(res.json())

תגובה (200 OK):

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678",
  "email": "sent",
  "calendar_invite": "sent",
  "recipient": "jane@example.com"
}

מחיקת פגישה #

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 Calendar (הגדרות ← אינטגרציות) עם הרשאת קריאה לפחות. אם לא, או אם הגישה שניתנה כבר לא כוללת את טווח הקריאה ליומן (calendar-read scope), תקבל 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"
    }
  ]
}

כל רשומה היא במבנה ה-CalendarListEntry של גוגל עצמה, לכן שמות השדות עוקבים אחר ה-camelCase של גוגל, ולא אחר ה-snake_case הרגיל של ה-API הזה — מדובר בנתונים של גוגל שעוברים כפי שהם, ולא שלנו. חיבור חסר או מבוטל יחזיר 400 עם שגיאה שמסבירה שיש לחבר (או לחבר מחדש) את Google Calendar.

ייבוא אירועים מיומן Google Calendar #

POST /appointments/import-calendar-events

מושך את האירועים שכבר קיימים ביומן/יומני Google המחוברים לקמפיין או לסוכן AI והופך אותם לפגישות — שימושי בפעם הראשונה שאתה מחבר יומן שכבר מכיל הזמנות. זה עלול לקחת זמן (כל אירוע עובר תהליך חילוץ כדי להבין למי הוא מיועד), לכן זה לעולם לא רץ באופן מיידי (inline): הבקשה מכניסה לתור משימת רקע ומחזירה לך job_id לבדיקת סטטוס (polling).

שלח בדיוק אחד מבין 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
}

GET על jobId שלא קיים (או ששייך לחשבון אחר) יחזיר 404.

אינטגרציות הזמנה חיצוניות (Zenchef / Formitable / OpenTable / TheFork / Trafft) #

Zenchef ו-Formitable הן מערכות להזמנת מקומות במסעדות שדרכן סוכן ה-AI שלך יכול להזמין שולחנות אמיתיים; Trafft היא פלטפורמת תזמון לעסקים מבוססי פגישות, המחוברת פעם אחת לכל חשבון ולא לכל מסעדה. לשתי פלטפורמות המסעדות יש ווידג’ט הזמנות ציבורי ללא אימות (https://api.youraiconnector.com/v1/zenchef-widget/... ו-https://api.youraiconnector.com/v1/formitable-widget/...) שמוצג בתוך הצ’אט עבור הסועד — נתיבי הווידג’ט הללו הם דפי HTML פשוטים שנועדו להיפתח בדפדפן, ולא נקודות קצה של JSON API, לכן הם אינם מתועדים כאן. להלן נקודות הקצה לניהול חשבון: אימות שמזהה מסעדה שייך לבעל החשבון, ולאחר מכן הוספה, עדכון או הסרה שלו.

Zenchef #

חיבור מסעדה ב-Zenchef הוא תהליך אימות דו-שלבי, כך שבעל החשבון מוכיח שהוא אכן מנהל את המסעדה לפני שהיא מקושרת לבוט: ראשית יש לבדוק שהמזהה קיים (מבלי לחשוף את השם), ולאחר מכן לבקש מהם להקליד את שם המסעדה בעצמם ולוודא שהוא תואם.

שלב 1 — בדיקת קיום מזהה מסעדה

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

תגובה (200 OK):

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

exists: false פירושו שאף מסעדת Zenchef אינה מחזיקה במזהה זה — אין מה לעשות מעבר לכך. מוגבל ל-10 בדיקות לכל 5 דקות לכל חשבון; חריגה מכך תחזיר 429.

שלב 2 — אימות שם המסעדה

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

תגובה (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 מושמט, בקש מבעל החשבון לנסות שוב. מוגבל ל-3 ניסיונות לכל 5 דקות (מחמיר יותר מבדיקת הקיום, כיוון שזהו שלב ההוכחה בפועל). restaurant_id שכבר לא קיים ב-Zenchef יחזיר 404.

שלב 3 — שמירת המסעדה

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

תגובה (201 Created):

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

עדכון מסעדת Zenchef שמורה

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

תגובה (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 — מזהי המסעדות שלה כבר מוגדרים ברמת העסק, לכן קריאת אימות אחת מספיקה. היא כוללת גם חיפוש פרטים המשמש לשמירה במטמון של כתובת אתר האינטרנט של המסעדה במהלך ההגדרה.

אימות מזהה מסעדה

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

תגובה (200 OK):

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

עבור restaurant_id ש-Formitable אינה מזהה, תוחזר שגיאת 404. מוגבל ל-10 ניסיונות לכל 5 דקות לכל חשבון.

קבלת פרטי מסעדה

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

שולף את הפרופיל הציבורי של המסעדה מ-Formitable, כולל אתר האינטרנט שלה — משמש לשמירה במטמון של כתובת האתר בזמן הגדרת המסעדה. 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

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}

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 בעת עדכון או מחיקה.

OpenTable #

אל מסעדות OpenTable מגיעים דרך אישורי השותף של OpenTable בפלטפורמה, ו-OpenTable מאפשרת לאישורים אלו לראות רק מסעדות שחיברו את הרישום של הפלטפורמה בתוך ה-Integrations Marketplace של OpenTable. לכן, בדומה ל-Formitable, קריאת אימות אחת מספיקה: מזהה מסעדה (Restaurant ID) נגיש (המספר “RID”) מוכיח גם שהמסעדה קיימת וגם שהיא חיברה את האינטגרציה. עד שרישום השותף של OpenTable יופעל בפלטפורמה, קריאת האימות תחזיר 503.

אימות מסעדת OpenTable

POST /appointments/opentable-restaurants/verify

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

תגובה (200 OK):

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "restaurantId": "1038007",
      "diningAreaCount": 2,
      "diningAreaNames": ["Main Room", "Garden"],
      "tableTypes": ["default", "outdoor", "bar"]
    }
  }
}

verified: false פירושו שאף מסעדת OpenTable אינה מחזיקה במזהה זה. 403 פירושו שהמסעדה קיימת אך טרם חיברה את האינטגרציה של הפלטפורמה בתוך OpenTable. מוגבל ל-10 ניסיונות לכל 5 דקות לכל חשבון.

הוספת מסעדת OpenTable

POST /appointments/opentable-restaurants

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

תגובה (201 Created): { "success": true, "data": { "restaurantId": "1038007" } }

עדכון מסעדת OpenTable שמורה

PUT /appointments/opentable-restaurants/{restaurantId}

שלח כל אחד מ-restaurant_name, is_active (השהיה עם false) או website_url (מחרוזת ריקה מנקה אותו); שדות שהושמטו נותרים ללא שינוי.

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

תגובה (200 OK): { "success": true, "data": { "restaurantId": "1038007" } }

הסרת מסעדת OpenTable

DELETE /appointments/opentable-restaurants/{restaurantId}

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

תגובה (200 OK): { "success": true, "data": { "restaurantId": "1038007" } }

עבור restaurantId שאינו נמצא כרגע בחשבון, תוחזר השגיאה 404 בעת עדכון.

TheFork #

הגישה למסעדות TheFork מתבצעת באמצעות אישורי השותף של TheFork בפלטפורמה, ו-TheFork מאפשרת לאישורים אלו לראות רק מסעדות שהפעילו את השותף של הפלטפורמה בחשבון ה-TheFork שלהן. לכן, בדומה ל-Formitable ו-OpenTable, קריאת אימות אחת מספיקה: מזהה מסעדה (Restaurant ID) נגיש מוכיח גם שהמסעדה קיימת וגם שהשותף מופעל בה. המזהה הוא ה-UUID ש-TheFork מעניקה למסעדה ב-TheFork Manager, ונשלח כמחרוזת. עד ש-TheFork תאשר את הפלטפורמה כשותפה ותנפיק את האישורים, קריאת האימות תענה 503 — ראה TheFork למה זה אומר כיום.

אימות מסעדת TheFork

POST /appointments/thefork-restaurants/verify

curl -X POST "https://api.youraiconnector.com/v1/appointments/thefork-restaurants/verify?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" }'

תגובה (200 OK):

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60",
      "partySizes": [1, 2, 3, 4, 5, 6, 7, 8]
    }
  }
}

partySizes הם גדלי הקבוצות שהמסעדה מקבלת באופן מקוון במהלך 30 הימים הקרובים. 404 או 403 פירושם ש-TheFork לא סיפקה לנו מסעדה עם המזהה הזה — או שהמזהה שגוי, או שהשותף של הפלטפורמה עדיין לא מופעל במסעדה זו; 400 פירושו שהמזהה אינו UUID. מוגבל ל-10 ניסיונות לכל 5 דקות לכל חשבון.

הוספת מסעדת TheFork

POST /appointments/thefork-restaurants

curl -X POST "https://api.youraiconnector.com/v1/appointments/thefork-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60", "restaurant_name": "The Blue Door", "website_url": "https://thebluedoor.example" }'

תגובה (201 Created): { "success": true, "data": { "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" } }

עדכון מסעדת TheFork שמורה

PUT /appointments/thefork-restaurants/{restaurantId}

שלח כל אחד מ-restaurant_name, is_active (השהיה עם false) או website_url (מחרוזת ריקה מנקה אותו); שדות שהושמטו נותרים ללא שינוי.

curl -X PUT "https://api.youraiconnector.com/v1/appointments/thefork-restaurants/9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

תגובה (200 OK): { "success": true, "data": { "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" } }

הסרת מסעדת TheFork

DELETE /appointments/thefork-restaurants/{restaurantId}

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/thefork-restaurants/9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" \
  -H "X-API-Key: YOUR_API_KEY"

תגובה (200 OK): { "success": true, "data": { "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" } }

restaurantId שאינו נמצא כרגע בחשבון יחזיר 404 בעת עדכון או מחיקה.

Trafft #

Trafft מחובר פעם אחת עבור כל החשבון, לא לכל מיקום: כתובת חברה אחת בתוספת אישורי ה-API מלוח הבקרה של מנהל Trafft (Features & Integrations → API & Connectors, חלק מהתוכנית העסקית של Trafft). קריאת החיבור בודקת את האישורים הללו מול Trafft לפני אחסון כל דבר, כך שכתובת שגויה, אישורים שגויים או תוכנית ללא גישת API ייכשלו כאן ולא במהלך שיחה עם לקוח. ה-client secret מאוחסן בצורה מוצפנת ולעולם אינו מוחזר על ידי אף נקודת קצה.

כל שלוש קריאות הכתיבה (POST, PUT, DELETE) דורשות הרשאת עריכה (edit) של אינטגרציות; הסטטוס GET דורש הרשאת צפייה (view) של אינטגרציות.

חיבור Trafft

POST /appointments/trafft/connect

curl -X POST "https://api.youraiconnector.com/v1/appointments/trafft/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subdomain": "acme",
    "client_id": "YOUR_TRAFFT_CLIENT_ID",
    "client_secret": "YOUR_TRAFFT_CLIENT_SECRET",
    "company_name": "Acme Salon"
  }'

תגובה (200 OK):

{
  "success": true,
  "data": {
    "subdomain": "acme",
    "service_count": 12,
    "employee_count": 4,
    "location_count": 2
  }
}

הספירות חוזרות מ-Trafft במהלך הבדיקה — הן הדרך המהירה ביותר לאשר שהאישורים מצביעים על החשבון שאליו התכוונת.

קבלת סטטוס החיבור

GET /appointments/trafft

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

תגובה (200 OK):

{
  "success": true,
  "data": {
    "connected": true,
    "subdomain": "acme",
    "hostname": "acme.admin.trafft.com",
    "client_id": "YOUR_TRAFFT_CLIENT_ID",
    "company_name": "Acme Salon",
    "is_active": true,
    "service_count": 12,
    "employee_count": 4,
    "location_count": 2
  }
}

connected: false אומר ששום דבר עדיין לא הוגדר. ה-client secret לעולם אינו נכלל בתגובה זו.

עדכון החיבור

PUT /appointments/trafft

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

תגובה (200 OK): אותו אובייקט חיבור כמו ה-GET לעיל.

ניתוק Trafft

DELETE /appointments/trafft

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

תגובה (200 OK): { "success": true }

ניתוק מסיר רק את פרטי ההתחברות השמורים. פגישות שכבר נמצאות ב-Trafft נשארות ללא שינוי.

מבנה שגיאה בכל נקודות הקצה של Zenchef/Formitable/OpenTable/TheFork: בניגוד לשאר דף זה, שגיאות כאן נושאות את הסטטוס שלהן פעמיים — פעם אחת כסטטוס HTTP ופעם אחת כ-error_code בגוף התגובה — לדוגמה { "success": false, "error": "Restaurant not found", "error_code": 404 }. יש לטפל בכך באותו אופן כמו בכל שגיאה אחרת: בדוק את success, וקרא את error עבור ההודעה.

שגיאות ב-API של פגישות #

נקודות הקצה של פגישות מחזירות את מעטפת השגיאה הסטנדרטית:

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

הקודים המשותפים שכל נקודת קצה יכולה להחזיר — 401, 403 (התוכנית שלך אינה כוללת גישת API), 429 (מגבלת קצב) ו-500 — מפורטים עם הנחיות לניסיון חוזר ב-שגיאות ועימוד.

צעדים הבאים #

• אנשי קשר — צור וחפש את אנשי הקשר עבורם אתה מבצע הזמנות.
• הודעות ושיחות — שלח לאיש קשר אישור או תזכורת.
• Webhooks — קבל התראות כאשר פגישות משתנות.