Numara Kiralama API

Numara Kiralama API

Eski API uyumlu handler_api.php ucu üzerinden bir numarayı belirli bir süre kiralayın ve gelen tüm SMS mesajlarını okuyun.

Kiralama aksiyonları tüm API anahtarlarına açıktır; anahtar başına günlük sınır vardır (bkz. Sınırlar).

Nasıl çalışır

Her istek api_key ve action ile /stubs/handler_api.php adresine yapılan bir GET isteğidir. Kiralama aksiyonları hem başarıda hem hatada JSON döner.

Kiralama aksiyonlarında yalnız API anahtarı ile kimlik doğrulama kabul edilir. Web oturum token'ı WRONG_ACTION alır.

Fiyatlar web paneldekiyle aynıdır ve cüzdanınızdan USD olarak tahsil edilir.

Aksiyonlar

AksiyonParametrelerNe yapar
getRentServicesAndCountriescountry, rent_timeBir ülke ve süre için fiyatlı kiralama teklifleri. services.{code}.cost fiyat, quant mevcut stoktur.
getRentNumberservice, country, rent_timeNumara kiralar ve cüzdandan tahsil eder. phone.id, phone.number ve phone.endDate döner.
getRentStatusid, page, sizeKiralanan numaraya gelen SMS mesajları, en yeni önce. İsteğe bağlı page (0'dan başlar) ve size.
setRentStatusid, status (1 | 2)status=1 kiralamayı iadesiz erken bitirir. status=2 iptal eder; tam iade yalnız hiç SMS gelmediyse yapılır.
continueRentNumberid, rent_time, expectedChargeAktif kiralamayı rent_time saat uzatır ve cüzdandan tahsil eder.
getRentList-Aktif kiralamalarınız: id ve phone.
getContinueRentPriceNumberid, rent_timeUzatma fiyatı, tahsilat yapılmadan.

Ülke kodları

  • Kiralama 27 ülkede açık: AT, BE, BR, CZ, DE, EE, ES, FI, FR, GB, GE, GR, HR, ID, IT, LV, MD, MY, NL, PL, PT, RO, SE, SI, SK, UA, US. Numara kiralamak ve fiyat okumak için country zorunludur, iki harfli ISO kodu önerilir. Süreler: 24, 72, 168 saat.
  • Bu listeyi API'den okumak için getRentServicesAndCountries aksiyonunu country göndermeden çağırın: yanıtta countryList (ISO kodları), hours ve currency döner; fiyat ve stok dönmez. Fiyat ve stok için country ve rent_time gönderin.
  • Önerilen: ISO ülke kodunu gönderin, örneğin country=US ya da country=GB. Büyük ve küçük harf ikisi de çalışır.
  • Sayısal ülke kodları her serviste aynı değildir. Sayı gönderecekseniz kodu kendi API anahtarınızla getCountries yanıtından okuyun; başka bir sağlayıcının listesinden kopyalamayın.
  • Kiralama aksiyonları sayısal kodu yalnız kiralamaya açık ülkeler için, getCountries listesindeki haliyle kabul eder. Başka bir sayı BAD_COUNTRY döner; emin değilseniz ISO kodunu kullanın.
  • 42 (DE), 44 (HR), 45 (SE), 47 (NL), 48 (LV), 49 (AT), 51 (TH), 55 (ES), 58 (SI), 62 (CZ), 72 (BR), 77 (FR), 90 (SK), 97 (PT), 115 (GE), 116 (GR), 128 (BE), 175 (FI), 178 (IT) sayıları kiralamada kabul edilmez, çünkü başka servislerde farklı bir ülkeyi gösterir. Bu sayılar her zaman BAD_COUNTRY_USE_ISO döner; ücret alınmaz, numara kiralanmaz. Bunun yerine ISO kodunu gönderin, örneğin country=DE. Bu ülkelerde getRentServicesAndCountries yanıtındaki countries alanı boştur.
  • Ülke slug'ımız da kabul edilir.
  • getRentServicesAndCountries, ülkenin sayısal kodunu countries alanında döner.

Ülkeleri ve kodlarını listeleme

curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getCountries"

ISO koduyla bir ülkenin kiralama teklifleri

curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentServicesAndCountries&country=US&rent_time=24"

Kiralamaya açık ülkeleri listeleme

curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentServicesAndCountries"

Yanıt

{"countryList":["AT","BE","BR","CZ","DE","EE","ES","FI","FR","GB","GE","GR","HR","ID","IT","LV","MD","MY","NL","PL","PT","RO","SE","SI","SK","UA","US"],"hours":[24,72,168],"currency":840}

Örnek

İstek

curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentNumber&service=wa&country=US&rent_time=24"

Yanıt

{
  "status": "success",
  "phone": {
    "id": "cm4x9k2...",
    "endDate": "2026-11-02T12:00:00",
    "number": "15550000001"
  }
}

İstek

curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentStatus&id=cm4x9k2..."

Yanıt

{
  "status": "success",
  "quantity": "1",
  "values": {
    "0": {
      "phoneFrom": "WhatsApp",
      "text": "Your code: 123456",
      "service": "wa",
      "date": "2026-11-01 12:05:00"
    }
  }
}

Yanıt ayrıntıları

  • Kiralama id'si sayı değil, dizgedir (örnek "cm4x9k2..."). Metin olarak saklayın.
  • Saat cinsinden süre rent_time parametresinden okunur; time parametresi de kabul edilir.
  • Süre gönderilmezse mevcut en kısa süre kullanılır (şu an 24 saat). Kiralarken ve uzatırken rent_time değerini açıkça gönderin.
  • currency 840 (USD) değerindedir. cost ve price USD cinsinden sayıdır.
  • endDate ve SMS tarihleri UTC'dir, saat dilimi eki yoktur.
  • url parametresi yok sayılır: kiralamalar webhook göndermez. Yeni SMS için getRentStatus ile sorgulayın.
  • Hatalar {"status":"error","message":"<CODE>"} biçiminde döner. Kimlik doğrulama ve hız sınırı hataları düz metin biçimini korur (BAD_KEY, RATE_LIMITED).
  • continueRentNumber'dan önce getContinueRentPriceNumber ile teklif alın. Tahsil edilen tutar, size son gösterilen teklifi (10 dakika geçerli, aynı kiralama ve rent_time) asla aşmaz. İsteğe bağlı expectedCharge (USD, örneğin 1.334) bu tavanı yalnız düşürür, yükseltmez. Fiyat tavanı aşarsa ya da geçerli teklifiniz yoksa uzatma yapılmaz, ücret alınmaz ve yeni teklif döner: WRONG_CHARGE, tutar price alanında. Yeni teklifle tekrar deneyin.
  • Kiralama ancak ücretsiz iptal penceresi (ilk 20 dakika) bittikten sonra uzatılabilir; daha önce continueRentNumber CONTINUE_TOO_EARLY döner ve ücret alınmaz.

İptal penceresi

Kiralamanın ilk 2 dakikasında iptal reddedilir (CANT_CANCEL).

Ücretsiz iptal, kiralama başladıktan sonra en fazla 20 dakika içinde yapılabilir. Bu pencereden sonra iptal reddedilir, genellikle CANT_CANCEL ile (nadiren TEMPORARILY_UNAVAILABLE); bunun yerine status=1 ile bitirin.

İptal edilen kiralama yalnız hiç SMS almadıysa tam iade edilir.

Zaman aşımı ve yeniden deneme

getRentNumber tekrarlanabilir (idempotent) değildir: zaman aşımından sonra yeniden göndermeyin. Önce getRentList çağırın; gereksiz bir kiralama bulursanız 2. ile 20. dakika arasında iptal ederek tam iade alın (SMS gelmemişse).

Sınırlar

Yeni kiralamalar API anahtarı başına UTC günü başına sınırlıdır (uzatmalar sayılmaz): anahtar başına en fazla 50 kiralama. Üstünde: RENT_LIMIT.

getRentNumber ve continueRentNumber, anahtarın günlük API satın alma kotasına da sayılır.

Bu aksiyonları hesabınızdaki tüm API anahtarları kullanabilir.

Hata kodları

{ "status": "error", "message": "NO_BALANCE" }
NO_BALANCECüzdan bakiyesi yetersiz.
NO_NUMBERSBu servis, ülke ve süre için şu an uygun numara yok.
BAD_SERVICEServis kodu eksik ya da desteklenmiyor.
BAD_COUNTRYÜlke eksik, bilinmiyor ya da uygun değil (ISO kodu kullanın).
BAD_COUNTRY_USE_ISOSayısal ülke kodu kiralamada kabul edilmez (başka servislerde farklı bir ülkeyi gösterir). ISO kodunu kullanın; ücret alınmaz. Bu sayılar Ülke kodları bölümünde listelenir. Yanıtta okunabilir bir description alanı da vardır.
BAD_TIMEBu süre sunulmuyor.
NO_ID_RENTid parametresi eksik.
INVALID_PHONEHesabınızda bu id ile kiralama yok.
INCORECT_STATUSsetRentStatus status değeri 1 ya da 2 olmalı.
CANT_CANCELŞu an iptal edilemez (ilk 2 dakika içinde ya da en fazla 20 dakikalık ücretsiz pencere geçtikten sonra).
ALREADY_FINISHKiralama zaten bitti.
ALREADY_CANCELKiralama zaten iptal edildi.
STATUS_WAIT_CODEKiralama aktif ama henüz SMS gelmedi.
STATUS_CANCELKiralama iptal edildi.
STATUS_FINISHKiralama bitti ya da süresi doldu.
RENT_LIMITBu API anahtarının günlük kiralama sınırına ulaşıldı.
TEMPORARILY_UNAVAILABLEGeçici sorun. getRentNumber ve continueRentNumber için tahsilat yapılmadı ya da iade edildi. İptalde sonuç belirsiz olabilir: yeniden denemeden önce kiralamayı getRentStatus ile kontrol edin.
WRONG_CHARGEcontinueRentNumber: fiyat tavanınızın (size son gösterilen teklif, 10 dakika geçerli, expectedCharge ile düşürülmüş) üstünde ya da geçerli teklifiniz yok. Uzatma yapılmadı, ücret alınmadı. Yeni teklif price alanında; onunla tekrar deneyin.
CONTINUE_TOO_EARLYcontinueRentNumber: kiralamanın ilk 20 dakikasında (ücretsiz iptal penceresi) uzatma yapılamaz. Ücret alınmadı; pencere bitince tekrar deneyin. getContinueRentPriceNumber bu sürede de çalışır.
ERROR_SQLBeklenmeyen sunucu hatası.

REST API

Aynı işlemler tüm API anahtarları için /api/v1/rentals altında JSON uçları olarak da sunulur (anahtarı x-api-key başlığında gönderin). Anahtar başına günlük kiralama sınırı yukarıdaki aksiyonlarla ortaktır; sınır aşılınca REST API 429 ve rent_daily_cap nedeniyle yanıt verir.

curl -X POST "https://smsbulk.net/api/v1/rentals" \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "serviceCode": "wa", "countryIso": "US", "durationHours": 24 }'

Uzatma: önce GET /api/v1/rentals/{id}/extend-price ile teklif alın, sonra POST /api/v1/rentals/{id}/extend çağırın. Tahsil edilen tutar, size son gösterilen teklifi (10 dakika geçerli, aynı kiralama ve süre) asla aşmaz. İsteğe bağlı expectedCharge (metin olarak USD, örneğin "1.334") bu tavanı yalnız düşürür, yükseltmez. Fiyat tavanı aşarsa ya da geçerli teklifiniz yoksa uzatma yapılmaz, ücret alınmaz ve API 409 PRICE_CHANGED ile yanıt verir; yeni teklif currentCharge alanındadır. Yeni teklifle tekrar deneyin.

Kiralamanın ilk 20 dakikasında (ücretsiz iptal penceresi) POST /api/v1/rentals/{id}/extend 409 RENTAL_EXTEND_TOO_EARLY ile yanıt verir; gövdedeki extendAllowedFrom (ISO zaman) uzatmanın kabul edileceği anı gösterir. Ücret alınmaz, teklif sorgusu açık kalır.