Kimlik doğrulama İstek biçimi Cevap biçimi Hata kodları Hız sınırları Test ortamı Sürüm ve değişiklikler Yardım

Genel Bakış

Buluthat API'si, mevcut yazılımlarınızı (CRM, ERP, e-ticaret, destek masası) bulut santralinizle bütünleştirmenizi sağlar: tıkla-ara, çağrı kontrolü, kuyruk yönetimi, karaliste, ses dosyaları, otomatik arama kampanyaları, sesli asistan görevleri ve sesli doğrulama kodu.

Tüm uçlar düz HTTP üzerindedir; cevaplar JSON'dur. Herhangi bir dilden, bir HTTP istemcisiyle kullanılır.

Temel adres: https://api.buluthat.com/api/

Kimlik doğrulama

Tüm uçlar aynı API anahtarını kullanır. Anahtar panelde Hesap ve Destek > API Anahtarları sayfasından, hesap yetkilisi tarafından üretilir; bt_ ile başlar ve yalnızca üretildiği an bir kez gösterilir.

Anahtar her istekte başlıkta gönderilir:

Authorization: Bearer bt_xxxxxxxx

Authorization başlığı ayarlanamıyorsa X-Api-Key: bt_xxxxxxxx de kabul edilir. Anahtarı URL'de (?key=) göndermek yeni anahtarlarda kapalıdır.

Her anahtar tek bir müşteri hesabına bağlıdır ve yalnızca o hesabın verisine erişir. Anahtarda kapsam tanımlıdır:

Kapsam	Uçlar
`call`	Çağrı yönetimi, kuyruklar, temsilci durumları
`autocall`	Otomatik arama (eski entegrasyon uyumu için sesli asistan, sesli OTP ve çağrı uçlarını da açar)
`voicebot`	Sesli asistan
`voice_otp`	Sesli doğrulama kodu
`sms`	SMS API

Kapsam dışı istek 403 scope_denied, hesabınızda kapalı modül 403 module_disabled döner. Anahtara izinli IP listesi, son kullanma tarihi ve zorunlu HMAC istek imzası tanımlanabilir; hepsi API Güvenliği sayfasında.

Anahtarınızı tarayıcı tarafında (JavaScript) kullanmayın; her zaman kendi sunucunuzdan çağırın. Sızdığını düşünürseniz panelden "Anahtarı yenile > Eskisini hemen kapat" deyin, eskisi anında geçersiz olur.

İstek biçimi

Okuma işlemleri GET, değiştiren işlemler POST (ses dosyalarında PUT/DELETE).
POST gövdesi application/json ya da application/x-www-form-urlencoded olabilir.
Entegrasyon uçlarında işlem action parametresiyle seçilir (?action=create_campaign).
Zaman damgaları Türkiye saatidir (2026-09-18 10:12:03).
Telefon numaraları 05xxxxxxxxx, 5xxxxxxxxx ya da 905xxxxxxxxx biçiminde kabul edilir; cevaplarda normalize döner.

Cevap biçimi

Entegrasyon uçları (autocall, voicebot, voice_otp) her zaman zarf döner:

{ "ok": true, "data": { } }

{ "ok": false, "error": "Kampanya bulunamadı.", "code": "campaign_not_found" }

Santral uçları (begin_call, queues, blocked_numbers…) HTTP durum koduyla konuşur: başarıda 200 OK ve gövdede sonuç (JSON dizi ya da düz metin), hatada 4xx ve gövdede Türkçe hata mesajı.

Hata kodları

HTTP	`code`	Anlamı
400	`validation_failed`	Alan doğrulaması geçmedi; mesaj sebebi açıklar
401	`missing_token` / `invalid_token` / `token_expired`	Anahtar yok, geçersiz ya da süresi dolmuş
401	`query_key_disabled` / `signature_*`	Anahtar URL'de geldi ya da imza doğrulanamadı (API Güvenliği)
403	`module_disabled` / `scope_denied` / `ip_not_allowed`	Modül kapalı, kapsam yetersiz ya da IP izinli değil
404	`*_not_found`	Kayıt yok ya da başka müşteriye ait
405	`method_not_allowed`	POST gereken işleme GET geldi
422	(uca özel)	İş kuralı reddi: kota, süre, hat yok vb.
413	`payload_too_large`	İstek gövdesi 5 MB'ı aşıyor
429	`rate_limited` / `ip_locked`	Hız sınırı aşıldı ya da IP çok hatalı deneme nedeniyle geçici kilitli
503	`db_unavailable`	Geçici servis sorunu; biraz sonra tekrar deneyin

Hız sınırları

Sınır	Varsayılan
Anahtar başına	dakikada 120 istek (anahtar ayarından düşürülebilir)
Hesabın tüm anahtarları toplamı	dakikada 600 istek
Temsilci durumları	ayrıca dakikada 2 istek (canlı durum için webhook tercih edin)
Otomatik arama `add_leads`	tek istekte 5.000 kayıt

Cevaplarda X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset başlıkları gelir. Aşımda 429 Too Many Requests ve Retry-After başlığı döner. Her cevaptaki X-Request-Id değerini destek taleplerinde paylaşın.

Test ortamı

Ayrı bir sandbox yoktur; hesabınızda test amaçlı bir dahili ve küçük bir kampanya ile deneyin. Otomatik arama kampanyalarını status: "draft" ile oluşturup results/summary uçlarını veri gelmeden de çağırabilirsiniz. Sesli doğrulama kodunda kendi numaranıza gönderim yapın; ücretlendirme paket kurallarınıza göre işler.

Sürüm ve değişiklikler

Uçlar geriye uyumlu tutulur; yeni alanlar eklenir, mevcut alanların adı ve tipi değişmez. Kaldırılacak bir alan en az 90 gün önce panelde ve bu sayfada duyurulur.

Yardım

Entegrasyon sırasında takıldığınız yerde panel içindeki Destek Merkezi'nden "Entegrasyon / API" konulu kayıt açın; örnek istek/cevabınızı ekleyin, birlikte bakalım.

API Güvenliği