REST API v1

smsonay.io
API Dokümantasyonu

Servis ve ülke seçeneklerini sorgulayın, numara satın alın, sipariş durumunu ve SMS kodunu takip edin.

İlk istek

API anahtarınızı ekleyerek hesap bilgilerinizi sorgulayın.

cURL

curl "https://smsonay.io/api/v1/user/profile" \
  -H "Authorization: Bearer YOUR_API_KEY"

Bearer kimlik doğrulamaHTTP 200 · JSON

Bağlantı ve kimlik doğrulama

Tüm uç noktalar API anahtarı gerektirir. POST isteklerinin gövdesini JSON biçiminde gönderin.

API anahtarı

API anahtarınızı profil sayfanızdan alın ve sunucu ortamında saklayın. Herkese açık depolara veya tarayıcıda çalışan uygulama koduna eklemeyin.

API anahtarımı aç

API adresi

Temel API adresi aşağıdadır. Referanstaki yollar /api/v1 önekini zaten içerir; tam URL oluştururken bu yolları site adresine ekleyin.

https://smsonay.io/api/v1

Örnek tam URL: https://smsonay.io/api/v1/user/profile

Kimlik doğrulama

API anahtarını Authorization başlığında, Bearer önekiyle gönderin. POST isteklerinde Content-Type: application/json kullanın.

Authorization: Bearer YOUR_API_KEY

Desteklenen URL parametreleri

Alternatif olarak ?key=YOUR_API_KEY veya ?api_key=YOUR_API_KEY kullanılabilir. URL parametresi varsa anahtar bu alandan okunur. Anahtarın URL kayıtlarında yer almaması için Authorization başlığı önerilir.

API referansı

7 uç nokta

İşlem seçerek parametrelerini, davranışını, istek örneklerini ve yanıt alanlarını inceleyin.

GET/api/v1/user/profile

Kullanıcı profili

API anahtarına bağlı hesabın e-posta adresini, bakiyesini ve para birimini getirir.

Başarılı yanıt: HTTP 200Kimlik doğrulama: Bearer

Parametreler

Bu istek için ek parametre gerekmez. Authorization başlığını göndermeniz yeterlidir.

İşlem davranışı

İlk isteğinizde API anahtarınızı doğrulamak ve hesap bakiyesini görmek için kullanabilirsiniz.

Ortak hata kodları

cURL

curl "https://smsonay.io/api/v1/user/profile" \
  -H "Authorization: Bearer YOUR_API_KEY"

Sipariş akışı ve durumlar

Numara satın alma ile SMS yanıtını alma ayrı işlemlerdir. Satın alma yanıtındaki sipariş kimliğini saklayın.

Servis ve ülke seçin
Servis listesi içindeki servis kodunu ve ülke kodunu alın.
Sipariş oluşturun
Numara satın alma isteğini gönderin. HTTP 201 yanıtındaki order.id ve order.phone alanlarını saklayın.
Durumu sorgulayın
Sipariş durumu isteğinde aynı kimliği kullanın. SMS için sms_code, işlem durumu için status alanını okuyun.

Sorgulama ve tekrar deneme

API zorunlu bir sorgulama aralığı belirlemez. Uygulamanız için birkaç saniye aralıkla sorgulama önerilir; bu bir API limiti değildir. COMPLETED, CANCELED, REFUNDED veya TIMEOUT döndüğünde düzenli sorgulamayı durdurun.

remaining_time: 0 tek başına siparişin iptal veya iade edildiğini göstermez. provider_sync_warning varsa yanıt kayıtlı veriyi içerir. Satın alma isteğinin yanıtı alınamazsa yeni sipariş oluşturmadan önce panelde Numaralarım sayfasından siparişlerinizi kontrol edin; API sipariş listeleme uç noktası sunmaz.

Durum	Anlamı ve kullanım
`PENDING`	Yeni oluşturulan siparişin başlangıç durumu. SMS kodu ve sonraki durum için sorgulayın.
`ACTIVE`	İptal talebi işlenebilen aktif sipariş durumu.
`RECEIVED`	İptal talebi için kabul edilen kayıtlı durumlardan biri. İptal sonucu ayrıca sağlayıcıya bağlıdır.
`COMPLETED`	SMS kodu elde edildiğinde veya sağlayıcı işlemi bitirdiğinde döner. Kod için sms_code alanını kontrol edin.
`CANCELED`	Sipariş iptal edilmiş. Yeni SMS sorgulamasını durdurun; bu değer tek başına REFUNDED anlamına gelmez.
`TIMEOUT`	Sağlayıcı siparişin süresinin dolduğunu bildirmiş. Yeni SMS sorgulamasını durdurun.
`REFUNDED`	Sipariş iade durumunda. Yeni SMS sorgulamasını durdurun.

İptal talebi PENDING, ACTIVE ve RECEIVED durumlarında işlenir; başarı sağlayıcı sonucuna bağlıdır. İade ile sonuçlanan iptal yanıtı REFUNDED döner. Sağlayıcıdan gelen diğer durum değerleri de kayda yansıyabileceği için istemcinizde tanınmayan değerleri güvenli biçimde ele alın.

Yanıt yapısı

