Sam Stars APIDeveloper documentation
SOURCE-BASED · v2.1
SAM STARS · API REFERENCE

API bilan integratsiyani
aniq va oson boshlang.

Sam Stars platformasining API metodlari, parametrlar, xizmat IDlari va javob formatlari bo‘yicha dasturchilar uchun rasmiy qo‘llanma.

Base URL: /api/v2JSON responseCurrency: UZSv2.1 docs
Qo‘llanma haqida: bu sahifa statik hujjat bo‘lib, API bilan integratsiya qilish tartibini tushuntiradi. Buyurtmalar va hisob amallari API serverida bajariladi.
Xavfsizlik: API kalit va maxfiy tokenlarni sir saqlang. Ularni ommaviy kod, brauzer JavaScripti, GitHub yoki skrinshotlarda joylashtirmang. Kalit oshkor bo‘lsa, uni yangisiga almashtiring.

Autentifikatsiya

API key

Har bir action uchun key parametri kerak. Server API kalitni tekshiradi va faol hisobga tegishli ekanini tasdiqlaydi.

ParametrTurMajburiyIzoh
keystringHaFoydalanuvchining API kaliti.

Kalitni ommaviy frontend JavaScript, GitHub yoki skrinshotlarda oshkor qilmang.

So‘rov formati

HTTP request

Asosiy manzil:

POSThttps://samnomer.uz/api/v2

Kod $_REQUEST dan parametr o‘qiydi; texnik jihatdan PHP sozlamalariga qarab GET yoki POST orqali kelishi mumkin. Integratsiyada maxfiy API kalitni URL loglariga tushirmaslik uchun POST ishlatish tavsiya etiladi.

FORM URLENCODED
POST /api/v2
Content-Type: application/x-www-form-urlencoded

key=YOUR_API_KEY&action=balance

Javoblar application/json; charset=utf-8 formatida qaytariladi. Xato javobining umumiy ko‘rinishi:

JSON ERROR
{ "error": "Incorrect API key" }

Balansni tekshirish

action=balance
POST/api/v2

API kalit egasining joriy balansini UZS da qaytaradi.

ParametrTurMajburiy
keystringHa
actionstringHa: balance
SUCCESS RESPONSE
{
  "balance": 150000,
  "currency": "UZS"
}

Javobdagi balance maydoni hisobning joriy mablag‘ini bildiradi.

Xizmatlar ro‘yxati

action=services

Mavjud xizmatlarni va ularning joriy narxlarini qaytaradi. Narxlar tashqi provayder narxlari, ustama foizlar va IMO paketlari jadvalidan shakllantiriladi.

ParametrTurMajburiy
keystringHa
actionstringHa: services

Javob elementlari:

MaydonMa’nosi
serviceXizmat ID raqami.
nameXizmat nomi.
typeDefault yoki Package.
categoryTelegram, PUBG, Gift yoki IMO.
rateUshbu koddagi narx; UZS.
min, maxBuyurtma miqdori chegarasi sifatida ko‘rsatiladi.
SAMPLE RESPONSE
[
  {
    "service": 1,
    "name": "Telegram Stars",
    "type": "Default",
    "category": "Telegram",
    "rate": 209,
    "min": 50,
    "max": 10000
  }
]

Bu faqat namunaviy obyekt. Amaldagi ro‘yxat narxlar va faol IMO paketlariga qarab o‘zgarishi mumkin.

Buyurtma berish

action=add

Bu metod Stars, Premium, PUBG UC, Telegram Gift va IMO paketlari uchun ishlatiladi. Har bir turda link maydonining mazmuni farq qiladi.

ParametrTurMajburiyIzoh
keystringHaFaol API kalit.
actionstringHaadd
serviceintegerHaservices action qaytargan ID.
linkstringHaUsername, PUBG ID yoki IMO ID.
quantityintegerStars uchun haStars miqdori. Boshqa turlarda kod bu parametrdan foydalanmaydi.

Buyurtma misollari

Telegram Stars — service=1, username @ belgisiz ham qabul qilinadi, minimum 50 Stars.

STARS REQUEST
key=YOUR_API_KEY
action=add
service=1
link=telegram_username
quantity=100

Telegram Premium — service=2 (3 oy), service=3 (6 oy), service=4 (12 oy). link — Telegram username.

PREMIUM REQUEST
key=YOUR_API_KEY
action=add
service=2
link=telegram_username

PUBG UC — service ID 10 dan boshlanadi; keyingi IDlar provayder qaytargan tariflar tartibida belgilanadi. link — 6–12 xonali PUBG account ID.

PUBG UC REQUEST
key=YOUR_API_KEY
action=add
service=10
link=123456789

Telegram Gift — service ID 100–104. link — qabul qiluvchi Telegram username.

GIFT REQUEST
key=YOUR_API_KEY
action=add
service=100
link=telegram_username

IMO olmos — service ID 200 + imo_packages.id. link — IMO ID (raqamlar ko‘rinishida, kamida 5 raqam).

