REST API

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ı ve MCP örnekleri için ilgili sayfalara bakın.

Bağlantıyı hazırlayın

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

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.

İlk okuma isteğini gönderin

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:

{
  "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:

{
  "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:

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:

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.

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.

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

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

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

{
  "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:

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

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:

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.

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:

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:

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

Bağlantı

Formlar

Başvuru

Bağlantıyı hazırlayın

Yetki kapsamları

Uç noktaları

Listeleme ve sayfalama

Sıralama ve süzgeçler

Kayıt oluşturun ve güncelleyin

Firma ve kişi

Süreç

Görev

Not

Gelen kutusunu kullanın

Müşteriye mesaj gönderin

İç not ekleyin

Tekrarlanan POST isteklerini güvene alın

Sınırlar ve önbellek

Hata yanıtları

Bu sürümde olmayanlar

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

​Yetki kapsamları

​Uç noktaları

​Listeleme ve sayfalama

​Sıralama ve süzgeçler

​Kayıt oluşturun ve güncelleyin

​Firma ve kişi

​Süreç

​Görev

​Not

​Gelen kutusunu kullanın

​Müşteriye mesaj gönderin

​İç not ekleyin

​Tekrarlanan POST isteklerini güvene alın

​Sınırlar ve önbellek

​Hata yanıtları

​Bu sürümde olmayanlar

Bağlantıyı hazırlayın

Yetki kapsamları

Uç noktaları

Listeleme ve sayfalama

Sıralama ve süzgeçler

Kayıt oluşturun ve güncelleyin

Firma ve kişi

Süreç

Görev

Not

Gelen kutusunu kullanın

Müşteriye mesaj gönderin

İç not ekleyin

Tekrarlanan POST isteklerini güvene alın

Sınırlar ve önbellek

Hata yanıtları

Bu sürümde olmayanlar