API’nin başarılı ve hatalı işlem yanıtları JSON biçimindedir. HTTP durumunu ve success alanını birlikte kontrol edin.

success boolean: Başarılı işlemde true, hata yanıtında false.
data object: Başarılı yanıttaki işlem verisi. Alanlar seçilen uç noktaya göre değişir.
error object: Hata yanıtındaki code ve message alanları. Bazı hatalarda details de bulunur.
requestId string: İsteğin takip kimliği. Yanıtın x-request-id başlığında da bulunur. İstekte x-request-id gönderirseniz aynı değer kullanılır; göndermediğinizde API üretir.
timestamp string: Yanıt oluşturulma zamanı, ISO 8601 biçiminde.

JSON

{
  "success": true,
  "requestId": "c4f7d7f0-71f8-4e0d-9f71-87f26a3b3b21",
  "timestamp": "2026-10-01T10:00:00.000Z",
  "data": {
    "user": {
      "email": "user@example.com",
      "balance": 150.5,
      "currency": "TRY"
    }
  }
}

Temsili yanıt. Bakiye, servis fiyatları, order.price ve refund_amount dahil tüm tutarlar TRY cinsinden sayı olarak döner.

HTTP durumları ve hata kodları

İstemci davranışını error.code alanına göre belirleyin. İngilizce message alanı açıklama içindir; metne göre koşul kurmayın.

HTTP	Hata kodu	Açıklama	Yapılacak işlem
401	`UNAUTHORIZED`	API anahtarı eksik veya geçersiz.	API anahtarını ve Authorization başlığını kontrol edin.
400	`INVALID_JSON`	İstek gövdesi JSON olarak okunamadı.	Geçerli JSON gövdesi gönderin.
400	`VALIDATION_ERROR`	Zorunlu alanlar eksik veya beklenen türde değil.	Alanları düzeltin; varsa error.details içeriğini inceleyin.
400	`INSUFFICIENT_BALANCE`	Satın alma için hesap bakiyesi yetersiz.	Bakiyeyi kontrol edin. İşlem anında hesaplanan fiyat daha yüksek olabilir.
404	`NOT_FOUND`	Servis, ülke seçeneği veya hesabınıza ait sipariş bulunamadı.	Servis/ülke kodlarını ve sipariş kimliğini kontrol edin.
400 / 409	`BAD_REQUEST`	Sipariş iptale uygun değil (400) veya sağlayıcıda iptal edilemedi (409).	Sipariş durumunu ve varsa error.details.providerStatus alanını inceleyin.
429	`RATE_LIMITED`	API anahtarı limiti aşıldı veya anahtar geçici olarak kısıtlandı.	Retry-After başlığında belirtilen saniye boyunca bekleyin.
503	`TEMPORARILY_BLOCKED`	IP veya ortak satın alma limiti aşıldı ya da IP geçici olarak kısıtlandı.	Retry-After başlığında belirtilen saniye boyunca bekleyin.
503	`SERVICE_UNAVAILABLE`	API erişimi geçici olarak kapalı.	İstekleri duraklatın; sorun sürerse destek ekibine ulaşın.
500	`INTERNAL_ERROR`	İşlem sırasında sunucu hatası oluştu.	requestId ile destek alın. Satın alma isteğini kontrol etmeden tekrarlamayın.
500	`PROVIDER_ERROR`	İptal işlemi tamamlanamadı.	Sipariş durumunu kontrol edin; gerekirse requestId ile destek alın.

Tüm uç noktalarda kimlik doğrulama, erişim kapatma ve limit hataları oluşabilir. Uç nokta ayrıntılarında bunlara ek işlem hataları listelenir. HTTP 503 için error.code alanını kontrol edin: erişim kapalı olması ile limit aşımı farklı durumlardır. Destek talebinize requestId değerini ekleyin.

Kullanım limitleri

Limitler birlikte uygulanır. Sınır aşıldığında Retry-After yanıt başlığındaki saniye kadar bekleyin.

Kapsam	İstek sınırı	Limit yanıtı
Aynı IP adresinden gelen istekler	100 istek / saniye	503 · TEMPORARILY_BLOCKED
Aynı API anahtarına ait istekler	100 istek / saniye	429 · RATE_LIMITED
Numara satın alma için ortak sayaç	100 istek / saniye	503 · TEMPORARILY_BLOCKED

Aynı IP veya API anahtarı için 10 dakika içinde 5 limit ihlali kaydedilirse ilgili erişim 10 dakika kısıtlanır. Ortak satın alma limitindeki ihlaller de isteğin IP ve API anahtarı sayaçlarına işlenir.

Limit yanıt başlıkları

Retry-After beklenmesi gereken saniyeyi belirtir. İlk limit aşımı yanıtında ilgili kapsama ait x-ratelimit-limit-ip/key/buy, x-ratelimit-remaining-ip/key/buy ve x-ratelimit-reset-ip/key/buy başlıkları bulunabilir. Buradaki ip/key/buy yerine ilgili kapsam yazılır; reset Unix zamanını saniye olarak verir. Geçici kısıtlama yanıtlarında bu ek başlıkların bulunacağını varsaymayın.

smsonay.ioAPI Dokümantasyonu