API'ye genel bakış

Her RolChat REST endpoint’i tek bir sözleşmeye uyar: aynı temel URL, aynı yanıt zarfı, aynı sayfalama, aynı hata yapısı. Bunu bir kez öğrenin, endpoint referansındaki her endpoint ailesi aynı şekilde okunur.

Temel URL ve sürümleme

https://api.rolchat.com/api/v1/

Sürüm yolun içindedir. İsteğe bağlı alanlar, yeni endpoint’ler veya varsayılan değerli yeni sorgu parametreleri eklemek uyumluluğu bozan bir değişiklik değildir ve sürümü artırmaz. Uyumluluğu bozan değişiklikler v2 olarak yayınlanır ve kullanımdan kaldırılan v1 endpoint’leri duyurulduktan sonra en az altı ay çalışmaya devam eder (bkz. Kullanımdan kaldırma).

Kimlik doğrulama

Yöntem	Başlık	Kullanım alanı
JWT bearer	`Authorization: Bearer <access_token>`	Etkileşimli oturumlar (web uygulaması, mobil uygulamalar)
API anahtarı	`Authorization: Bearer rcp_<secret>`	Makineden makineye çağrılar, eklenti API anahtarları
HMAC imzası	`X-RolChat-Signature: sha256=…`	Sistemlerinizden gelen webhook’lar, bkz. Webhook’lar
Yok	-	Site ve origin ile sınırlandırılmış herkese açık widget endpoint’leri (`/widget/…`, `/forms/…`)

Entegrasyonlar için bir API anahtarı (kişisel erişim token’ı) kullanın. Anahtarlar Ayarlar → Eklentiler → RolChat API anahtarları bölümünde oluşturulur, bir kez gösterilir ve yalnızca hash olarak saklanır. Bir anahtar asla onu oluşturan üyeden fazlasını yapamaz: kapsamları her çağrıda o üyenin mevcut izinlerine karşı kontrol edilir. JWT süreleri, X-Account-Id başlığı ve çok şirketli oturumlar için Kimlik doğrulama sayfasına bakın.

Yanıt zarfı

Tek bir kaynak:

{
  "data": { "id": "cnt_01HK…", "email": "ada@example.com" },
  "meta": {
    "request_id": "req_01HK…"
  }
}

Bir liste:

{
  "data": [ { … }, { … } ],
  "meta": {
    "request_id": "req_01HK…",
    "count": 50,
    "next_cursor": "cur_01HK…",
    "prev_cursor": "cur_01HK…",
    "has_more": true
  }
}

Gövdesi olmayan yanıtlar (silme sonrası 204 No Content) yine de X-Request-Id başlığını taşır.

Bir hata:

{
  "errors": [
    {
      "code": "validation_failed",
      "message": "Email must be valid.",
      "field": "email",
      "details": { "received": "not-an-email" }
    }
  ],
  "meta": { "request_id": "req_01HK…" }
}

code makinece okunabilir snake_case değeridir ve mantığınızı buna göre dallandırmalısınız; message İngilizcedir ve loglar içindir. field ve details yardımcı olduklarında bulunur ve asla kişisel veri içermez. API hiçbir zaman errors dizisiyle 200 yanıtı vermez: hata varsa durum kodu 400 veya daha yüksektir. Tam kod listesi Hatalar sayfasındadır.

Sayfalama

Büyüyebilen liste endpoint’leri imleç tabanlı sayfalama kullanır. İlk sayfayı imleç olmadan isteyin, ardından aldığınız next_cursor değerini olduğu gibi geri gönderin:

GET /api/v1/contacts?limit=50
GET /api/v1/contacts?limit=50&cursor=eyJrIjoi…

limit varsayılan olarak 50’dir ve en fazla 200 olabilir; daha büyük değerler 400 validation_failed ile reddedilir.
İmleçler opaktır ve 24 saat sonra geçerliliğini yitirir (code: cursor_expired ile 400 validation_failed).
Sonuçlar ilk sayfada alınan anlık görüntüye göre tutarlıdır: sayfalar arasında silinen kayıtlar kaybolur, yeni kayıtlar yalnızca imleç olmadan yeniden başladığınızda görünür.
Tercih eden istemciler için rel="next" ve rel="prev" içeren bir Link başlığı da gönderilir.

Idempotency

Her POST, PATCH veya DELETE ile bir Idempotency-Key başlığı (UUID veya ULID, en fazla 255 karakter) gönderin:

Bir anahtarla yapılan ilk istek çalışır ve durum kodu ile gövdesi 24 saat saklanır.
Aynı anahtar ve aynı gövdeyle yapılan tekrar, yan etkileri yeniden çalıştırmadan saklanan yanıtı döndürür.
Aynı anahtar ama farklı gövdeyle yapılan tekrar 409 idempotency_key_conflict ile reddedilir.

Yan etkisi olan bir şey oluşturan her çağrıda kullanın: mesaj, e-posta veya SMS gönderme, arama yapma, faturalandırılan her şey. GET istekleri her zaman idempotent’tir ve başlığı yok sayar.

