REST API — handler_api Uyumlu

SMS Onay API Dokümantasyonu

Turonay altyapısını kendi yazılımınıza, botunuza veya panelinize bağlayın. Tek bir API anahtarı ile numara alabilir, gelen SMS kodunu okuyabilir ve işlemi iptal edebilirsiniz. API handler_api protokolüyle uyumludur: bu protokol için yazılmış bir entegrasyonunuz varsa çoğu durumda yalnızca taban adresi ve anahtarı değiştirmeniz yeterlidir. Kodu yoklamak yerine webhook ile imzalı bildirim de alabilirsiniz.

API Anahtarı Al Servis ve Fiyatlar

Uç nokta — öğrenmesi 5 dakika

GET

Tek metot, düz metin + JSON yanıt

İade

Kod gelmezse ücret alınmaz

Hızlı Başlangıç

Üç adımda ilk numaranızı alabilirsiniz. Önce panele girip API anahtarınızı oluşturun, sonra aşağıdaki isteği çalıştırın.

# 1) Bakiyeni kontrol et curl "https://turonay.com/api/?api_key=YOUR_KEY&action=getBalance" # → ACCESS_BALANCE:125.4000 # 2) Numara al (servis kodu + ülke kimliği) curl "https://turonay.com/api/?api_key=YOUR_KEY&action=getNumber&service=wa&country=62" # → ACCESS_NUMBER:184213:628123456789 # 3) Kodu bekle (birkaç saniyede bir sor) curl "https://turonay.com/api/?api_key=YOUR_KEY&action=getStatus&id=184213" # → STATUS_WAIT_CODE … sonra → STATUS_OK:123456

Klasik uçlar düz metin döner (iki nokta ile ayrılan alanlar, handler_api biçimi); V2 ve keşif uçları JSON döner. Kod için sürekli sorgu yapmak yerine webhook kullanabilirsiniz.

Taban Adres ve Kimlik Doğrulama

Tüm istekler aşağıdaki iki eşdeğer adresten birine GET ile gider; ikisi de aynı yanıtı verir:

https://turonay.com/api/ https://turonay.com/stubs/handler_api.php

handler_api protokolünü kullanan başka bir sağlayıcıdan geliyorsanız çoğu entegrasyonda taban adresi ve API anahtarını değiştirmek yeterlidir: /stubs/handler_api.php yolu bu protokolün yaygın handler_api.php yolunu izler; parametre ve yanıt biçimleri aynı protokole dayanır, bilinen birkaç fark vardır.

Kimlik doğrulama api_key sorgu parametresiyle yapılır. Başlık (header) kullanılmaz. Anahtarın URL'de ve sunucu günlüklerinde görünmesini istemezseniz parametreleri POST ile form alanı (application/x-www-form-urlencoded) olarak da gönderebilirsiniz. Anahtarınızı panelden istediğiniz zaman yenileyebilirsiniz; yenilediğiniz anda eski anahtar geçersiz olur.

Anahtarınızı istemci tarafında kullanmayın. Tarayıcıda çalışan koda gömülen bir anahtarla bakiyeniz harcanabilir; çağrıları kendi sunucunuzdan yapın.

İstek Sınırı

API hem anahtar hem IP bazında dakikalık sınıra tabidir. Sınırı aşan istekler HTTP 429 ve gövdede NO_CONNECTION döner.

Kod bekleme döngüsünde saniyede bir sorgu atmayın. Önerilen aralık 3–5 saniyedir; 429 aldığınızda bekleme süresini katlayarak (örn. 5s, 10s, 20s) tekrar deneyin.

Varsayılan sınır, anahtar ve IP başına dakikada 60 istektir. Bu sınırın altında kalmak için sık yoklama yerine webhook kullanın.

Ücretlendirme

Yalnızca SMS kodu size ulaştığında ücretlendirilirsiniz. Numara aldığınız anda fiyat bakiyenizde bloke edilir (getBalance kullanılabilir bakiyeyi düşük gösterir); ücret yalnızca kod teslim edildiğinde kesinleşir. Kod gelmeden iptal ederseniz ya da süre dolarsa hiçbir ücret alınmaz.

