Kimlik doğrulama Sorğu formatı Cavab formatı Xəta kodları Sürət limitləri Test mühiti Versiya və dəyişikliklər Kömək

Ümumi Baxış

Buluthat API-si mövcud proqramlarınızı (CRM, ERP, e-ticarət, dəstək masası) bulud santralınızla inteqrasiya etməyə imkan verir: kliklə-zəng, zəng idarəetməsi, növbə idarəetməsi, qara siyahı, səs faylları, avtomatik zəng kampaniyaları, səsli asistent tapşırıqları və səsli doğrulama kodu.

Bütün nöqtələr düz HTTP üzərindədir; cavablar JSON-dur. İstənilən dildən, HTTP klienti ilə istifadə olunur.

Əsas ünvan: https://api.buluthat.com/api/

Kimlik doğrulama

Bütün nöqtələr eynidir API açarını istifadə edir. Açar paneldə Hesab və Dəstək > API Açarları səhifəsindən, hesab səlahiyyətlisi tərəfindən yaradılır; bt_ ilə başlayır və yalnız yaradıldığı an bir dəfə göstərilir.

Açar hər sorğuda başlıqda göndərilir:

Authorization: Bearer bt_xxxxxxxx

Authorization başlığı ayarlanamırsa X-Api-Key: bt_xxxxxxxx də qəbul edilir. Açarı URL-də (?key=) göndərmək yeni açarlarda bağlıdır.

Hər açar tək müştəri hesabına bağlıdır və yalnız həmin hesabın məlumatına çıxış əldə edir. Açarda əhatə təyin edilib:

Əhatə	Nöqtələr
`call`	Zəng idarəetməsi, növbələr, nümayəndə vəziyyətləri
`autocall`	Avtomatik zəng (köhnə inteqrasiya uyğunluğu üçün səsli asistent, səsli OTP və zəng nöqtələrini də açır)
`voicebot`	Səsli asistent
`voice_otp`	Səsli doğrulama kodu
`sms`	SMS API

Əhatədən kənar sorğu 403 scope_denied, hesabınızda bağlı modul 403 module_disabled qaytarır. Açara icazəli IP siyahısı, son istifadə tarixi və məcburi HMAC sorğu imzası təyin edilə bilər; hamısı API Təhlükəsizliyi səhifəsində.

Açarınızı brauzer tərəfində (JavaScript) istifadə etməyin; həmişə öz serverinizdən çağırın. Sızdığını düşünürsünüzsə paneldən "Açarı yenilə > Köhnəsini dərhal bağla" deyin, köhnəsi dərhal etibarsız olur.

Sorğu formatı

Oxuma əməliyyatları GET, dəyişdirən əməliyyatlar POST (səs fayllarında PUT/DELETE).
POST gövdəsi application/json ya da application/x-www-form-urlencoded ola bilər.
İnteqrasiya nöqtələrində əməliyyat action parametri ilə seçilir (?action=create_campaign).
Vaxt damğaları Türkiyə saatıdır (2026-09-18 10:12:03).
Telefon nömrələri 05xxxxxxxxx, 5xxxxxxxxx ya da 905xxxxxxxxx formatında qəbul edilir; cavablarda normallaşdırılmış qayıdır.

Cavab formatı

İnteqrasiya nöqtələri (autocall, voicebot, voice_otp) həmişə zərf qaytarır:

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

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

Santral nöqtələri (begin_call, queues, blocked_numbers…) HTTP status kodu ilə danışır: uğurda 200 OK və gövdədə nəticə (JSON massiv ya da düz mətn), xəta olduqda 4xx və gövdədə Türkcə xəta mesajı.

Xəta kodları

HTTP	`code`	Mənası
400	`validation_failed`	Sahə doğrulaması keçmədi; mesaj səbəbi izah edir
401	`missing_token` / `invalid_token` / `token_expired`	Açar yoxdur, yanlışdır ya da müddəti bitib
401	`query_key_disabled` / `signature_*`	Açar URL-də gəldi ya da imza doğrulanmadı (API Təhlükəsizliyi)
403	`module_disabled` / `scope_denied` / `ip_not_allowed`	Modul bağlıdır, əhatə kifayət deyil ya da IP icazəli deyil
404	`*_not_found`	Qeyd yoxdur ya da başqa müştəriyə aiddir
405	`method_not_allowed`	POST tələb olunan əməliyyata GET gəldi
422	(xüsusi son nöqtə üçün)	İş qaydası rədd: kvota, müddət, xətt yoxdur və s.
413	`payload_too_large`	Sorğu gövdəsi 5 MB-ı aşır
429	`rate_limited` / `ip_locked`	Sürət limiti aşıldı ya da IP çox yanlış cəhd səbəbindən müvəqqəti kilidlidir
503	`db_unavailable`	Müvəqqəti xidmət problemi; bir az sonra yenidən cəhd edin

Sürət limitləri

Limit	Defolt
Açar başına	dəqiqədə 120 sorğu (açar ayarından azaldıla bilər)
Hesabın bütün açarlarının cəmi	dəqiqədə 600 sorğu
Nümayəndə vəziyyətləri	əlavə olaraq dəqiqədə 2 sorğu (canlı vəziyyət üçün webhook seçin)
Avtomatik zəng `add_leads`	tək sorğuda 5.000 qeyd

Cavablarda X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset başlıqları gəlir. Aşımda 429 Too Many Requests və Retry-After başlığı qaytarılır. Hər cavabdakı X-Request-Id dəyərini dəstək sorğularında paylaşın.

Test mühiti

Ayrıca sandbox yoxdur; hesabınızda test məqsədli bir daxili və kiçik bir kampaniya ilə sınayın. Avtomatik zəng kampaniyalarını status: "draft" ilə yaradıb results/summary nöqtələrini məlumat gəlmədən də çağıra bilərsiniz. Səsli doğrulama kodunda öz nömrənizə göndəriş edin; tarifləndirmə paket qaydalarınıza görə işləyir.

Versiya və dəyişikliklər

Nöqtələr geriyə uyğun saxlanılır; yeni sahələr əlavə olunur, mövcud sahələrin adı və tipi dəyişmir. Silinəcək sahə ən azı 90 gün əvvəl paneldə və bu səhifədə elan edilir.

Kömək

İnteqrasiya zamanı ilişdiyiniz yerdə panel daxilindəki Dəstək Mərkəzindən "İnteqrasiya / API" mövzulu qeyd açın; nümunə sorğu/cavabınızı əlavə edin, birlikdə baxaq.

API Təhlükəsizliyi