πŸ”Œ Hamkorlik API β€” to'liq qo'llanma

Virtual raqamlarni (Server 1) o'z botingiz, saytingiz yoki dasturingiz orqali avtomatik oling. Pul bizning botdagi balansingizdan so'mda yechiladi.

πŸš€ Tez boshlash (5 qadam)

1
Botda bosh menyu β†’ Β«πŸ”Œ Hamkorlik APIΒ» β†’ Β«πŸ”‘ API kalit yaratishΒ» ni bosing. Kalit (sk_…) faqat bir marta ko'rsatiladi β€” darhol nusxalab, xavfsiz joyda saqlang.
2
Botda balansni to'ldiring (karta, avto to'lov yoki Telegram Stars). API xaridlari shu balansdan yechiladi.
3
Ulanishni tekshiring: GET /balance β€” balansingiz qaytsa, kalit to'g'ri.
4
GET /countries bilan davlat va narxni tanlang, POST /numbers bilan raqam oling.
5
Raqamni Telegram'ga kiriting va GET /numbers/{id} ni 5–10 soniyada bir so'rab, status = ok bo'lganda code ni oling.
Asosiy manzil (Base URL):
https://sinovbot.c4461.orax1.vip/api/v1
Barcha so'rovlar shu manzilga qo'shiladi: masalan https://sinovbot.c4461.orax1.vip/api/v1/balance. Javob har doim JSON.

πŸ”‘ Kalit (autentifikatsiya)

Kalitni quyidagi usullardan biri bilan yuboring (birinchisi tavsiya etiladi):

UsulMisol
Sarlavha (tavsiya)X-Api-Key: sk_…
BearerAuthorization: Bearer sk_…
Parametr?api_key=sk_… (URL loglarda qolishi mumkin)
πŸ”’ Xavfsizlik: kalit = balansingizdagi pul. Uni hech kimga bermang, GitHub'ga yoki ochiq kodga (sayt JavaScript'iga, mobil ilovaga) joylamang β€” faqat server tomonda saqlang. Kalit oshkor bo'lsa, botda Β«πŸ”„ Yangi kalitΒ» ni bosing: eskisi darhol ishlamay qoladi.

πŸ” Ish tartibi

GET /countriesβ†’POST /numbersβ†’raqamni Telegram'ga kiritishβ†’GET /numbers/{id} (har 5–10 s)β†’status: ok β†’ code

Kod 30 daqiqagacha kutiladi. Shu vaqt ichida kelmasa holat expired bo'ladi.

πŸ“‘ So'rovlar

Parametrlarni query (?country=US), form (application/x-www-form-urlencoded) yoki JSON (application/json) ko'rinishida yuborish mumkin. Barcha narxlar so'mda.

GET/ping β€” kalitsiz, xizmat ishlayaptimi
{"ok": true, "service": "numbers", "version": 1}
GET/balance β€” balans
{"ok": true, "balance": 125400.0, "currency": "UZS"}
GET/countries β€” davlatlar, narx va mavjud soni (arzonidan boshlab)
{"ok": true, "currency": "UZS", "countries": [
  {"country": "CO", "name": "Colombia", "dial": "57", "price": 4000, "stock": 538},
  {"country": "US", "name": "United States", "dial": "1", "price": 4300, "stock": 625}
]}

Narx sizning foizingiz bo'yicha hisoblanadi va kurs o'zgarsa o'zgarishi mumkin β€” xarid oldidan yangilab turing (β‰ˆ1 daqiqa kesh qilish yetarli).

POST/numbers β€” raqam olish (balansdan yechiladi)
ParametrMajburiyIzoh
countryha2 harfli ISO kod: US, CO, BD…
max_priceyo'qSo'mda. Narx bundan oshib ketsa xarid qilinmaydi (PRICE_TOO_HIGH). Tavsiya etiladi.
request_idyo'qSizning buyurtma ID ingiz (1–56 belgi: A-Z a-z 0-9 . _ -). Shu ID bilan qayta yuborilsa pul ikkinchi marta yechilmaydi, avvalgi natija qaytadi ("duplicate": true). Har doim yuboring!
// 200 β€” raqam berildi
{"ok": true, "balance": 121100.0, "id": 4521, "status": "wait", "country": "US",
 "phone": "+15550142387", "price": 4300, "created_at": "2026-11-17 10:21:05"}

