# OP-tarmoq — Publisher API

Bazaviy manzil (jonli): **https://api2.auronsmm.com** — faqat API (`/api/v1/*`, kodsiz `/op/*`, Swagger `/api/docs`); panel: **https://op.auronsmm.com**
Autentifikatsiya: har soʻrovda `X-Api-Key: pub_xxxxxxxx` sarlavhasi.
Kalitni panelda **Publisher → yaratish** boʻlimidan olasiz.

Umumiy qoidalar:

- Barcha javoblar JSON (UTF-8).
- Pul — butun **soʻm** (`UZS`), kasr yoʻq.
- Vaqt — server UTC.
- Rate limit: **soniyada 30 soʻrov** har kalit uchun (token bucket). Oshsa `429`.

## Xato kodlari

| HTTP | Sabab |
|------|-------|
| 401 | `X-Api-Key` yoʻq yoki notoʻgʻri |
| 403 | Publisher `paused` (admin toʻxtatgan yoki sifat avto-pauzasi) |
| 422 | Validatsiya xatosi (`user_id` yoʻq, notoʻgʻri tur) |
| 429 | Rate limit |
| 5xx | Server xatosi — 1-2 soniyadan keyin qayta urinib koʻring |

Xato tanasi: `{"detail": "Sabab"}`.

---

## 1. `GET /api/v1/tasks`

Foydalanuvchiga koʻrsatiladigan obuna vazifalarini qaytaradi.

Parametrlar:

| Nom | Tur | Standart | Izoh |
|-----|-----|----------|------|
| `user_id` | int | — | Telegram foydalanuvchi id (majburiy) |
| `lang` | str | `uz` | `uz` / `ru` / boshqa → `en` |
| `premium` | 0/1 | 0 | Foydalanuvchi Telegram Premium/bot premiumimi |
| `limit` | int | 3 | 1..10 |

```bash
curl -H "X-Api-Key: pub_xxx" \
  "$BASE_URL/api/v1/tasks?user_id=55&lang=uz&premium=0&limit=3"
```

```json
{
  "tasks": [
    {
      "task_id": "c12-u55",
      "campaign_id": 12,
      "chat_id": -1001234567890,
      "title": "Kanal nomi",
      "url": "https://t.me/kanal",
      "price_pub": 650
    }
  ],
  "ttl": 600
}
```

Tanlash mantiqi (server tomonida):

1. `type=sub`, `status=active`, kanali tasdiqlangan kampaniyalar.
2. Budjet (kunlik va umumiy) va reklama beruvchi balansi yetarli.
3. Til va `premium_only` filtri mos.
4. Foydalanuvchi shu kampaniyani **oxirgi 30 kunda** bajarmagan.
5. Foydalanuvchining kunlik limiti (`MAX_TASKS_PER_USER_PER_DAY`) toʻlmagan.
6. Tarmoq boti `getChatMember` bilan tekshiradi: foydalanuvchi **allaqachon aʼzo boʻlsa vazifa berilmaydi** (bepul obuna sotilmaydi).
7. Tartib: narx boʻyicha kamayish, teng boʻlsa tasodifiy.

`ttl` — vazifalar amal qilish muddati (sekund). Undan keyin qayta soʻrang.

## 2. `POST /api/v1/check`

Foydalanuvchi obuna boʻldimi — tekshiradi va pulni **hold** ga yozadi.

```bash
curl -X POST -H "X-Api-Key: pub_xxx" -H "Content-Type: application/json" \
  -d '{"user_id": 55, "task_ids": ["c12-u55"]}' \
  "$BASE_URL/api/v1/check"
```

```json
{
  "results": [{"task_id": "c12-u55", "ok": true, "status": "hold"}],
  "all_ok": true
}
```

`status` qiymatlari:

| status | maʼnosi |
|--------|---------|
| `hold` | Konversiya yozildi, pul hold da (`HOLD_DAYS` kun) |
| `settled` / `clawback` | Dublikat: shu kampaniya shu foydalanuvchi uchun avval yozilgan (pul qayta yozilmaydi) |
| `not_member` | Foydalanuvchi kanalda emas |
| `no_funds` | Reklama beruvchi balansi tugadi, kampaniya toʻxtatildi |
| `not_found` | Kampaniya/kanal topilmadi |
| `invalid` | `task_id` formati notoʻgʻri yoki boshqa foydalanuvchiniki |
| `check_failed` | Telegram API vaqtincha javob bermadi — keyinroq qayta tekshiring |

