Geliştirici API

SMS API dokümantasyonu — numara al, kodu çek

Bu sayfa çalışan kodun sözleşmesi. Ülke + hizmet gönderirsin, numara ve SMS kodu alırsın. Kaynak adı dönmez. Anahtar Hesap sayfasından üretilir; anahtar orada durur, yenileyene kadar aynı kalır.

Akış

İsteğe bağlı fiyat bak: GET /api/v1/quote veya ülke listesi için GET /api/v1/prices. Anahtar gerekmez.
Numara kirala: POST /api/v1/activations gövdesinde country ve service. Yanıttaki phone kayıt ekranına yazılır. id sonraki istekler için.
Kodu al: aynı id ile GET /api/v1/activations/{id} çağır (2 sn’de bir yeter). status değeri received olunca sms[0].code doğrulama kodudur. SMS gelmezse 15 dk sonra timeout, bakiye iade edilir.

Kimlik

Üye ol, bakiye yükle, Hesap’tan anahtar üret. Korumalı uçlara ikisinden biri yeter:

Authorization: Bearer smsal_…
X-Api-Key: smsal_…

Tarayıcıdaki smsal.vip oturumu da aynı uçları açar; dış uygulama için anahtar kullan. Anahtar yenilenince eskisi hemen düşer. Bir üyede tek aktif anahtar vardır. Anahtar Hesap sayfasında durur.

Webhook

Hesap → Tercihler’e HTTPS adresi yaz. SMS düşünce smsal.vip şu gövdeyi POST eder (yaklaşık 4 sn zaman aşımı; hata kiralamayı durdurmaz):

{
  "event": "sms.received",
  "brand": "smsal.vip",
  "id": "act_…",
  "phone": "+4915…",
  "country": "germany",
  "service": "whatsapp",
  "sms": [{ "from": "WhatsApp", "text": "…", "code": "482193" }]
}

Uçlar

GET /api/v1/catalog

Açık

Ülke ve hizmet kimlikleri. demo: true ise kaynak API anahtarı yok, alınan hat örnektir.

{
  "brand": "smsal.vip",
  "demo": true,
  "countries": [{ "id": "germany", "name": "Almanya", "iso": "DE", "dial": "+49", "flag": "🇩🇪" }],
  "services": [{ "id": "whatsapp", "name": "WhatsApp", "hint": "" }]
}

GET /api/v1/prices?service=whatsapp

Açık

Seçilen hizmet için ülke satırları. country alanı POST /activations gövdesine aynen yazılır (örn. england, germany). available false ise stok yok.

{
  "service": "whatsapp",
  "serviceName": "WhatsApp",
  "demo": true,
  "rows": [{
    "country": "germany",
    "name": "Almanya",
    "nameEn": "Germany",
    "flag": "🇩🇪",
    "iso": "DE",
    "dial": "+49",
    "priceUsd": 0.4,
    "stock": 12,
    "available": true
  }]
}

curl -s 'https://smsal.vip/api/v1/prices?service=whatsapp'

GET | POST /api/v1/quote

Açık

Tek ülke+hizmet fiyatı. GET query: country, service. POST JSON aynı alanlar. available false veya priceUsd null ise alma.

{
  "country": "germany",
  "service": "whatsapp",
  "demo": true,
  "available": true,
  "priceUsd": 0.4,
  "stock": 12,
  "etaSeconds": 20
}

curl -s 'https://smsal.vip/api/v1/quote?country=germany&service=whatsapp'

GET /api/v1/me

Anahtar

Üye, bakiye (kuruş), anahtar öneki, davet kodu, varsayılan ülke. Numara ücreti bakiyeden kuruş olarak düşülür: round(priceUsd × kur × 100).

{
  "id": "usr_…",
  "name": "Nizam",
  "email": "[email protected]",
  "balanceKurus": 5000,
  "apiKeyPrefix": "smsal_ab12cd",
  "referralCode": "ab3dk2pq",
  "defaultCountry": "germany",
  "webhookUrl": null
}

curl -s https://smsal.vip/api/v1/me \
  -H 'authorization: Bearer smsal_SENIN_ANAHTARIN'

POST /api/v1/activations

Anahtar

Numara kirala. Gövde: { country, service }. 401 anahtar yok/yanlış, 402 bakiye yetmez, 400 stok veya geçersiz hizmet. Yanıt PublicActivation.

{
  "id": "act_…",
  "country": "germany",
  "countryName": "Almanya",
  "service": "whatsapp",
  "serviceName": "WhatsApp",
  "phone": "+491512345678",
  "priceUsd": 0.4,
  "status": "waiting",
  "sms": [],
  "demo": true,
  "createdAt": "2026-09-05T22:00:00.000Z",
  "expiresAt": "2026-09-05T22:15:00.000Z"
}

curl -s https://smsal.vip/api/v1/activations \
  -H 'authorization: Bearer smsal_SENIN_ANAHTARIN' \
  -H 'content-type: application/json' \
  -d '{"country":"germany","service":"whatsapp"}'

GET /api/v1/activations

Anahtar

Senin kiralama işlemlerin. { activations: PublicActivation[] } en fazla 50, yeniden taze.

GET /api/v1/activations/{id}

Anahtar

SMS kutusunu yenile. Yalnız kendi id’n. status received olunca sms dizisi dolar. code, metindeki 4–8 haneli sayı; yoksa null. Başkasının id’si 404.

{
  "id": "act_…",
  "status": "received",
  "phone": "+491512345678",
  "sms": [{
    "from": "WhatsApp",
    "text": "Your code is 482193",
    "code": "482193",
    "receivedAt": "2026-09-05T22:00:20.000Z"
  }],
  "demo": true,
  "expiresAt": "2026-09-05T22:15:00.000Z"
}

curl -s https://smsal.vip/api/v1/activations/act_... \
  -H 'authorization: Bearer smsal_SENIN_ANAHTARIN'

POST /api/v1/activations/{id}/cancel

Anahtar

Yalnız status waiting iken iptal. Bakiye iade. Gövde yok.

curl -s -X POST https://smsal.vip/api/v1/activations/act_.../cancel \
  -H 'authorization: Bearer smsal_SENIN_ANAHTARIN'

POST /api/v1/activations/{id}/demo-sms

Anahtar

Yalnız demo: true hatlarda örnek SMS basar. Canlı hatta 400: “Canlı hatlarda demo SMS yok”. İsteğe bağlı gövde { text }.

status

waiting — hat duruyor, SMS yok. Poll et.
received — kod geldi. sms[0].code
timeout — 15 dk doldu, SMS gelmedi, ücret iade.
cancelled — iptal, ücret iade.

Hatalar

Gövde her zaman { "error": "…" }.

400 — country/service eksik, bilinmeyen hizmet, stok yok, numara kiralanamadı.
401 — anahtar yok, geçersiz, veya üye oturumu yok.
402 — yetersiz bakiye.
404 — aktivasyon yok veya sana ait değil.

Kimlikler

service: katalogdaki id ( whatsapp, telegram, google, instagram…) veya fiyat listesindeki id. Küçük harf, rakam; bazı hizmetler h- önekli. Bilinmeyen hizmet 400.

country: GET /api/v1/prices satırındaki değer. İngiltere için katalogda england kullanılır, turkey stokta yoksa alma. GET /catalog ülkeleri kısmi listedir; canlı stok prices’tadır.