API de SMS de Buluthat
SMS masivo, SMS personalizado, SMS OTP (código de verificación), SMS entrantes, informe de entrega y lista negra.
- Dirección:
https://api.buluthat.com/api/sms.php?action=<eylem> - Identidad:
Authorization: Bearer <anahtar>(oX-Api-Key: <anahtar>). Clave: Panel > SMS masivo > API y ajustes. - Cuerpo: JSON (
Content-Type: application/json) o formulario. Las respuestas son JSON, UTF-8. - Error:
{"ok":false,"error":"<kod>","message":"<açıklama>"}+ HTTP 4xx/5xx. - Números
05321234567,5321234567,+905321234567,905321234567se acepta en los formatos.
Longitud del mensaje
| Codificación | 1 SMS | 2 SMS | 3 SMS | … 7 SMS |
|---|---|---|---|---|
| Estándar | 160 | 306 | 459 | 1071 |
| Turco (si contiene Ş ş Ğ ğ ç ı İ) | 155 | 298 | 447 | 1043 |
| Unicode (emoji, etc.) | 70 | 134 | 201 | 469 |
^ { } \ [ ] ~ | € cuenta como dos caracteres. Ö ö Ü ü Ç están en la codificación estándar.
Envío — 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"
}| Campo | Descripción |
|---|---|
header | Encabezado aprobado. Si está vacío, el encabezado predeterminado. |
message | Texto. Marcadores: {ad} {soyad} {adsoyad} {telefon} {firma} {ret_link} + los demás campos del destinatario. |
recipients | [{phone, name?, ref?, <alan>…}]. El mismo número se envía una sola vez. |
phones | Atajo: ["0532…","0533…"] o texto separado por comas (el mismo mensaje para todos). |
messages | Un texto totalmente distinto para cada persona: [{phone, message, ref?}] (en este caso message no se requiere). |
send_at | Fecha futura (máximo 90 días). Si está vacío, de inmediato. |
is_commercial | Mensaje comercial. true si es iys_recipient_type: BIREYSEL / TACIR; no se envía a destinatarios sin consentimiento de İYS. |
valid_for | Si el teléfono está apagado, el tiempo de prueba, SS:DD (00:01 – 48:00). |
rate_per_minute | Envío por minuto (0 = lo más rápido). |
custom_ref | Su propia referencia; status se consulta con. |
Respuesta:
{"ok":true,"data":{"campaign_id":152,"status":"queued","recipients":2,"credits":2,
"skipped":{"invalid":0,"blacklist":0,"duplicate":0}, ...}}Se omiten los números de la lista negra, erróneos y (si la protección antiduplicados está activa) los que ya recibieron el mismo texto hoy; no se descuenta crédito. El crédito del mensaje no entregado se reembolsa automáticamente.
Códigos de error: missing_recipients, missing_message, request_failed (crédito insuficiente, encabezado sin aprobar, mensaje demasiado largo… — message explica), account_inactive.
Informe — status (GET)
?action=status&campaign_id=152 o &custom_ref=EYLUL-KAMPANYA; opcional status, phone, limit (≤1000), offset.
Estados del mensaje: queued (en cola), sending, waiting (a la espera del informe del operador), delivered, failed, expired, rejected, cancelled.
Otras acciones
| Acción | Método | Descripción |
|---|---|---|
balance | GET | {"sms":1200,"otp":500,"lots":[…]} crédito restante y fechas de vencimiento |
headers | GET | Encabezados aprobados |
campaigns | GET | Lista de envío (from, to, limit, offset) |
cancel | POST | campaign_id — los mensajes no enviados se cancelan, se reembolsa el crédito |
inbound | GET | SMS entrantes: since_id, limit → [{id, from, to, keyword, text, optout, received_at}] |
blacklist | GET | Lista negra |
blacklist_add / blacklist_remove | POST | phones: ["0532…"] |
SMS 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- También puede entregar usted el código (
code, 4-10 dígitos); si lo generamos nosotros, se devuelve una sola vez en esta respuesta y lo que se almacena es solo el hash. templatepuede cambiar el texto con ({kod}obligatorio,{firma},{sure}).- El OTP se descuenta primero del crédito OTP y, al agotarse, del crédito SMS; se envía sin esperar.
- Existe un límite de envíos al mismo número en 10 minutos.
Webhook
Si introduce una dirección en Panel > SMS masivo > API y ajustes, los eventos se envían por 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}}Si no devuelve 2xx, se reintenta tras 1 min, 5 min, 15 min, 1 h, 3 h y 6 h.
Ejemplo (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);