Muhim: `task_id` ichida foydalanuvchi id bor (`c12-u55`), shuning uchun soʻrovdagi `user_id` mos kelishi shart.

## 3. `GET /api/v1/ads`

CPM (`type=post`) kampaniyalaridan reklama.

```bash
curl -H "X-Api-Key: pub_xxx" "$BASE_URL/api/v1/ads?user_id=55&lang=uz&limit=1"
```

```json
{"ads": [{"ad_id": "p7-u55", "campaign_id": 7, "text": "...", "url": "https://t.me/...", "button": "Oʻtish"}]}
```

Bir reklama bir foydalanuvchiga **24 soatda bir marta** beriladi.

## 4. `POST /api/v1/ads/impression`

Koʻrsatuvni qayd etadi. Pul shu yerda hisoblanadi: `CPM / 1000` reklama
beruvchidan darhol yechiladi (hold yoʻq), publisherga ulush **available** ga
qoʻshiladi.

```json
{"ad_id": "p7-u55", "user_id": 55}
```
→ `{"ok": true, "status": "counted", "charged": 10, "earned": 7}`

Bir soat ichidagi takroriy koʻrsatuv `{"ok": true, "status": "duplicate", "charged": 0}` qaytaradi.

## 5. `POST /api/v1/ads/click`

Faqat statistika: `{"ad_id": "p7-u55", "user_id": 55}` → `{"ok": true, "status": "counted"}`.

## 6. `GET /api/v1/stats`

`?from=YYYY-MM-DD&to=YYYY-MM-DD` (standart: oxirgi 7 kun).

```json
{
  "days": [{"date": "2026-09-05", "shown": 120, "passed": 80, "hold": 80,
            "settled": 60, "clawback": 5, "earned": 52000, "ads": 300}],
  "totals": {"hold": 20, "settled": 60, "clawback": 5,
             "earned_hold": 13000, "earned_total": 39000, "quality": 92}
}
```

## 7. `GET /api/v1/me`

Publisher maʼlumoti va balans:

```json
{
  "publisher": {"id": 3, "name": "Saver bot", "bot_username": "mybot",
                "status": "active", "quality_score": 0.95},
  "balance": {"pending": 13000, "available": 39000, "locked": 0, "currency": "UZS"},
  "totals": {"settled": 60, "clawback": 5, "quality": 92},
  "share": 0.65,
  "min_payout": 100000
}
```

---

# Kodsiz rejim (`/op/<api_key>`)

Agar botga kod yozishni xohlamasangiz — foydalanuvchini shu havolaga yuboring:

```
BASE_URL/op/<api_key>?uid=<telegram_user_id>&back=https://t.me/<bot>?start=opdone
```

| Parametr | Izoh |
|----------|------|
| `uid` | Telegram foydalanuvchi id (majburiy) |
| `back` | Tekshiruvdan keyin qaytish havolasi (ixtiyoriy) |
| `lang` | `uz` / `ru` / `en` (ixtiyoriy) |
| `premium` | 0/1 (ixtiyoriy) |

Sahifa mobil uchun moslashgan: kanallar roʻyxati + «Tekshirish» tugmasi.
Tugma bosilganda JS `POST /op/<api_key>/check` chaqiradi:

```json
{"uid": 55, "task_ids": ["c12-u55"]}
```

`task_ids` boʻsh boʻlsa server shu foydalanuvchiga oxirgi koʻrsatilgan
vazifalarni oʻzi oladi. Javob `POST /api/v1/check` bilan bir xil.

Hammasi ok boʻlsa sahifa `back` ga qaytaradi va Telegram Mini App ichida
`Telegram.WebApp.close()` chaqiriladi.

---

# Hisob-kitob va hold

1. `check` da konversiya yaratiladi: reklama beruvchida `price` **band** qilinadi
   (`reserve`), publisherga `price × PUBLISHER_SHARE` **hold** ga yoziladi
   (`pub_pending`).
2. Scheduler har 6 soatda `RECHECK_DAYS` (masalan 3 va 7-kun) boʻyicha
   aʼzolikni qayta tekshiradi.
3. Foydalanuvchi chiqib ketsa → `clawback`: reklama beruvchiga `refund`,
   publisherdan `pub_clawback`, kampaniya sarfi kamayadi.
4. `HOLD_DAYS` oʻtib, foydalanuvchi hali aʼzo boʻlsa → `settled`: reklama
   beruvchida `charge`, publisherda `pub_settle` (available ga oʻtadi).
