# Randevular

Randevu API'si, kişileriniz için etkinlik türleriniz üzerinden randevu almanıza, ardından bunları getirmenize, listelemenize, güncellemenize, iptal etmenize veya silmenize olanak tanır. Ayrıca çoğu rezervasyon akışında ilk sorulan soruyu — hangi zamanların gerçekten boş olduğunu — yanıtlar ve takvim tarafını kapsar: bağlı olan Google Takvimlerinizi listeler ve halihazırda içinde bulunan etkinlikleri içe aktarır. Bir Google Takvim bağlantısı aktif olduğunda, eşleşen takvim etkinliği oluşturulur ve arka planda otomatik olarak senkronize edilir. Kendi rezervasyon sistemleri için Zenchef veya Formitable kullanan restoranlar da burada doğrulanabilir ve bağlanabilir, böylece Yapay Zeka Temsilcisi dahili randevular yerine gerçek masalar için rezervasyon yapar.

Bu sayfadaki tüm yollar `https://api.youraiconnector.com/v1` temel URL'sine göredir. Her istek API anahtarınızı gerektirir — gönderme yollarının tam listesi için [Kimlik Doğrulama](authentication.md) bölümüne bakın. Aşağıdaki örnekler `X-API-Key` başlığını kullanır; bir cURL örneği ise `?apiKey=` sorgu biçimini de gösterir.

> **Etkinlikler ve randevular:** *Etkinlik türü*, rezerve edilebilir bir zaman dilimi tanımıdır (toplantı türü, süresi, odaları). *Randevu*, belirli bir kişi için bir etkinlik türünün rezerve edilmiş bir örneğidir. Bir kişiye ve etkinlik türüne referans vererek bir randevu alırsınız.

---

## Randevu nesnesi

Randevu döndüren her uç nokta aynı yapıyı kullanır:

| Alan | Açıklama |
|---|---|
| `id` | Randevunun benzersiz kimliği. |
| `contact_id` | Randevunun alındığı kişinin kimliği. |
| `event_id` | Randevunun alındığı etkinlik türünün kimliği. |
| `status` | `Confirmed` veya `Canceled`. |
| `start_time` | Randevunun başlangıcı, UTC cinsinden ISO 8601. |
| `end_time` | Randevunun bitişi, UTC cinsinden ISO 8601. |
| `created_at` | Randevunun oluşturulduğu zaman. |
| `last_modified_at` | Randevunun en son değiştirildiği zaman. |
| `room_name` | Etkinlik türü oda kullandığında, randevunun alındığı oda veya kaynak. |
| `description` | Randevunun serbest biçimli açıklaması. |
| `summary` | Kısa özet veya başlık. |
| `cancelation_reason` | Varsa, randevu iptal edildiğinde sağlanan neden. |
| `google_calendar_event_id` | Bağlantılı Google Takvim etkinliğinin kimliği. Takvim senkronizasyonu tamamlandığında ayarlanır; takvim bağlı olmadığında veya senkronizasyon devam ederken `null` değerini alır. |
| `calendar_synced` | Randevu bir takvim etkinliğine bağlandığında `true` değerini alır. |
| `imported` | Randevu doğrudan alınmak yerine harici bir takvimden içe aktarıldığında `true` değerini alır. |
| `is_recurring` | Randevu yinelenen bir serinin parçası olduğunda `true` değerini alır. |
| `recurrence_frequency` | Yinelenen randevuların ne sıklıkla tekrarlandığı. |
| `recurring_event_id` | Bu randevunun ait olduğu yinelenen serinin kimliği. |
| `recurring_interval` | Yinelenen randevularda tekrarlar arasındaki aralık. |
| `recurring_sequence` | Bu randevunun yinelenen serisi içindeki konumu. |
| `end_after_x_occurrences` | Yinelenen serinin sona erdiği oluşum sayısı. |
| `booking_provider` | Bağlı bir rezervasyon sağlayıcısı aracılığıyla alındığında, rezervasyonun geldiği kaynak sistem. |

> **Takvim senkronizasyonu hakkında:** Bir randevu aldıktan veya değiştirdikten hemen sonra, senkronizasyon arka planda bir an sonra gerçekleştiği için `google_calendar_event_id` hala `null` olabilir ve `calendar_synced` değeri `false` olabilir. Doldurulmuş takvim alanlarını görmek için kısa bir süre sonra randevuyu tekrar getirin.

