> For the complete documentation index, see [llms.txt](https://developer.konukcrm.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.konukcrm.com/rehberler/api-temelleri.md).

# API Temelleri

Tüm uçlar bu kuralları paylaşır. Bir kez okuyun; referans sayfalarında tekrar edilmez.

## Taban URL ve sürümleme

```
https://{{api.konukcrm.com}}/api/v{sürüm}/{kaynak}
```

Güncel sürüm: **`v1`**. Sürüm URL yolundadır; başlıkla sürüm seçilmez.

Kırıcı olmayan değişiklikler (yeni alan, yeni uç, yeni enum değeri) `v1` içinde yayınlanır — **istemciniz bilinmeyen alanları yok saymalıdır**. Kırıcı değişiklikler yeni bir sürümle gelir.

## Yanıt zarfı

Başarılı da olsa hatalı da olsa **her yanıt aynı zarfla** döner:

```json
{
  "success": true,
  "data": { },
  "message": null,
  "errors": null,
  "statusCode": 200,
  "traceId": "0HN7A2K9V3B1C:00000003"
}
```

| Alan         | Açıklama                                                                 |
| ------------ | ------------------------------------------------------------------------ |
| `success`    | İşlemin sonucu. HTTP durumuyla tutarlıdır.                               |
| `data`       | Yük. Hatalarda `null`.                                                   |
| `message`    | İnsan tarafından okunabilir özet. Son kullanıcıya doğrudan göstermeyin.  |
| `errors`     | Doğrulama/alan hataları listesi. Başarıda `null`.                        |
| `statusCode` | HTTP durumunun kopyası.                                                  |
| `traceId`    | **Destek talebinde mutlaka paylaşın.** İsteği loglarda bulmamızı sağlar. |

`204` semantiği: gövde yine döner, `data` boştur, `statusCode` `204`'tür.

## Sayfalama

Liste uçları sayfalıdır.

```http
GET /api/v1/guests?page=1&pageSize=50
```

| Parametre  | Varsayılan | Üst sınır |
| ---------- | ---------- | --------- |
| `page`     | `1`        | —         |
| `pageSize` | `{{20}}`   | `{{100}}` |

```json
{
  "success": true,
  "data": {
    "items": [],
    "page": 1,
    "pageSize": 50,
    "totalCount": 1240,
    "totalPages": 25
  }
}
```

Büyük dışa aktarımlarda sayfa sayfa ilerleyin; `pageSize` üst sınırını aşan istekler sınıra kırpılır.

## Filtreleme ve sıralama

```http
GET /api/v1/calls?from=2026-09-01&to=2026-09-30&outcome=reserved&sort=-startedAt
```

* Tarihler **ISO 8601 / UTC**: `2026-09-01T00:00:00Z` veya salt tarih `2026-09-01`.
* `sort` alan adıdır; `-` öneki azalan sıralama.
* Bilinmeyen filtre parametreleri sessizce yok sayılmaz — `422` döndürür.

## Dizi parametreleri

Dizi query parametreleri **tekrar formatında** gönderilir:

```http
GET /api/v1/availability?guests=adult:2&guests=child:1
```

Köşeli parantezli form (`guests[]=` veya `guests[0]=`) **desteklenmez** ve `422` üretir. Axios kullanıyorsanız:

```typescript
axios.create({ paramsSerializer: { indexes: null } });
```

## Idempotency

Yan etkili `POST` uçlarında (rezervasyon oluşturma, mesaj gönderme) tekrar denemelerin çift kayıt üretmemesi için:

```http
Idempotency-Key: {{uuid-v4}}
```

Aynı anahtarla {{24 saat}} içinde gelen tekrar istekler ilk yanıtı döndürür.

## Hız limitleri

| Kapsam                    | Limit                                   |
| ------------------------- | --------------------------------------- |
| `auth` uçları             | {{5 istek / dakika / IP}}               |
| Genel API                 | {{600 istek / dakika / tenant}}         |
| Webhook teslimatı (giden) | {{sıraya alınır, eşzamanlılık sınırlı}} |

Limit aşımında `429` döner:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 30
```

`Retry-After` değerine **uyun** ve üstüne üstel geri çekilme (exponential backoff) + jitter uygulayın.

## Hata yönetimi

```json
{
  "success": false,
  "data": null,
  "message": "Validation failed",
  "errors": [
    { "field": "checkOut", "code": "date_range", "message": "Çıkış tarihi girişten sonra olmalıdır." }
  ],
  "statusCode": 422,
  "traceId": "0HN7A2K9V3B1C:0000000A"
}
```

Kod tablosu ve tekrar deneme kuralları **API Referansı → Hata Kodları** sayfasındadır.

## İstemci için altın kurallar

1. `success` değil **HTTP durumuna** göre dallanın; `success` yalnızca teyittir.
2. Bilinmeyen JSON alanlarını yok sayın — katı şema doğrulaması entegrasyonunuzu kırar.
3. `traceId`'yi kendi loglarınıza yazın.
4. `4xx` hatalarını tekrar denemeyin (`429` hariç). `5xx` ve `429` için geri çekilerek deneyin.
5. Zaman alanlarını UTC olarak saklayın, yalnızca gösterimde yerelleştirin.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.konukcrm.com/rehberler/api-temelleri.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.