5. Publisher `available ≥ MIN_PAYOUT` boʻlganda panelda kartaga toʻlov soʻraydi.

Sifat: `settled / (settled + clawback)`. Oxirgi 7 kunda ≥ 50 konversiya boʻlib,
clawback ulushi `CLAWBACK_PAUSE_RATIO` dan oshsa publisher avtomatik `paused`
boʻladi (admin qayta yoqadi).

---

# SDK

- Python: `sdk/python/op_sdk.py` — `OpClient` (sync) va `AsyncOpClient` (aiogram).
- PHP: `sdk/php/OpClient.php` — cURL, PHP 7.4+.

```python
from op_sdk import AsyncOpClient

op = AsyncOpClient("https://op.example.uz", "pub_xxx")
tasks = await op.tasks(user_id, lang="uz")
result = await op.check(user_id, [t["task_id"] for t in tasks])
if result["all_ok"]:
    ...  # botning asosiy amalini bajarish
```

```php
$op = new OpClient('https://op.example.uz', 'pub_xxx');
$tasks = $op->tasks($userId, 'uz');
$res = $op->check($userId, array_column($tasks, 'task_id'));
```

# Toʻlov shlyuzlari (server tomoni)

Bu endpointlar publisherlar uchun emas — toʻlov tizimlari chaqiradi:

| Yoʻl | Tizim | Format |
|------|-------|--------|
| `POST /payments/payme` | Payme Merchant API | JSON-RPC 2.0, Basic auth `Paycom:PAYME_KEY` |
| `POST /payments/click/prepare` | Click SHOP API | form-urlencoded, md5 imzo |
| `POST /payments/click/complete` | Click SHOP API | form-urlencoded, md5 imzo |

Payme summasi **tiyinda** (soʻm × 100). `account.order_id` = `topups.id`.

---

# Stars ishlash boti API — `/api/v1/earn/*`

Bot foydalanuvchiga vazifa (kanal obunasi, kirish soʻrovi, botga kirish) evaziga **Telegram Stars**
beradi. Auth — oddiy publisher kaliti. Summalar **centistars** (`*_cs`, 1 ⭐ = 100) va matn (`"0.43"`).
Mukofot = reklama beruvchi narxi × `EARN_USER_SHARE` / `EARN_STAR_PRICE_UZS` (yoki `fixed`).

| Endpoint | Nima qiladi |
|----------|-------------|
| `GET /config` | minimal yechish, bonuslar, usullar |
| `POST /start` `{user_id, username, name, lang, ref_by}` | foydalanuvchini roʻyxatga oladi (referal faqat birinchi kirishda) |
| `GET /me?user_id=` | balans, ishlangan, yechilgan, referallar, kutayotgan yechish |
| `GET /tasks?user_id=&lang=&limit=` | vazifalar (`type`: `sub` / `bot`) + `reward_cs` |
| `POST /check` `{user_id, task_ids}` | tekshiradi, YANGI konversiyalar uchun Stars yozadi (`credited_cs`, `balance_cs`, `referrer_bonus`) |
| `POST /bonus` `{user_id}` | kunlik bonus (`ok:false, status:"wait"` — bugun olingan) |
| `POST /withdraw` `{user_id, method: stars\|gift\|premium, amount, username}` | yechish soʻrovi; `auto:true` — bot oʻzi toʻlashga urinadi |
| `POST /withdrawals/{id}/complete` `{user_id, note, provider_tx}` | bot avto toʻladi → `paid` |
| `POST /withdrawals/{id}/fail` `{user_id, note}` | avto toʻlov boʻlmadi → admin uchun qoladi |
| `GET /history?user_id=` | ledger va yechishlar |
| `POST /confirm` `{campaign_id, user_id}` | **maqsad bot** chaqiradi: foydalanuvchi `/start et_<campaign>_<user>` bosdi |

Xato tanasi: `{"detail": {"code": "min|insufficient|pending|no_username|blocked|not_found|forbidden", "message": "..."}}`.

Kirish soʻrovi (zayafka): tarmoq boti kanalda admin («Foydalanuvchilarni taklif qilish» huquqi bilan) boʻlsa
`chat_join_request` yangilanishini oladi, soʻrovni yozadi va (sozlamaga koʻra) tasdiqlaydi; `check` soʻrov bor
foydalanuvchini aʼzo deb hisoblaydi, `recheck` clawback qilmaydi.