SMS Onay API
Numara alımını kendi yazılımından yönet. İki arayüz sunuyoruz: modern JSON REST API ve mevcut araçlarla uyumlu SMS-Activate protokolü. İkisi de aynı bakiye ve aynı fiyatlarla çalışır; kod gelmeyen işlemler otomatik iade edilir.
Hızlı başlangıç
- Hesap aç ve bakiye yükle (kart veya kripto).
- Panel → API sayfasından anahtarını oluştur (
alf_…ile başlar, yalnızca bir kez gösterilir). - Aşağıdaki akışı çalıştır: numara al → kodu bekle → bitti.
curl -X POST https://alfsmm.com/api/v1/activations \
-H "Authorization: Bearer alf_ANAHTARIN" \
-H "Content-Type: application/json" \
-d '{ "service": "wa", "country": 0 }'
# → { "ok": true, "activation": { "id": "cm9x…", "phone": "79261234567",
# "status": "waiting", "priceKurus": 850, … } }curl https://alfsmm.com/api/v1/activations/cm9x… \
-H "Authorization: Bearer alf_ANAHTARIN"
# kod gelince:
# → { "ok": true, "activation": { "status": "code_received",
# "code": "123456", "sms": "WhatsApp code 123-456", … } }Kod 20 dakika içinde gelmezse aktivasyon expired olur ve ücret otomatik iade edilir — takılı işlem kalmaz. Servis kodlarını GET /api/v1/services, ülke fiyatlarını GET /api/v1/prices?service=wa ile listeleyebilirsin.
Kimlik doğrulama
Her istekte anahtarını Authorization başlığıyla gönder; X-Api-Key başlığı da kabul edilir. Güvenlik gereği JSON API'de anahtar yalnızca başlıktakabul edilir — URL'ye (query string) yazılan anahtarlar reddedilir, çünkü sunucu ve proxy loglarına sızabilir.
curl https://alfsmm.com/api/v1/balance \
-H "Authorization: Bearer alf_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"- • Aynı anda en fazla 5 aktif anahtarın olabilir; her birini panelden anında iptal edebilirsin.
- • Anahtarlar veritabanında yalnızca özet (hash) olarak saklanır — kaybedersen yenisini oluştur.
- • Anahtarı istemci tarafı kodda (tarayıcı, mobil uygulama) asla kullanma; her zaman kendi sunucundan çağır.
Yanıt biçimi ve hata kodları
Tüm yanıtlar JSON'dur ve tek bir kalıba uyar. Hata durumunda error insan-okur (Türkçe) mesajı, code ise makine-okur sabiti taşır — entegrasyonunu her zaman code üzerinden dallandır.
// başarı
{ "ok": true, …veri… }
// hata
{ "ok": false, "error": "Yetersiz bakiye. Lütfen bakiye yükleyin.", "code": "INSUFFICIENT_BALANCE" }Parasal alanlar iki biçimde döner: priceKurus / balanceKurus tam sayı kuruş (hesap yaparken bunu kullan — kayan nokta hatası olmaz) ve priceTry / balanceTry gösterim kolaylığı için TL karşılığı.
| code | HTTP | Anlamı |
|---|---|---|
UNAUTHORIZED | 401 | API anahtarı eksik veya geçersiz. |
RATE_LIMITED | 429 | Hız sınırı aşıldı — Retry-After başlığındaki saniye kadar bekleyin. |
INVALID_BODY / INVALID_QUERY / INVALID_SERVICE | 422 | İstek gövdesi ya da sorgu parametresi hatalı. |
INSUFFICIENT_BALANCE | 402 | Bakiye yetersiz — panelden bakiye yükleyin. |
NO_STOCK | 409 | Bu servis/ülke için şu anda stok yok. Farklı ülke deneyin. |
NO_PRICE | 400 | Bu servis/ülke kombinasyonu için fiyat yok (muhtemelen geçersiz kod). |
TR_DISABLED | 400 | Türkiye (+90) numara satışı geçici olarak kapalı. |
PRICE_CHANGED | 400 | Fiyat siz işlem yaparken güncellendi — isteği yineleyin. |
CANCEL_TOO_EARLY | 409 | Numara alındıktan sonraki ilk 2 dakika iptal edilemez. |
NOT_CANCELABLE / NOT_RETRYABLE | 400 | İşlem bu duruma artık uygun değil (ör. kod zaten geldi). |
EXPIRED | 400 | Numaranın 20 dakikalık süresi doldu (ücret otomatik iade edilir). |
IN_PROGRESS | 400 | Aynı numara üzerinde eşzamanlı başka bir işlem sürüyor. |
NOT_FOUND | 404 | Aktivasyon bulunamadı ya da size ait değil. |
PROVIDER_BALANCE / PROVIDER_ERROR | 503 / 400 | Sağlayıcı tarafında geçici sorun — kısa bir süre sonra yeniden deneyin. |
UPSTREAM_UNAVAILABLE | 503 | Canlı fiyat/servis listesi geçici olarak alınamıyor. |
INTERNAL | 500 | Beklenmedik sunucu hatası. |
Aktivasyon durumları
Bir aktivasyon status alanıyla şu yaşam döngüsünü izler:
| status | Anlamı | Sonrası |
|---|---|---|
waiting | Numara alındı, SMS bekleniyor (20 dk). | code_received · cancelled · expired |
code_received | Kod geldi — code ve sms alanları dolu. | finished (otomatik/işaretleyince) |
finished | İşlem tamamlandı. | — |
cancelled / refunded | İptal edildi, ücret bakiyeye iade edildi. | — |
expired | Süre doldu, ücret otomatik iade edildi. | — |
- • İlk 2 dakika iptal mümkün değildir (sağlayıcı kuralı) —
CANCEL_TOO_EARLYalırsın. - • Yalnızca
waitingdurumundaki aktivasyonlar iptal edilebilir; kod geldiyse ücret iadesi yapılmaz. - • Para yalnızca iki yönde hareket eder: satın almada düşer, iptal/iade/süre dolumunda geri gelir.
JSON REST uçları
Taban adres: https://alfsmm.com/api/v1
/api/v1/balanceMevcut bakiyen.
{ "ok": true, "balanceKurus": 12550, "balanceTry": "125.50" }/api/v1/servicesSatın alınabilir tüm servisler. code alanını numara alırken kullanırsın.
{ "ok": true, "services": [ { "code": "wa", "name": "WhatsApp" }, { "code": "tg", "name": "Telegram" }, … ] }/api/v1/countriesTüm ülkeler: sayısal id (numara alırken kullanılır), ad ve ISO kodu.
{ "ok": true, "countries": [ { "id": 0, "name": "Russia", "iso": "ru" }, … ] }/api/v1/prices?service=waBir servis için ülke bazında canlı fiyat ve stok. Fiyatlar panelde gördüğünle aynıdır.
| Parametre | Tip | Açıklama |
|---|---|---|
service | string (zorunlu) | Servis kodu, ör. wa |
{
"ok": true,
"service": "wa",
"countries": [
{ "country": 0, "name": "Russia", "iso": "ru", "stock": 1543, "priceKurus": 850, "priceTry": "8.50" },
…
]
}/api/v1/activationsNumara satın al. Ücret bakiyenden peşin düşer; kod gelmezse 20 dakika sonunda otomatik iade edilir.
| Alan | Tip | Açıklama |
|---|---|---|
service | string (zorunlu) | Servis kodu, ör. wa |
country | int (zorunlu) | Ülke id'si, ör. 0 |
operator | string (isteğe bağlı) | Operatör kodu; boş bırakılırsa otomatik seçilir |
{
"ok": true,
"activation": {
"id": "cm9x…",
"phone": "79261234567",
"service": "wa", "serviceName": "WhatsApp",
"country": 0, "countryName": "Russia", "iso": "ru",
"priceKurus": 850, "priceTry": 850,
"status": "waiting", "code": null, "sms": null,
"createdAt": "2026-07-08T12:14:56.000Z",
"expiresAt": "2026-07-08T12:34:56.000Z"
}
}Not: priceTry geriye dönük uyumluluk için korunur ve priceKurus ile aynı tam-sayı kuruş değerini taşır. Yeni entegrasyonlarda priceKurus kullan.
/api/v1/activations/{id}Durumu sorgula. Kod geldiğinde status=code_received, code ayıklanmış kod, sms mesajın tam metni olur. 3-5 saniyede bir sorgulaman yeterli — daha sık istek hız sınırına takılır.
/api/v1/activations?limit=20&status=waitingSon aktivasyonların, en yenisi önce. limit 1-100 arası (varsayılan 20); status ile filtreleyebilirsin.
/api/v1/activations/{id}/cancelBekleyen numarayı iptal et — ücret bakiyene iade edilir. İlk 2 dakika CANCEL_TOO_EARLY döner; kod geldiyse NOT_CANCELABLE.
/api/v1/activations/{id}/retryAynı numaraya yeni bir SMS iste (ücretsiz). Kod geldikten sonra aynı servisten ikinci bir kod beklerken kullanılır; aktivasyon waiting durumuna döner.
Node.js ve Python örnekleri
Uçtan uca akış: numara al, kodu bekle, süre dolarsa vazgeç. İki örnek de yalnızca standart kütüphane/yerleşik fetch kullanır.
const BASE = "https://alfsmm.com/api/v1";
const HEADERS = {
"Authorization": "Bearer " + process.env.ALFSMM_API_KEY,
"Content-Type": "application/json",
};
async function getCode(service, country) {
// 1) numara al
let res = await fetch(BASE + "/activations", {
method: "POST", headers: HEADERS,
body: JSON.stringify({ service, country }),
});
let data = await res.json();
if (!data.ok) throw new Error(data.code + ": " + data.error);
const { id, phone } = data.activation;
console.log("Numara:", phone);
// 2) kodu bekle (5 sn'de bir, süre dolana dek)
while (true) {
await new Promise((r) => setTimeout(r, 5000));
res = await fetch(BASE + "/activations/" + id, { headers: HEADERS });
data = await res.json();
const a = data.activation;
if (a.status === "code_received") return a.code;
if (a.status !== "waiting") throw new Error("Kod gelmedi: " + a.status); // iade edildi
}
}
getCode("wa", 0).then((code) => console.log("Kod:", code));import os, time, requests
BASE = "https://alfsmm.com/api/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["ALFSMM_API_KEY"]}
def get_code(service: str, country: int) -> str:
r = requests.post(f"{BASE}/activations", headers=HEADERS,
json={"service": service, "country": country}).json()
if not r["ok"]:
raise RuntimeError(f"{r['code']}: {r['error']}")
act = r["activation"]
print("Numara:", act["phone"])
while True:
time.sleep(5)
r = requests.get(f"{BASE}/activations/{act['id']}", headers=HEADERS).json()
a = r["activation"]
if a["status"] == "code_received":
return a["code"]
if a["status"] != "waiting":
raise RuntimeError("Kod gelmedi: " + a["status"]) # ücret iade edildi
print("Kod:", get_code("wa", 0))SMS-Activate uyumlu protokol
SMS-Activate / hero-sms protokolünü konuşan hazır yazılımlar (otomasyon araçları, kayıt botları vb.) taban adresi bize çevirerek doğrudan çalışır. Anahtar olarak yine alf_… anahtarını kullan:
https://alfsmm.com/stubs/handler_api.php?api_key=alf_…&action=<eylem>| action | Parametreler | Yanıt |
|---|---|---|
getBalance | — | ACCESS_BALANCE:125.50 |
getNumber | service, country, operator? | ACCESS_NUMBER:<id>:<telefon> |
getStatus | id | STATUS_WAIT_CODE · STATUS_OK:123456 · STATUS_CANCEL |
setStatus | id, status (3=yeni SMS · 6=tamamla · 8=iptal) | ACCESS_RETRY_GET · ACCESS_ACTIVATION · ACCESS_CANCEL |
getPrices | service (zorunlu), country? | JSON — fiyatlar TL |
getCountries | — | JSON {id:{id,eng,iso}} |
getNumbersStatus | country | JSON {servis:stok} |
- • Aktivasyon
id'leri sayı değil, kısa metin kimliklerdir — aldığın değeri olduğu gibi geri gönder. - •
maxPriceparametresi yok sayılır — panelde gördüğün fiyat neyse API'de de odur. - • Erken iptal denemesi
EARLY_CANCEL_DENIED, geçersiz anahtarBAD_KEYdöndürür.
Webhook'lar
Sürekli sorgulamak yerine, Panel → API sayfasından bir webhook URL'i tanımla: kod geldiğinde (activation.code_received) ve işlem iade edildiğinde (activation.refunded / activation.expired) adresine imzalı bir POST göndeririz.
POST <senin-url'in>
Content-Type: application/json
X-Webhook-Event: activation.code_received
X-Webhook-Signature: sha256=<gövdenin HMAC-SHA256 imzası>
{
"event": "activation.code_received",
"deliveryId": "a1b2c3…",
"sentAt": "2026-07-08T09:00:00.000Z",
"activation": { "id": "cm9x…", "phone": "79261234567", "code": "123456",
"sms": "WhatsApp code 123-456", "status": "code_received", … }
}İmzayı panelde gösterilen anahtarla doğrula:
const crypto = require("crypto");
const expected = "sha256=" + crypto.createHmac("sha256", WEBHOOK_SECRET)
.update(rawBody) // ham istek gövdesi (string)
.digest("hex");
const received = String(req.headers["x-webhook-signature"] ?? "");
const valid =
received.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));- • Teslimat en-az-bir-kez'dir; aynı olay nadiren iki kez gelebilir —
activation.idile tekilleştir. - • 2xx dışındaki yanıtlarda 5 sn ve 30 sn sonra iki kez yeniden deneriz.
- • URL https olmalı ve herkese açık bir adrese işaret etmelidir (özel ağ adresleri reddedilir).
- • "Test gönder" düğmesiyle
webhook.testolayı gönderip kurulumunu doğrulayabilirsin. - • Webhook'lar sorgulamanın yerine değil, yanına: kritik akışlarda durumu yine de sorgulayarak teyit et.
Hız sınırları
| Uç grubu | Limit |
|---|---|
| Okuma (bakiye, fiyat, listeler, durum sorgulama) | dakikada 120 istek |
| Numara satın alma | dakikada 20 istek |
| İptal / yeniden SMS | dakikada 60 istek |
Sınır aşımında 429 / RATE_LIMITED ve kaç saniye bekleyeceğini söyleyen bir Retry-After başlığı döner. Limitler kullanıcı başınadır — birden çok anahtar kotayı artırmaz. SMS-Activate ucu da aynı kotaları paylaşır. Daha yüksek limit gerekiyorsa kurumsal sayfamızdan ulaş.
Başlamak için
- Ücretsiz hesap aç ve bakiye yükle (kart veya kripto)
- Panel → API sayfasından anahtarını oluştur
- İlk isteğini gönder:
GET /api/v1/balance