Hız sınırları

Sınırlar dakika başına sayılır ve hesaba, API anahtarına veya kullanıcıya göre (oturum gerektirmeyen yollarda IP adresine göre) uygulanır. Varsayılan üst sınırlar:

Kova	Varsayılan sınır	Dakikada
Oturumsuz istekler (IP’ye göre)	60	IP başına
Oturum açmış kullanıcı (panel)	1 000	kullanıcı başına
API anahtarı	1 000	anahtar başına
Herkese açık widget endpoint’leri	ziyaretçi başına 60 ve ağ adresi başına 600	dakikada
Oturum açma (`/auth/login`)	5	IP başına
Gelen webhook’lar	300	dakikada
MCP sunucusu	600	dakikada
OAuth endpoint’leri	600	dakikada

Üst sınırlar platform varsayılanlarıdır ve operatör tarafından değiştirilebilir; planınız bunları çarpmaz, Enterprise sınırları sözleşmenizde kararlaştırılır. Hız sınırlı endpoint’ler şunları döndürür:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 543

Bir sınırı aştığınızda yanıt, errors dizisinde code: rate_limited ve saniye cinsinden bir Retry-After başlığıyla 429 olur. Bir sonraki çağrıdan önce o kadar bekleyin. On başarısız oturum açma denemesi hesabı 30 dakika kilitler.

Boyutlar ve zaman aşımları

Kategori	Azami istek gövdesi	Sunucu zaman aşımı
Varsayılan	1 MB	30 sn
Ekli mesaj	25 MB	30 sn
CSV içe aktarma	50 MB	`202` döndürür ve arka planda çalışır
Bilgi bankası görselleri	10 MB	30 sn
Toplu API	10 MB	30 sn
Arama	1 MB	10 sn
Yapay zeka istekleri	1 MB	60 sn
Widget endpoint’leri	100 KB	30 sn

Aşırı büyük gövdeler 413 payload_too_large alır. Zaman aşımına uğrayan bir üst servis, yeniden denemenin işe yarayabileceği durumlarda code: upstream_timeout ve bir retry_after ipucuyla 504 yanıtı verir.

İçerik türleri, tarihler ve kimlikler

İstekler ve yanıtlar application/json; charset=utf-8 biçimindedir. Dosya yüklemeleri multipart/form-data kullanır; CSV dışa aktarmaları text/csv döndürür. Geçersiz UTF-8 400 validation_failed ile reddedilir.
Zaman damgaları milisaniye hassasiyetinde UTC cinsinden ISO-8601’dir: 2026-04-20T14:23:45.123Z. Girişte herhangi bir ISO-8601 ofseti kabul edilir ve UTC’ye normalleştirilir.
Kimlikler opak ULID veya UUID’lerdir. Sayısal kimlik yoktur ve e-posta adresleri veya telefon numaraları asla bir URL’de yer almaz.

Kiracı izolasyonu ve izinler

Kimliği doğrulanmış her istek tek bir hesap içinde çalışır. Başka bir hesaba veya çağıranın rolünün kapsamadığı bir siteye ait bir kaynak, kayıtların varlığı asla sızdırılmasın diye 403 yerine 404 not_found yanıtı verir. Gerekli izne sahip olmayan (örneğin contacts.delete) geçerli bir token 403 forbidden yanıtı alır. Bazı izinler, bir listenin döndürdüğü sonuçları daraltan bir kapsam son eki taşır (conversations.read:own, :team, :all).

PATCH yalnızca yazılabilir alanları kabul eder. id, account_id, created_at, updated_at ve resolved_at gibi durum alanları salt okunurdur; bunlardan birini göndermek details.forbidden_fields ile 400 validation_failed döndürür. Durum değişiklikleri POST /tickets/:id/resolve gibi özel eylemlerle yapılır.

Her yazma işlemi hesabın denetim kaydına kaydedilir.

Gözlemlenebilirlik başlıkları

Her yanıt şunları taşır:

X-Request-Id: req_01HK…

X-Request-Id değerini loglayın. Destek ekibinin ilk isteyeceği şey budur.

CORS

Tarayıcıdaki panelin origin’i https://app.rolchat.com’dur. Herkese açık widget endpoint’leri her origin’e veya yalnızca bir site için doğruladığınız origin’lere izin verir. API anahtarıyla yapılan sunucudan sunucuya çağrılar CORS’a tabi değildir.

Kullanımdan kaldırma

Değişiklik değişiklik günlüğünde duyurulur ve etkilenen endpoint, kaldırılma tarihini içeren Deprecation: true ve Sunset başlıklarını göndermeye başlar.
Herkese açık endpoint’ler duyurudan sonra en az altı ay çalışmaya devam eder.
Kaldırma yalnızca yeni bir ana sürümde gerçekleşir. v1 içinde değişiklikler yalnızca eklemeler şeklindedir.

Sağlık

Her servis /healthz (liveness) ve /readyz (readiness) sunar.