OTP servisleri

OTP (tek kullanımlık şifre), kullanıcıdan gelen bir kodu doğrulatarak işlemi onaylatma yöntemidir. Giriş, kayıt ve işlem onayı adımlarında kullanılır. Servis yalnızca API anahtarı ya da panel oturumuyla çağrılır; kayıtlar hesabınıza bağlıdır ve başka hesaplar tarafından görülemez.

Doğrulama akışı

Kurallar

• Kod varsayılan olarak 6 hanelidir; 6 ile 8 hane arasında seçilebilir.
• Varsayılan geçerlilik 180 saniyedir; 60 ile 600 saniye arasında seçilebilir.
• Her kod için en fazla 5 doğrulama denemesi yapılır; sonrasında kod kilitlenir.
• Aynı numaraya 45 saniyede bir ve saatte en fazla 5 kod gönderilebilir.
• Hesap başına günlük gönderim sınırı vardır; aşıldığında 429 döner.
• Her gönderim bir SMS segmenti kadar kredi düşer. Sağlayıcı mesajı kabul etmezse kredi iade edilir.
• Numaralar 905XXXXXXXXX biçimine dönüştürülerek işlenir.

Kimlik doğrulama

Paneldeki API Ayarları ekranından bir API anahtarı oluşturun. Anahtar bsl_live_ ile başlar ve yalnızca oluşturulurken bir kez gösterilir. Her isteğe X-API-Key başlığıyla ekleyin. Anahtarı yalnızca sunucu tarafında saklayın.

Uç noktalar

Temel adres: https://basliklisms.com/api/v1

Kod gönderme isteği:

POST /otp/send
X-API-Key: bsl_live_...
Idempotency-Key: giris-1042

{
  "phone": "05321234567",
  "length": 6,
  "ttlSeconds": 180,
  "brand": "Firmam",
  "header": "FIRMAM"
}

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ğrulama isteği:

POST /otp/verify
X-API-Key: bsl_live_...

{
  "id": "otp-3f6c1e0a-9d2b-4b7e-8a51-0c4d9e7f2a10",
  "code": "849201"
}

id yerine phone da gönderilebilir; bu durumda numaranın en yeni kodu doğrulanır. Başarılı yanıt:

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

Kayıtlar: GET /otp/logs?limit=25&cursor=... yalnızca kendi gönderimlerinizi döner.

İstek alanları

• phone: zorunlu, Türkiye cep numarası.
• length: isteğe bağlı, 6 ile 8.
• ttlSeconds: isteğe bağlı, 60 ile 600.
• brand: isteğe bağlı, 2 ile 20 karakter; yalnızca harf, rakam ve boşluk içerebilir (nokta, eğik çizgi, iki nokta ve @ kabul edilmez). Mesajın başına eklenir. Mesaj: “Firmam doğrulama kodunuz: 849201. Kodu kimseyle paylaşmayın.”
• header: isteğe bağlı gönderici başlığı. ANKARA YZLM genel başlığı ya da hesabınızda onaylı bir başlık olabilir.
• Idempotency-Key: isteğe bağlı başlık, en fazla 100 karakter. Aynı anahtarla tekrarlanan istek yeni SMS göndermez ve kredi düşmez; ilk isteğin sonucunu döner.

Gönderici başlığı

header 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ığı kullanılır. Genel başlık ya da onaylı başlıklarınız dışında bir başlık istenirse 403, kullanılabilir hiçbir başlık yoksa 409 döner. OTP gönderimi için e-imza doğrulaması gerekmez.

Hata kodları

Hata yanıtı success: false ile error.code ve Türkçe error.message içerir.

• 400: geçersiz alan, geçersiz numara ya da hatalı kod (remainingAttempts ile).
• 401: anahtar eksik, geçersiz, iptal edilmiş veya hesap pasif.
• 402: yetersiz kredi.
• 403: gönderici başlığı hesabınıza ait değil.
• 409: gönderici başlığı tanımlı değil.
• 410: kodun süresi doldu ya da kod daha önce kullanıldı.
• 423: 5 hatalı deneme sonrası kod kilitlendi.
• 429: istek limiti; Retry-After saniyesi kadar bekleyin.
• 424: SMS sağlayıcısı mesajı kabul etmedi (PROVIDER_REJECTED) ya da sağlayıcıya ulaşılamadı (PROVIDER_UNAVAILABLE); kredi iade edildi. error.providerCode ve error.providerDescription nedeni verir.
• 503: servis ya da SMS sağlayıcısı yapılandırılmamış.

İzleme

Paneldeki OTP SMS ekranından test gönderimi yapabilir, son gönderimleri ve günlük özeti izleyebilirsiniz. Kayıtlarda kod bulunmaz, numaralar maskelidir.

Hazır kütüphaneler

Node.js, Python, PHP ve Go için hazır kütüphaneler API referansı sayfasında listelenir. Kütüphanelerin tamamı aynı uç noktaları kullanır; dil seçimi projenizin yığınına bağlıdır.

İlgili rehberler

API kimlik doğrulaması ve diğer uç noktalar için API referansı, SMS API ile gönderim akışı için SMS API sayfasına bakabilirsiniz.