Numara alırken bakiyenizin fiyatı karşılaması gerekir; aksi hâlde NO_BALANCE döner. Kod geldikten sonra iptal (setStatus&status=8) edilemez: EARLY_CANCEL_DENIED döner ve ücret iade edilmez, çünkü hizmet teslim edilmiştir. Sağlayıcı numarayı iptal ederse ya da kod gelmeden süre dolarsa rezerve tutar bakiyenize geri bırakılır.

Uç Noktalar

action	Parametreler	Başarılı yanıt	Açıklama
`getPrices`	`service`, `country` (isteğe bağlı)	`{"62":{"wa":{"cost":12.50,"count":744716}}}`	Satılabilir servis/ülke için ödeyeceğiniz fiyat ve stok. `cost` bakiyenizden düşecek tutardır; kademe indiriminiz uygulanmış hâlde döner. Verilen fiyat kısa süre kilitlenir: aradaki sunucu değişse bile gördüğünüz tutar tahsil edilir.
`getCountries`	—	`{"62":{"id":62,"eng":"Turkey"}}`	Numara alabileceğiniz ülkeler. Yalnızca gerçekten stok bulunan ülkeler listelenir.
`getNumbersStatus`	`country`	`{"wa_0":"744716"}`	Bir ülkedeki servis başına stok. Anahtar biçimi `servis_0`.
`getBalance`	—	`ACCESS_BALANCE:<tutar>`	Kullanılabilir bakiyenizi döner.
`getOperators`	`country` (isteğe bağlı)	`{"status":"success","countryOperators":{"62":["any"]}}`	Ülke başına seçilebilir operatörler. `getNumber` / `getNumberV2` çağrısındaki `operator` parametresine bu değerlerden biri verilir.
`getNumber`	`service`, `country`, `operator` (isteğe bağlı), `maxPrice` (isteğe bağlı)	`ACCESS_NUMBER:<id>:<telefon>`	Numara tahsis eder. Dönen `id`, sonraki çağrılarda kullanılır. `maxPrice` verirseniz fiyat bu tutarı aşıyorsa numara alınmaz.
`getNumberV2`	`service`, `country`, `operator` (isteğe bağlı), `maxPrice` (isteğe bağlı)	`{"activationId":"184213","phoneNumber":"628123456789",…}`	`getNumber` ile aynı, ancak yanıt JSON'dur ve fiyat, süre ve operatör bilgisini de içerir.
`getStatus`	`id`	`STATUS_WAIT_CODE` / `STATUS_WAIT_RETRY:<kod>` / `STATUS_OK:<kod>` / `STATUS_CANCEL`	SMS kodunun gelip gelmediğini sorar. Ücret, kod geldiği anda kesinleşir.
`getStatusV2`	`id`	`{"sms":{"code":"123456",…}}`	`getStatus`'un JSON karşılığı. Kod geldiğinde `sms` nesnesiyle JSON döner; kod yokken JSON değil, düz metin durum (`STATUS_WAIT_CODE` vb.) döner.
`getActiveActivations`	—	`{"status":"success","activeActivations":[…]}`	Hesabınızdaki açık (süresi dolmamış / kapatılmamış) aktivasyonların listesi. Bağlantınız koptuysa kaldığınız yerden devam etmek için kullanın.
`setStatus`	`id`, `status` (1 / 3 / 6 / 8)	`ACCESS_READY` / `ACCESS_RETRY_GET` / `ACCESS_ACTIVATION` / `ACCESS_CANCEL`	`1` hazır, `3` yeni SMS iste (ücretsiz), `6` tamamla (yalnızca kod geldikten sonra), `8` iptal (kod geldiyse reddedilir).

getNumber — Numara Alma

service servis kısa kodu (örn. WhatsApp için wa), country ise ülke kimliğidir. Güncel kod ve kimlikleri fiyatlar sayfasından görebilirsiniz.

İsteğe bağlı: operator belirli bir operatör ister (getOperators); maxPrice ödemeyi kabul ettiğiniz en yüksek fiyattır, güncel fiyat bunu aşarsa numara alınmaz.

GET ?action=getNumber&service=wa&country=62&maxPrice=15 ACCESS_NUMBER:184213:628123456789 │ └─ telefon └─ sipariş id NO_NUMBERS → şu an stok yok NO_BALANCE → bakiye yetersiz BAD_SERVICE → servis kodu bilinmiyor / satışa kapalı WRONG_MAX_PRICE:18.40 → maxPrice geçersiz ya da güncel fiyatı karşılamıyor; satın alma yapılmaz BAD_KEY → API anahtarı geçersiz