// 202 β€” raqam holati aniqlanmoqda (tarmoq uzilishi): shu id ni /numbers/{id} bilan so'rang
{"ok": true, "id": 4522, "status": "pending", "phone": null, ...}
GET/numbers/{id} β€” raqam holati va kod
// kod kutilmoqda
{"ok": true, "id": 4521, "status": "wait", "phone": "+15550142387", "expires_in": 1640, ...}
// kod keldi
{"ok": true, "id": 4521, "status": "ok", "phone": "+15550142387", "code": "48213", "password": "…", ...}

password β€” faqat akkauntda 2 bosqichli parol bo'lsa. expires_in β€” kod kutishning qolgan soniyalari. Provayder 5 soniyada ko'pi bilan bir marta tekshiriladi β€” tezroq so'rash foyda bermaydi.

GET/numbers?limit=20 β€” oxirgi raqamlaringiz (limit ≀ 100)
{"ok": true, "numbers": [{"id": 4521, "status": "ok", "country": "US", "phone": "+1…", "price": 4300, "code": "48213", ...}]}

🚦 Raqam holatlari

statusMa'nosiNima qilish kerak
pendingRaqam holati aniqlanmoqdaKuting, /numbers/{id} ni so'rashda davom eting. Raqam keladi yoki pul qaytadi.
waitRaqam berildi, kod kutilmoqdaRaqamni Telegram'ga kiriting, har 5–10 s da so'rang.
okKod keldicode (va password) ni ishlating. Tugadi βœ…
expired30 daqiqada kod kelmadiPul qaytmaydi (pastga qarang). So'rashni to'xtating.
refundedPul balansga qaytarilganYangi raqam oling.
failedXatoSo'rashni to'xtating, kerak bo'lsa yangi raqam oling.

⚠️ Xato kodlari

Xato javobi: {"ok": false, "error": "KOD", "message": "tushuntirish"}. Dasturingizda error kodiga qarab ish tuting (message o'zgarishi mumkin).

errorHTTPSabab va yechim
BAD_KEY401Kalit noto'g'ri yoki eskirgan β†’ yangi kalitni tekshiring.
DISABLED403Hamkorlik o'chirilgan β†’ administratorga yozing.
RATE_LIMIT42910 soniyada 30 tadan ko'p so'rov β†’ biroz kuting, so'rovlarni kamaytiring.
NO_BALANCE402Balans yetmaydi (javobda balance, price) β†’ botda balansni to'ldiring.
NO_NUMBERS409Bu davlatda raqam yo'q β†’ boshqa davlat. refunded: true bo'lsa pul qaytarilgan.
PRICE_TOO_HIGH409Narx max_price dan oshdi (javobda price) β†’ narxni yangilab qaror qiling.
PRICE_CHANGED409Xarid paytida narx o'zgardi, pul qaytarildi β†’ qayta urinib ko'ring.
BAD_COUNTRY400country 2 harfli ISO kod emas.
BAD_MAX_PRICE400max_price musbat son emas.
BAD_REQUEST_ID400request_id formati noto'g'ri (1–56 belgi, A-Z a-z 0-9 . _ -).
NOT_FOUND404Raqam topilmadi yoki sizniki emas / bunday manzil yo'q.
SERVICE_UNAVAILABLE503Provayder javob bermayapti β†’ 1–2 daqiqadan so'ng qayta urining.
INTERNAL500Ichki xato β†’ qayta urining, takrorlansa administratorga yozing.

πŸ’» Kod namunalari

To'liq jarayon: balans β†’ raqam olish (request_id va max_price bilan) β†’ kodni kutish. KALIT o'rniga o'z kalitingizni qo'ying.

import time, uuid, requests

BASE = "https://sinovbot.c4461.orax1.vip/api/v1"
H = {"X-Api-Key": "KALIT"}

def api(method, path, **kw):
    r = requests.request(method, BASE + path, headers=H, timeout=60, **kw)
    return r.json()

print(api("GET", "/balance"))                      # {'ok': True, 'balance': ...}

order_id = "order-" + uuid.uuid4().hex[:12]        # o'z buyurtma ID ingiz
res = api("POST", "/numbers", data={"country": "US", "max_price": 6000, "request_id": order_id})
if not res["ok"]:
    raise SystemExit(f"Xato: {res['error']} - {res['message']}")

num_id = res["id"]
print("Raqam:", res.get("phone"))
for _ in range(200):                               # ~30 daqiqa
    time.sleep(8)
    st = api("GET", f"/numbers/{num_id}")
    if st.get("status") == "ok":
        print("KOD:", st["code"], "| 2FA:", st.get("password"))
        break
    if st.get("status") in ("expired", "refunded", "failed"):
        print("Tugadi:", st["status"]); break
<?php
const BASE = "https://sinovbot.c4461.orax1.vip/api/v1";
const KEY  = "KALIT";

function api($method, $path, $params = []) {
    $ch = curl_init(BASE . $path);
    curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 60,
        CURLOPT_HTTPHEADER => ["X-Api-Key: " . KEY], CURLOPT_CUSTOMREQUEST => $method]);
    if ($method === "POST") curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $res;
}

