Geliştirici

API referansı

Başlıklı SMS'i kendi yazılımınıza bağlamak için kullanacağınız REST kontratı: temel adres, kimlik doğrulama, uç noktalar ve hata biçimi. Örnekler curl ve Node.js fetch ile verilmiştir.

Temel adres ve API anahtarı

Her istek X-API-Key başlığıyla gönderilir. Anahtar, paneldeki API Ayarları ekranından oluşturulur, yalnızca oluşturulurken bir kez gösterilir ve dilediğiniz zaman iptal edilebilir.

Temel adreshttps://basliklisms.com/api/v1

Kimlik doğrulamaX-API-Key: bsl_live_...

İçerik türüapplication/json

Anahtar yönetimiPanel, API Ayarları

CURL

curl -X POST https://basliklisms.com/api/v1/sms/send \
  -H "X-API-Key: bsl_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: siparis-1001" \
  -d '{
    "header": "ANKARA YZLM",
    "message": "Siparişiniz kargoya verildi.",
    "recipients": ["05321234567"]
  }'

Uç noktalar

Uç noktalar aynı anahtarla çalışır. Gönderim isteği sağlayıcıya iletilir ve sonucu aynı yanıtta döner.

POST/sms/send

SMS gönderir; başlık verilmezse ANKARA YZLM genel başlığı (onaylı tek başlığınız varsa o) kullanılır. Gövde: message ve recipients (veya phone); isteğe bağlı header ve commercial. Idempotency-Key başlığı çift gönderimi önler.

GET/balance

Kalan SMS kredisini ve gönderim sayaçlarını döner.

POST/otp/send

Doğrulama kodunu SMS ile gönderir. Gövde: phone; isteğe bağlı length, ttlSeconds, brand ve header.

POST/otp/verify

Kullanıcının girdiği kodu doğrular. Gövde: id veya phone ile code.

GET/otp/logs

Kendi OTP gönderim kayıtlarınızı ve günlük özeti döner. Kod hiçbir kayıtta yer almaz.

GET/opt-outs

SMS RET listenizi sayfalı döner. Sorgu: page ve limit (en fazla 200).

POST/opt-outs

Listeye numara ekler. Gövde: phone veya phones (en fazla 1.000).

DELETE/opt-outs

Listeden numara çıkarır. Gövde: phone veya id.

SMS gönderimi

POST /sms/send mesajı sağlayıcıya iletir. Kredi gönderimden önce işlem içinde düşülür; sağlayıcının kabul etmediği alıcıların kredisi iade edilir.

headerİsteğe bağlı. Hesabınızda onaylı gönderici başlığı. Tek onaylı başlığınız varsa atlanabilir

messageZorunlu. 1 ile 918 karakter, en fazla 6 SMS segmenti

recipientsAlıcı listesi. 05xx, 5xx veya 905xx biçimi. recipients veya phone zorunlu

phoneTek alıcı için kısa yol

commercialİsteğe bağlı, true veya false. Varsayılan false

Idempotency-Keyİsteğe bağlı başlık. En fazla 100 karakter

MaliyetSMS segmenti sayısı x geçerli alıcı sayısı. Türkçe karakter içeren mesajlarda segment 70/67 karakterdir

Alıcı sınırıİstek başına en fazla 1.000 geçerli alıcı

Geçersiz numaralar atlanır ve invalid alanında listelenir; tekrar eden numaralar tek sayılır. SMS RET listenizdeki numaralar gönderilmez, ücretlendirilmez ve optedOut alanında sayılır. Aynı Idempotency-Key ile tekrarlanan istek yeni SMS göndermez ve ikinci kez kredi düşmez; ilk isteğin sonucunu döner. Sağlayıcıya yapılan çağrı hiçbir koşulda otomatik tekrarlanmaz.

İstek

curl -X POST https://basliklisms.com/api/v1/sms/send \
  -H "X-API-Key: bsl_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: siparis-1001" \
  -d '{
    "header": "ANKARA YZLM",
    "message": "Siparişiniz kargoya verildi.",
    "recipients": ["05321234567", "05331234567"],
    "commercial": false
  }'