Numara alırken fiyat bakiyenizde rezerve edilir (getBalance kullanılabilir bakiyeyi düşük gösterir); ücret yalnızca SMS kodu geldiğinde kesinleşir. Kod gelmeden iptal edilirse ya da süre dolarsa rezerve tutar serbest kalır. Bakiyenin fiyatı karşılaması gerekir.

getStatus — Kodu Okuma

id değeri getNumber çağrısından döner.

GET ?action=getStatus&id=184213 STATUS_WAIT_CODE → kod henüz gelmedi STATUS_OK:123456 → kod geldi STATUS_WAIT_RETRY:123456 → ek SMS istediniz (setStatus&status=3) ve önceki kod hâlâ gösteriliyor; yeni kod gelince STATUS_OK'a döner STATUS_CANCEL → iptal / süre doldu

Kod geldiğinde yoklama yapmadan bildirim almak için Webhooks kullanın (genellikle 1–2 dakika içinde ulaşır). Kodu aldıktan sonra setStatus&status=6 göndererek işlemi kapatmanız önerilir.

getNumberV2 — JSON ile Numara Alma

getNumber ile aynı parametreleri alır; başarıda JSON döner. Hata durumunda klasik düz metin kodları (NO_NUMBERS, NO_BALANCE, WRONG_MAX_PRICE:<fiyat> ...) gelir.

GET ?action=getNumberV2&service=wa&country=62 { "activationId": "184213", "phoneNumber": "628123456789", "activationCost": "12.50", "currency": 949, "countryCode": "62", "canGetAnotherSms": true, "activationTime": "2026-10-07 12:00:00", "activationEndTime": "2026-10-07 12:20:00", "activationOperator": "any" }

field	Açıklama
`activationId`	Aktivasyon kimliği; `getStatus` / `setStatus` çağrılarında `id` olarak kullanılır.
`phoneNumber`	Telefon numarası (ülke kodu dahil, + işareti yok).
`activationCost`	Fiyat (metin olarak, örn. "12.50"); kod gelirse kesinleşen tutar.
`currency`	Para birimi: ISO-4217 sayısal kodu (tam sayı; örn. `949` = TRY).
`countryCode`	Ülke kimliği.
`canGetAnotherSms`	Aynı numaradan ek SMS istenebilir mi (`setStatus&status=3`).
`activationTime`	Aktivasyonun başladığı zaman (sunucu saati, Europe/Istanbul, UTC+3; `Y-m-d H:i:s` biçimi, saat dilimi yok).
`activationEndTime`	Numaranın geçerlilik süresinin bittiği zaman; kod gelmezse bundan sonra iptal olur. `activationTime` ile aynı biçim ve saat dilimi.
`activationOperator`	Kullanılan operatör (`any` = fark etmez).

getStatusV2 — JSON ile Durum

id değeri getNumber çağrısından döner. Kod geldiğinde JSON döner: sms nesnesi dateTime (ISO-8601), code ve text içerir; call şu an her zaman nulldır. Kod henüz yoksa JSON değil, düz metin durum döner (STATUS_WAIT_CODE, STATUS_WAIT_RETRY:..., STATUS_CANCEL).

GET ?action=getStatusV2&id=184213 // kod geldiğinde: JSON { "verificationType": 0, "sms": { "dateTime": "2026-10-07T12:00:41+03:00", "code": "123456", "text": "Your code: 123456" }, "call": null } // kod yokken: JSON değil, düz metin durum STATUS_WAIT_CODE

getActiveActivations — Açık Aktivasyonlar

Hesabınızdaki açık aktivasyonları JSON olarak listeler (kimlik, servis, numara, tutar, durum, varsa gelen kodlar). activationStatus: "4" kod bekleniyor, "1" kod geldi, "3" yeniden SMS bekleniyor. Kodun gelip gelmediğinin güvenilir göstergesi smsCode dizisidir; durum alanına tek başına güvenmeyin. Uygulamanız yeniden başladığında bekleyen işlemleri buradan toparlayın.

