# פגישות

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

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

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

---

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

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

| שדה | תיאור |
|---|---|
| `id` | מזהה ייחודי של הפגישה. |
| `contact_id` | מזהה איש הקשר שעבורו נקבעה הפגישה. |
| `event_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 Calendar המקושר. נקבע ברגע שסנכרון היומן מסתיים; `null` כאשר לא מחובר יומן או בזמן שהסנכרון עדיין בעיצומו. |
| `calendar_synced` | `true` ברגע שהפגישה מקושרת לאירוע יומן. |
| `imported` | `true` כאשר הפגישה יובאה מיומן חיצוני במקום להיקבע ישירות. |
| `is_recurring` | `true` כאשר הפגישה היא חלק מסדרה חוזרת. |
| `recurrence_frequency` | באיזו תדירות הפגישה חוזרת, כאשר היא חוזרת. |
| `recurring_event_id` | מזהה הסדרה החוזרת שאליה שייכת פגישה זו. |
| `recurring_interval` | מרווח בין חזרות, כאשר היא חוזרת. |
| `recurring_sequence` | מיקום פגישה זו בתוך הסדרה החוזרת שלה. |
| `end_after_x_occurrences` | מספר המופעים שלאחריהם הסדרה החוזרת מסתיימת. |
| `booking_provider` | מערכת המקור שממנה הגיעה ההזמנה, כאשר הוזמנה דרך ספק הזמנות מחובר. |

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

---

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

`GET /appointments/available-slots`

מחזיר את הזמנים הפנויים באמת עבור סוג אירוע מסוים בין שתי נקודות זמן. זוהי בדרך כלל הקריאה ה**ראשונה** בתהליך הזמנה: הצג משבצות אלו, תן לאדם לבחור אחת, ולאחר מכן שלח (post) את הזמן שנבחר אל [קביעת פגישה](#book-an-appointment).

התשובה כבר לוקחת בחשבון את שעות הפתיחה ואורך המשבצת של סוג האירוע עצמו, את החדרים שלו, פגישות שכבר קבעת בו, וכל מה שחסום ביומני 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` הם ערכי שעון קיר באזור הזמן של סוג האירוע עצמו (ההגדרה העוקפת שלו, או אזור הזמן של החשבון שלך כשאין כזו). [קביעת פגישה](#book-an-appointment) מצפה לזמן UTC בתבנית ISO 8601, לכן המר את המשבצת שבחרת לפני שליחתה.

**cURL**

```bash
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**

```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**

```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`):

```json
{
  "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` | כן | מזהה איש הקשר שעבורו יש לקבוע. חייב להיות שייך לחשבונך. |
| `event_id` | כן | מזהה סוג האירוע שעליו יש לקבוע. חייב להיות שייך לחשבונך. |
| `start_time` | כן | התחלה רצויה כתאריך-שעה בפורמט ISO 8601. |
| `room_name` | לא | שם חדר או משאב, כאשר סוג האירוע משתמש בחדרים. |

**cURL** (באמצעות טופס השאילתה `?apiKey=`)

```bash
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**

```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**

```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`):

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

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

**cURL**

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

**JavaScript**

```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**

```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`):

```json
{
  "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` | לא | החזר רק פגישות ביום זה ביומן (`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` בכל החשבון.
- המסנן `date` ללא `contact_id`, או `status=Canceled` יחד עם `contact_id`, מחזיר `400`.

**cURL**

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

**JavaScript**

```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**

```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`):

```json
{
  "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`. עיין ב-[שגיאות ודפדוף](errors-and-pagination.md) עבור תבנית הדפדוף המשותפת.

---

## עדכון פגישה

`PUT /appointments/{appointmentId}`

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

| שדה | תיאור |
|---|---|
| `start_time` | התחלה חדשה, תאריך-שעה בפורמט ISO 8601. |
| `end_time` | סיום חדש, תאריך-שעה בפורמט ISO 8601. חייב להיות לאחר זמן ההתחלה. |
| `room_name` | שם חדש של חדר או משאב. |
| `description` | תיאור חדש, או `null` כדי לנקות אותו. |
| `summary` | סיכום חדש, או `null` כדי לנקות אותו. |

**cURL**

```bash
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**

```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**

```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`):

```json
{
  "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**

```bash
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**

```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**

```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`):

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

---

## מחיקת פגישה

`DELETE /appointments/{appointmentId}`

מוחק לצמיתות פגישה ואת ההפניות אליה. אם ברצונך רק לבטל את ההזמנה תוך שמירה על התיעוד, השתמש ב-[ביטול](#cancel-an-appointment) במקום זאת.

**cURL**

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

**JavaScript**

```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**

```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`):

```json
{
  "success": true
}
```

---

## הצגת יומני Google המחוברים שלך

`GET /appointments/google-calendars`

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

זה עובד רק לאחר שהחשבון חיבר את Google Calendar (הגדרות ← אינטגרציות) עם הרשאת קריאה לפחות. אם לא, או אם הגישה שניתנה כבר לא כוללת את טווח הקריאה ליומן (calendar-read scope), תקבל `400` שינחה אותך לחבר (או לחבר מחדש) אותו.

