> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iletisim.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> İletişim REST API v1 ile kayıtları ve gelen kutusunu okuyun, kayıt oluşturun veya güncelleyin, müşteriye mesaj ve ekibe iç not gönderin.

REST API v1, kendi yazılımınızın İletişim verileriyle doğrudan HTTP üzerinden çalışmasını sağlar. Kişiler, firmalar, süreçler, görevler ve notlar için okuma ve yazma; gelen kutusu için okuma, müşteriye mesaj gönderme ve iç not ekleme uçları bulunur.

| Alan | Değer |
| - | - |
| Temel adres | `https://api.iletisim.app/api/v1` |
| Kimlik doğrulama | `Authorization: Bearer <API_ANAHTARI>` |
| İçerik türü | `Content-Type: application/json` |
| Yanıt biçimi | JSON |
| Paket | Kurumsal |

Yapay zekâ istemcinize araç sunan MCP bağlantısı ayrıdır ve `/api/mcp` adresini kullanır. [MCP bağlantısı](https://docs.iletisim.pro/api/mcp.md) ve [MCP örnekleri](https://docs.iletisim.pro/api/ornekler.md) için ilgili sayfalara bakın.

## Bağlantıyı hazırlayın

**1. API anahtarı oluşturun**

**Ayarlar → API ve MCP → Yeni anahtar** yolunu izleyin. Bağlantınızın kullanacağı modüllerde en düşük gerekli yetkiyi seçin. Anahtarın tamamı yalnızca oluşturulduğunda gösterilir. [API anahtarı oluşturma](https://docs.iletisim.pro/api/api-anahtari.md)

**2. Anahtarı güvenli bir yerde saklayın**

Anahtarı kaynak koduna, tarayıcıda çalışan koda veya belgelere yazmayın. Aşağıdaki örnekler anahtarı `ILETISIM_API_KEY` ortam değişkeninden okur.

**3. İlk okuma isteğini gönderin**

```bash theme={"system"}
curl --request GET 'https://api.iletisim.app/api/v1/contacts?limit=5' \
  --header "Authorization: Bearer ${ILETISIM_API_KEY}" \
  --header 'Content-Type: application/json'
```

API anahtarı kullanıcı oturumunun yerine geçmez. Panel oturumu tek başına `/api/v1` uçlarını açmaz; API anahtarı da panelin oturumla çalışan `/api/*` uçlarına erişim sağlamaz.

## Yetki kapsamları

Her uç, anahtarın modül ve eylem yetkisini denetler. Bir modülün **Yazma** yetkisi aynı modülün okumasını da kapsar. **Müşteriye mesaj** (`inbox:send`) ayrı bir yetkidir; `inbox:write` müşteriye mesaj göndermeye izin vermez.

| Kaynak | Okuma | Oluşturma ve güncelleme |
| - | - | - |
| Kişiler | `contacts:read` | `contacts:write` |
| Firmalar | `contacts:read` | `contacts:write` |
| Süreçler | `processes:read` | `processes:write` |
| Görevler | `tasks:read` | `tasks:write` |
| Notlar | `notes:read` | `notes:write` |
| Sohbetler ve mesajlar | `inbox:read` | — |
| Müşteriye mesaj | — | `inbox:send` |
| Sohbete iç not | — | `inbox:write` |

Anahtar yalnızca oluşturulduğu işletmenin verilerine erişir. **Anahtarlar proje bazında sınırlandırılmaz:** seçilen kapsamlar işletmenin bütün projelerinde geçerlidir. Anahtarı oluşturan kişinin rolü veya proje kapsamı anahtara devredilmez.

Yetkisiz istek `403` ve gerekli kapsamı bildiren bir gövde döndürür:

```json theme={"system"}
{
  "error": "api_scope",
  "scope": "contacts:read",
  "module": "contacts",
  "action": "read",
  "message": "Bu API anahtarının \"contacts:read\" kapsamı yok (Ayarlar → API ve MCP'den yeni bir anahtar oluşturun)."
}
```

Yetkileri değiştirmek için yeni anahtar oluşturun, bağlantınızda kullanıp doğruladıktan sonra eskisini iptal edin.

## Uç noktaları

Aşağıdaki yolların başına `https://api.iletisim.app/api/v1` gelir. `:id` yerine kaydın UUID değerini yazın.

| Kaynak | Okuma | Yazma |
| - | - | - |
| Kişiler | `GET /contacts` `GET /contacts/:id` | `POST /contacts` `PATCH /contacts/:id` |
| Firmalar | `GET /accounts` `GET /accounts/:id` | `POST /accounts` `PATCH /accounts/:id` |
| Süreçler | `GET /processes` `GET /processes/:id` | `POST /processes` `PATCH /processes/:id` |
| Görevler | `GET /tasks` `GET /tasks/:id` | `POST /tasks` `PATCH /tasks/:id` |
| Notlar | `GET /notes` `GET /notes/:id` | `POST /notes` `PATCH /notes/:id` |
| Gelen kutusu | `GET /conversations` `GET /conversations/:id` `GET /conversations/:id/messages` | `POST /conversations/:id/messages` `POST /conversations/:id/notes` |

Oluşturma istekleri başarılı olduğunda `201`, güncelleme istekleri `200` döner. Tek kayıt, oluşturma ve güncelleme yanıtları kayıt nesnesini doğrudan içerir; ayrıca bir `data` sarmalayıcısı yoktur. Liste yanıtlarında `items` dizisi bulunur.

`DELETE` uçları yoktur. Bulunmayan bir uç veya erişilemeyen kayıt `404 not_found` döner.

## Listeleme ve sayfalama

Listeler imleç temelli (keyset) sayfalama kullanır. Sayfa boyutu varsayılan olarak `50`, en çok `200`'dür.

| Parametre | Açıklama |
| - | - |
| `limit` | Sayfadaki kayıt sayısı: `1`–`200`; varsayılan `50`. |
| `cursor` | Önceki yanıtın `nextCursor` değeri. Sonraki sayfada aynen, URL kodlu olarak gönderin. |
| `sort` | Sıralama alanı; kaynaklara göre değişir. |
| `dir` | `asc` veya `desc`; varsayılan `desc`. |
| `q` | Destekleyen listelerde en çok 100 karakterlik arama. |
| `projectId` | Destekleyen listelerde proje UUID'si veya projesiz kayıtlar için `none`. |

Örnek yanıt:

```json theme={"system"}
{
  "items": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Örnek Kişi",
      "contactType": "customer",
      "createdAt": "2026-11-11T09:00:00.000Z"
    }
  ],
  "nextCursor": "W10sWzE3OTM1MjQwMDAwMDBdLCIxMTExMTExMS0xMTExLTQxMTEtODExMS0xMTExMTExMTExMTExIl0=",
  "total": 18
}
```

`nextCursor` `null` olana kadar aynı `sort`, `dir` ve süzgeçlerle sonraki sayfayı isteyin:

```bash theme={"system"}
curl --get 'https://api.iletisim.app/api/v1/contacts' \
  --header "Authorization: Bearer ${ILETISIM_API_KEY}" \
  --data-urlencode 'limit=50' \
  --data-urlencode 'sort=name' \
  --data-urlencode 'dir=asc' \
  --data-urlencode 'cursor=ÖNCEKİ_NEXT_CURSOR'
```

Kişiler, firmalar, süreçler, görevler ve notlar ilk sayfada süzgece uyan toplam kayıt sayısını `total` alanında verir. Sonraki sayfalarda `total` gönderilmez. Sohbet ve mesaj listelerinde `total` yoktur.

### Sıralama ve süzgeçler

| Liste | `sort` değerleri | Kaynağa özgü süzgeçler |
| - | - | - |
| Kişiler | `name`, `contactType`, `lastActivity`, `createdAt` | `accountId` (UUID veya `none`) |
| Firmalar | `name`, `city`, `owner`, `people`, `lastActivity`, `createdAt` | `archived` |
| Süreçler | `number`, `title`, `priority`, `createdAt`, `updatedAt`, `dueAt` | `projectMatch`, `typeId`, `componentId`, `stageId`, `category`, `assignee`, `priority`, `overdue`, `dueToday`, `following`, `contactId`, `accountId`, `conversationId`, `tagIds`, `q` |
| Görevler | `dueAt`, `createdAt`, `updatedAt`, `position` | `assignee`, `status`, `taskStatus`, `statusId`, `bucket`, `recordType`, `recordId`, `processId`, `componentId`, `q` |
| Notlar | `createdAt`, `updatedAt` | `author`, `recordType`, `recordId`, `unlinked`, `q` |
| Sohbetler | `lastMessageAt`, `createdAt`, `updatedAt` | `audience`, `status`, `channel`, `assignee`, `channelAccountId`, `tagId`, `unread`, `awaiting`, `projectPending`, `fromAd`, `q` |
| Mesajlar | `sentAt` | Sohbet kimliği yolda verilir. |

Süzgeçlerin önemli varsayılanları:

* Süreçlerde `category=active`; açık, işlemde ve bekleyen kayıtlar gelir. Tüm kayıtlar için `category=all` kullanın. Diğer değerler: `open`, `in_progress`, `waiting`, `done`, `cancelled`, `closed`.
* Görevlerde `status=open`; tamamlananlar için `completed`, tümü için `all` kullanın. `taskStatus` değerleri `todo`, `in_progress`, `done`; `bucket` değerleri `overdue`, `today`, `upcoming`, `no_due`, `completed`'dir.
* Sohbetlerde `status=open`, `audience=customer`, `assignee=all` kullanılır. `status` ayrıca `pending`, `closed`, `active` veya `all`; `channel` ise `whatsapp`, `instagram`, `messenger`, `phone` veya `email` olabilir.
* `unread`, `awaiting`, `projectPending`, `fromAd`, `archived`, `overdue`, `dueToday`, `following` ve `unlinked` sorgu dizgesinde `true` veya `false` olarak gönderilir.
* Süreçlerde birden çok etiket `tagIds=id1,id2` biçiminde, en çok 20 UUID ile süzülür.

Örneğin yüksek öncelikli, açık işleri listelemek için:

```bash theme={"system"}
curl --get 'https://api.iletisim.app/api/v1/processes' \
  --header "Authorization: Bearer ${ILETISIM_API_KEY}" \
  --data-urlencode 'category=active' \
  --data-urlencode 'priority=high' \
  --data-urlencode 'sort=dueAt' \
  --data-urlencode 'dir=asc' \
  --data-urlencode 'limit=50'
```

## Kayıt oluşturun ve güncelleyin

İstek gövdeleri JSON'dur ve bilinmeyen alanlar kabul edilmez. `PATCH` isteklerinde yalnızca değiştirmek istediğiniz alanları gönderin. `customFields`, `records`, `assigneeIds`, `projectIds` ve `fileIds` gibi bütün bir koleksiyonu temsil eden alanlar verildiğinde yeni değerin tamamı kullanılır.

Aşağıda temel alanlar ve örnekler yer alır. İlişkili UUID değerleri kendi işletmenizdeki kayıtlara ait olmalıdır.

### Firma ve kişi

Firma için `name` zorunludur. İsteğe bağlı alanlar: `taxNo`, `phone`, `email`, `website`, `address`, `city`, `notes`, `ownerId`, `customFields`.

```bash theme={"system"}
curl --request POST 'https://api.iletisim.app/api/v1/accounts' \
  --header "Authorization: Bearer ${ILETISIM_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: firma-servis-0001' \
  --data '{
    "name": "Örnek Servis Ltd.",
    "city": "İstanbul",
    "email": "info@example.com"
  }'
```

Kişi için `name` zorunludur. İsteğe bağlı alanlar: `accountId`, `phone`, `title`, `notes`, `contactType`, `email`, `customFields`. `contactType` değerleri `customer`, `team`, `supplier`, `unknown`'dur.

```json theme={"system"}
{
  "name": "Ayşe Yılmaz",
  "accountId": "11111111-1111-4111-8111-111111111111",
  "contactType": "customer",
  "phone": "+90 555 000 00 00",
  "email": "ayse@example.com"
}
```

### Süreç

Süreç için `typeId` ve `title` zorunludur. Türün başlangıç aşaması kullanılır; farklı aşama için `stageId` gönderin. Sık kullanılan isteğe bağlı alanlar `description`, `priority`, `assigneeId`, `assigneeTeamId`, `dueAt`, `contactId`, `accountId`, `conversationId`, `customFields`'tür. Öncelik değerleri `low`, `normal`, `high`, `urgent`'tir.

```json theme={"system"}
{
  "typeId": "22222222-2222-4222-8222-222222222222",
  "title": "Kurulum randevusu",
  "contactId": "33333333-3333-4333-8333-333333333333",
  "priority": "high",
  "dueAt": "2026-11-15T12:00:00.000Z"
}
```

`notifyCustomer: true` kullanılırsa süreç türündeki bildirim kuralı çalışır ve müşteriye mesaj gönderilebilir. Bu işlem ayrıca `inbox:send` yetkisi gerektirir. Müşteriye giden metni ve alıcıyı önceden doğrulayın.

### Görev

Görev için `title` zorunludur. İsteğe bağlı alanlar `dueAt`, `dueHasTime`, `assigneeIds`, `records`, `status`, `statusId`, `projectIds`, `primaryProjectId`, `processId`, `componentId`'dir. Görevi tamamlamak veya yeniden açmak için `PATCH` gövdesinde `completed: true` ya da `completed: false` kullanın.

```json theme={"system"}
{
  "title": "Müşteriyi kurulum için ara",
  "processId": "44444444-4444-4444-8444-444444444444",
  "assigneeIds": ["55555555-5555-4555-8555-555555555555"],
  "dueAt": "2026-11-12T09:00:00.000Z",
  "dueHasTime": true
}
```

### Not

Notta `title` isteğe bağlıdır. Düz metin için `bodyText`, zengin belge için `body`, kayıt bağlantıları için `records`, önceden yüklenmiş ekler için `fileIds` kullanılabilir.

```json theme={"system"}
{
  "title": "Kurulum notları",
  "bodyText": "Kurulum sırasında kontrol edilecek bilgiler.",
  "records": [
    { "type": "contact", "id": "33333333-3333-4333-8333-333333333333" }
  ]
}
```

Bağsız notlar yalnızca onları oluşturan API anahtarına görünür; başka bir anahtar aynı işletmede olsa da bu notları okuyamaz.

## Gelen kutusunu kullanın

Sohbet listesi ve ayrıntısı `inbox:read`; mesaj listesi de aynı kapsamı kullanır. Mesajlar varsayılan olarak yeniden eskiye gelir; eskiden yeniye okumak için `dir=asc` kullanın:

```bash theme={"system"}
curl --get 'https://api.iletisim.app/api/v1/conversations/66666666-6666-4666-8666-666666666666/messages' \
  --header "Authorization: Bearer ${ILETISIM_API_KEY}" \
  --data-urlencode 'dir=asc' \
  --data-urlencode 'limit=50'
```

Mesaj nesnesinde `direction` değeri `inbound`, `outbound` veya `note`; teslim durumunu izleyen `status` değeri ise `received`, `pending`, `sent`, `delivered`, `read` veya `failed` olabilir. İç notlar `direction: "note"` ile döner.

### Müşteriye mesaj gönderin

> [!WARNING]
>
> Bu işlem gerçek müşteriye mesaj gönderir. İsteği çalıştırmadan önce sohbet kimliğini, metni ve kanalın mesajlaşma koşullarını doğrulayın.

Metin mesajı için `inbox:send` gerekir:

```bash theme={"system"}
curl --request POST 'https://api.iletisim.app/api/v1/conversations/66666666-6666-4666-8666-666666666666/messages' \
  --header "Authorization: Bearer ${ILETISIM_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: mesaj-servis-0001' \
  --data '{
    "kind": "text",
    "body": "Merhaba, servis kaydınızla ilgili bilgiyi hazırlıyoruz."
  }'
```

Başarılı `201` yanıtı mesajın oluşturulduğunu ve gönderim için kabul edildiğini gösterir; nihai teslim durumunu mesajın `status` alanından izleyin. `replyToMessageId` ile aynı sohbetteki bir mesajı yanıtlayabilirsiniz.

Kanala göre mevcut kurallar uygulanır:

* WhatsApp serbest metni için 24 saatlik müşteri hizmetleri penceresi açık olmalıdır. Pencere dışında onaylı şablon için `kind: "template"`, `templateId` ve isteğe bağlı `variables` kullanın.
* Instagram ve Messenger'da müşteri yeniden yazana kadar 24 saat dolduktan sonra gönderim yapılamaz.
* Bağlantısı kesik kanaldan müşteriye mesaj gönderilemez; bu durum `409 channel_disconnected` döndürür.
* E-posta sohbetinde `kind: "email"` ile `body`, isteğe bağlı `subject`, `cc`, `uploadIds` ve `replyToMessageId` kullanılabilir.
* `kind: "media"` mevcut bir `uploadId` kabul eder; ancak v1'de dosya yükleme ucu yoktur. Yeni dosya yükleme ve indirme entegrasyonu bu sürüm kapsamında değildir.

Yanıtlardaki medya adresleri panel oturumu gerektirebilir; API anahtarıyla medya indirme ucu bulunmaz.

### İç not ekleyin

İç not `inbox:write` gerektirir ve müşteriye gönderilmez. Bağlantısı kesik kanalın sohbetine de iç not eklenebilir.

```bash theme={"system"}
curl --request POST 'https://api.iletisim.app/api/v1/conversations/66666666-6666-4666-8666-666666666666/notes' \
  --header "Authorization: Bearer ${ILETISIM_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: ic-not-servis-0001' \
  --data '{
    "kind": "note",
    "body": "Tamirhane ekibi parça durumunu kontrol edecek."
  }'
```

İç notta isteğe bağlı `mentions` alanıyla en çok 20 kullanıcı kimliği belirtilebilir.

## Tekrarlanan POST isteklerini güvene alın

Bütün `POST` uçları isteğe bağlı `Idempotency-Key` başlığını kabul eder. Ağ zaman aşımı veya bağlantı kesintisi sonrasında aynı mantıksal işlemi tekrarlarken aynı değeri kullanın:

```http theme={"system"}
Idempotency-Key: 7e0ee2de-620f-4f46-9b69-c80ebba84f18
```

* Değer `1`–`200` karakter olmalı ve her mantıksal işlem için benzersiz olmalıdır.
* Kayıt, API anahtarı + uç + istek gövdesi + idempotency değeriyle ilişkilendirilir ve **24 saat** saklanır.
* Aynı istek tekrarlandığında yeni kayıt açılmaz; ilk yanıtın durumu ve gövdesi aynen döner. Tekrar yanıtında `Idempotency-Replayed: true` başlığı bulunur.
* Aynı idempotency değeri farklı bir uç veya gövdeyle kullanılırsa `409 idempotency_conflict` döner.
* Başarısız doğrulama veya yazma isteği değeri tüketmez; hatayı düzeltip aynı değerle yeniden deneyebilirsiniz.
* Başlık gönderilmezse her `POST` bağımsız işlem olarak çalışır.

`PATCH` istekleri bu makbuz mekanizmasını kullanmaz.

## Sınırlar ve önbellek

* **İstek hızı:** API anahtarı başına **120 istek / 60 saniye**. Aşımda `429 rate_limit`, `Retry-After: 60` başlığı ve ISO 8601 biçiminde `retryAt` döner. İstemciniz bu zamana kadar bekleyip sınırlı sayıda yeniden denemelidir.
* **Gövde boyutu:** İstek gövdesi en çok **1 MB** olabilir; aşımda `413 body_too_large` döner.
* **Önbellek:** Başarılı ve hatalı bütün v1 yanıtları `Cache-Control: no-store` taşır.
* **Zaman ve kimlik biçimi:** Kayıt kimlikleri UUID, tarih-saat alanları ISO 8601 metnidir.

## Hata yanıtları

Hataların temel biçimi:

```json theme={"system"}
{
  "error": "validation",
  "message": "İstek alanlarını kontrol edin",
  "fieldErrors": {
    "name": ["String must contain at least 1 character(s)"]
  }
}
```

| HTTP | Örnek `error` değerleri | Anlamı |
| - | - | - |
| `400` | `invalid_request` | JSON gövdesi okunamadı veya istek geçersiz. |
| `401` | `unauthorized` | Anahtar eksik, geçersiz veya iptal edilmiş. |
| `402` | `plan_limit` | Paketin ilgili kullanım sınırı doldu. |
| `403` | `api_scope`, `plan_feature`, `forbidden` | Gerekli kapsam veya paket özelliği yok; işlem yetkisi bulunmuyor. |
| `404` | `not_found` | Uç veya kayıt yok; kayıt başka işletmede ya da anahtarın erişemeyeceği bir kayıt. |
| `409` | `idempotency_conflict`, `channel_disconnected`, `phone_in_use` | İstek mevcut durumla çelişiyor. |
| `413` | `body_too_large` | Gövde 1 MB sınırını aştı. |
| `422` | `validation`, `invalid_owner`, `invalid_assignee`, `invalid_team` | Alanlar, UUID'ler veya ilişkili kayıtlar doğrulanamadı. |
| `423` | `workspace_suspended` | İşletme askıda. |
| `429` | `rate_limit` | Anahtarın istek hızı sınırı aşıldı. |
| `500` | `internal_error` | İstek işlenirken beklenmeyen hata oluştu. |

`fieldErrors` alanında anahtar, sorunlu alanın yolu; değer ise o alana ait hata metinlerinin dizisidir. Kapsam hatasında ayrıca `scope`, `module`, `action`; hız sınırında `retryAt` bulunur.

## Bu sürümde olmayanlar

* Kayıt silme ve `DELETE` uçları.
* Teklifler, görüşmeler, takvim, formlar, dosyalar, bilgi bankası ve raporlar için v1 uçları.
* Yeni sohbet başlatma, sohbet durumunu veya atamasını değiştirme.
* Proje, süreç türü, aşama, kullanıcı ve kanal ayarlarını listeleyen yardımcı uçlar.
* v1 üzerinden dosya yükleme veya indirme.
* Kayıt değiştiğinde sizin adresinize bildirim gönderen giden webhook'lar.

MCP'nin mevcut araçları çalışmaya devam eder; REST v1 hız sınırı MCP'yi etkilemez.

Son güncelleme: 11 Kasım 2026.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.