API hujjati

01 API nima va nimaga kerak

API — ikkita dastur bir-biri bilan gaplashadigan til. Siz saytga kirib tugma bosasiz; sizning dasturingiz esa tugma bosolmaydi — u maxsus manzilga so'rov yuboradi va javobni matn (JSON) ko'rinishida oladi.

# So'rov (siz yuborasiz):
https://www.numbers.net.uz/api?key=SIZNING_KALITINGIZ&action=balance

# Javob (server qaytaradi):
{
  "status": "ok",
  "user_id": 12,
  "balance": 125000,
  "spend": 48000,
  "currency": "UZS",
  "discount_percent": 10
}

Bu API bilan nima qila olasiz

• Qaysi davlatlarning Telegram raqamlari sotuvda ekanini va narxini bilish
• Tanlangan davlatdan telefon raqam sotib olish
• O'sha raqamga kelgan tasdiqlash (SMS) kodini olish
• Hisobingizdagi pulni tekshirish

Ko'pincha o'z Telegram botingiz yoki saytingizni qurish uchun ishlatiladi: mijoz botdan raqam so'raydi, botingiz esa fon rejimida shu API'ga murojaat qilib raqamni oladi.

02 Birinchi so'rovingiz

Uch qadamda birinchi natijani olasiz. Hech qanday dastur yozish shart emas — brauzer yetadi.

1. API kalitni oling. Tizimga kiring → Profil → «API kalit yaratish». Kalit — sizning shaxsiy parolingiz: serverga «bu men» deb aytadi.
2. Havolani yig'ing. Quyidagi havolada SIZNING_KALITINGIZ o'rniga o'z kalitingizni qo'ying.
3. Brauzerga joylang va Enter bosing. Ekranda JSON javobni ko'rasiz — bu sizning birinchi API so'rovingiz.

https://www.numbers.net.uz/api?key=SIZNING_KALITINGIZ&action=balance

03 So'rov yig'uvchi

Havolani qo'lda yozish shart emas. Kerakli amalni tanlang, kalitingizni kiriting — tayyor havola o'zi yig'iladi. (Kalit hech qayerga yuborilmaydi va saqlanmaydi: hammasi brauzeringizda hisoblanadi.)

04 So'rov tuzilishi

Har bir so'rov bir xil qoidaga bo'ysunadi.

https://www.numbers.net.uz/api  ?  key=abc123  &  action=getnum  &  code=UZ
└── manzil ──┘  ↑  └─ 1-param ─┘ ↑  └── 2-param ──┘ ↑  └─ 3-param ─┘
                savol belgisi     ampersand          ampersand

• Manzil — doim bir xil: https://www.numbers.net.uz/api (qisqa shakl — https://www.numbers.net.uz/ — ham ishlaydi)
• ? — shundan keyin parametrlar boshlanadi; nom=qiymat — bitta parametr; & — parametrlarni ajratadi

GET, POST va JSON

Uchalasi ham qabul qilinadi. GET — parametrlar havolada, brauzerdan sinash uchun qulay. POST — parametrlar so'rov tanasida: kalit brauzer tarixiga va server jurnallariga tushmaydi. Haqiqiy dasturda POST ni tanlang. Kalitni X-API-Key yoki Authorization: Bearer … sarlavhasida ham yuborish mumkin.

Javobni qanday o'qish kerak

Javobda doim status maydoni bo'ladi. "ok" bo'lsa hammasi joyida. Xato bo'lsa error maydoni paydo bo'ladi va unda sabab yozilgan.

{
  "status": "ok",
  "balance": 125000
}

{
  "status": "error",
  "error": "Noto'g'ri API kalit"
}

05 API kalit

Kalit — hisobingizga to'liq kirish huquqi: u orqali balansingizni ko'rish va pulingizga raqam sotib olish mumkin.

Kalit qanday saqlanadi

