API de SMS da Buluthat

SMS em massa, SMS personalizado, SMS OTP (código de verificação), SMS recebidos, relatório de entrega e lista negra.

• Morada: https://api.buluthat.com/api/sms.php?action=<eylem>
• Identidade: Authorization: Bearer <anahtar> (ou X-Api-Key: <anahtar>). Chave: Painel > SMS em Massa > API e Definições.
• Corpo: JSON (Content-Type: application/json) ou formulário. As respostas são JSON, UTF-8.
• Erro: {"ok":false,"error":"<kod>","message":"<açıklama>"} + HTTP 4xx/5xx.
• Números 05321234567, 5321234567, +905321234567, 905321234567 são aceites nos formatos.

Tamanho da mensagem

^ { } \ [ ] ~ | € contam como dois caracteres. Ö ö Ü ü Ç estão na codificação padrão.

Envio — 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"
}

Resposta:

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

São ignorados os números em lista negra, errados e (se a proteção contra duplicados estiver ativa) que já receberam o mesmo texto hoje; não consomem crédito. O crédito de uma mensagem não entregue é reposto automaticamente.

Códigos de erro: missing_recipients, missing_message, request_failed (créditos insuficientes, cabeçalho não aprovado, mensagem demasiado longa… — message explica), account_inactive.

Relatório — status (GET)

?action=status&campaign_id=152 ou &custom_ref=EYLUL-KAMPANYA; opcional status, phone, limit (≤1000), offset.

Estados da mensagem: queued (em fila), sending, waiting (a aguardar o relatório do operador), delivered, failed, expired, rejected, cancelled.

Outras ações

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

• Também pode indicar o código (code, 4-10 dígitos); se o gerarmos nós, só é devolvido uma vez nesta resposta, e o que fica guardado é apenas o hash.
• template pode alterar o texto com ({kod} obrigatório, {firma}, {sure}).
• O OTP é debitado primeiro do crédito OTP e, depois, do crédito SMS; é enviado sem espera.
• Existe um limite de envios para o mesmo número em 10 minutos.

Webhook

Se indicar um endereço em Painel > SMS em Massa > API e Definições, os eventos são enviados 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}}

Se não devolver 2xx, volta a tentar após 1 min, 5 min, 15 min, 1 h, 3 h, 6 h.

Exemplo (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);