$res = api("POST", "/numbers", ["country" => "US", "max_price" => 6000,
                                "request_id" => "order-" . bin2hex(random_bytes(6))]);
if (!$res["ok"]) die("Xato: {$res['error']} - {$res['message']}");
echo "Raqam: {$res['phone']}\n";

for ($i = 0; $i < 200; $i++) {
    sleep(8);
    $st = api("GET", "/numbers/" . $res["id"]);
    if ($st["status"] === "ok") { echo "KOD: {$st['code']}\n"; break; }
    if (in_array($st["status"], ["expired", "refunded", "failed"])) { echo "Tugadi: {$st['status']}\n"; break; }
}
// Node.js 18+ (fetch o'rnatilgan)
const BASE = "https://sinovbot.c4461.orax1.vip/api/v1";
const H = { "X-Api-Key": "KALIT", "Content-Type": "application/json" };
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function api(method, path, body) {
  const r = await fetch(BASE + path, { method, headers: H, body: body ? JSON.stringify(body) : undefined });
  return r.json();
}

(async () => {
  const res = await api("POST", "/numbers", { country: "US", max_price: 6000,
                                              request_id: "order-" + Date.now() });
  if (!res.ok) throw new Error(`${res.error}: ${res.message}`);
  console.log("Raqam:", res.phone);
  for (let i = 0; i < 200; i++) {
    await sleep(8000);
    const st = await api("GET", `/numbers/${res.id}`);
    if (st.status === "ok") { console.log("KOD:", st.code); break; }
    if (["expired", "refunded", "failed"].includes(st.status)) { console.log("Tugadi:", st.status); break; }
  }
})();
# Balans
curl -H "X-Api-Key: KALIT" https://sinovbot.c4461.orax1.vip/api/v1/balance

# Davlatlar va narxlar
curl -H "X-Api-Key: KALIT" https://sinovbot.c4461.orax1.vip/api/v1/countries

# Raqam olish
curl -H "X-Api-Key: KALIT" -d "country=US" -d "max_price=6000" -d "request_id=order-1001" https://sinovbot.c4461.orax1.vip/api/v1/numbers

# Holat va kod (har 5-10 soniyada)
curl -H "X-Api-Key: KALIT" https://sinovbot.c4461.orax1.vip/api/v1/numbers/4521

βœ… To'g'ri ishlatish qoidalari