Kalit bazada faqat xesh ko'rinishida saqlanadi, shuning uchun u yaratilgan paytda bir marta ko'rsatiladi. Yo'qotsangiz — yangisini yaratasiz.

IP cheklovi

Kalit birinchi marta getnum bilan ishlatilganda, so'rov kelgan IP avtomatik saqlanadi — keyin raqamni faqat shu IP dan olish mumkin. Boshqa IP dan kelgan so'rov pulga tegilmasdan rad etiladi. IP ni almashtirish (5 tagacha) yoki cheklovni o'chirish — Profil → «IP manzilga bog'lash» bo'limida.

// Brauzerda ishlaydigan kod — kalit hammaga ko'rinadi!
fetch("https://www.numbers.net.uz/api?key=abc123&action=balance")

// Server tomonidagi kod — kalit yashirin
$key = getenv("NOMERSAYT_KEY");
$url = "https://www.numbers.net.uz/api?key=$key&action=balance";

06 balance GET / POST pul sarflamaydi

Hisobingizdagi pul miqdorini va shu paytgacha sarflangan summani qaytaradi.

https://www.numbers.net.uz/api?key=SIZNING_KALITINGIZ&action=balance

{
  "status": "ok",
  "user_id": 12,
  "balance": 125000,
  "spend": 48000,
  "currency": "UZS",
  "discount_percent": 10
}

07 countries GET / POST pul sarflamaydi

Hozir sotuvda turgan davlatlar va narxlarini qaytaradi. getnum ga yuboradigan code qiymatini shu yerdan olasiz.

https://www.numbers.net.uz/api?key=SIZNING_KALITINGIZ&action=countries

{
  "status": "ok",
  "count": 87,
  "currency": "UZS",
  "discount_percent": 10,
  "countries": [
    {
      "code": "UZ",
      "name": "Uzbekistan",
      "price": 5491,
      "price_without_discount": 6864
    },
    {
      "code": "RU",
      "name": "Russia",
      "price": 8112
    }
  ]
}

08 getnum GET / POST pul yechiladi

Tanlangan davlatdan bitta Telegram uchun telefon raqam sotib oladi va narxini balansingizdan yechadi. Keyin unga kelgan kodni getsms orqali olasiz.

https://www.numbers.net.uz/api?key=SIZNING_KALITINGIZ&action=getnum&code=UZ

{
  "status": "ok",
  "phone": "+998901234567",
  "hash": "+998901234567",
  "price": 5491,
  "price_without_discount": 6864,
  "currency": "UZS",
  "discount_percent": 10,
  "country": "Uzbekistan",
  "country_code": "UZ",
  "balance": 119509,
  "order_id": 1042
}

09 getsms GET / POST pul sarflamaydi

Sotib olgan raqamingizga kelgan tasdiqlash kodini qaytaradi. Kod hali kelmagan bo'lsa «SMS kodi hali kelmadi» javobi qaytadi — bu normal holat, biroz kutib qayta so'rang.

https://www.numbers.net.uz/api?key=SIZNING_KALITINGIZ&action=getsms&hash=%2B998901234567

{
  "status": "ok",
  "sms": "12345",
  "password": "",
  "phone": "+998901234567"
}

{
  "status": "error",
  "error": "SMS kodi hali kelmadi",
  "waiting": true
}

Havoladagi «+» belgisi

URL manzilida + belgisi bo'sh joy degani. Shuning uchun raqamni havolaga to'g'ridan-to'g'ri yozsangiz, plyus yo'qolib ketishi mumkin. To'g'ri yo'l — qiymatni kodlash (%2B): PHP'da urlencode(), JavaScript'da encodeURIComponent(), Python'da requests buni o'zi qiladi. Yoki oddiygina POST ishlating. Xotirjam bo'ling: server plyus yo'qolgan holatni ham tushunadi.

10 To'liq stsenariy

