Автентифікація Формат запиту Формат відповіді Коди помилок Ліміти швидкості Тестове середовище Версії та зміни Допомога

Загальний огляд

API Buluthat дає змогу інтегрувати ваше наявне програмне забезпечення (CRM, ERP, e-commerce, служба підтримки) з хмарною АТС: клік-дзвінок, керування дзвінками, керування чергами, чорний список, звукові файли, кампанії автоматичного дзвінка, завдання голосового асистента та голосовий код підтвердження.

Усі кінцеві точки працюють через звичайний 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`	SMS API

Запит поза областю 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`	Для операції, що потребує POST, надійшов GET
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 значення поділіться в запитах до підтримки.

Тестове середовище

Окремого sandbox немає; спробуйте в обліковому записі з тестовим внутрішнім номером і невеликою кампанією. Кампанії автоматичного дзвінка status: "draft" створивши за допомогою results/summary кінцеві точки можна викликати й без даних. Для голосового коду підтвердження надсилайте на власний номер; тарифікація виконується за правилами вашого пакета.

Версії та зміни

Кінцеві точки зберігають зворотну сумісність; додаються нові поля, назви та типи наявних полів не змінюються. Про поле, що буде видалено, оголошується в панелі та на цій сторінці щонайменше за 90 днів.

Допомога

Якщо під час інтеграції виникли труднощі, створіть запис у Центрі підтримки в панелі за темою «Інтеграція / API»; додайте приклад запиту/відповіді, подивимося разом.

Безпека API