Partner API

Do'koningiz, botingiz yoki saytingiz mijozlari uchun Telegram Stars va Premium'ni HTTP orqali avtomatik sotib oling. Pul YuDrop hamyoningizdan darhol yechiladi, yetkazish odatdagidek avtomatik.

Qanday ulanish mumkin

Hamkorlik do'kon bilan kelishiladi: yordam chatiga yozing — chegirma va kunlik limit belgilanadi.
Kalit (yd_live_…) va webhook maxfiy kaliti bot orqali sizga yuboriladi. Bot'dagi /partner buyrug'i holatni ko'rsatadi.
Hamyonni odatdagidek ilovadan to'ldirasiz; har bir buyurtma narxi asosiy narxdan chegirmangizni ayirib hisoblanadi.

Avtorizatsiya

Har bir so'rovga sarlavha qo'shing: Authorization: Bearer <kalit>. Kalitni hech kimga bermang — u hamyoningizdan xarid qiladi. Yangi kalit kerak bo'lsa, do'konga yozing: eskisi darhol o'chadi.

https://tgstars.uz/partner/v1

So'rovlar

GET/partner/v1/me

Hamkor: balans, chegirma, bugungi xarid va limit, webhook.

GET/partner/v1/prices

Siz uchun narxlar: 1 Stars narxi, misollar, Premium davrlari.

POST/partner/v1/recipient

Qabul qiluvchini tekshirish: {"product", "username"}.

POST/partner/v1/orders

Buyurtma: {"product", "recipient", "quantity" | "months", "ref", "expected_amount"?}.

GET/partner/v1/orders

Buyurtmalar ro'yxati: ?limit=1..100&before=<id>.

GET/partner/v1/orders/{id}

Buyurtma holati.

GET/partner/v1/orders/ref/{ref}

Buyurtma o'z ref'ingiz bo'yicha.

POST/partner/v1/orders/{id}/refund

Kechikkan buyurtma pulini hamyonga qaytarish.

POST/partner/v1/webhook

Webhook manzili: {"url": "https://…" | null, "rotate_secret"?: true}.

Buyurtma berish

Stars uchun quantity — 50…100000; Premium uchun months — 3, 6, 12. ref — sizning buyurtma raqamingiz (1–64 belgi): bir xil ref bilan qayta yuborilgan so'rov o'sha buyurtmani qaytaradi va ikki marta sotib olmaydi (javob 200, created: false). Xuddi shu ref boshqa mahsulot/qabul qiluvchi/miqdor bilan kelsa — 409 ref_conflict. expected_amount — siz kutgan eng yuqori summa: narx undan oshsa, buyurtma yaratilmaydi (409 quote_changed). Qabul qiluvchi pul yechilishidan oldin Fragment orqali tekshiriladi.

curl -X POST https://tgstars.uz/partner/v1/orders \
  -H "Authorization: Bearer yd_live_…" \
  -H "Content-Type: application/json" \
  -d '{"product": "stars", "recipient": "@username", "quantity": 100, "ref": "shop-order-1001"}'

HTTP/1.1 201 Created
{"order": {"id": 1234, "ref": "shop-order-1001", "product": "stars", "recipient": "username", "quantity": 100,
  "amount": 22000, "currency": "UZS", "status": "processing", "created_at": "2026-10-28T12:00:00Z",
  "paid_at": "2026-10-28T12:00:00Z", "delivered_at": null}, "created": true}

Holatlar

processing

To'langan, yetkazilmoqda (odatda bir necha daqiqa).

delivered

Yetkazildi.

cancelled

Bekor qilindi; refunded: true bo'lsa pul hamyonga qaytgan. reason: recipient_not_found / already_premium / recipient_restricted (qabul qiluvchini tuzatib, yangi ref bilan qayta yuboring), refunded (kechikkani uchun qaytarildi) yoki cancelled.

expired / pending

To'lov yakunlanmagan buyurtma (kamdan-kam: masalan, so'rov to'xtab qolganda). O'sha ref bilan qayta yuboring — to'lov yakunlanadi.

Xatolar

Javob: {"error": "kod", "message": "…"}. 400 noto'g'ri so'rov · 401 kalit yo'q/noto'g'ri · 402 hamyonda pul yetmaydi (wallet_low) · 403 to'xtatilgan yoki kunlik limit · 404 topilmadi (recipient_not_found ham) · 409 ref_conflict / quote_changed / refund_too_early · 422 already_premium · 429 juda ko'p so'rov (Retry-After) · 503 xizmat vaqtincha ishlamayapti.

Webhook'lar

Hodisalar: order.delivered, order.cancelled, order.expired, order.delayed (to'langan, lekin kechikmoqda — /refund mumkin). Tanasi JSON: {"id", "event", "created_at", "order": {…}}. Imzo: X-YuDrop-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<body>")>. 2xx javob kelmaguncha 1 daq, 5 daq, 30 daq, 2 s, 6 s, 12 s va 24 s'dan keyin qayta yuboriladi; bir hodisa bir necha marta kelishi mumkin — X-YuDrop-Delivery (id) bo'yicha takrorni tashlang. Faqat https va ochiq serverlar; yo'naltirishlar (redirect) kuzatilmaydi.

Imzoni tekshirish (Python)

import hashlib, hmac, time

def verified(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
    parts = dict(item.split("=", 1) for item in header.split(","))
    stamp, signature = parts.get("t", ""), parts.get("v1", "")
    expected = hmac.new(secret.encode(), stamp.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature) and abs(time.time() - int(stamp or 0)) <= tolerance

Cheklovlar

Bitta kalitga daqiqasiga 120 o'qish va 60 yozish so'rovi (bir zumda 120 / 30 gacha). Noto'g'ri kalit bilan bitta manzildan daqiqasiga 20 urinish.