Yanıt (200)

{
  "success": true,
  "data": {
    "id": "msg-6f1c0a52-3b7e-4d0a-9c1e-2a7d5b8f4e10",
    "status": "SENT",
    "accepted": 2,
    "rejected": 0,
    "invalid": [],
    "invalidCount": 0,
    "optedOut": 0,
    "creditsUsed": 2,
    "creditsRefunded": 0,
    "balance": 998
  }
}

Node.js

const response = await fetch('https://basliklisms.com/api/v1/sms/send', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.BASLIKLISMS_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'siparis-1001',
  },
  body: JSON.stringify({
    header: 'ANKARA YZLM',
    message: 'Siparişiniz kargoya verildi.',
    recipients: ['05321234567'],
  }),
});

const result = await response.json();
if (!response.ok) {
  throw new Error(result.error.code + ': ' + result.error.message);
}
console.log(result.data.status, result.data.balance);

Kısmi iletim (200)

{
  "success": true,
  "data": {
    "id": "msg-6f1c0a52-3b7e-4d0a-9c1e-2a7d5b8f4e10",
    "status": "PARTIAL",
    "accepted": 1,
    "rejected": 1,
    "invalid": [],
    "invalidCount": 0,
    "optedOut": 0,
    "creditsUsed": 1,
    "creditsRefunded": 1,
    "balance": 998
  }
}

Yetersiz kredi (402)

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Yetersiz SMS kredisi. Mevcut bakiye: 1, Gereken: 2"
  }
}

Sağlayıcı reddetti (424)

{
  "success": false,
  "error": {
    "code": "PROVIDER_REJECTED",
    "message": "SMS sağlayıcısı mesajı kabul etmedi; kredi iade edildi.",
    "providerCode": "40",
    "providerDescription": "Gönderici başlığı NetGSM hesabında tanımlı değil."
  },
  "data": {
    "id": "msg-6f1c0a52-3b7e-4d0a-9c1e-2a7d5b8f4e10",
    "status": "FAILED",
    "accepted": 0,
    "rejected": 2,
    "creditsUsed": 0,
    "creditsRefunded": 2
  }
}

Bakiye

GET /balance kalan krediyi ve gönderim sayaçlarını döner.

İstek

curl https://basliklisms.com/api/v1/balance \
  -H "X-API-Key: bsl_live_..."

Yanıt

{
  "success": true,
  "data": {
    "balance": 998,
    "currency": "SMS",
    "credits": 998,
    "totalSmsSent": 120,
    "successfulSms": 118,
    "failedSms": 2
  }
}

SMS RET listesi

Mesaj almak istemeyen alıcıları listeye ekleyin. Listedeki numaralara hiçbir SMS gönderimi yapılmaz ve ücretlendirilmez; OTP bu filtrenin dışındadır.

Numara ekle

curl -X POST https://basliklisms.com/api/v1/opt-outs \
  -H "X-API-Key: bsl_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "phones": ["05321234567"] }'

Yanıt

{
  "success": true,
  "data": { "added": 1, "alreadyPresent": 0, "invalid": [] }
}

Listele

curl "https://basliklisms.com/api/v1/opt-outs?page=1&limit=50" \
  -H "X-API-Key: bsl_live_..."

Numara çıkar

curl -X DELETE https://basliklisms.com/api/v1/opt-outs \
  -H "X-API-Key: bsl_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "phone": "05321234567" }'

OTP gönderimi ve doğrulama

Kod yanıtta ve kayıtlarda hiç dönmez; yalnızca kullanıcının telefonuna SMS ile gider. Her gönderim bir SMS segmenti kadar kredi düşer; sağlayıcı reddederse kredi iade edilir.

GönderPOST /otp/send

DoğrulaPOST /otp/verify

KayıtlarGET /otp/logs

phoneZorunlu. 05xx veya 905xx biçiminde Türkiye cep numarası

lengthİsteğe bağlı. 6 ile 8 arası, varsayılan 6

