Buluthat SMS API
Toplu SMS, kişiye özel SMS, OTP (doğrulama kodu) SMS'i, gelen SMS, teslim raporu ve kara liste.
- Adres:
https://api.buluthat.com/api/sms.php?action=<eylem> - Kimlik:
Authorization: Bearer <anahtar>(ya daX-Api-Key: <anahtar>). Anahtar: Panel > Toplu SMS > API ve Ayarlar. - Gövde: JSON (
Content-Type: application/json) ya da form. Cevaplar JSON, UTF-8. - Hata:
{"ok":false,"error":"<kod>","message":"<açıklama>"}+ HTTP 4xx/5xx. - Numaralar
05321234567,5321234567,+905321234567,905321234567biçimlerinde kabul edilir.
Mesaj boyu
| Kodlama | 1 SMS | 2 SMS | 3 SMS | … 7 SMS |
|---|---|---|---|---|
| Standart | 160 | 306 | 459 | 1071 |
| Türkçe (Ş ş Ğ ğ ç ı İ içeriyorsa) | 155 | 298 | 447 | 1043 |
| Unicode (emoji vb.) | 70 | 134 | 201 | 469 |
^ { } \ [ ] ~ | € iki karakter sayılır. Ö ö Ü ü Ç standart kodlamadadır.
Gönderim — 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"
}| Alan | Açıklama |
|---|---|
header | Onaylı başlık. Boşsa varsayılan başlık. |
message | Metin. Yer tutucular: {ad} {soyad} {adsoyad} {telefon} {firma} {ret_link} + alıcının diğer alanları. |
recipients | [{phone, name?, ref?, <alan>…}]. Aynı numara bir kez gönderilir. |
phones | Kısa yol: ["0532…","0533…"] ya da virgüllü metin (herkese aynı mesaj). |
messages | Kişiye tamamen farklı metin: [{phone, message, ref?}] (bu durumda message gerekmez). |
send_at | İleri tarih (en fazla 90 gün). Boşsa hemen. |
is_commercial | Ticari ileti. true ise iys_recipient_type: BIREYSEL / TACIR; İYS onayı olmayan alıcıya gitmez. |
valid_for | Telefon kapalıysa deneme süresi, SS:DD (00:01 – 48:00). |
rate_per_minute | Dakikada gönderim (0 = en hızlı). |
custom_ref | Kendi referansınız; status ile sorgulanır. |
Cevap:
{"ok":true,"data":{"campaign_id":152,"status":"queued","recipients":2,"credits":2,
"skipped":{"invalid":0,"blacklist":0,"duplicate":0}, ...}}Kara listedeki, hatalı ve (mükerrer koruması açıksa) bugün aynı metni almış numaralar atlanır; kontör düşmez. İletilemeyen mesajın kontörü otomatik iade edilir.
Hata kodları: missing_recipients, missing_message, request_failed (kontör yetersiz, başlık onaysız, mesaj çok uzun… — message açıklar), account_inactive.
Rapor — status (GET)
?action=status&campaign_id=152 ya da &custom_ref=EYLUL-KAMPANYA; isteğe bağlı status, phone, limit (≤1000), offset.
Mesaj durumları: queued (sırada), sending, waiting (operatör raporu bekleniyor), delivered, failed, expired, rejected, cancelled.
Diğer eylemler
| Eylem | Yöntem | Açıklama |
|---|---|---|
balance | GET | {"sms":1200,"otp":500,"lots":[…]} kalan kontör ve son kullanma tarihleri |
headers | GET | Onaylı başlıklar |
campaigns | GET | Gönderim listesi (from, to, limit, offset) |
cancel | POST | campaign_id — gönderilmemiş mesajlar iptal, kontör iade |
inbound | GET | Gelen SMS'ler: since_id, limit → [{id, from, to, keyword, text, optout, received_at}] |
blacklist | GET | Kara liste |
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- Kodu kendiniz de verebilirsiniz (
code, 4-10 hane); biz ürettiysek yalnızca bu cevapta bir kez döner, saklanan yalnızca hash'tir. templateile metni değiştirebilirsiniz ({kod}zorunlu,{firma},{sure}).- OTP önce OTP kontöründen, bitince SMS kontöründen düşer; beklemeden gönderilir.
- Aynı numaraya 10 dakikada gönderim sınırı vardır.
Webhook
Panel > Toplu SMS > API ve Ayarlar'da adres girerseniz olaylar POST edilir:
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 dönmezseniz 1 dk, 5 dk, 15 dk, 1 sa, 3 sa, 6 sa sonra tekrar denenir.
Örnek (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);