احراز هویت قالب درخواست قالب پاسخ کدهای خطا محدودیت‌های نرخ محیط آزمایش نسخه و تغییرات راهنما

نمای کلی

API Buluthat امکان می‌دهد نرم‌افزارهای موجود (CRM، ERP، تجارت الکترونیک، میز پشتیبانی) را با سانترال ابری یکپارچه کنید: کلیک برای تماس، کنترل تماس، مدیریت صف، لیست سیاه، فایل‌های صوتی، کمپین‌های تماس خودکار، مأموریت‌های دستیار صوتی و کد تأیید صوتی.

همه نقاط روی HTTP ساده هستند؛ پاسخ‌ها JSON هستند. از هر زبانی، با یک کلاینت HTTP استفاده می‌شود.

نشانی پایه: https://api.buluthat.com/api/

احراز هویت

همه نقاط یکسان کلید API را استفاده می‌کند. کلید در پنل حساب و پشتیبانی > کلیدهای API از صفحه، توسط مدیر حساب تولید می‌شود؛ bt_ شروع می‌شود و فقط لحظه ساخت یک‌بار نمایش داده می‌شود.

کلید در هر درخواست در هدر ارسال می‌شود:

Authorization: Bearer bt_xxxxxxxx

Authorization اگر نتوان هدر را تنظیم کرد X-Api-Key: bt_xxxxxxxx نیز پذیرفته می‌شود. کلید را در URL (?key=) در کلیدهای جدید غیرفعال است.

هر کلید به یک حساب مشتری وصل است و فقط به داده همان حساب دسترسی دارد. در کلید دامنه تعریف شده است:

دامنه	نقاط
`call`	مدیریت تماس، صف‌ها، وضعیت نمایندگان
`autocall`	تماس خودکار (برای سازگاری با یکپارچه‌سازی‌های قدیمی مسیرهای دستیار صوتی، OTP صوتی و تماس را هم باز می‌کند)
`voicebot`	دستیار صوتی
`voice_otp`	کد تأیید صوتی
`sms`	API SMS

درخواست خارج از دامنه 403 scope_denied، ماژول غیرفعال در حساب شما 403 module_disabled برمی‌گردد. به کلید فهرست IP مجاز, تاریخ انقضا و امضای اجباری درخواست با HMAC قابل تعریف است؛ همه امنیت API در صفحه.

کلید خود را در سمت مرورگر (JavaScript) استفاده نکنید؛ همیشه از سرور خودتان فراخوانی کنید. اگر فکر می‌کنید فاش شده، از پنل «تمدید کلید > بستن فوری کلید قدیمی» را بزنید، کلید قدیمی بلافاصله باطل می‌شود.

قالب درخواست

عملیات خواندن GET، عملیات تغییردهنده POST (در فایل‌های صوتی PUT/DELETE).
بدنه POST application/json یا application/x-www-form-urlencoded ممکن است باشد.
عملیات در نقاط یکپارچه‌سازی action با پارامتر انتخاب می‌شود (?action=create_campaign).
مهر زمانی‌ها به وقت ترکیه است (2026-09-18 10:12:03).
شماره‌های تلفن 05xxxxxxxxx, 5xxxxxxxxx یا 905xxxxxxxxx به‌صورت پذیرفته می‌شود؛ در پاسخ‌ها نرمال‌شده برمی‌گردد.

قالب پاسخ

نقاط یکپارچه‌سازی (autocall، voicebot، voice_otp) همیشه یک پوشش برمی‌گردانند:

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

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

نقاط سانترال (begin_call، queues، blocked_numbers…) با کد وضعیت HTTP صحبت می‌کنند: در موفقیت 200 OK و نتیجه در بدنه (آرایه JSON یا متن ساده)، در خطا 4xx و پیام خطای ترکی در بدنه.

کدهای خطا

HTTP	`code`	معنی
400	`validation_failed`	اعتبارسنجی فیلد ناموفق بود؛ پیام دلیل را توضیح می‌دهد
401	`missing_token` / `invalid_token` / `token_expired`	کلید وجود ندارد، نامعتبر یا منقضی شده است
401	`query_key_disabled` / `signature_*`	کلید در URL آمده بود یا امضا تأیید نشد (امنیت API)
403	`module_disabled` / `scope_denied` / `ip_not_allowed`	ماژول بسته است، دامنه ناکافی است یا IP مجاز نیست
404	`*_not_found`	رکوردی وجود ندارد یا متعلق به مشتری دیگری است
405	`method_not_allowed`	GET برای عملیاتی که باید POST باشد آمد
422	(مخصوص هر مسیر)	رد قاعده کاری: سهمیه، مدت، نبود خط و غیره.
413	`payload_too_large`	بدنه درخواست از 5 مگابایت بیشتر است
429	`rate_limited` / `ip_locked`	محدودیت نرخ رد شد یا IP به دلیل تلاش‌های نادرست زیاد موقتاً قفل است
503	`db_unavailable`	مشکل موقت سرویس؛ کمی بعد دوباره تلاش کنید

محدودیت‌های نرخ

محدودیت	پیش‌فرض
برای هر کلید	120 درخواست در دقیقه (از تنظیم کلید قابل کاهش است)
مجموع همه کلیدهای حساب	600 درخواست در دقیقه
وضعیت نمایندگان	علاوه بر آن 2 درخواست در دقیقه (برای وضعیت زنده Webhook را ترجیح دهید)
تماس خودکار `add_leads`	5.000 رکورد در یک درخواست

در پاسخ‌ها X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset هدرها می‌آید. در صورت تجاوز 429 Too Many Requests و Retry-After هدر برمی‌گردد. در هر پاسخ X-Request-Id مقدار را در درخواست‌های پشتیبانی به اشتراک بگذارید.

محیط آزمایش

سندباکس جداگانه‌ای وجود ندارد؛ با یک داخلی آزمایشی و یک کمپین کوچک در حساب خود امتحان کنید. کمپین‌های تماس خودکار را status: "draft" بسازید و results/summary می‌توانید نقاط را بدون داده هم فراخوانی کنید. در کد تأیید صوتی به شماره خودتان ارسال کنید؛ هزینه‌گیری طبق قوانین بسته شما پردازش می‌شود.

نسخه و تغییرات

نقاط با سازگاری رو به عقب نگه داشته می‌شود؛ فیلدهای جدید اضافه می‌شود، نام و نوع فیلدهای موجود تغییر نمی‌کند. فیلدی که حذف خواهد شد دست‌کم 90 روز قبل در پنل و همین صفحه اعلام می‌شود.

راهنما

هر جا حین یکپارچه‌سازی گیر کردید، از مرکز پشتیبانی داخل پنل درخواستی با موضوع «یکپارچه‌سازی / API» باز کنید؛ نمونه درخواست/پاسخ‌تان را ضمیمه کنید، با هم بررسی کنیم.

امنیت API