ttlSecondsİsteğe bağlı. 60 ile 600 arası, varsayılan 180

brandİsteğe bağlı. 2 ile 20 karakter; yalnızca harf, rakam ve boşluk. Mesajın başına eklenir

headerİsteğe bağlı. ANKARA YZLM genel başlığı ya da hesabınızda onaylı gönderici başlığı

Idempotency-Keyİsteğe bağlı başlık. En fazla 100 karakter

Deneme hakkıHer kod için en fazla 5 doğrulama denemesi

Başlık verilmezse hesabınızdaki tek onaylı başlık kullanılır; birden fazla ya da hiç onaylı başlık yoksa ANKARA YZLM genel başlığı devreye girer. Genel başlık ve onaylı başlıklarınız dışında bir başlık 403 döner. OTP gönderimi e-imza gerektirmez. Aynı Idempotency-Key ile tekrarlanan istek yeni SMS göndermez ve ikinci kez kredi düşmez; ilk isteğin id ve durumunu döner. Numara başına 45 saniyede bir ve saatte en fazla 5 gönderim yapılabilir.

Gönder

curl -X POST https://basliklisms.com/api/v1/otp/send \
  -H "X-API-Key: bsl_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: giris-1042" \
  -d '{
    "phone": "05321234567",
    "brand": "Firmam"
  }'

Gönder yanıtı

{
  "success": true,
  "data": {
    "id": "otp-3f6c1e0a-9d2b-4b7e-8a51-0c4d9e7f2a10",
    "phone": "90532*****67",
    "status": "SENT",
    "expiresAt": "2026-09-14T09:03:00.000Z",
    "creditsUsed": 1,
    "header": "FIRMAM"
  }
}

Doğrula

curl -X POST https://basliklisms.com/api/v1/otp/verify \
  -H "X-API-Key: bsl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "otp-3f6c1e0a-9d2b-4b7e-8a51-0c4d9e7f2a10",
    "code": "849201"
  }'

Doğrula yanıtı

{
  "success": true,
  "data": { "verified": true }
}

Hatalı kod (400)

{
  "success": false,
  "error": {
    "code": "OTP_INVALID_CODE",
    "message": "Doğrulama kodu hatalı."
  },
  "remainingAttempts": 4
}

İstek limiti (429)

HTTP/1.1 429 Too Many Requests
Retry-After: 38

{
  "success": false,
  "error": {
    "code": "PHONE_RATE_LIMITED",
    "message": "Bu numaraya çok sık kod gönderiliyor. 38 saniye sonra tekrar deneyin."
  }
}

İstek ve yanıt

Başarılı yanıtta success: true ve data döner. Hatalı istekte success: false ve hata kodu ile Türkçe mesaj içeren error alanı döner.

Hata yanıtı

{
  "success": false,
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Oturum açmanız gerekmektedir."
  }
}

İstek limiti (429)

HTTP/1.1 429 Too Many Requests
Retry-After: 12

Hata kodları

Taşıma katmanı hataları HTTP durum koduyla döner. Hata yanıtında HTTP durum kodu ile birlikte error.code ve Türkçe error.message döner.

400Geçersiz istek

Alan eksik veya hatalı, mesaj 918 karakteri ya da 6 SMS uzunluğunu aşıyor, geçerli alıcı yok veya doğrulama kodu yanlış. Yanlış kodda kalan deneme hakkı remainingAttempts alanında döner.

401Kimlik doğrulama

Anahtar eksik, geçersiz veya iptal edilmiş; ya da hesap pasif.

402Yetersiz kredi

Gönderim için yeterli kredi yok. Kredi düşülmez, mesaj gönderilmez.

403Yetkisiz başlık

İstenen gönderici başlığı hesabınızda onaylı değil.

409Başlık tanımsız

Başlık seçilemedi. Birden fazla onaylı başlığınız varsa header alanını gönderin (ANKARA YZLM genel başlığı da gönderilebilir). Aynı Idempotency-Key ile hâlâ işlenen bir istek varsa da 409 döner.

410Kod geçersiz

