Buluthat SMS API
一括SMS、個別メッセージSMS、OTP（確認コード）SMS、受信SMS、配信レポート、ブラックリスト。
- 住所：
https://api.buluthat.com/api/sms.php?action=<eylem> - 認証：
Authorization: Bearer <anahtar>（またはX-Api-Key: <anahtar>）。キー：パネル > 一括SMS > APIと設定。 - 本文：JSON（
Content-Type: application/json）またはフォーム。レスポンスはJSON、UTF-8です。 - エラー：
{"ok":false,"error":"<kod>","message":"<açıklama>"}+ HTTP 4xx/5xx。 - 番号
05321234567,5321234567,+905321234567,905321234567形式で受け付けられます。
メッセージの長さ
| エンコード | 1 SMS | 2 SMS | 3 SMS | … 7 SMS |
|---|---|---|---|---|
| スタンダード | 160 | 306 | 459 | 1071 |
| トルコ語（Ş ş Ğ ğ ç ı İ を含む場合） | 155 | 298 | 447 | 1043 |
| Unicode（絵文字など） | 70 | 134 | 201 | 469 |
^ { } \ [ ] ~ | € 2文字として数えられます。Ö ö Ü ü Ç は標準エンコーディングです。
送信 — send （POST）
{
"header": "FIRMAADI",
"message": "Merhaba {ad}, {tutar} TL ödemeniz alınmıştır.",
"recipients": [
{"phone": "05321234567", "name": "Ayşe Yılmaz", "tutar": "1.250", "ref": "CARI-17"},
{"phone": "05331234567", "name": "Mehmet Kaya", "tutar": "300"}
],
"send_at": "2026-10-01 10:00",
"is_commercial": false,
"valid_for": "24:00",
"rate_per_minute": 500,
"custom_ref": "EYLUL-KAMPANYA"
}| エリア | 説明 |
|---|---|
header | 承認済みヘッダー。空の場合はデフォルトのヘッダー。 |
message | テキスト。プレースホルダー： {ad} {soyad} {adsoyad} {telefon} {firma} {ret_link} + 受信者のその他のフィールド。 |
recipients | [{phone, name?, ref?, <alan>…}]。同じ番号には1回のみ送信されます。 |
phones | ショートカット： ["0532…","0533…"] またはカンマ区切りのテキスト（全員に同じメッセージ）。 |
messages | お客様ごとにまったく異なる文面： [{phone, message, ref?}] （この場合 message は不要です）。 |
send_at | 日時指定（最大90日）。空の場合はすぐに。 |
is_commercial | 商用メッセージ。 true の場合は iys_recipient_type: BIREYSEL / TACIR；IYSの承認がない受信者には送信されません。 |
valid_for | 電話の電源が切れている場合は試用期間、 SS:DD (00:01 – 48:00). |
rate_per_minute | 1分あたりの送信数（0 = 最速）。 |
custom_ref | お客様ご自身の参照番号； status で照会できます。 |
レスポンス：
{"ok":true,"data":{"campaign_id":152,"status":"queued","recipients":2,"credits":2,
"skipped":{"invalid":0,"blacklist":0,"duplicate":0}, ...}}ブラックリストに載っている番号、誤った番号、（重複防止が有効な場合）本日すでに同じ文面を受信した番号はスキップされ、クレジットは消費されません。配信できなかったメッセージのクレジットは自動的に返還されます。
エラーコード： missing_recipients, missing_message, request_failed （クレジット不足、ヘッダー未承認、メッセージが長すぎる… — message を明らかにします）、 account_inactive.
レポート — status （GET）
?action=status&campaign_id=152 または &custom_ref=EYLUL-KAMPANYA；任意 status, phone, limit (≤1000), offset.
メッセージのステータス： queued （待機中）、 sending, waiting （事業者レポート待ち）、 delivered, failed, expired, rejected, cancelled.
その他の操作
| 操作 | 方法 | 説明 |
|---|---|---|
balance | GET | {"sms":1200,"otp":500,"lots":[…]} 残りのクレジットと有効期限 |
headers | GET | 承認済みヘッダー |
campaigns | GET | 送信リスト（from, to, limit, offset) |
cancel | POST | campaign_id — 未送信のメッセージはキャンセル、クレジット返還 |
inbound | GET | 受信SMS： since_id, limit → [{id, from, to, keyword, text, optout, received_at}] |
blacklist | GET | ブラックリスト |
blacklist_add / blacklist_remove | POST | phones: ["0532…"] |
OTP SMS
POST ?action=otp_send {"phone":"05321234567","reference":"UYE-1452"}
→ {"ok":true,"data":{"id":88,"status":"sent","expires_at":"…"},"code":"482913"}
POST ?action=otp_verify {"id":88,"code":"482913"}
→ {"ok":true,"verified":true}
hata: wrong_code | expired | too_many_attempts | already_verified | not_found
GET ?action=otp_status&id=88- コードはご自身で指定することもできます（
code、4-10桁）。当社が生成した場合は、このレスポンスで一度だけ返され、保存されるのはハッシュのみです。 templateでテキストを変更できます（{kod}必須、{firma},{sure}).- OTPはまずOTPクレジットから、なくなるとSMSクレジットから差し引かれます。待たずに送信されます。
- 同じ番号への送信は10分間に制限があります。
Webhook
パネル > 一括SMS > APIと設定でアドレスを入力すると、イベントがPOSTされます：
X-Buluthat-Event: sms.delivery | sms.inbound | sms.optout
X-Buluthat-Signature: sha256=<HMAC-SHA256(gövde, sır)>
{"event":"delivery","data":{"message_id":9012,"campaign_id":152,"ref":"CARI-17",
"phone":"905321234567","status":"delivered","detail":"İletildi","done_at":"…"}}
{"event":"inbound","data":{"id":44,"from":"905321234567","to":"…","keyword":"","text":"…","optout":false}}2xxが返らない場合、1分、5分、15分、1時間、3時間、6時間後に再試行されます。
例（PHP）
$ch = curl_init('https://api.buluthat.com/api/sms.php?action=send');
curl_setopt_array($ch, [
CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $key, 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['message' => 'Siparişiniz kargoda.', 'phones' => ['05321234567']]),
]);
$res = json_decode(curl_exec($ch), true);