Developer Platform · API v1

UZFOX Developer API

OpenAPI 3.1

UZFOX API — OpenBudget loyiha ma’lumotlarini aniqlash, foydalanuvchini rasmiy ovoz sahifasiga xavfsiz yo‘naltirish va developer balansini boshqarish uchun HTTPS interfeys.

API JSON formatida ishlaydi. Yopiq metodlar Coder tarifida yaratilgan Bearer kalitini talab qiladi. Server URL:

https://api.uzfox.uz

https://api.uzfox.uz

#So‘nggi o‘zgarishlar

29-iyul, 2026

createVoteSession xavfsiz foydalanuvchi handoff’i sifatida ishga tushirildi.
Ovoz sessiyasi telefon, SMS kod yoki CAPTCHA ma’lumotini API orqali qabul qilmaydi.
API hujjatlari ixcham, o‘qishga yo‘naltirilgan yangi interfeysga o‘tkazildi.

#So‘rovlarni avtorizatsiya qilish

Har bir Coder hisobiga serverda ishlatiladigan maxfiy API kaliti beriladi. Uni kabinetdagi API sahifasi orqali yarating.

Authorization: Bearer uzf_live_xxxxxxxxxxxxxxxxx
Accept: application/json

API kalitini frontend JavaScript, mobil ilova bundle’i, Git repository yoki URL query ichiga joylamang. Kalit faqat server secret sifatida saqlanishi kerak.

#So‘rov yuborish

Barcha so‘rovlar HTTPS orqali yuboriladi. GET metodlari query parametrlarini, POST metodlari esa application/json body’ni qabul qiladi.

curl "https://api.uzfox.uz/v1/wallet" \
  -H "Authorization: Bearer $UZFOX_API_KEY" \
  -H "Accept: application/json"

Muvaffaqiyatli javobda ok qiymati true, natija esa data obyektida keladi. Har bir javobda support uchun request_id mavjud.

GET

#getHealth

API xizmatining joriy holatini qaytaradi. Avtorizatsiya talab qilinmaydi.

GET /v1/health

Qaytaradi

Xizmat faol bo‘lsa, HTTP 200 va health obyektini qaytaradi.

{
  "ok": true,
  "service": "uzfox-developer-api",
  "version": "v1",
  "status": "operational"
}

GET

#resolveProject

Rasmiy OpenBudget loyiha havolasidan nom, tashabbuskor, tavsif, joriy ovozlar va rasmlarni aniqlaydi.

GET /v1/projects/resolve

Query parametrlari
Maydon	Tur	Majburiy	Tavsif
`url`	String	Ha	Rasmiy `https://openbudget.uz/...` loyiha havolasi.

Misol

curl --get "https://api.uzfox.uz/v1/projects/resolve" \
  -H "Authorization: Bearer $UZFOX_API_KEY" \
  --data-urlencode "url=https://openbudget.uz/boards/initiatives/initiative/..."

Qaytaradi

Muvaffaqiyatli holatda Project obyektini qaytaradi. Resolver so‘rovi balansdan pul yechmaydi.

POST

#createVoteSession

Loyihani tekshiradi va foydalanuvchi o‘zi rasmiy OpenBudget sahifasida davom ettirishi uchun vaqtinchalik handoff sessiyasini qaytaradi.

POST /v1/vote-sessions

Bu metod avtomatik ovoz bermaydi. Telefon raqami, CAPTCHA va SMS tasdiqlash kodi faqat foydalanuvchi tomonidan rasmiy OpenBudget interfeysida kiritiladi; UZFOX API ularni qabul qilmaydi yoki saqlamaydi.

JSON body
Maydon	Tur	Majburiy	Tavsif
`project_url`	String	Ha	Rasmiy OpenBudget loyiha havolasi.
`locale`	String	Yo‘q	`uz` yoki `ru`. Standart: `uz`.

Misol

curl -X POST "https://api.uzfox.uz/v1/vote-sessions" \
  -H "Authorization: Bearer $UZFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_url": "https://openbudget.uz/boards/initiatives/initiative/...",
    "locale": "uz"
  }'

Qaytaradi

{
  "ok": true,
  "data": {
    "vote_session": {
      "id": "vhs_...",
      "status": "user_action_required",
      "handoff": {
        "type": "official_browser",
        "url": "https://openbudget.uz/...",
        "requires_user_presence": true,
        "expires_in": 900
      },
      "billing": {
        "charged": false,
        "charge_amount": 0,
        "unit_price": 5000
      }
    }
  }
}

