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.
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
| Aksiyon | Parametreler | Ne yapar |
|---|---|---|
getRentServicesAndCountries | country, rent_time | Bir ülke ve süre için fiyatlı kiralama teklifleri. services.{code}.cost fiyat, quant mevcut stoktur. |
getRentNumber | service, country, rent_time | Numara kiralar ve cüzdandan tahsil eder. phone.id, phone.number ve phone.endDate döner. |
getRentStatus | id, page, size | Kiralanan numaraya gelen SMS mesajları, en yeni önce. İsteğe bağlı page (0'dan başlar) ve size. |
setRentStatus | id, status (1 | 2) | status=1 kiralamayı iadesiz erken bitirir. status=2 iptal eder; tam iade yalnız hiç SMS gelmediyse yapılır. |
continueRentNumber | id, rent_time, expectedCharge | Aktif kiralamayı rent_time saat uzatır ve cüzdandan tahsil eder. |
getRentList | - | Aktif kiralamalarınız: id ve phone. |
getContinueRentPriceNumber | id, rent_time | Uzatma 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_ | Cüzdan bakiyesi yetersiz. |
NO_ | Bu servis, ülke ve süre için şu an uygun numara yok. |
BAD_ | Servis kodu eksik ya da desteklenmiyor. |
BAD_ | Ülke eksik, bilinmiyor ya da uygun değil (ISO kodu kullanın). |
BAD_ | Sayı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_ | Bu süre sunulmuyor. |
NO_ | id parametresi eksik. |
INVALID_ | Hesabınızda bu id ile kiralama yok. |
INCORECT_ | setRentStatus status değeri 1 ya da 2 olmalı. |
CANT_ | Şu an iptal edilemez (ilk 2 dakika içinde ya da en fazla 20 dakikalık ücretsiz pencere geçtikten sonra). |
ALREADY_ | Kiralama zaten bitti. |
ALREADY_ | Kiralama zaten iptal edildi. |
STATUS_ | Kiralama aktif ama henüz SMS gelmedi. |
STATUS_ | Kiralama iptal edildi. |
STATUS_ | Kiralama bitti ya da süresi doldu. |
RENT_ | Bu API anahtarının günlük kiralama sınırına ulaşıldı. |
TEMPORARILY_ | Geç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_ | continueRentNumber: 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_ | continueRentNumber: 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_ | Beklenmeyen 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.