Doğrulama kodunun süresi doldu ya da kod daha önce doğrulandı.

413Alıcı sınırı

Tek istekte en fazla 1.000 geçerli alıcı gönderilebilir. Daha büyük listeler için panelden toplu gönderim kullanın.

423Kilitli

Bir kod için 5 hatalı deneme yapıldı. Yeni kod isteyin.

429İstek limiti

Dakikadaki istek sayısı aşıldı. OTP için ayrıca numara başına 45 saniyede bir ve saatte en fazla 5 gönderim, hesap başına günlük sınır uygulanır. Yanıttaki Retry-After süresi kadar bekleyin.

424Sağlayıcı hatası

SMS sağlayıcısı mesajı kabul etmedi (PROVIDER_REJECTED) ya da sağlayıcıya ulaşılamadı (PROVIDER_UNAVAILABLE). error.providerCode ve error.providerDescription nedeni verir. Düşülen kredi otomatik iade edilir.

503Servis hazır değil

OTP veya SMS sağlayıcısı yapılandırılmamış. Düşülen kredi iade edilir.

500Sunucu hatası

Geçici sistem sorunu. İsteği daha sonra tekrarlayın.

Anahtarınızı oluşturup gönderime başlayın

Panelden API anahtarınızı alın, onaylı başlığınızı seçin ve ilk isteğinizi gönderin. Entegrasyon sırasında takıldığınızda teknik ekibe ulaşabilirsiniz.

Üye Ol Teknik destek

curl -X POST https://basliklisms.com/api/v1/sms/send \ -H "X-API-Key: bsl_live_..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: siparis-1001" \ -d '{ "header": "ANKARA YZLM", "message": "Siparişiniz kargoya verildi.", "recipients": ["05321234567"] }'

{ "success": true, "data": { "id": "msg-6f1c0a52-3b7e-4d0a-9c1e-2a7d5b8f4e10", "status": "SENT", "accepted": 2, "rejected": 0, "invalid": [], "invalidCount": 0, "optedOut": 0, "creditsUsed": 2, "creditsRefunded": 0, "balance": 998 } }

{ "success": true, "data": { "id": "msg-6f1c0a52-3b7e-4d0a-9c1e-2a7d5b8f4e10", "status": "PARTIAL", "accepted": 1, "rejected": 1, "invalid": [], "invalidCount": 0, "optedOut": 0, "creditsUsed": 1, "creditsRefunded": 1, "balance": 998 } }

{ "success": false, "error": { "code": "PROVIDER_REJECTED", "message": "SMS sağlayıcısı mesajı kabul etmedi; kredi iade edildi.", "providerCode": "40", "providerDescription": "Gönderici başlığı NetGSM hesabında tanımlı değil." }, "data": { "id": "msg-6f1c0a52-3b7e-4d0a-9c1e-2a7d5b8f4e10", "status": "FAILED", "accepted": 0, "rejected": 2, "creditsUsed": 0, "creditsRefunded": 2 } }

curl -X POST https://basliklisms.com/api/v1/otp/send \ -H "X-API-Key: bsl_live_..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: giris-1042" \ -d '{ "phone": "05321234567", "brand": "Firmam" }'

{ "success": true, "data": { "id": "otp-3f6c1e0a-9d2b-4b7e-8a51-0c4d9e7f2a10", "phone": "90532*****67", "status": "SENT", "expiresAt": "2026-09-14T09:03:00.000Z", "creditsUsed": 1, "header": "FIRMAM" } }

curl -X POST https://basliklisms.com/api/v1/otp/verify \ -H "X-API-Key: bsl_live_..." \ -H "Content-Type: application/json" \ -d '{ "id": "otp-3f6c1e0a-9d2b-4b7e-8a51-0c4d9e7f2a10", "code": "849201" }'

HTTP/1.1 429 Too Many Requests Retry-After: 38 { "success": false, "error": { "code": "PHONE_RATE_LIMITED", "message": "Bu numaraya çok sık kod gönderiliyor. 38 saniye sonra tekrar deneyin." } }