PayStars Unified API · v3.0
Bitta API.
StarKerak bilan bir xil balans.
Website, Telegram WebApp va tashqi API bir xil StarKerak narxlari, balans va fulfillment mexanizmidan foydalanadi. API javoblari JSON formatida.
Autentifikatsiya
Dashboard’da API kalit yarating. Kalit faqat bir marta to‘liq ko‘rsatiladi. Uni server environment’ida saqlang, frontend JavaScript yoki Git repository’ga yozmang.
X-API-Key: ps_your_secret_api_key Content-Type: application/json Idempotency-Key: order_20260719_0001
Limit, tekshiruv va idempotency
- Har bir API kalit uchun sekundiga 3 ta so‘rov.
- API orqali qabul qiluvchini tekshirish limiti: bir hisob uchun daqiqasiga 120 ta; website/WebApp uchun 12 ta.
- Xariddan oldin
/check-usernamechaqirilib, 180 soniyalikverification_tokenolinishi shart. - Har bir verification token faqat bitta mantiqiy buyurtmaga bog‘lanadi; ayni idempotency kaliti bilan xavfsiz retry mumkin.
- Stars va Premium xaridida 8–128 belgili noyob
Idempotency-Keyyuboring. - Bir xil
Idempotency-Keyva ayni payload qayta yuborilsa, yangi pul yechilmaydi; avvalgi buyurtma qaytadi. - Ayni idempotency kaliti boshqa payload bilan ishlatilsa
409 Conflictqaytadi.
API status
/statuscurl https://paystars.uz/api/v1/status
Balans va narxlar
Balans ham, narxlar ham bevosita StarKerak’dan olinadi.
/accountcurl https://paystars.uz/api/v1/account \
-H "X-API-Key: $PAYSTARS_API_KEY"{
"ok": true,
"user": { "telegram_id": 123456789, "balance": 250000 },
"pricing": {
"currency": "UZS",
"star_price": 215,
"premium_3_price": 160000,
"premium_6_price": 220000,
"premium_12_price": 400000
}
}/pricesFaqat joriy narx konfiguratsiyasini qaytaradi.
Username tekshirish
Bu endpoint Fragment orqali ism, rasm va Premium holatini aniqlaydi. verification_token faqat xarid qilish mumkin bo‘lgan qabul qiluvchi uchun qaytadi.
/check-usernamecurl -X POST https://paystars.uz/api/v1/check-username \ -H "X-API-Key: $PAYSTARS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"username":"telegram","kind":"premium"}'
{
"valid": true,
"username": "telegram",
"nickname": "Telegram User",
"photo_url": "https://cdn4.telesco.pe/...",
"premium_active": false,
"verification_token": "...",
"verification_expires_in": 180
}kind qiymati stars yoki premium. Agar Premium mavjud bo‘lsa, premium_active: true, valid: false va token null bo‘ladi.
Stars buyurtma
/stars/buycurl -X POST https://paystars.uz/api/v1/stars/buy \ -H "X-API-Key: $PAYSTARS_API_KEY" \ -H "Idempotency-Key: order_20260719_0001" \ -H "Content-Type: application/json" \ -d '{"username":"telegram","quantity":100,"verification_token":"TOKEN_FROM_CHECK"}'
{
"ok": true,
"order_id": 1842,
"status": "processing",
"cost": 21500,
"balance": 228500,
"currency": "UZS"
}Buyurtmalar
/ordersWeb, WebApp va API orqali berilgan so‘nggi 50 ta buyurtmani qaytaradi.
/order/{order_id}curl https://paystars.uz/api/v1/order/1842 \
-H "X-API-Key: $PAYSTARS_API_KEY"Xatoliklar
| Status | Ma’nosi | Tavsiya |
|---|---|---|
| 400 | Payload yoki idempotency kalit xato | So‘rov formatini tekshiring |
| 401 | API kalit yaroqsiz | Yangi kalit yarating |
| 402 | StarKerak balans yetarli emas | Balansni to‘ldiring |
| 409 | Verification eskirgan/ishlatilgan yoki idempotency konflikti | Qabul qiluvchini qayta tekshiring |
| 422 | Username yoki xizmat mavjud emas | Qabul qiluvchini tekshiring |
| 429 | So‘rov limiti oshdi | Retry-After bo‘yicha qaytaring |
| 503 | Xizmat vaqtincha mavjud emas | Exponential backoff ishlating |
{
"detail": {
"code": "insufficient_balance",
"message": "StarKerak balance is insufficient"
}
}Ishlaydigan namunalar
Turli dasturlash tillarida
Har bir namuna qabul qiluvchini tekshiradi, qisqa muddatli tokenni oladi va ayni buyurtmani xavfsiz retry qilish uchun idempotency kalit ishlatadi.
API="https://paystars.uz/api/v1"
ORDER_KEY="stars_$(uuidgen)"
VERIFY=$(curl --fail-with-body -sS -X POST "$API/check-username" \
-H "X-API-Key: $PAYSTARS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"username":"telegram","kind":"stars"}')
TOKEN=$(printf '%s' "$VERIFY" | jq -r '.verification_token')
curl --fail-with-body -sS -X POST "$API/stars/buy" \
-H "X-API-Key: $PAYSTARS_API_KEY" \
-H "Idempotency-Key: $ORDER_KEY" \
-H "Content-Type: application/json" \
-d "{\"username\":\"telegram\",\"quantity\":100,\"verification_token\":\"$TOKEN\"}"import { randomUUID } from 'node:crypto';
const base = 'https://paystars.uz/api/v1';
const headers = { 'X-API-Key': process.env.PAYSTARS_API_KEY, 'Content-Type': 'application/json' };
const verify = await fetch(`${base}/check-username`, {
method: 'POST', headers, body: JSON.stringify({ username: 'telegram', kind: 'stars' })
}).then(async r => { if (!r.ok) throw new Error(await r.text()); return r.json(); });
const order = await fetch(`${base}/stars/buy`, {
method: 'POST', headers: { ...headers, 'Idempotency-Key': `stars_${randomUUID()}` },
body: JSON.stringify({ username: verify.username, quantity: 100, verification_token: verify.verification_token })
}).then(async r => { if (!r.ok) throw new Error(await r.text()); return r.json(); });
console.log(order.order_id, order.status);import os, uuid, requests
base = "https://paystars.uz/api/v1"
headers = {"X-API-Key": os.environ["PAYSTARS_API_KEY"]}
verify = requests.post(f"{base}/check-username", headers=headers,
json={"username": "telegram", "kind": "premium"}, timeout=15)
verify.raise_for_status()
recipient = verify.json()
order = requests.post(f"{base}/premium/buy", headers={
**headers, "Idempotency-Key": f"premium_{uuid.uuid4()}"
}, json={"username": recipient["username"], "months": 3,
"verification_token": recipient["verification_token"]}, timeout=20)
order.raise_for_status()
print(order.json())<?php
$base = 'https://paystars.uz/api/v1';
$key = getenv('PAYSTARS_API_KEY');
function postJson($url, $headers, $body) {
$ch = curl_init($url);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true,
CURLOPT_HTTPHEADER => $headers, CURLOPT_POSTFIELDS => json_encode($body), CURLOPT_TIMEOUT => 20]);
$raw = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch);
if ($status < 200 || $status >= 300) throw new RuntimeException($raw);
return json_decode($raw, true, flags: JSON_THROW_ON_ERROR);
}
$common = ["X-API-Key: $key", 'Content-Type: application/json'];
$user = postJson("$base/check-username", $common, ['username' => 'telegram', 'kind' => 'stars']);
$order = postJson("$base/stars/buy", [...$common, 'Idempotency-Key: stars_'.bin2hex(random_bytes(16))],
['username' => $user['username'], 'quantity' => 100, 'verification_token' => $user['verification_token']]);
print_r($order);package main
import ("bytes"; "encoding/json"; "fmt"; "io"; "net/http"; "os"; "github.com/google/uuid")
func post(path string, body any, idempotency string, out any) error {
data, _ := json.Marshal(body)
req, _ := http.NewRequest("POST", "https://paystars.uz/api/v1"+path, bytes.NewReader(data))
req.Header.Set("X-API-Key", os.Getenv("PAYSTARS_API_KEY")); req.Header.Set("Content-Type", "application/json")
if idempotency != "" { req.Header.Set("Idempotency-Key", idempotency) }
res, err := http.DefaultClient.Do(req); if err != nil { return err }; defer res.Body.Close()
if res.StatusCode >= 300 { raw, _ := io.ReadAll(res.Body); return fmt.Errorf("API %d: %s", res.StatusCode, raw) }
return json.NewDecoder(res.Body).Decode(out)
}
func main() {
var user struct { Username string `json:"username"`; VerificationToken string `json:"verification_token"` }
if err := post("/check-username", map[string]any{"username":"telegram", "kind":"stars"}, "", &user); err != nil { panic(err) }
var order map[string]any
if err := post("/stars/buy", map[string]any{"username":user.Username, "quantity":100,
"verification_token":user.VerificationToken}, "stars_"+uuid.NewString(), &order); err != nil { panic(err) }
fmt.Println(order)
}Bir prompt bilan integratsiya
AI Prompt
Quyidagi promptni Codex, ChatGPT yoki boshqa coding agent’ga yuboring. Qavs ichidagi qiymatlarni loyihangizga moslang.
Sen senior backend va application-security muhandisisan. Menga PayStars API bilan to‘liq, production-ready integratsiya yarat.
LOYIHA TURI: [Telegram bot / web backend / mobil ilova backend]
TIL VA FRAMEWORK: [masalan: Python 3.12 + aiogram 3 + FastAPI]
LOYIHA NOMI: [nom]
PayStars base URL: https://paystars.uz/api/v1
API kalitni faqat PAYSTARS_API_KEY environment o‘zgaruvchisidan ol. Uni frontendga, logga, Git’ga yoki xatolik matniga chiqarmagin. Barcha so‘rovlar HTTPS va server tomondan bo‘lsin. Timeout, structured logging (secretsiz), input validation va testlar qo‘sh.
Quyidagi oqimni to‘liq amalga oshir:
1. GET /account orqali StarKerak balans va joriy narxlarni ol; qiymatlarni lokal hardcode qilma.
2. Stars yoki Premium xarididan oldin POST /check-username ga {"username":"...","kind":"stars|premium"} yubor.
3. Javobdagi valid, nickname, photo_url, premium_active va verification_token ni tekshir. Foydalanuvchiga rasm, ism, @username va Premium holatini ko‘rsatib, alohida tasdiq ol. Tasdiqsiz order yaratma.
4. verification_token 180 soniya amal qiladi. Eskirsa yoki 409 qaytsa username’ni qayta tekshir.
5. Stars uchun POST /stars/buy ga username, quantity va verification_token; Premium uchun POST /premium/buy ga username, months (3, 6 yoki 12) va verification_token yubor.
6. Har mantiqiy buyurtma uchun kriptografik UUID asosidagi 8–128 belgili Idempotency-Key yarat. Network retry’da aynan o‘sha kalit va payloadni qayta ishlat; boshqa buyurtmada qayta ishlatma.
7. GET /order/{order_id} orqali holatni polling qil va GET /orders orqali tarixni ko‘rsat. processing/pending/completed/failed holatlarini to‘g‘ri boshqar.
8. API limiti har kalitga sekundiga 3 so‘rov. 429 da Retry-After’ni hurmat qil; 503 va vaqtinchalik network xatolarida jitter bilan bounded exponential backoff ishlat. 400, 401, 402, 409, 422, 429 va 503 uchun foydalanuvchiga xavfsiz, tushunarli xabar ber.
9. API javoblariga ishonib ketma: schema bo‘yicha tekshir, username’ni normalizatsiya qil, quantity/months limitini server tomonda tekshir. photo_url ni faqat ruxsat etilgan HTTPS rasm sifatida ko‘rsat. Hech qachon verification token, API key yoki to‘liq request header’larni loglama.
10. Bir foydalanuvchining parallel bosishlari, replay, duplicate order, forged callback, race condition, timeout va process restart holatlarini hisobga ol. Holatni bazada tranzaksiya bilan saqla va foydalanuvchi tasdig‘ini order bilan bog‘la.
Agar loyiha Telegram bot bo‘lsa: /start, “Stars olish”, “Premium olish”, “Balans”, “Buyurtmalar” menyularini yarat; username va miqdorni bosqichma-bosqich ol; tekshiruv natijasidan keyin inline “Tasdiqlash/Bekor qilish” tugmalarini ko‘rsat; callback ownership va TTL’ni tekshir; webhook secret yoki long-polling xavfsizligini sozla.
Natijada pseudo-code emas, ishga tushadigan to‘liq kod ber: aniq papka tuzilmasi, dependency fayli, .env.example (real secretsiz), database migration, Dockerfile, healthcheck, README, lokal ishga tushirish va deploy ko‘rsatmalari, unit/integration testlar. API client’ni alohida modul qil. Barcha narx, balans va order uchun PayStars API’ni yagona source of truth deb ol; StarKerak bazasiga to‘g‘ridan-to‘g‘ri ulanma. Yetishmayotgan biznes qiymatlarini avval qisqa ro‘yxatda so‘ra, qolgan texnik qarorlarni xavfsiz default bilan o‘zing yakunla.