SMS Onay API Nedir? Entegrasyon Rehberi

SMS onay API'si, numara alma ve doğrulama kodunu okuma adımlarını panel yerine kendi yazılımınızdan yapmanızı sağlayan programlama arayüzüdür. Test otomasyonu, çok sayıda uygulamanın SMS akışını deneyen ekipler veya bu adımları kendi sistemine eklemek isteyen geliştiriciler için tasarlanmıştır.

Bir entegrasyon hangi adımlardan oluşur?

Onay360 API'si ile bir doğrulama döngüsünde şu beş uç nokta kullanılır:

Bakiye kontrolü: GET /api/v1/user/profile ile bakiyenizi kontrol edersiniz.
Servis ve fiyat listesi: GET /api/v1/services ile servisleri, desteklenen ülkeleri ve anlık fiyatları alırsınız. Fiyatlar değişebildiği için bu listeyi her siparişten önce güncellemeniz önerilir.
Numara alma: POST /api/v1/user/buy isteğine servis ve ülke kodunu gönderirsiniz. Yanıtta sipariş kimliği, telefon numarası ve kalan süre (expires_in, saniye) döner; tutar bakiyenizden düşülür.
Kodu okuma: GET /api/v1/user/orders/{id} ile siparişin durumunu sorgularsınız. Kod geldiğinde sms_code alanı dolar.
İptal: Kod gelmeyen bir siparişi POST /api/v1/user/cancel ile iptal edebilir ve ücretin iadesini alabilirsiniz. SMS kodu gelmiş siparişler iptal edilemez.

Tüm istekler JSON yanıt döner. Her yanıtta isteğin başarılı olup olmadığını belirten success alanı ve takip için bir requestId bulunur.

Kimlik doğrulama

API anahtarınızı her istekte Authorization: Bearer API_ANAHTARINIZ başlığıyla gönderirsiniz. Anahtar URL parametresi olarak da gönderilebilir, ancak bu yöntem anahtarın sunucu kayıtlarında ve tarayıcı geçmişinde görünmesine yol açabileceği için başlık yöntemini kullanmanızı öneririz.

Örnek akış

Aşağıdaki Node.js örneği bir numara alır, kodu 5 saniyede bir sorgular ve süre dolarsa siparişi iptal eder:

const API = 'https://onay360.com/api/v1';
const headers = {
  Authorization: `Bearer ${process.env.ONAY360_API_KEY}`,
  'Content-Type': 'application/json',
};

async function call(path, options = {}) {
  const res = await fetch(`${API}${path}`, { headers, ...options });
  const json = await res.json();
  if (!json.success) throw new Error(json.error?.message || 'API hatası');
  return json.data;
}

async function getCode(service, country) {
  const { order } = await call('/user/buy', {
    method: 'POST',
    body: JSON.stringify({ service, country }),
  });

  const deadline = Date.now() + order.expires_in * 1000;
  while (Date.now() < deadline) {
    await new Promise((r) => setTimeout(r, 5000));
    const { order: current } = await call(`/user/orders/${order.id}`);
    if (current.sms_code) return { phone: order.phone, code: current.sms_code };
  }

  await call('/user/cancel', { method: 'POST', body: JSON.stringify({ id: order.id }) });
  return null;
}

Servis ve ülke kodlarını sabit yazmak yerine /services yanıtından alın. Bir ülkede kod gelmezse aynı servis için başka bir ülkeyle yeni sipariş oluşturmak, aynı numarada beklemekten daha verimlidir.

Kullanım limitleri

Her IP adresi ve her API anahtarı için saniyede en fazla 100 istek kabul edilir.
10 dakika içinde 5 kez limit aşılırsa erişim 10 dakika süreyle kısıtlanır.

Sipariş durumunu saniyede birkaç kez sorgulamak kodun daha hızlı gelmesini sağlamaz. Birkaç saniyelik aralıklarla sorgulamak hem limitlere takılmanızı önler hem de yeterince hızlı sonuç verir.

API anahtarınızı nasıl korumalısınız?

API anahtarı, bakiyenizi harcayabilen bir erişim bilgisidir. Anahtarı yalnızca sunucu tarafında kullanın; web sayfasına, mobil uygulamaya veya herkese açık kod depolarına eklemeyin. Anahtarı kodun içine yazmak yerine ortam değişkeninde saklayın ve sızdığından şüphelendiğinizde yenileyin. OWASP'ın gizli bilgi yönetimi rehberi (İngilizce) bu konuda ayrıntılı öneriler sunar.

Nereden başlamalı?

Endpoint'lerin tamamını, parametreleri ve örnek yanıtları API dokümantasyonunda bulabilirsiniz. API anahtarınızı panelden oluşturduktan sonra ilk denemeyi düşük maliyetli bir servis ve başarı oranı yüksek bir ülkeyle yapmanızı öneririz. Aynı işlemleri kod yazmadan yapmak isterseniz SMS onay panelini doğrudan kullanabilirsiniz; kullanıcı tarafındaki akışı adım adım anlattığımız yazıda bulabilirsiniz.

SMS Onay API Nedir? Entegrasyon Akışı ve Güvenlik