Buluthat SMS API
SMS الجماعي وSMS المخصص وOTP (رمز التحقق) و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 |
^ { } \ [ ] ~ | € تُعدّ حرفين. أما Ö ö Ü ü Ç فهي في الترميز القياسي.
الإرسال — 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 | رسائل 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);