IMO REQUEST
key=YOUR_API_KEY
action=add
service=201
link=1234567890

Muvaffaqiyatli javob:

SUCCESS RESPONSE
{
  "order": 12345,
  "charge": 35000,
  "currency": "UZS"
}

order — ichki buyurtma ID; charge — yechilgan summa. Ichki ID turli buyurtma jadvallaridan kelishi mumkin.

Buyurtma holati

action=status

Metod order parametrini qabul qiladi va buyurtma holati haqidagi JSON javobni qaytaradi.

ParametrTurMajburiy
keystringHa
actionstringHa: status
orderinteger/stringHa
CURRENT CODE RESPONSE
{
  "order": 12345,
  "status": "Completed",
  "charge": "0.00",
  "currency": "UZS"
}
Diqqat: hozirgi API versiyasida status metodi haqiqiy bajarilish holatini tekshirmaydi. U so‘rovdagi order raqamini qaytarib, Completed va charge: 0.00 qiymatlarini beradi. Shu sababli bu javob buyurtma amalda bajarilganini tasdiqlamaydi. Buyurtma holatini ishonchli tekshirish uchun status funksiyasi yangilanishi kerak.

SMS davlatlari ro‘yxati

action=available_countries

Moonum provayderidan server=1 bo‘yicha davlatlarni oladi, narxni so‘mdagi kurs va 10% ustama bilan hisoblaydi hamda narx bo‘yicha saralaydi.

ParametrTurMajburiy
keystringHa
actionstringHa: available_countries
RESPONSE SHAPE
[
  {
    "country": "Uzbekistan",
    "iso": "UZ",
    "price": 15000,
    "currency": "UZS"
  }
]

Virtual raqam olish

action=get_number

Tanlangan ISO davlat kodi bo‘yicha raqam so‘raydi. Mablag‘ yetarli bo‘lsa, balansdan narxni ayiradi va SMS buyurtmasini saqlaydi.

ParametrTurMajburiy
keystringHa
actionstringHa: get_number
countrystringHa — ISO kodi, masalan UZ
SUCCESS RESPONSE
{
  "number": "+998XXXXXXXXX",
  "hash_code": "PROVIDER_NUMBER_ID",
  "price": 15000,
  "currency": "UZS",
  "balance_left": 135000
}

hash_code keyingi get_sms so‘rovida ishlatiladi. Raqam va hash qiymatlari provayderdan keladi.

SMS kodini olish

action=get_sms

Oldin olingan raqam uchun Moonum provayderidan SMS kodini tekshiradi.

ParametrTurMajburiy
keystringHa
actionstringHa: get_sms
hash_codestringHa

Kod hali kelmagan bo‘lsa:

WAITING
{ "status": "waiting" }

Kod kelgan bo‘lsa:

READY
{
  "status": "ready",
  "code": "12345",
  "password": ""
}

Kod kelganda tegishli sms_orders yozuvi done holatiga o‘tkaziladi.

Service ID xaritasi

add uchun
IDXizmatlink maydoniquantity
1Telegram StarsTelegram usernameStars miqdori, min 50
2Premium 3 oyTelegram usernameIshlatilmaydi
3Premium 6 oyTelegram usernameIshlatilmaydi
4Premium 12 oyTelegram usernameIshlatilmaydi
10+PUBG UC tariflariPUBG account ID (6–12 raqam)Ishlatilmaydi
100–104Telegram GiftTelegram usernameIshlatilmaydi
200 + package idIMO olmosIMO ID (kamida 5 raqam)Ishlatilmaydi
Dinamik IDlar: PUBG UC tariflari ID 10 dan boshlab provayder qaytargan tartibda belgilanadi. IMO ID esa imo_packages jadvalidagi paket ID ga bog‘liq. Integratsiya dasturi service ID ni taxmin qilmasin — avval services action orqali ro‘yxatni olsin.

Gift ID va yulduz miqdori

Service IDGift narxi (Stars)
10015
10115
10225
10325
10450

Kod namunalari

Copy & adapt

Misollar amaldagi request shakliga mos. API kalitni backend/server muhitida saqlang. Frontend brauzerga maxfiy kalitni joylamang.

PHP · cURL
<?php
$apiUrl = 'https://samnomer.uz/api/v2';
$apiKey = getenv('SAMSTARS_API_KEY'); // kalitni env orqali bering

function samStarsRequest(string $action, array $params = []): array {
    global $apiUrl, $apiKey;

    $post = array_merge($params, [
        'key' => $apiKey,
        'action' => $action
    ]);

    $ch = curl_init($apiUrl);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($post),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HTTPHEADER => ['Content-Type: application/x-www-form-urlencoded']
    ]);

    $raw = curl_exec($ch);
    if ($raw === false) {
        $error = curl_error($ch);
        curl_close($ch);
        throw new RuntimeException('Network error: ' . $error);
    }

    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $data = json_decode($raw, true);
    if (!is_array($data)) {
        throw new RuntimeException('API JSON emas qaytardi. HTTP ' . $httpCode);
    }
    return $data;
}