Boshidan oxirigacha bitta amaliy misol: mijozga O'zbekiston raqamini sotib berish.

1. Balansni tekshiring. Pul yetarli ekaniga ishonch hosil qiling: action=balance
2. Davlatlar ro'yxatini oling. Kerakli davlatning code va price ini toping: action=countries
3. Raqam sotib oling. Javobdagi hash ni albatta saqlang: action=getnum&code=UZ
4. Raqamni Telegramga kiriting. Telegram shu raqamga kod yuboradi.
5. Kodni so'rang. Kod kelmaguncha har 5 soniyada takrorlang, lekin 3 daqiqadan oshirmang: action=getsms&hash=…
6. Kodni ishlating. Tayyor. Bir raqam odatda bitta ro'yxatdan o'tish uchun mo'ljallangan.

11 Kod namunalari

Nusxalab oling; kalitni o'zgaruvchiga (yoki muhit o'zgaruvchisiga) qo'ying. Har bir namuna to'liq ishlaydigan dastur.

<?php
$key  = getenv("NOMERSAYT_KEY");          // kalitni serverda, muhit o'zgaruvchisida saqlang
$base = "https://www.numbers.net.uz/api";

/** API ga so'rov yuboruvchi yordamchi funksiya (POST: kalit server jurnaliga tushmaydi). */
function api($action, array $params = array()) {
    global $key, $base;
    $params["key"]    = $key;
    $params["action"] = $action;

    $ch = curl_init($base);
    curl_setopt_array($ch, array(
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => http_build_query($params),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 40,
    ));
    $body = curl_exec($ch);
    curl_close($ch);

    $data = json_decode((string)$body, true);
    return is_array($data) ? $data : array("status" => "error", "error" => "Javob JSON emas");
}

// 1. Balans
$bal = api("balance");
if ($bal["status"] !== "ok") exit("Xatolik: " . $bal["error"]);
echo "Balans: " . $bal["balance"] . " so'm\n";

// 2. Davlatlar
$c = api("countries");
if ($c["status"] !== "ok") exit("Xatolik: " . $c["error"]);
foreach ($c["countries"] as $country) {
    echo $country["code"] . " - " . $country["name"] . " - " . $country["price"] . " so'm\n";
}

// 3. Raqam sotib olish (pul yechiladi!)
$num = api("getnum", array("code" => "UZ"));
if ($num["status"] !== "ok") exit("Raqam olinmadi: " . $num["error"]);
$phone = $num["phone"];
$hash  = $num["hash"];                     // buni saqlab qo'ying
echo "Raqam: $phone\n";

// 4. SMS kodni kutish (har 5 soniyada, ko'pi bilan 3 daqiqa)
$code = null;
for ($i = 0; $i < 36; $i++) {
    sleep(5);
    $r = api("getsms", array("hash" => $hash));
    if ($r["status"] === "ok") { $code = $r["sms"]; break; }
    if (empty($r["waiting"])) { echo "Xatolik: " . $r["error"] . "\n"; break; }   // "kod hali kelmadi" bo'lmasa — to'xtaymiz
}
echo $code ? "SMS kod: $code\n" : "Kod olinmadi\n";

import os, time, requests

KEY  = os.environ["NOMERSAYT_KEY"]        # kalitni serverda, muhit o'zgaruvchisida saqlang
BASE = "https://www.numbers.net.uz/api"

def api(action, **params):
    """API ga so'rov yuboradi va JSON javobni qaytaradi."""
    params["key"] = KEY
    params["action"] = action
    r = requests.post(BASE, data=params, timeout=40)
    try:
        return r.json()
    except ValueError:
        return {"status": "error", "error": "Javob JSON emas"}

# 1. Balans
bal = api("balance")
if bal["status"] != "ok":
    raise SystemExit("Xatolik: " + bal["error"])
print("Balans:", bal["balance"], "so'm")