GET ?action=getActiveActivations { "status": "success", "activeActivations": [ { "activationId": "184213", "serviceCode": "wa", "phoneNumber": "628123456789", "activationCost": "12.50", "activationStatus": "1", "smsCode": ["123456"], "countryCode": "62" } ] }

setStatus — Durum Değiştirme

Örnek: GET ?action=setStatus&id=184213&status=6. Dört durum kabul edilir:

status	Başarılı yanıt	Açıklama
`1`	`ACCESS_READY`	Numara hazır / SMS bekleniyor (bilgi amaçlı).
`3`	`ACCESS_RETRY_GET`	Aynı numaradan ek SMS iste. Ücretsizdir; yeni kod gelirse `STATUS_WAIT_RETRY` ile `STATUS_OK` arasında ilerler.
`6`	`ACCESS_ACTIVATION`	Tamamla ve kapat. Yalnızca kod geldiyse geçerlidir; kod yokken `STATUS_WAIT_CODE` (ya da `BAD_STATUS`) döner ve işlem tamamlanmaz.
`8`	`ACCESS_CANCEL`	İptal et. Kod gelmediyse iptal edilir ve rezerve tutar serbest kalır. Kod geldiyse `EARLY_CANCEL_DENIED` döner; ücret kesinleşmiştir ve iade edilmez.

Hata Kodları

Kod	Anlamı	Ne yapmalı?
`BAD_KEY`	API anahtarı boş veya geçersiz.	Panelden anahtarı kontrol edin; yenilediyseniz kodunuzu güncelleyin.
`BAD_ACTION`	Bilinmeyen `action` değeri.	Yalnızca bu belgedeki action değerleri geçerlidir.
`BAD_SERVICE`	Servis/ülke eksik ya da satışa kapalı.	Parametreleri ve fiyat listesindeki durumu doğrulayın.
`NO_BALANCE`	Bakiye yetersiz veya asgarinin altında.	Bakiye yükleyip tekrar deneyin.
`NO_NUMBERS`	O servis/ülke için o an stok yok.	Farklı bir ülke deneyin ya da kısa süre sonra tekrarlayın.
`NO_ACTIVATION`	Verilen `id` size ait değil.	`id` değerini getNumber yanıtından aldığınızdan emin olun.
`BAD_STATUS`	setStatus için geçersiz durum.	Yalnızca `1`, `3`, `6` ve `8` kabul edilir.
`NO_CONNECTION`	Geçici sorun ya da istek sınırı (HTTP 429).	Bekleyip tekrar deneyin; süreyi katlayarak artırın.
`WRONG_MAX_PRICE:<fiyat>`	Verdiğiniz `maxPrice` geçersiz ya da güncel fiyatı karşılamıyor; satın alma yapılmaz.	Yanıttaki fiyatı kabul ediyorsanız onu `maxPrice` olarak gönderin ya da isteği `maxPrice` olmadan tekrarlayın.
`EARLY_CANCEL_DENIED`	Kod zaten geldiği için aktivasyon iptal edilemez (`setStatus&status=8`).	Hizmet teslim edilmiştir; ücret iade edilmez. Aktivasyonu `status=6` ile kapatın.

PHP Örneği

<?php $key = 'YOUR_KEY'; $base = 'https://turonay.com/api/'; function tur(string $base, array $q): string { return trim((string)file_get_contents( $base . '?' . http_build_query($q) )); } // Numara al $r = tur($base, ['api_key'=>$key, 'action'=>'getNumber', 'service'=>'wa', 'country'=>'62']); if (!str_starts_with($r, 'ACCESS_NUMBER')) { exit($r); } [, $id, $phone] = explode(':', $r); // Kodu bekle for ($i = 0; $i < 40; $i++) { sleep(4); $s = tur($base, ['api_key'=>$key, 'action'=>'getStatus', 'id'=>$id]); if (str_starts_with($s, 'STATUS_OK')) { echo explode(':', $s)[1]; break; } if ($s === 'STATUS_CANCEL') { break; } }

Python Örneği