**cURL**

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

**JavaScript**

```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**

```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`):

```json
{
  "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`](https://developers.google.com/calendar/api/v3/reference/calendarList) של גוגל עצמה, לכן שמות השדות עוקבים אחר ה-`camelCase` של גוגל, ולא אחר ה-`snake_case` הרגיל של ה-API הזה — מדובר בנתונים של גוגל שעוברים כפי שהם, ולא שלנו. חיבור חסר או מבוטל יחזיר `400` עם שגיאה שמסבירה שיש לחבר (או לחבר מחדש) את Google Calendar.

---

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

`POST /appointments/import-calendar-events`

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

| שדה | חובה | תיאור |
|---|---|---|
| `campaign_id` | אחד משניים אלו | הקמפיין שממנו יש לייבא את היומן/יומנים המחוברים. |
| `agent_id` | אחד משניים אלו | סוכן ה-AI שממנו יש לייבא את היומן/יומנים המחוברים. |
| `identifier` | כן | `"EMAIL"` או `"PHONE_NUMBER"` — איזה פרט איש קשר לחלץ מכל אירוע ביומן כדי להתאים או ליצור את איש הקשר שאליו הוא שייך. |

שלח בדיוק אחד מבין `campaign_id` / `agent_id`, לעולם לא את שניהם ולעולם לא אף אחד מהם — כל שילוב אחר יחזיר `400`. כל אחד מהם שתשלח חייב להיות שייך לחשבון שלך, אחרת תקבל `404`.

**cURL**

```bash
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**

```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**

```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`):

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

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

**תגובה** (`200 OK`):

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

| `status` | משמעות |
|---|---|
| `queued` | טרם נאסף. המשך לבדוק. |
| `processing` | הייבוא מתבצע. המשך לבדוק. |
| `completed` | הושלם — `message` מכיל סיכום קצר וקריא. |
| `failed` | משהו השתבש — `error` מכיל את הסיבה. |

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

---

## אינטגרציות להזמנת מסעדות (Zenchef / Formitable)

Zenchef ו-Formitable הן מערכות להזמנת מקומות במסעדות שסוכן ה-AI שלך יכול להזמין דרכן שולחנות בפועל. לכל אחת יש **ווידג'ט הזמנות ציבורי ללא אימות** (`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`

| שדה | נדרש | תיאור |
|---|---|---|
| `restaurant_id` | כן | מזהה המסעדה ב-Zenchef לבדיקה. |

```bash
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`):

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

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

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

`POST /appointments/zenchef-restaurants/verify-name`

| שדה | נדרש | תיאור |
|---|---|---|
| `restaurant_id` | כן | מזהה המסעדה ב-Zenchef משלב 1. |
| `user_input_name` | כן | השם שבעל החשבון הקליד — מושווה מול השם האמיתי של המסעדה ב-Zenchef (ללא רגישות לאותיות גדולות/קטנות או רווחים). |

```bash
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`):

```json
{
  "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`

| שדה | נדרש | תיאור |
|---|---|---|
| `restaurant_id` | כן | 1–64 תווים, אותיות/מספרים/קו תחתון/מקף. |
| `restaurant_name` | כן | שם המסעדה המאומת משלב 2. |

```bash
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`):

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

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

`PUT /appointments/zenchef-restaurants/{restaurantId}`

| שדה | נדרש | תיאור |
|---|---|---|
| `restaurant_name` | לא | שם תצוגה חדש. |
| `is_active` | לא | הגדר את `false` כדי למנוע מהבוט לבצע הזמנות מול מסעדה זו מבלי להסיר אותה. |

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

```bash
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`

| שדה | נדרש | תיאור |
|---|---|---|
| `restaurant_id` | כן | מזהה המסעדה ב-Formitable. |
| `language` | לא | תג שפה עבור בקשת הבדיקה. ברירת המחדל היא `"nl"`. |

```bash
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`):

```json
{
  "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"`.

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

**תגובה** (`200 OK`):

```json
{
  "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)://`. |

```bash
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` | לא | כתובת אתר חדשה. |

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

```bash
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 של פגישות

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

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

| סטטוס | מתי זה קורה בנקודת קצה של פגישה |
|---|---|
| `400` | שדה חובה חסר או לא תקין — לדוגמה, `start_time` שגוי, `end_time` שאינו אחרי `start_time`, שילוב מסננים לא תקין, אין שדות לעדכון, או פגישה שכבר בוטלה. |
| `404` | הפגישה, איש הקשר או סוג האירוע לא נמצאו. |
| `409` | משבצת הזמן המבוקשת כבר תפוסה (התנגשות בזימון). |

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

---

## צעדים הבאים

- [אנשי קשר](contacts.md) — צור וחפש את אנשי הקשר עבורם אתה מבצע הזמנות.
- [הודעות ושיחות](messages.md) — שלח לאיש קשר אישור או תזכורת.
- [Webhooks](webhooks.md) — קבל התראות כאשר פגישות משתנות.