Аутентификация Формат запроса Формат ответа Коды ошибок Лимиты запросов Тестовая среда Версия и изменения Помощь

Обзор

API Buluthat позволяет интегрировать уже используемое вами ПО (CRM, ERP, электронную коммерцию, службу поддержки) с облачной АТС: click-to-call, управление вызовами, управление очередями, чёрный список, аудиофайлы, кампании автодозвона, задания голосового ассистента и голосовой код подтверждения.

Все методы работают по обычному 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); всегда вызывайте API со своего сервера. Если подозреваете утечку, в панели нажмите «Обновить ключ > Закрыть старый сразу» — старый ключ мгновенно станет недействительным.

Формат запроса

Операции чтения 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 делитесь значением в заявках в поддержку.

Тестовая среда

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

Версия и изменения

Методы сохраняют обратную совместимость; добавляются новые поля, имя и тип существующих полей не меняются. Поле, которое будет удалено, объявляется в панели и на этой странице не менее чем за 90 дней.

Помощь

Если возникли трудности при интеграции, создайте заявку по теме «Интеграция / API» в Центре поддержки внутри панели; приложите пример запроса/ответа, и мы разберём вместе.

Безопасность API