SMS Onay API Entegrasyonu: Geliştirici Rehberi

OnayHattı'nın sms-activate uyumlu REST API'siyle numara alma, kod okuma ve iptal işlemlerini kendi yazılımınızdan programatik olarak yapabilirsiniz. Tek bir GET uç noktası (handler_api.php) üzerinden çalışır, mevcut sms-activate istemcileri yalnızca host değiştirerek uyum sağlar ve SMS gelmeyen siparişlerde ücret 15 dakika sonra otomatik iade edilir. Bu rehberde entegrasyonu sıfırdan kurup ilk onay akışını uçtan uca çalıştıracağız.

1. API Anahtarı Üretin

Panelinizdeki API sayfasından anahtar üretin (sms_... biçiminde). Tüm isteklerde anahtar api_key sorgu parametresiyle gönderilir. Anahtarı kod deponuza veya istemci tarafına koymayın; yalnızca sunucunuzda, ortam değişkeninde tutun.

2. Uç Nokta ve Genel Yapı

Tüm eylemler tek uç nokta üzerinden, action parametresiyle çağrılır:

GET https://onayhatti.com/api/stubs/handler_api.php?api_key=ANAHTAR&action=<eylem>

Yanıtlar sms-activate konvansiyonundadır: başarı durumunda önekli düz metin (ACCESS_NUMBER:..., STATUS_OK:...), hata durumunda büyük harfli hata kodu (NO_BALANCE gibi) döner. Tam eylem ve hata listesi API dokümantasyonunda yer alır; burada en kritik akışı kuracağız.

3. Bakiyeyi Sorgulayın (Sağlık Kontrolü)

Entegrasyonun çalıştığını doğrulamanın en hızlı yolu:

curl "https://onayhatti.com/api/stubs/handler_api.php?api_key=ANAHTAR&action=getBalance"
# ACCESS_BALANCE:12.50

ACCESS_BALANCE döndüyse anahtarınız geçerlidir. BAD_KEY alıyorsanız anahtarı ve sondaki/baştaki boşlukları kontrol edin.

4. Numara Alın

curl "https://onayhatti.com/api/stubs/handler_api.php?api_key=ANAHTAR&action=getNumber&service=wa&country=TR"
# ACCESS_NUMBER:ord_123:905551112233

• service: OnayHattı kodu (whatsapp) veya sms-activate kısa kodu (wa, tg, go, ig, lf) kabul edilir.
• country: iso2 (TR) veya sms-activate numerik id'si (62).
• Yanıtın ikinci parçası sipariş kimliğidir (ord_123) — sonraki tüm çağrılarda bunu kullanırsınız; üçüncü parça telefon numarasıdır.
• Ağ hatalarına karşı opsiyonel idempotencyKey parametresini kullanın: aynı anahtarla tekrarlanan istek çift numara tahsis etmez.

NO_NUMBERS dönerse bu servis/ülke için stok yok demektir; başka ülke deneyin veya kısa bekleyip tekrar sorgulayın.

5. Kodu Okuyun (Polling)

curl "https://onayhatti.com/api/stubs/handler_api.php?api_key=ANAHTAR&action=getStatus&id=ord_123"
# STATUS_WAIT_CODE   → SMS henüz gelmedi
# STATUS_OK:123456   → kod geldi

Kod STATUS_WAIT_CODE döndükçe birkaç saniyede bir tekrar sorgulayın. Önerilen döngü: 3–5 saniye aralık, maksimum 15 dakika — 15. dakikada SMS gelmediyse sistem siparişi zaten otomatik iptal edip ücreti iade eder. Polling aralığını daha sık tutmayın; 60 istek/dakika hız sınırına takılırsınız.

6. Siparişi Kapatın: setStatus

curl "https://onayhatti.com/api/stubs/handler_api.php?api_key=ANAHTAR&action=setStatus&id=ord_123&status=6"
# ACCESS_ACTIVATION

Kodu başarıyla kullandıysanız status=6 ile siparişi tamamlayın; kod işe yaramadıysa veya vazgeçtiyseniz status=8 ile iptal edip ücreti iade alın.

7. Uçtan Uca Örnek Akış

1. getBalance — anahtarı ve bakiyeyi doğrulayın.
2. getNumber&service=wa&country=TR — sipariş kimliği ve numarayı alın.
3. Numarayı hedef platformun kayıt ekranına girin.
4. getStatus döngüsü — STATUS_OK:<kod> gelene kadar 3–5 sn aralıkla sorgulayın.
5. Kodu platforma girin; onay başarılıysa setStatus status=6, değilse status=8.

8. Node.js ile Minimal İstemci Örneği

Aynı akışı kodda görmek isterseniz, bağımlılıksız (Node 18+, yerleşik fetch) bir örnek:

const BASE = "https://onayhatti.com/api/stubs/handler_api.php";
const KEY = process.env.ONAYHATTI_API_KEY;

async function api(params) {
  const q = new URLSearchParams({ api_key: KEY, ...params });
  const res = await fetch(`${BASE}?${q}`);
  return res.text();
}

const num = await api({ action: "getNumber", service: "wa", country: "TR" });
// "ACCESS_NUMBER:ord_123:9055..."
const [, orderId, phone] = num.split(":");

let code = null;
for (let i = 0; i < 180 && !code; i++) {           // en fazla 15 dk
  const st = await api({ action: "getStatus", id: orderId });
  if (st.startsWith("STATUS_OK:")) code = st.slice(10);
  else await new Promise((r) => setTimeout(r, 5000)); // 5 sn aralık
}

if (code) await api({ action: "setStatus", id: orderId, status: "6" });
else await api({ action: "setStatus", id: orderId, status: "8" });

Örnek kasıtlı olarak yalındır; üretimde HTTP hataları, NO_NUMBERS için ülke yedeği ve idempotencyKey desteği ekleyin.

9. Hata Yönetimi

10. Üretime Çıkarken Kontrol Listesi

• API anahtarını ortam değişkeninde tutun; depoya ve loglara yazmayın.
• getNumber çağrılarına mutlaka idempotencyKey ekleyin.
• Polling'i 3–5 saniye aralıkla sınırlayın; HTTP hatalarında üstel geri çekilme uygulayın.
• 15 dakikalık otomatik iade penceresini iş mantığınıza yansıtın: süre dolan siparişi yeniden denenebilir sayın.
• Açık sipariş bırakmayın; koddan sonra setStatus çağrısını unutmayın — 3 eşzamanlı sipariş limiti aksi halde dolabilir.
• Fiyat ve liste verileri için getPrices, getCountries, getServicesList eylemlerini kullanın; sabit kodlanmış fiyat tutmayın.

API'nin arkasındaki ürün akışını (iade garantisi, sağlayıcı seçimi, ülke stokları) kullanıcı gözünden anlamak isterseniz SMS onay nedir rehberimize ve panel üzerinden sunulan uzun süreli numara modeli için numara kiralama rehberimize göz atabilirsiniz.