Klient handoff.url manzilini tizim brauzerida ochishi kerak. Rasmiy imzolangan confirmation callback mavjud bo‘lmaguncha API balansidan mablag‘ yechilmaydi.

GET

#getWallet

Developer hisobining prepaid balansi va amaldagi birlik narxini qaytaradi.

GET /v1/wallet

Qaytaradi

Muvaffaqiyatli holatda Wallet obyektini qaytaradi. Pul qiymatlari float emas, butun UZS ko‘rinishida beriladi.

POST

#createTopup

Developer balansi uchun rasmiy checkout havolasini yaratadi.

POST /v1/wallet/topups

Header va JSON body
Maydon	Tur	Majburiy	Tavsif
`Idempotency-Key`	Header	Ha	8–128 belgilik noyob retry kaliti.
`amount`	Integer	Ha	50 000–100 000 000 UZS, 5 000 qadam bilan.
`provider`	String	Ha	`click` yoki `payme`.

curl -X POST "https://api.uzfox.uz/v1/wallet/topups" \
  -H "Authorization: Bearer $UZFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: topup_20260729_001" \
  -d '{"amount":1000000,"provider":"payme"}'

GET

#getUsage

So‘nggi API so‘rovlari, HTTP status, birliklar va hisoblangan summalarni audit uchun qaytaradi.

GET /v1/usage

Query parametrlari
Maydon	Tur	Majburiy	Tavsif
`limit`	Integer	Yo‘q	1–100. Standart qiymat: 30.

#Project

OpenBudget loyihasining normalizatsiya qilingan ochiq ma’lumotlari.

Project maydonlari
Maydon	Tur	Tavsif
`external_id`	String	OpenBudget loyiha identifikatori.
`source_url`	String	Rasmiy loyiha havolasi.
`title`	String	Loyiha nomi.
`owner_name`	String	Loyiha tashabbuskori.
`description`	String	Loyiha tavsifi.
`current_votes`	Integer	Manbada mavjud bo‘lsa, joriy ovozlar.
`images`	Array<String>	HTTPS rasm havolalari.

#VoteSession

Foydalanuvchini rasmiy sahifaga olib borish uchun qaytariladigan vaqtinchalik handoff tavsifi.

VoteSession maydonlari
Maydon	Tur	Tavsif
`id`	String	So‘rovni kuzatish uchun sessiya identifikatori.
`status`	String	Hozir: `user_action_required`.
`project`	Project	Tekshirilgan loyiha ma’lumotlari.
`handoff`	Object	Rasmiy URL, foydalanuvchi ishtiroki talabi va amal muddati.
`billing`	Object	Joriy charge holati va tarif ma’lumoti.

#Wallet

Wallet maydonlari
Maydon	Tur	Tavsif
`currency`	String	`UZS`.
`available_amount`	Integer	Sarflash mumkin bo‘lgan balans.
`debt_amount`	Integer	Qarzdorlik miqdori.
`total_credited`	Integer	Jami kirim.
`total_debited`	Integer	Jami sarf.
`unit_price`	Integer	Amaldagi birlik narxi.

#ApiError

{
  "ok": false,
  "error": {
    "code": "INVALID_PROJECT_URL",
    "message": "Only an official OpenBudget URL is accepted.",
    "details": {}
  },
  "request_id": "..."
}

#Xatolar

Asosiy xato kodlari
HTTP	Kod	Sabab
401	`AUTHENTICATION_REQUIRED`	Bearer kaliti yuborilmagan.
401	`INVALID_API_KEY`	Kalit noto‘g‘ri, bekor qilingan yoki hisob faol emas.
403	`INSUFFICIENT_SCOPE`	Kalitda kerakli scope yo‘q.
422	`INVALID_PROJECT_URL`	OpenBudget havolasi noto‘g‘ri.
422	`UNSUPPORTED_VOTE_INPUT`	Telefon, OTP yoki CAPTCHA kabi yopiq maydon yuborilgan.
429	`RATE_LIMIT_EXCEEDED`	Bir daqiqalik limit tugagan.

#Idempotency

Moliyaviy POST so‘rovlarida Idempotency-Key majburiy. Network retry bo‘lsa, aynan bir xil qiymatni qayta yuboring; bu takroriy invoice yaratishning oldini oladi.

#Rate limit

Standart limit — har bir API kaliti uchun daqiqasiga 60 so‘rov. Qolgan limit javob header’larida ko‘rsatiladi.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
Retry-After: 60