Buluthat 短信 API
批量短信、个性化短信、OTP（验证码）短信、上行短信、送达报告和黑名单。
- 地址：
https://api.buluthat.com/api/sms.php?action=<eylem> - 身份：
Authorization: Bearer <anahtar>（或X-Api-Key: <anahtar>）。密钥位置：面板 > 批量短信 > API 与设置。 - 正文：JSON（
Content-Type: application/json）或表单。响应为 JSON，UTF-8。 - 错误：
{"ok":false,"error":"<kod>","message":"<açıklama>"}+ HTTP 4xx/5xx。 - 号码
05321234567,5321234567,+905321234567,905321234567格式均可接受。
消息长度
| 编码 | 1 条短信 | 2 条短信 | 3 条短信 | … 7 条短信 |
|---|---|---|---|---|
| 标准 | 160 | 306 | 459 | 1071 |
| 土耳其语（含 Ş ş Ğ ğ ç ı İ 时） | 155 | 298 | 447 | 1043 |
| Unicode（表情符号等） | 70 | 134 | 201 | 469 |
^ { } \ [ ] ~ | € 计为两个字符。Ö ö Ü ü Ç 属于标准编码。
发送 — 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>…}]。同一号码只发送一次。 |
phones | 快捷方式： ["0532…","0533…"] 或以逗号分隔的文本（所有人收到相同消息）。 |
messages | 对每个人完全不同的文本： [{phone, message, ref?}] （此时 message 无需）。 |
send_at | 预约日期（最多 90 天）。若为空则立即发送。 |
is_commercial | 商业信息。 true 则 iys_recipient_type: BIREYSEL / TACIR；未获 İYS 许可的收件人不会收到。 |
valid_for | 若电话关机，试用期限， SS:DD (00:01 – 48:00). |
rate_per_minute | 每分钟发送量（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 | 上行短信： since_id, limit → [{id, from, to, keyword, text, optout, received_at}] |
blacklist | GET | 黑名单 |
blacklist_add / blacklist_remove | POST | phones: ["0532…"] |
OTP 短信
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 额度，用完后扣除短信额度；无需等待即可发送。
- 对同一号码有 10 分钟内的发送限制。
Webhook
如果在面板 > 批量短信 > 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);