---

## Müsait zaman dilimlerini bulma

`GET /appointments/available-slots`

İki zaman dilimi arasında bir etkinlik türü için gerçekten boş olan zamanları döndürür. Bu normalde bir rezervasyon akışındaki **ilk** çağrıdır: bu zaman dilimlerini gösterin, kişinin birini seçmesine izin verin, ardından seçilen zamanı [Randevu al](#book-an-appointment) kısmına gönderin.

Yanıt, etkinlik türünün kendi açılış saatlerini ve zaman dilimi uzunluğunu, odalarını, üzerinde halihazırda ayırttığınız randevuları ve bağlı Google Takvimlerinde engellenen her şeyi hesaba katar; bu nedenle buradan dönen bir zaman dilimi, rezerve edebileceğiniz bir zaman dilimidir.

| Sorgu parametresi | Gerekli | Açıklama |
|---|---|---|
| `event_id` | Evet | Kontrol edilecek etkinlik türü. Hesabınıza ait olmalıdır. |
| `start_time` | Evet | Zaman dilimleri için istediğiniz pencerenin başlangıcı, ISO 8601 tarih-saat formatı. |
| `end_time` | Evet | Pencerenin sonu, ISO 8601 tarih-saat formatı. Günün tamamı dahildir. |

Sonuçlar güne göre gruplandırılmış olarak gelir — ve etkinlik türü odaları kullandığında, oda başına ve gün başına bir grup olacak şekilde:

| Alan | Açıklama |
|---|---|
| `date` | Grubun kapsadığı gün, `DD/MM/YYYY` olarak yazılır. |
| `day` | Küçük harflerle hafta içi adı, örneğin `monday`. |
| `room_name` | Etkinlik türü odaları kullandığında, bu grubun ait olduğu oda veya kaynak. |
| `available_slots` | O gün için rezerve edilebilir bloklar, en erken olandan başlayarak. |

`available_slots` içindeki her giriş şunlara sahiptir:

| Alan | Açıklama |
|---|---|
| `start_time` | `HH:mm` olarak blok başlangıcı. |
| `end_time` | `HH:mm` olarak blok bitişi. |
| `available` | `true` — yalnızca boş zaman döndürülür. |
| `spots_left` | Bu bloğa hala kaç randevunun sığabileceği. Yalnızca zaman dilimi başına birden fazla randevu alan etkinlik türlerinde bulunur. |

> **Zamanlar UTC değil, etkinlik türüne göre yereldir.** `date`, `start_time` ve `end_time`, etkinlik türünün kendi saat dilimindeki (geçersiz kılınmışsa o, yoksa hesap saat diliminizdeki) duvar saati değerleridir. [Randevu al](#book-an-appointment) bir ISO 8601 UTC anı bekler, bu nedenle seçtiğiniz zaman dilimini göndermeden önce dönüştürün.

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

**Yanıt** (`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 }
      ]
    }
  ]
}
```

Boş zamanı olmayan bir gün görünmez. Eksik `event_id`, `start_time` veya `end_time`, `400` döndürür; hesabınızda olmayan bir etkinlik türü `404` döndürür.

---

## Randevu al

`POST /appointments`

Etkinlik türlerinizden biri üzerinden bir kişi için yeni bir randevu alır. Bitiş zamanı, etkinlik türünün zaman dilimi süresinden otomatik olarak hesaplanır.

Rezervasyon çakışma kontrolüne tabidir: İstenen zaman dilimi, aynı etkinlik türündeki mevcut onaylanmış bir randevu ile çakışırsa, istek `409` hatasıyla başarısız olur ve hiçbir şey oluşturulmaz.

| Alan | Gerekli | Açıklama |
|---|---|---|
| `contact_id` | Evet | Randevu alınacak kişinin kimliği. Hesabınıza ait olmalıdır. |
| `event_id` | Evet | Randevu alınacak etkinlik türünün kimliği. Hesabınıza ait olmalıdır. |
| `start_time` | Evet | ISO 8601 tarih-saat formatında istenen başlangıç zamanı. |
| `room_name` | Hayır | Etkinlik türü oda kullandığında, oda veya kaynak adı. |

**cURL** (`?apiKey=` sorgu formunu kullanarak)

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

**Yanıt** (`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
  }
}
```

---

## Randevu al

`GET /appointments/{appointmentId}`

Takvim senkronizasyon durumu dahil olmak üzere, kimliğine göre tek bir randevuyu döndürür.

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

**Yanıt** (`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
  }
}
```

---

## Randevuları listele

`GET /appointments`

Hesabınızdaki randevuları, en yeniden başlayarak ve imleç tabanlı sayfalama ile listeler.

| Sorgu parametresi | Gerekli | Açıklama |
|---|---|---|
| `contact_id` | Hayır | Yalnızca bu kişi için olan randevuları döndürür. Kişi bazlı listelemeler **yalnızca onaylanmış randevuları** içerir. |
| `date` | Hayır | Yalnızca bu takvim günündeki (`YYYY-MM-DD`) randevuları döndürür. **`contact_id` gerektirir.** |
| `status` | Hayır | `Confirmed` veya `Canceled` ile filtreleyin. Yalnızca `contact_id` **olmadan** kullanılabilir. |
| `limit` | Hayır | Sayfa boyutu, 1 ile 100 arasında bir tam sayı. Varsayılan `50`. |
| `cursor` | Hayır | Önceki bir yanıttan gelen `next_cursor` değeri. |

Aklınızda bulundurmanız gereken birkaç kural:

- **Filtre olmadan**, hesaptaki her randevuyu sayfa sayfa alırsınız.
- **Kişiye göre** — bir kişinin onaylanmış randevularını görmek için `contact_id` değerini ayarlayın. Ayrıca `date` parametresini göndererek bunu tek bir günle sınırlandırabilirsiniz.
- **Duruma göre** — hesap genelinde yalnızca `Confirmed` veya yalnızca `Canceled` randevuları listelemek için `status` değerini ( `contact_id` olmadan) ayarlayın.
- `contact_id` olmadan `date` filtresi veya `contact_id` ile birlikte `status=Canceled`, bir `400` döndürür.

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

**Yanıt** (`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
}
```

Sonuçlar arasında gezinmek için, bir yanıttan gelen `next_cursor` değerini bir sonraki isteğin `cursor` parametresi olarak gönderin. `next_cursor` değeri `null` olana kadar devam edin. Paylaşılan sayfalama düzeni için [Hatalar ve Sayfalama](errors-and-pagination.md) bölümüne bakın.

---

## Randevuyu güncelle

`PUT /appointments/{appointmentId}`

Bir randevuyu yeniden planlayın veya ayrıntılarını değiştirin. Yalnızca değiştirmek istediğiniz alanları gönderin; en az bir alan gereklidir. Birleşik başlangıç ve bitiş zamanları kronolojik sırada kalmalıdır (`end_time`, `start_time` değerinden sonra olmalıdır). Değişiklikler, bağlantılı takvim etkinliği ile otomatik olarak senkronize edilir.

| Alan | Açıklama |
|---|---|
| `start_time` | Yeni başlangıç, ISO 8601 tarih-saat formatı. |
| `end_time` | Yeni bitiş, ISO 8601 tarih-saat formatı. Başlangıç zamanından sonra olmalıdır. |
| `room_name` | Yeni oda veya kaynak adı. |
| `description` | Yeni açıklama veya temizlemek için `null`. |
| `summary` | Yeni özet veya temizlemek için `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"])
```

**Yanıt** (`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
  }
}
```

---

## Bir randevuyu iptal et

`POST /appointments/{appointmentId}/cancel`

Onaylanmış bir randevuyu, isteğe bağlı olarak bir neden belirterek iptal eder. Randevu, `Canceled` durumuyla hesabınızda kalır ve bağlantılı takvim etkinliği arka planda otomatik olarak kaldırılır. Zaten iptal edilmiş bir randevuyu iptal etmek `400` döndürür.

| Alan | Gerekli | Açıklama |
|---|---|---|
| `cancellation_reason` | Hayır | Randevuda saklanacak iptal nedeni. |

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

**Yanıt** (`200 OK`):

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

---

## Bir randevuyu sil

`DELETE /appointments/{appointmentId}`

Bir randevuyu ve referanslarını kalıcı olarak siler. Eğer sadece kaydı tutarak rezervasyonu iptal etmek istiyorsanız, bunun yerine [iptal](#cancel-an-appointment) işlemini kullanın.

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

**Yanıt** (`200 OK`):

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

---

## Bağlı Google Takvimlerinizi listeleme

`GET /appointments/google-calendars`

Doğrudan Google'dan, bu hesapta mevcut olan Google Takvimlerini döndürür — hesap sahibine aşağıdan hangi takvimin içe aktarılacağını seçmesi için bir seçici göstermek veya sadece bağlantının canlı olduğunu doğrulamak için kullanışlıdır.

Bu, yalnızca hesap Google Takvim'i (Ayarlar → Entegrasyonlar) en az okuma erişimiyle bağladığında çalışır. Eğer bağlanmadıysa veya verilen erişim artık takvim-okuma kapsamını içermiyorsa, onu (yeniden) bağlamanızı söyleyen bir `400` alırsınız.

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

**Yanıt** (`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"
    }
  ]
}
```

Her girdi Google'ın kendi [`CalendarListEntry`](https://developers.google.com/calendar/api/v3/reference/calendarList) şeklindedir, bu nedenle alan adları bu API'nin olağan `snake_case` yapısını değil, Google'ın `camelCase` yapısını takip eder — bu, bizim verimiz değil, olduğu gibi aktarılan Google verisidir. Eksik veya iptal edilmiş bir bağlantı, Google Takvim'in (yeniden) bağlanması gerektiğini açıklayan bir hata ile `400` döndürür.

---

## Google Takvim'den etkinlikleri içe aktarma

`POST /appointments/import-calendar-events`

Bir kampanyanın veya Yapay Zeka Temsilcisinin bağlı Google Takvim(ler)inde halihazırda bulunan etkinlikleri çeker ve bunları randevulara dönüştürür — üzerinde zaten rezervasyonlar bulunan bir takvimi ilk kez bağladığınızda kullanışlıdır. Bu işlem biraz zaman alabilir (her etkinlik, kime ait olduğunu anlamak için ayıklama sürecinden geçer), bu nedenle asla satır içi çalışmaz: istek bir arka plan işini kuyruğa alır ve size sorgulamanız için bir `job_id` döndürür.

| Alan | Gerekli | Açıklama |
|---|---|---|
| `campaign_id` | Bu ikisinden biri | İçe aktarılacak bağlı takvim(ler)in ait olduğu kampanya. |
| `agent_id` | Bu ikisinden biri | İçe aktarılacak bağlı takvim(ler)in ait olduğu Yapay Zeka Temsilcisi. |
| `identifier` | Evet | `"EMAIL"` veya `"PHONE_NUMBER"` — her takvim etkinliğinden, ait olduğu kişiyi eşleştirmek veya oluşturmak için hangi iletişim bilgisinin çıkarılacağı. |

`campaign_id` / `agent_id` öğelerinden tam olarak birini gönderin, asla ikisini birden veya hiçbirini göndermeyin — her iki kombinasyon da bir `400` döndürür. Gönderdiğiniz öğe hesabınıza ait olmalıdır, aksi takdirde bir `404` alırsınız.

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

**Yanıt** (`202 Accepted`):

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

`campaign_id` ve `agent_id`, gönderdiğiniz hangisiyse onu geri yansıtır; diğeri her zaman `null` olur.

### İçe aktarma işini sorgulama

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

**Yanıt** (`200 OK`):

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

| `status` | Anlamı |
|---|---|
| `queued` | Henüz alınmadı. Sorgulamaya devam edin. |
| `processing` | İçe aktarma çalışıyor. Sorgulamaya devam edin. |
| `completed` | Tamamlandı — `message` kısa ve insan tarafından okunabilir bir özet içerir. |
| `failed` | Bir şeyler ters gitti — `error` nedenini içerir. |

Var olmayan (veya başka bir hesaba ait olan) bir `jobId` üzerinde `GET` işlemi `404` döndürür.

---

## Restoran rezervasyon entegrasyonları (Zenchef / Formitable)

Zenchef ve Formitable, Yapay Zeka Temsilcinizin gerçek masalar ayırtabileceği restoran rezervasyon sistemleridir. Her birinin, yemek yiyen kişi için sohbet içinde görüntülenen **herkese açık, kimlik doğrulaması gerektirmeyen bir rezervasyon aracı** (`https://api.youraiconnector.com/v1/zenchef-widget/...` ve `https://api.youraiconnector.com/v1/formitable-widget/...`) vardır — bu araç rotaları, JSON API uç noktaları değil, tarayıcıda açılması amaçlanan düz HTML sayfalarıdır, bu nedenle burada belgelenmemiştir. Aşağıdakiler hesap yönetimi uç noktalarıdır: bir restoran kimliğinin hesap sahibine ait olduğunu doğrulama, ardından onu ekleme, güncelleme veya kaldırma işlemleri.

### Zenchef

Bir Zenchef restoranını bağlamak iki aşamalı bir doğrulama gerektirir; böylece hesap sahibi, bot ile bağlantı kurulmadan önce restoranı gerçekten kendisinin yönettiğini kanıtlar: önce kimliğin var olup olmadığını kontrol edin (ismi açıklamadan), ardından restoranın adını kendilerinin yazmasını isteyin ve eşleşip eşleşmediğini doğrulayın.

**1. Adım — Bir restoran kimliğinin var olup olmadığını kontrol etme**

`POST /appointments/zenchef-restaurants/check`

| Alan | Gerekli | Açıklama |
|---|---|---|
| `restaurant_id` | Evet | Kontrol edilecek Zenchef restoran kimliği. |

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

**Yanıt** (`200 OK`):

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

`exists: false`, o kimliğe sahip bir Zenchef restoranı olmadığını belirtir; yapılacak başka bir işlem yoktur. Hesap başına 5 dakikada 10 kontrol ile sınırlandırılmıştır; aşılması durumunda `429` döner.

**2. Adım — Restoranın adını doğrulama**

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

| Alan | Gerekli | Açıklama |
|---|---|---|
| `restaurant_id` | Evet | 1. adımdaki Zenchef restoran kimliği. |
| `user_input_name` | Evet | Hesap sahibinin yazdığı isim — Zenchef'teki gerçek restoran ismiyle karşılaştırılır (büyük/küçük harf ve boşluk duyarsızdır). |

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

**Yanıt** (`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`, ismin eşleşmediği anlamına gelir — `restaurantDetails` atlanır, hesap sahibinden tekrar denemesini isteyin. 5 dakikada 3 deneme ile sınırlandırılmıştır (bu gerçek kanıtlama adımı olduğu için varlık kontrolünden daha sıkıdır). Artık Zenchef'te çözümlenmeyen bir `restaurant_id`, `404` döndürür.

**3. Adım — Restoranı kaydetme**

`POST /appointments/zenchef-restaurants`

| Alan | Gerekli | Açıklama |
|---|---|---|
| `restaurant_id` | Evet | 1–64 karakter, harfler/sayılar/alt çizgi/tire. |
| `restaurant_name` | Evet | 2. adımdan gelen doğrulanmış restoran ismi. |

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

**Yanıt** (`201 Created`):

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

**Kayıtlı bir Zenchef restoranını güncelleme**

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

| Alan | Gerekli | Açıklama |
|---|---|---|
| `restaurant_name` | Hayır | Yeni görünen ad. |
| `is_active` | Hayır | Botun bu restoran için rezervasyon yapmasını, restoranı kaldırmadan durdurmak için `false` değerini ayarlayın. |

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

**Yanıt** (`200 OK`): yukarıdaki kaydetme yanıtı ile aynı biçimdedir.

**Bir Zenchef restoranını kaldırın**

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

**Yanıt** (`200 OK`): `{ "success": true, "data": { "restaurantId": "12345" } }`

Hesapta bulunmayan bir `restaurantId`, güncelleme veya silme işleminde `404` döndürür.

### Formitable

Formitable, Zenchef'in gerektirdiği iki aşamalı isim kanıtına ihtiyaç duymaz; restoran kimlikleri zaten işletme bazında kapsamlandırılmıştır, bu nedenle tek bir doğrulama çağrısı yeterlidir. Ayrıca, kurulum sırasında restoranın web sitesi URL'sini önbelleğe almak için kullanılan bir detay sorgulaması da mevcuttur.

**Bir restoran kimliğini doğrulayın**

`POST /appointments/formitable-restaurants/verify`

| Alan | Gerekli | Açıklama |
|---|---|---|
| `restaurant_id` | Evet | Formitable restoran kimliği. |
| `language` | Hayır | İnceleme isteği için dil etiketi. Varsayılan değer `"nl"`'dir. |

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

**Yanıt** (`200 OK`):

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

Formitable tarafından tanınmayan bir `restaurant_id`, `404` döndürür. Hesap başına 5 dakikada 10 deneme ile hız sınırlandırılmıştır.

**Restoran detaylarını alın**

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

Restoranın web sitesi dahil olmak üzere Formitable'daki herkese açık profilini getirir; restoran kurulumu sırasında web sitesi URL'sini önbelleğe almak için kullanılır. `language`, varsayılan değeri `"en"` olan isteğe bağlı bir sorgu parametresidir.

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

**Yanıt** (`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"
  }
}
```

**Restoranı kaydet**

`POST /appointments/formitable-restaurants`

| Alan | Zorunlu | Açıklama |
|---|---|---|
| `restaurant_id` | Evet | 1–64 karakter, harfler/sayılar/alt çizgi/tire. |
| `restaurant_name` | Evet | Görünen ad. |
| `language` | Evet | ISO dil etiketi, örn. `"en"` veya `"en-GB"`. |
| `website_url` | Hayır | Yukarıdaki detay sorgulamasından restoranın web sitesi. `http(s)://` olmalıdır. |

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

**Yanıt** (`201 Created`): `{ "success": true, "data": { "restaurantId": "the-blue-door" } }`

**Kaydedilmiş bir Formitable restoranını güncelle**

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

| Alan | Zorunlu | Açıklama |
|---|---|---|
| `restaurant_name` | Hayır | Yeni görünen ad. |
| `language` | Hayır | Yeni ISO dil etiketi. |
| `is_active` | Hayır | Botun bu restoranı kaldırmadan rezervasyon yapmasını durdurmak için `false` değerini ayarlayın. |
| `website_url` | Hayır | Yeni web sitesi URL'si. |

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

**Yanıt** (`200 OK`): yukarıdaki kaydetme yanıtı ile aynı biçimdedir.

**Bir Formitable restoranını kaldır**

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

**Yanıt** (`200 OK`): `{ "success": true, "data": { "restaurantId": "the-blue-door" } }`

Hesapta bulunmayan bir `restaurantId`, güncelleme veya silme işleminde `404` döndürür.

> **Tüm Zenchef/Formitable uç noktalarındaki hata biçimi:** bu sayfanın geri kalanından farklı olarak, buradaki hatalar durumlarını iki kez taşır — bir kez HTTP durumu olarak ve bir kez gövdede `error_code` olarak — örneğin `{ "success": false, "error": "Restaurant not found", "error_code": 404 }`. Bunu diğer hatalarla aynı şekilde ele alın: `success` değerini kontrol edin, mesaj için `error` kısmını okuyun.

---

## Randevular API hataları

Randevu uç noktaları standart hata zarfını döndürür:

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

| Durum | Bir randevu uç noktasında ne zaman gerçekleşir |
|---|---|
| `400` | Gerekli bir alan eksik veya geçersiz — örneğin hatalı bir `start_time`, `start_time` sonrasında olmayan bir `end_time`, geçersiz bir filtre kombinasyonu, güncellenecek alan olmaması veya halihazırda iptal edilmiş bir randevu. |
| `404` | Randevu, kişi veya etkinlik türü bulunamadı. |
| `409` | İstenen zaman dilimi zaten dolu (rezervasyon çakışması). |

Her uç noktanın döndürebileceği ortak kodlar — `401`, `403` (planınız API erişimini içermiyor), `429` (hız sınırı) ve `500` — yeniden deneme rehberliği ile birlikte [Hatalar ve Sayfalandırma](errors-and-pagination.md) bölümünde listelenmiştir.

---

## Sonraki adımlar

- [Kişiler](contacts.md) — rezervasyon yaptığınız kişileri oluşturun ve arayın.
- [Mesajlar ve Konuşmalar](messages.md) — bir kişiye onay veya hatırlatıcı gönderin.
- [Web kancaları](webhooks.md) — randevular değiştiğinde bildirim alın.