API hujjati

Ikki versiya mavjud: v2 — sanoat standarti (mavjud skriptlaringiz o'zgarishsiz ishlaydi), v3 — zamonaviy REST (JSON, idempotentlik, kursorli sahifalash, 5 til).

Bu ochiq hujjatda narx va xizmat ID lari ko'rsatilmaydi: narx har mijoz uchun uning narx guruhiga qarab hisoblanadi. Ro'yxatdan o'tgach panelda O'Z ID va narxlaringiz bilan tayyor namunani olasiz.

Manzillar

API manzillari
Versiya	Manzil	Autentifikatsiya	Holat
v2	POST https://smmbilan.uz/api/v2	tanada `key`	yoqilgan
v3	https://smmbilan.uz/api/v3	Authorization: Bearer …	yoqilgan

So'rov chegarasi: kalitga 600 so'rov/daqiqa. Idempotentlik kaliti 24 soat saqlanadi.

v2 — sanoat standarti

Barcha amallar bitta manzilga POST bilan yuboriladi. Biznes xatosi HTTP 200 va `{"error":"..."}` bilan qaytadi — bu standartning bir qismi va mavjud skriptlar shunga tayanadi.

curl -X POST https://smmbilan.uz/api/v2 \
  -d "key=<KALITINGIZ>" \
  -d "action=add" \
  -d "service=<XIZMAT_ID>" \
  -d "link=https://t.me/kanalim" \
  -d "quantity=1000"

# Javob: {"order": 100123}

v2 amallari
action	Maydonlar	Nima qiladi
services	—	Katalog
add	service, link, quantity	Buyurtma berish
status	order	Bitta buyurtma holati
status	orders	Ommaviy holat (vergul bilan)
refill	order	Kafolat so'rash
refill_status	refill	Kafolat holati
cancel	orders	Bekor qilish
balance	—	Balans

v3 — REST

Haqiqiy HTTP kodlari, tuzilgan xato javobi, `X-Request-Id` sarlavhasi va xato xabari 5 tilda (`Accept-Language`).

{ "error": { "code": "insufficient_balance", "message": "...", "details": [] } }

curl -X POST https://smmbilan.uz/api/v3/orders \
  -H "Authorization: Bearer <KALITINGIZ>" \
  -H "Idempotency-Key: 3f9c1e40-…" \
  -H "Content-Type: application/json" \
  -d '{"service_id": <XIZMAT_ID>, "link": "https://t.me/kanalim", "quantity": 1000}'

`Idempotency-Key` buyurtma berishda MAJBURIY: tarmoq uzilib qayta yuborilganda ikkinchi buyurtma yaratilmaydi va pul ikki marta yechilmaydi.

v3 so'nggi nuqtalari
Usul	Yo'l	Nima qiladi
GET	/services	Katalog (kursorli)
GET	/services/{id}	Bitta xizmat
POST	/orders	Buyurtma berish
GET	/orders	Buyurtmalar (kursorli)
GET	/orders/{id}	Bitta buyurtma
POST	/orders/{id}/refill	Kafolat
POST	/orders/{id}/cancel	Bekor qilish
GET	/account	Balans va limitlar

Buyurtma holatlari

Holatlar xaritasi
v3	v2	Izoh
pending	Pending	Pending
awaiting	Pending	Awaiting
in_progress	In progress	In progress
processing	Processing	Processing
completed	Completed	Completed
partial	Partial	Partial
canceled	Canceled	Canceled
refunded	Canceled	Refunded
failed	Canceled	Failed

Diqqat: v2 da `refunded` va `failed` alohida holat sifatida YO'Q — ikkisi ham `Canceled` bo'lib ko'rinadi.

Xizmat turlari va majburiy maydonlar

Xizmat turlari
v3	v2	Qo'shimcha maydonlar	Miqdor
default	Default	—	siz yuborasiz
package	Package	—	qat'iy (min = max)
custom_comments	Custom Comments	comments	kirishdan hisoblanadi
custom_comments_package	Custom Comments Package	comments	qat'iy (min = max)
mentions	Mentions	usernames	kirishdan hisoblanadi
mentions_hashtags	Mentions with Hashtags	hashtags	siz yuborasiz
mentions_custom	Mentions Custom List	usernames	kirishdan hisoblanadi
mentions_followers	Mentions User Followers	username	siz yuborasiz
mentions_likers	Mentions Likers	username	siz yuborasiz
mentions_media_likers	Mentions Media Likers	media_url	siz yuborasiz
subscriptions	Subscriptions	username	siz yuborasiz
poll	Poll	answer_number	siz yuborasiz
invites	Invites	groups	siz yuborasiz
comment_likes	Comment Likes	username	siz yuborasiz

v3 xato kodlari

Xato kodlari
Kod	HTTP	Nima bo'ldi
invalid_api_key	401	Kalit yaroqsiz, muddati o'tgan yoki bekor qilingan.
wrong_api_version	401	v2 kaliti bilan v3 ga (yoki teskarisiga) murojaat.
account_blocked	403	Hisob to'xtatilgan yoki bloklangan.
api_disabled_for_account	403	Hisobda API o'chirilgan — qo'llab-quvvatlashga yozing.
insufficient_scope	403	Kalitda kerakli ruxsat yo'q. `details.required_scope` ni ko'ring.
not_found	404	Yozuv topilmadi yoki sizga tegishli emas.
idempotency_key_required	422	`Idempotency-Key` sarlavhasi yuborilmagan. Buyurtma berishda u MAJBURIY.
idempotency_in_progress	409	Ayni kalitli so'rov hali ishlanmoqda. 1-2 sekunddan keyin qayta urinib ko'ring.
idempotency_key_reused	409	Bir kalit BOSHQA tana bilan yuborildi. Har buyurtmaga yangi kalit yasang.
validation_failed	422	So'rov maydonlari to'g'ri emas.
order_rejected	422	Buyurtma rad etildi. `details.reason` sababni beradi.
refill_rejected	422	Kafolat rad etildi. `details.reason` sababni beradi.
insufficient_balance	402	Balans yetmadi. `details` da kerakli va mavjud summa.
rate_limited	429	So'rov chegarasi oshdi. `Retry-After` sarlavhasini kuting.
api_version_disabled	503	API vaqtincha o'chirilgan. Qayta urinib ko'ring.
sandbox_read_only	403	Sinov kaliti ma'lumotni o'zgartira olmaydi.

Boshlash

Ro'yxatdan o'tib panelda API kaliti yaratasiz. Kalit yaratilganda O'Z xizmat ID va narxlaringiz bilan tayyor namunani ko'rasiz.

Ro'yxatdan o'tish