// Balans
$balance = samStarsRequest('balance');
print_r($balance);

// Xizmatlar ro‘yxati
$services = samStarsRequest('services');
print_r($services);

// 100 ta Stars buyurtmasi
$order = samStarsRequest('add', [
    'service' => 1,
    'link' => 'telegram_username',
    'quantity' => 100
]);
print_r($order);
PYTHON · requests
import os
import requests

API_URL = "https://samnomer.uz/api/v2"
API_KEY = os.environ["SAMSTARS_API_KEY"]

def samstars_request(action, **params):
    payload = {"key": API_KEY, "action": action, **params}
    response = requests.post(API_URL, data=payload, timeout=30)
    response.raise_for_status()
    data = response.json()
    if isinstance(data, dict) and "error" in data:
        raise RuntimeError(data["error"])
    return data

print(samstars_request("balance"))
print(samstars_request("services"))
print(samstars_request(
    "add", service=1, link="telegram_username", quantity=100
))
NODE.JS · fetch
const API_URL = "https://samnomer.uz/api/v2";
const API_KEY = process.env.SAMSTARS_API_KEY;

async function samStarsRequest(action, params = {}) {
  const body = new URLSearchParams({
    key: API_KEY,
    action,
    ...Object.fromEntries(
      Object.entries(params).map(([k, v]) => [k, String(v)])
    )
  });

  const response = await fetch(API_URL, {
    method: "POST",
    headers: {"Content-Type": "application/x-www-form-urlencoded"},
    body
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  const data = await response.json();
  if (data && data.error) throw new Error(data.error);
  return data;
}

// Server-side Node.js misoli:
const balance = await samStarsRequest("balance");
console.log(balance);
cURL
# Balans
curl -X POST "https://samnomer.uz/api/v2" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "action=balance"

# Xizmatlar
curl -X POST "https://samnomer.uz/api/v2" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "action=services"

# 100 Stars buyurtma
curl -X POST "https://samnomer.uz/api/v2" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "action=add" \
  --data-urlencode "service=1" \
  --data-urlencode "link=telegram_username" \
  --data-urlencode "quantity=100"

Xatolar va javoblar

Error reference
ErrorQachon qaytadi
API key requiredkey berilmagan.
Incorrect API keyAPI kalit topilmadi yoki faol emas.
Invalid API keyAyrim actionlarda kalit tekshiruvi muvaffaqiyatsiz.
service and link requiredadd da service yoki link yo‘q.
Not enough fundsBalans buyurtma narxiga yetmaydi.
Minimum 50 StarsStars quantity 50 dan kam.
Invalid PUBG IDPUBG ID 6–12 raqam talabiga mos emas.
UC tariff not foundBerilgan UC service ID topilmadi.
Gift not foundGift ID tanilmagan.
IMO package not foundIMO paketi faol emas yoki topilmadi.
Invalid IMO IDIMO ID kamida 5 raqam bo‘lishi kerak.
country (ISO code) requiredget_number uchun country yo‘q.
Country not foundISO davlat kodi provayder ro‘yxatida topilmadi.
hash_code requiredget_sms uchun hash_code berilmagan.
Provider errorMoonum davlatlar so‘rovi muvaffaqiyatsiz.
Order failedBuyurtma provider/ichki amalda muvaffaqiyatli deb belgilanmagan.
Invalid action or missing parametersAction noma’lum yoki kerakli parametrlar yetishmaydi.

Muhim texnik cheklovlar

Source audit
  • Status action: hozircha real buyurtma holatini tekshirmaydi; doim Completed qaytaradi. Real holat uchun backendni yangilash kerak.
  • Buyurtma ID: Stars, Premium, UC, Gift va IMO yozuvlari turli jadvallarga yoziladi. API javobidagi order ichki ID; hozirgi status action bu ID ni tekshirmaydi.
  • UC service ID: xizmatlar ro‘yxatidagi tariflar tartibiga bog‘liq, shuning uchun ID ni doim services javobidan oling.
  • IMO service ID: 200 + imo_packages.id; paketlar ma’lumotlar bazasidagi faol yozuvlarga bog‘liq.
  • quantity: faqat Stars xaridida ishlatiladi. Premium, UC, Gift va IMO buyurtmalarida bu parametr talab qilinmaydi.
  • Qo‘shimcha metodlar: refund, refill, cancel, webhook, pagination, OAuth va API logs metodlari ushbu API versiyasida dokumentatsiya qilinmagan va qo‘llab-quvvatlanadigan funksiyalar sifatida taqdim etilmaydi.
  • SMS balans: get_number o‘z javobida balance_left qaytaradi; get_sms esa waiting yoki ready javobini qaytaradi.
  • Production xavfsizligi: integratsiya serverida HTTPS sertifikat tekshiruvini yoqilgan holda saqlang. Balansdan pul yechish va buyurtma yaratish amallari takroriy so‘rovlarda ikki marta bajarilmasligi uchun atomar tarzda himoyalanishi kerak.