import time, requests KEY = "YOUR_KEY" BASE = "https://turonay.com/api/" def tur(**q): q["api_key"] = KEY return requests.get(BASE, params=q, timeout=20).text.strip() # Numara al r = tur(action="getNumber", service="wa", country="62") if not r.startswith("ACCESS_NUMBER"): raise SystemExit(r) _, oid, phone = r.split(":") print("number:", phone) # Kodu bekle for _ in range(40): time.sleep(4) s = tur(action="getStatus", id=oid) if s.startswith("STATUS_OK"): print("code:", s.split(":")[1]); break if s == "STATUS_CANCEL": break

Webhooks (Bildirimler)

Kod geldiğinde veya aktivasyon iptal olduğunda sunucunuza imzalı bir HTTPS POST göndeririz; böylece getStatus ile sürekli yoklamanız gerekmez. Adresi ve gizli anahtarı profil sayfanızdan ayarlarsınız; panelden test olayı gönderebilir ve son 10 teslimatı görebilirsiniz.

event	Açıklama
`code_received`	Aktivasyona SMS kodu geldi (ücret bu anda kesinleşir). Ek SMS (`status=3`) için her yeni kod ayrı bir olay olarak gelir.
`cancelled`	Aktivasyon kod gelmeden sağlayıcı tarafından iptal edildi ya da siz `setStatus&status=8` ile iptal ettiniz; rezerve tutar serbest kalır, ücret alınmadı. Sessiz süre dolumu için bildirim gönderilmez: süresi dolan aktivasyonlar için `activationEndTime`'ı izleyin veya `getStatus` ile sorgulayın.
`test`	Panelde "Test gönder"e bastığınızda gelir; örnek değerler içerir.

Adres kuralları: yalnızca https://, port 443 veya 8443, en çok 500 karakter, kullanıcı adı/şifre içermeyen ve herkese açık bir alan adı (IP adresi, localhost ve özel ağ adresleri reddedilir). Yönlendirmeler (3xx) takip edilmez; geçerli bir TLS sertifikası gerekir.

İstek Gövdesi

Gövde JSON'dur. cancelled olayında code ve text alanları null gelir.

POST https://your-server.example.com/turonay-webhook Content-Type: application/json { "event": "code_received", "activationId": "184213", "phone": "628123456789", "service": "wa", "country": "62", "code": "123456", "text": "Your code: 123456", "receivedAt": "2026-10-07T12:00:41Z", "sentAt": "2026-10-07T12:00:42Z", "id": "dlv_9f2c4a7d1b3e5f60a8c2d4e6" }

code yalnızca code_received olayında doludur; text operatörden gelen SMS metnidir (boş olabilir). id her teslimat için tektir ve yeniden denemelerde aynı kalır: tekilleştirme için kullanın.

Başlıklar

header	Açıklama
`Content-Type`	`application/json`
`User-Agent`	`Turonay-Webhook/1.0`
`X-Turonay-Event`	Olay adı (`code_received`, `cancelled`, `test`).
`X-Turonay-Timestamp`	Gönderim zamanı, Unix saniyesi. İmzaya dahildir.
`X-Turonay-Signature`	`sha256=` + onaltılık HMAC-SHA256 imzası (aşağıya bakın).
`X-Turonay-Delivery`	Teslimat kimliği (gövdedeki `id` ile aynı).

İmza Doğrulama

İsteğin bizden geldiğini doğrulamak için HMAC_SHA256(secret, timestamp + "." + rawBody) değerini hesaplayın ve X-Turonay-Signature başlığındaki sha256= ile başlayan değerle sabit zamanlı karşılaştırın. Gizli anahtar (whsec_...) profil sayfanızda üretilir ve yalnızca üretildiği anda tam olarak gösterilir.

Ham gövdeyi (okuduğunuz baytlar) kullanın; JSON'u ayrıştırıp yeniden serileştirmeyin. Zaman damgası 5 dakikadan eskiyse isteği reddedin (tekrar saldırısı koruması). Gizli anahtarı sızdırdığınızı düşünüyorsanız panelden yenileyin; eskisi anında geçersiz olur.

PHP ile Doğrulama

