概要

Buluthat APIを使えば、既存のソフトウェア（CRM、ERP、ECサイト、ヘルプデスク）をクラウド交換機と連携できます：クリックで発信、通話制御、列の管理、ブラックリスト、音声ファイル、自動発信キャンペーン、音声アシスタントのタスク、音声確認コード。

すべてのエンドポイントは通常のHTTP上にあり、レスポンスはJSONです。どの言語からでも、HTTPクライアントで利用できます。

基本アドレス： https://api.buluthat.com/api/

認証

すべてのエンドポイントで共通 APIキーを を使用します。キーはパネルで アカウントとサポート > APIキー のページから、アカウントの代表者が生成します。 bt_ で始まり、生成された瞬間に一度だけ表示されます。

キーは毎回のリクエストでヘッダーに付けて送信します：

Authorization: Bearer bt_xxxxxxxx

Authorization ヘッダーを設定できない場合は X-Api-Key: bt_xxxxxxxx も受け付けられます。キーをURLで（?key=）の送信は、新しいキーでは無効です。

各キーは1つのお客様アカウントに紐づき、そのアカウントのデータにのみアクセスできます。キーで スコープ 定義されています：

スコープ外のリクエスト 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 とレスポンス本文にトルコ語のエラーメッセージ。

エラーコード

レート制限

レスポンスでは X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset ヘッダーが返ります。超過時は 429 Too Many Requests と Retry-After ヘッダーが返ります。すべてのレスポンスの X-Request-Id の値をサポートへのお問い合わせでお伝えください。

テスト環境

別のサンドボックスはありません。アカウントでテスト用の内線1つと小規模なキャンペーンでお試しください。自動発信キャンペーンを status: "draft" で作成し results/summary エンドポイントは、データが届く前でも呼び出せます。音声確認コードでは、ご自身の番号宛てに送信してください。課金はパッケージのルールに従って処理されます。

バージョンと変更点

エンドポイントは後方互換性が保たれます。新しいフィールドは追加されますが、既存のフィールドの名前と型は変わりません。廃止予定のフィールドは、少なくとも90日前にパネルとこのページで告知されます。

ヘルプ

連携中に行き詰まった場合は、パネル内のサポートセンターから「連携 / API」の件名で記録を作成し、リクエストとレスポンスの例を添付してください。一緒に確認します。