# 2. Davlatlar
c = api("countries")
if c["status"] != "ok":
    raise SystemExit("Xatolik: " + c["error"])
for country in c["countries"][:10]:
    print(country["code"], country["name"], country["price"], "so'm")

# 3. Raqam sotib olish (pul yechiladi!)
num = api("getnum", code="UZ")
if num["status"] != "ok":
    raise SystemExit("Raqam olinmadi: " + num["error"])
phone, hash_ = num["phone"], num["hash"]
print("Raqam:", phone)

# 4. SMS kodni kutish (har 5 soniyada, ko'pi bilan 3 daqiqa)
code = None
for _ in range(36):
    time.sleep(5)
    r = api("getsms", hash=hash_)
    if r["status"] == "ok":
        code = r["sms"]
        break
    if not r.get("waiting"):
        print("Xatolik:", r["error"])
        break
print("SMS kod:", code if code else "olinmadi")

// Node.js 18+ (server tomonida ishlating, brauzerda EMAS!)
const KEY  = process.env.NOMERSAYT_KEY;
const BASE = "https://www.numbers.net.uz/api";

async function api(action, params = {}) {
  const body = new URLSearchParams({ ...params, key: KEY, action });
  const res  = await fetch(BASE, { method: "POST", body });
  try { return await res.json(); }
  catch { return { status: "error", error: "Javob JSON emas" }; }
}
const sleep = ms => new Promise(r => setTimeout(r, ms));

(async () => {
  const bal = await api("balance");
  if (bal.status !== "ok") return console.error("Xatolik:", bal.error);
  console.log("Balans:", bal.balance, "so'm");

  const num = await api("getnum", { code: "UZ" });          // pul yechiladi!
  if (num.status !== "ok") return console.error("Raqam olinmadi:", num.error);
  console.log("Raqam:", num.phone);

  for (let i = 0; i < 36; i++) {                            // 36 x 5 s = 3 daqiqa
    await sleep(5000);
    const r = await api("getsms", { hash: num.hash });
    if (r.status === "ok") { console.log("SMS kod:", r.sms); return; }
    if (!r.waiting) { console.error("Xatolik:", r.error); return; }
  }
  console.log("Kod 3 daqiqada kelmadi");
})();

# Balans
curl -X POST "https://www.numbers.net.uz/api" -d "key=KALIT" -d "action=balance"

# Davlatlar
curl -X POST "https://www.numbers.net.uz/api" -d "key=KALIT" -d "action=countries"

# Raqam sotib olish (pul yechiladi!)
curl -X POST "https://www.numbers.net.uz/api" -d "key=KALIT" -d "action=getnum" -d "code=UZ"

# SMS kod
curl -X POST "https://www.numbers.net.uz/api" -d "key=KALIT" -d "action=getsms" --data-urlencode "hash=+998901234567"

12 Chegirma

Chegirma tariflar orqali beriladi va avtomatik qo'llanadi — promokod yoki qo'shimcha parametr yuborish shart emas. Tariflar sahifasidan tarifni sotib oling: amal qilish muddati davomida sayt va API orqali olingan har bir raqam arzonroq bo'ladi.

Chegirmangiz bor-yo'qligini qanday bilasiz

balance so'rovini yuboring va javobdagi discount_percent maydoniga qarang (0 — chegirma yo'q).

Oddiy narx              6 864 so'm
        ↓  chegirma ayiriladi (−10%)
Siz to'laysiz            5 491 so'm

13 Xatoliklar

Xatolik bo'lsa javobda error maydoni paydo bo'ladi (HTTP kodi ham mos ravishda o'zgaradi). Dasturingiz avval shuni tekshirsin.

Tezlik chegaralari

Har bir kalit uchun daqiqada 120 ta so'rov, shundan getnum — 20 ta, getsms — 60 ta; bitta IP dan daqiqada 300 ta. Chegaradan oshsangiz 429 va retry_after (soniya) qaytadi.