<?php $secret = 'whsec_...'; // panelden aldığınız gizli anahtar $raw = file_get_contents('php://input'); // HAM gövde; ayrıştırılmış JSON değil $ts = $_SERVER['HTTP_X_TURONAY_TIMESTAMP'] ?? ''; $sig = $_SERVER['HTTP_X_TURONAY_SIGNATURE'] ?? ''; // eski istekleri reddet (5 dk) if (abs(time() - (int)$ts) > 300) { http_response_code(400); exit; } $expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $raw, $secret); if (!hash_equals($expected, $sig)) { http_response_code(401); exit; } $e = json_decode($raw, true); if ($e['event'] === 'code_received') { // $e['activationId'], $e['code'] ... } http_response_code(200); // 5 sn içinde 2xx dön

Node.js ile Doğrulama

Python ile Doğrulama

import hmac, hashlib, time from flask import Flask, request, abort app = Flask(__name__) SECRET = b"whsec_..." # panelden aldığınız gizli anahtar @app.post("/turonay-webhook") def hook(): raw = request.get_data() # HAM gövde; ayrıştırılmış JSON değil ts = request.headers.get("X-Turonay-Timestamp", "") sig = request.headers.get("X-Turonay-Signature", "") if not ts.isdigit() or abs(time.time() - int(ts)) > 300: abort(400) expected = "sha256=" + hmac.new(SECRET, ts.encode() + b"." + raw, hashlib.sha256).hexdigest() if not hmac.compare_digest(expected, sig): abort(401) e = request.get_json(force=True) if e["event"] == "code_received": print(e["activationId"], e["code"]) return "", 200 # 5 sn içinde 2xx dön

Yeniden Deneme Politikası

Sunucunuz isteği 5 saniye içinde 2xx koduyla yanıtlamalıdır. Başka bir kod, zaman aşımı veya bağlantı hatası başarısız sayılır. Yanıt gövdesi okunmaz.

Başarısız teslimat en çok 8 kez denenir; bekleme süreleri 1, 2, 4, 8, 16, 32 ve 60 dakikadır (toplam yaklaşık 2 saat). Hepsi başarısız olursa olay bırakılır.

Aynı olay yeniden denemede tekrar gelebilir (aynı id); işlemi activationId ile tekil yapın. Olayların sırası garanti edilmez.

Webhook bir kolaylıktır, tek güvence değildir: kaçırdığınız bir olay olursa getStatus ile durumu her zaman sorgulayabilirsiniz.

Sık Sorulan Sorular

API entegrasyonu hakkında geliştiricilerden gelen sorular.

Destek Hattı

API ücretli mi?

API erişimi için ayrı bir ücret veya abonelik yoktur. Yalnızca aldığınız numaralar için bakiyenizden düşülür ve kodu gelmeyen işlemler ücretlendirilmez.

handler_api protokolü için yazılmış mevcut entegrasyonum çalışır mı?

Yanıt biçimi uyumludur. Çoğu durumda taban adresi ve API anahtarını değiştirmeniz yeterlidir. Servis kodları ve ülke kimlikleri için fiyat listesini kontrol etmeniz gerekir.

Yanıtlar JSON mı, düz metin mi?

Klasik uçlar (getNumber, getStatus, setStatus, getBalance) handler_api uyumluluğu için düz metin döner; getNumberV2, getStatusV2, getActiveActivations, getOperators ve fiyat/ülke uçları JSON döner.

Anahtarımı yenilersem ne olur?

Eski anahtar anında geçersiz olur ve onu kullanan tüm istekler BAD_KEY döner. Yenilemeden önce uygulamanızı güncellemeye hazır olun.

Aynı anda kaç numara alabilirim?

Eşzamanlı işlem sayısı bakiyenize ve dakikalık istek sınırına (varsayılan olarak anahtar ve IP başına dakikada 60 istek) bağlıdır.

Kod gelmezse ücret alınır mı?

Hayır. Ücret yalnızca SMS kodu size ulaştığında bakiyenizden düşülür. Kod gelmeden iptal ederseniz veya süre dolarsa hiçbir ücret alınmaz.

Kodu yoklamak mı webhook mu kullanmalıyım?

İkisi birlikte çalışır. Webhook bildirimi kod kaydedildiğinde kuyruğa alınır ve genellikle 1–2 dakika içinde ulaşır; getStatus ise alternatif yol ve kaçırılan olaylar ile yeniden başlatmalar için güvence olarak kalır. Çoğu entegrasyon webhook'u ana yol, yoklamayı yedek olarak kullanır.