Mesaj uzunluğu Göndəriş — `send` (POST)Hesabat — `status` (GET)Digər əməliyyatlar OTP SMS Webhook Nümunə (PHP)

Buluthat SMS API

Toplu SMS, şəxsi SMS, OTP (doğrulama kodu) SMS-i, daxil olan SMS, çatdırılma hesabatı və qara siyahı.

Ünvan: https://api.buluthat.com/api/sms.php?action=<eylem>
Kimlik: Authorization: Bearer <anahtar> (və ya X-Api-Key: <anahtar>). Açar: Panel > Toplu SMS > API və Ayarlar.
Gövdə: JSON (Content-Type: application/json) və ya forma. Cavablar JSON, UTF-8.
Xəta: {"ok":false,"error":"<kod>","message":"<açıklama>"} + HTTP 4xx/5xx.
Nömrələr 05321234567, 5321234567, +905321234567, 905321234567 formatlarında qəbul edilir.

Mesaj uzunluğu

Kodlaşdırma	1 SMS	2 SMS	3 SMS	… 7 SMS
Standart	160	306	459	1071
Türkcə (Ş ş Ğ ğ ç ı İ varsa)	155	298	447	1043
Unicode (emoji və s.)	70	134	201	469

^ { } \ [ ] ~ | € iki simvol sayılır. Ö ö Ü ü Ç standart kodlaşdırmadadır.

Göndəriş — `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"
}

Sahə	İzah
`header`	Təsdiqli başlıq. Boşdursa defolt başlıq.
`message`	Mətn. Yer tutucular: `{ad}` `{soyad}` `{adsoyad}` `{telefon}` `{firma}` `{ret_link}` + alıcının digər sahələri.
`recipients`	`[{phone, name?, ref?, <alan>…}]`. Eyni nömrəyə bir dəfə göndərilir.
`phones`	Qısa yol: `["0532…","0533…"]` ya da vergüllü mətn (hamıya eyni mesaj).
`messages`	Şəxsə tamamilə fərqli mətn: `[{phone, message, ref?}]` (bu halda `message` lazım deyil).
`send_at`	Gələcək tarix (ən çox 90 gün). Boşdursa dərhal.
`is_commercial`	Kommersiya mesajı. `true` isə `iys_recipient_type`: `BIREYSEL` / `TACIR`; İYS təsdiqi olmayan alıcıya getmir.
`valid_for`	Telefon bağlıdırsa sınaq müddəti, `SS:DD` (00:01 – 48:00).
`rate_per_minute`	Dəqiqədə göndəriş (0 = ən sürətli).
`custom_ref`	Öz referansınız; `status` ilə sorğulanır.

Cavab:

{"ok":true,"data":{"campaign_id":152,"status":"queued","recipients":2,"credits":2,
 "skipped":{"invalid":0,"blacklist":0,"duplicate":0}, ...}}

Qara siyahıdakı, yanlış və (təkrar qoruması açıqdırsa) bu gün eyni mətni almış nömrələr atlanır; kontor çıxılmır. Çatdırılmayan mesajın kontoru avtomatik qaytarılır.

Xəta kodları: missing_recipients, missing_message, request_failed (kontor çatışmır, başlıq təsdiqsizdir, mesaj çox uzundur… — message izah edir), account_inactive.

Hesabat — `status` (GET)

?action=status&campaign_id=152 ya da &custom_ref=EYLUL-KAMPANYA; istəyə bağlı status, phone, limit (≤1000), offset.

Mesaj vəziyyətləri: queued (növbədə), sending, waiting (operator hesabatı gözlənilir), delivered, failed, expired, rejected, cancelled.

Digər əməliyyatlar

Əməliyyat	Metod	İzah
`balance`	GET	`{"sms":1200,"otp":500,"lots":[…]}` qalan kontor və son istifadə tarixləri
`headers`	GET	Təsdiqli başlıqlar
`campaigns`	GET	Göndəriş siyahısı (`from`, `to`, `limit`, `offset`)
`cancel`	POST	`campaign_id` — göndərilməmiş mesajlar ləğv, kontor qaytarılır
`inbound`	GET	Daxil olan SMS-lər: `since_id`, `limit` → `[{id, from, to, keyword, text, optout, received_at}]`
`blacklist`	GET	Qara siyahı
`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 özünüz də verə bilərsiniz (code, 4-10 rəqəm); biz yaratmışıqsa yalnız bu cavabda bir dəfə qaytarılır, saxlanan yalnız hash-dir.
template ilə mətni dəyişə bilərsiniz ({kod} məcburi, {firma}, {sure}).
OTP əvvəlcə OTP kontorundan, bitəndə SMS kontorundan çıxılır; gözləmədən göndərilir.
Eyni nömrəyə 10 dəqiqədə göndəriş limiti var.

Webhook

Panel > Toplu SMS > API və Ayarlarda ünvan daxil etsəniz hadisələr 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 qaytarmasanız 1 dəq, 5 dəq, 15 dəq, 1 saat, 3 saat, 6 saat sonra yenidən cəhd edilir.

Nümunə (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);

← Səsli Doğrulama (OTP) Webhook-lar