1. Har bir xaridda request_id yuboring. Internet uzilsa yoki javob kelmasa β€” xuddi shu request_id bilan qayta yuboring: pul ikki marta yechilmaydi, avvalgi raqam qaytadi.
2. max_price qo'ying. Kurs o'zgarsa siz kutmagan narxda xarid bo'lib ketmaydi.
3. Kodni 5–10 soniyada bir so'rang. Tezroq so'rash kodni tezlashtirmaydi va RATE_LIMIT ga olib keladi (10 soniyada 30 ta so'rov chegarasi).
4. Bir vaqtda ko'pi bilan 3 ta xarid. Ko'proq parallel so'rovlar navbatda turadi.
5. 202 (pending) javobini xato deb hisoblamang. Shu id ni so'rashda davom eting β€” raqam keladi yoki pul avtomatik qaytadi.
6. Raqamni olgach darhol ishlating. Raqamni rasmiy Telegram ilovasida ishlatmang. Kod kelishi 30 daqiqagacha kutiladi.
7. Balansni kuzating. NO_BALANCE kelishidan oldin /balance ni tekshirib, o'z vaqtida to'ldiring.

πŸ’° Pul qachon yechiladi va qaytadi

HolatPul
Raqam berilmadi (NO_NUMBERS, narx o'zgardi, provayder xatosi)βœ… Darhol avtomatik qaytadi
pending va raqam oxir-oqibat berilmadiβœ… Avtomatik qaytadi (refunded)
Raqam berildi, kod keldiXarid bajarildi
Raqam berildi, lekin 30 daqiqada kod kelmadi (expired)⚠️ Provayder pulni qaytarmaydi. Shuning uchun raqamni olgach darhol ishlating.

Narx = provayder narxi Γ— USD kursi + hamkor foizi, 100 so'mga yaxlitlanadi. Joriy narxlarni har doim /countries dan oling.

πŸ€– Botingiz nusxasi uchun (Moonum formati)

Agar sizda shu botning nusxasi bo'lsa, u bizning API'ga Moonum formatida ulanadi β€” kodni o'zgartirish shart emas. Nusxa botning .env fayliga:

MOONUM_API_URL=https://sinovbot.c4461.orax1.vip/api/v1/moonum
MOONUM_API_KEY=sk_…  (o'z kalitingiz)

Bu formatda narxlar USD da ko'rsatiladi (so'm Γ· bizdagi USD kursi), amallar: getBalance, getCountries, getNumber (country, max_price, request_id), getCode (id). Nusxa botda USD kursini bizdagi bilan bir xil qo'ying.

❓ Savol-javob

Kalitni yo'qotdim, nima qilay?
Botda Β«πŸ”Œ Hamkorlik APIΒ» β†’ Β«πŸ”„ Yangi kalitΒ». Eski kalit darhol o'chadi, yangisi bir marta ko'rsatiladi.
Narxlar botdagi narx bilan bir xilmi?
Narx hamkor foiziga qarab hisoblanadi (odatda botdagi Server 1 narxi bilan bir xil). Aniq narx β€” /countries javobida.
Javob kelmay qoldi (timeout) β€” pul yechildimi?
Xuddi shu request_id bilan qayta POST /numbers yuboring. Xarid bo'lgan bo'lsa o'sha raqam qaytadi (duplicate: true), bo'lmagan bo'lsa yangi xarid qilinadi. Pul ikki marta yechilmaydi.
Kod kelmadi, pulni qaytarib bera olasizmi?
Provayder kod kelmagan raqam uchun pulni qaytarmaydi, shu sababli avtomatik qaytarish yo'q. Alohida holatlar uchun buyurtma id si bilan administratorga yozing.
Bir nechta kalit yoki bot ulasam bo'ladimi?
Bitta akkauntga bitta kalit. Bir kalitni bir nechta bot/serverda ishlatish mumkin, lekin chegaralar (10 s da 30 so'rov, 3 ta parallel xarid) umumiy.
Balansni API orqali to'ldirsa bo'ladimi?
Yo'q, balans botning o'zida to'ldiriladi: Β«πŸ’³ Balansni to'ldirishΒ» (karta, avto to'lov yoki Telegram Stars).
Xizmat ishlayaptimi β€” qanday tekshiraman?
GET https://sinovbot.c4461.orax1.vip/api/v1/ping β€” kalitsiz ishlaydi.

Savollar bo'lsa β€” botdagi Β«πŸ’¬ Qo'llab-quvvatlashΒ» orqali yozing.

Nusxalandi