API Integratsiyasiga Umumiy Nazar

Bu sahifa Bione HTTP API-larining tuzilishini, autentifikatsiya qanday ishlashini va javoblardan nimani kutish kerakligini tushuntiradi. API Ma'lumotnomasi har bir endpointni hujjatlashtiradi; bu sahifa sizga umumiy manzarani beradi, qaerdan qidirish va qanday konventsiyalarga amal qilishni bilasiz.

API nima uchun

Bione — savdo platformasi: kompaniyalar o'z do'konlarini boshqaradi, mijozlar keshibek (cashback) oladi, integratsiya hamkorlari esa ma'lumot almashish uchun ulanadi. To'rtta alohida API maydoni to'rt xil auditoriyaga xizmat qiladi, ularning har biri o'z autentifikatsiya strategiyasiga ega. Siz Integratsiya maydoni haqida o'qiyapsiz — tashqi hamkorlar foydalanadigan — lekin barcha to'rttasini tushunish ma'lumotlarga egalik va kirish chegaralari haqida fikr yuritishga yordam beradi.

To'rtta maydon

Maydon	URL prefiksi	Autentifikatsiya	Kim foydalanadi
Mijoz	`/v1/customer/*`	JWT cookie yoki body tokenlari	Mobil ilova, veb-sayt, Telegram Mini App
Kompaniya	`/v1/company/*`	JWT + `OrganizationMember`	Kompaniya admin veb
Platforma	`/v1/platform/*`	JWT + `platformRole` + 2FA	Platforma admin veb
Integratsiya	`/integration/v1/*`	`api-key` headeridagi API kalit	Tashqi hamkor tizimlari

Integratsiya maydoni /integration/v1/* da joylashgan — global /v1 prefiksidan tashqarida — shuning uchun u Bione ichki relizlaridan mustaqil ravishda versiyalanishi va bekor qilinishi mumkin.

Autentifikatsiya

Brauzer maydonlari (Mijoz, Kompaniya, Platforma)

Uchalasi ham httpOnly cookie seanslaridan foydalanadi (bione_at / bione_rt). Tokenlar brauzer mijozlari uchun javob tanalarida hech qachon bo'lmaydi; ular Set-Cookie orqali o'rnatiladi va avtomatik yuboriladi. Yangilash POST /<surface>/auth/refresh orqali amalga oshiriladi.

Native mobil (Mijoz)

Kotlin Multiplatform mobil ilovasi javob tanasida tokenlarni olishga ruxsat etilgan yagona mijozdir. Autentifikatsiya so'rovlarida u X-Client-Type: native yuboradi, tokenlarni platforma bilan himoyalangan saqlashda saqlaydi va keyingi chaqiruvlarda ularni Authorization: Bearer <accessToken> sifatida yuboradi.

Integratsiya (tashqi hamkorlar)

API kalitingizni api-key headerida yuboring:

api-key: bik_your_key_here

OAuth oqimi, token almashinuvi va yangilash yo'q. Kalit — bu savdogar uni bekor qilmaguncha kredensialdir. Bione kalitning faqat argon2 heshini saqlaydi — yo'qolgan kalitni tiklab bo'lmaydi va uni qayta chiqarish kerak.

Kalit doiralari, aylanishi va amal qilish muddati haqida Autentifikatsiya bo'limiga qarang.

Javob konverti

Har bir javob — muvaffaqiyat yoki xato — bir xil konvertga o'ralgan. Bu Bito bilan mos keladigan shakl bo'lib, Bito ERP API bilan ham integratsiya qiluvchi mijozlar jo'natish mantiqini umumlashtira oladi.

code bo'yicha ish tuting, HTTP holatiga emas. 0 — muvaffaqiyat; boshqa hamma narsa — xato. Raqamli kod relizlar bo'ylab barqaror; prozaik xabar qayta so'zlab chiqilishi mumkin.

json

{
  "code": 0,
  "message": "Success",
  "data": {
    "id": "prod_1",
    "name": "Kofe",
    "price": "9900.00"
  },
  "messages": {
    "uz": "Muvaffaqiyatli",
    "ru": "Успешно",
    "en": "Success"
  },
  "status_code": 200,
  "time": "2026-08-25T08:32:00.000Z"
}

Asosiy xususiyatlar:

code — 0 muvaffaqiyatni bildiradi. Nolga teng bo'lmagan qiymat xato; Xato Kodlari bo'limiga qarang.
data — yuk. Xato holatida bu null yoki validatsiya kontekstini olib yuradi. Hech narsa qaytarmaydigan kontroller null o'rniga data: "OK" beradi.
messages — Bione yetkazib beradigan uchta tilda (uz / ru / en) bir xil tushuntirish, shuning uchun qayta so'rov yubormasdan lokalizatsiya qilishingiz mumkin.
status_code — konvertda aks ettirilgan haqiqiy HTTP holati.
Har bir muvaffaqiyat HTTP 200, fe'l (verb) qanday bo'lishidan qat'iy nazar. Resurs yaratadigan POST 200 javob qaytaradi, 201 emas.

Sahifalangan javoblar

Ro'yxatlar data ostida sahifalash metama'lumotlari bilan joylashadi:

json

{
  "code": 0,
  "message": "Success",
  "data": {
    "items": [...],
    "total": 42,
    "page": 1,
    "pageSize": 20,
    "totalPages": 3
  },
  "messages": { "uz": "...", "ru": "...", "en": "..." },
  "status_code": 200,
  "time": "2026-08-25T08:32:00.000Z"
}

Simdagi (Wire) pul

Barcha pul qiymatlari Decimal(14,2) bo'lib, raqamlar sifatida emas, qatorlar sifatida ketma-ketlashtiriladi. Siz 5000 emas, "5000.00" ko'rasiz.

Pul qatorlarini hech qachon Number() yoki parseFloat() bilan tahlil qilmang.
Ko'rsatish vaqtida Intl.NumberFormat yoki mahalliy tilizning ekvivalenti bilan formatlang.

Bu suzuvchi nuqtali yaxlitlashning oldini oladi va sizning tizimingiz hamda Bione o'rtasida aniqlikni barqaror saqlaydi.

Standart REST fe'llari

Bione standart HTTP fe'llarini ishlatadi — bu faqat POST bo'lgan RPC emas:

Fe'l	Qachon	Misol
`GET`	O'qish (ro'yxat, id bo'yicha)	`GET /integration/v1/products`
`POST`	Yaratish yoki amal bajarish	`POST /integration/v1/orders`
`PATCH`	Qisman yangilash	`PATCH /integration/v1/orders/:id`
`DELETE`	Yumshoq o'chirish	`DELETE /integration/v1/products/:id`

Operatsiyangizga mos keladigan fe'lni ishlating. Backend noto'g'ri foydalanishni tekshiradi va rad etadi.

Idempotentlik

Xavfsiz qayta urinishlar o'rnatilgan. Har qanday GET bo'lmagan so'rovga qo'shilish uchun Idempotency-Key headerini yuboring.

Vaziyat	Natija
Ushbu kalit bilan birinchi so'rov	Handler ishlaydi; javob 2xx da saqlanadi
Qayta urinish — bir xil kalit, bir xil tana, asl tugallangan	Saqlangan javob so'zma-so'z takrorlanadi
Qayta urinish — bir xil kalit, boshqa tana	`409` idempotentlik mos kelmasligi
Qayta urinish — birinchi so'rov hali davom etmoqda	`425` so'rov davom etmoqda

Idempotentlik yozuvlari Redis'da 24 soat saqlanadi. 2xx bo'lmagan javob yozuvni o'chiradi, shuning uchun muvaffaqiyatsiz chaqiruvni bir xil kalit bilan qayta urinish mumkin.

Maslahat: Tana heshi tahlildan so'ng, xom baytlar emas, solishtiriladi. Bir xil JSON lekin turli kalit tartibiga ega ikkita so'rov bir xil tana deb hisoblanadi.

Sahifalash

Ro'yxat endpointlari standart so'rov parametrlarini qabul qiladi va Paginated<T> shaklini qaytaradi:

GET /integration/v1/products?page=1&pageSize=20&q=kofe

Parametr	Standart	Tavsif
`page`	1	1-dan boshlanadigan sahifa raqami
`pageSize`	20	Bir sahifadagi elementlar soni
`q`	—	Erkin matnli qidiruv filtri

Javob data obyekti items, total, page, pageSize va totalPages larni o'z ichiga oladi.

Xatolarni boshqarish

Xatolar muvaffaqiyatlar bilan bir xil konvertdan foydalanadi. code maydoni Bione nomlangan enum'idan raqamli xato kodini olib yuradi; 0 har doim muvaffaqiyat.

json

{
  "code": 10012,
  "message": "X-Audit-Reason header is required for this action",
  "data": null,
  "messages": {
    "uz": "Audit sababini ko'rsating",
    "ru": "Укажите причину для аудита",
    "en": "X-Audit-Reason header is required for this action"
  },
  "status_code": 400,
  "time": "2026-08-25T08:32:00.000Z",
  "path": "/v1/platform/organizations/abc/suspend"
}

code — barqaror, mashina tomonidan o'qiladigan identifikator. Xabar matniga mos kelish o'rniga, uni mijozingizda xaritalang.
messages — bitta javobda uchala tilni beradi, shuning uchun ikkinchi chaqiruvsiz lokalizatsiya qilishingiz mumkin.
status_code — haqiqiy HTTP holati (400, 403, 404, …).

To'liq ro'yxat uchun Xato Kodlari bo'limiga qarang.

Birinchi chaqiruvingiz

Savdogardan allaqachon API kalitingiz bor deb hisoblaymiz:

1. Sog'liqni tekshirish

Bu marshrut kalit talab qilmaydi. U "noto'g'ri tarmoq yo'li"ni "noto'g'ri kalit"dan ajratadi:

bash

curl https://api.bione.uz/integration/v1/health

json

{
  "code": 0,
  "message": "Success",
  "data": { "status": "ok", "version": "1" },
  "messages": { "uz": "Muvaffaqiyatli", "ru": "Успешно", "en": "Success" },
  "status_code": 200,
  "time": "2026-08-25T08:32:00.000Z"
}

2. Mahsulotlar ro'yxati

bash

curl -H "api-key: bik_your_key_here" \
     https://api.bione.uz/integration/v1/products

Siz savdogarning mahsulot katalogini o'z ichiga olgan data.items bilan konvertni qaytarib olasiz.

3. Keyingi qadamlar

Bu yerdan endpointlarning to'liq ro'yxati, so'rov sxemalari va javob shakllari uchun API Ma'lumotnomasini ko'rib chiqishingiz mumkin.

APIda NIMA YO'Q

Integratsiya maydoni ataylab cheklangan. U ochib beradigan narsalar ro'yxati emas:

Webhook yo'q. Bione v1 faqat pull (tortish) usulida. O'zgarishlarni so'rov qiling yoki dolzarb bo'lish uchun health va status endpointlaridan foydalaning.
OAuth yo'q. Autentifikatsiya faqat API kaliti orqali. Token almashinuvi, avtorizatsiya URL va yangilash sikli yo'q.
Buyurtmani bekor qilish, qaytarish yoki keshibek (cashback) sozlash yo'q. Bular Kompaniya admin maydoni orqali amalga oshiriladigan savdo xodimlarining operatsiyalari.
Savdogarlararo kirish yo'q. Bitta API kaliti bitta savdogarga tegishli. Yagona kalit bilan savdogarlar bo'ylab so'rov qilishning hech qanday usuli yo'q.

Bu cheklovlar dizayn bo'yicha. Agar webhook yetkazib berish yoki savdogarlararo agregatsiya kerak bo'lsa, murojaat qiling — bular kelajakdagi versiyalar uchun nomzodlardir.

Barqarorlik va versiyalash

Integratsiya maydoni /integration/v1/* da joylashgan. Asosiy versiya ichida:

Maydonlar javoblarga ogohlantirmasdan qo'shilishi mumkin.
Maydonlar olib tashlanmaydi yoki qayta nomlanmaydi v1 ichida.
Endpointlar olib tashlanmaydi yoki qayta nomlanmaydi v1 ichida.

Buziluvchi o'zgarishlar — olib tashlash, qayta nomlash yoki semantik siljishlar — prefiksni /integration/v2/* ga oshiradi. Eski versiya bekor qilish davrida ishlashda davom etadi.

To'liq siyosat uchun Versiyalash bo'limiga qarang.

API ma'lumotnomasi

Mahsulotlar

Buyurtmalar

Mijozlar

API Integratsiyasiga Umumiy Nazar

API nima uchun

To'rtta maydon

Autentifikatsiya

Brauzer maydonlari (Mijoz, Kompaniya, Platforma)

Native mobil (Mijoz)

Integratsiya (tashqi hamkorlar)

Javob konverti

Sahifalangan javoblar

Simdagi (Wire) pul

Standart REST fe'llari

Idempotentlik

Sahifalash

Xatolarni boshqarish

Birinchi chaqiruvingiz

1. Sog'liqni tekshirish

2. Mahsulotlar ro'yxati

3. Keyingi qadamlar

APIda NIMA YO'Q

Barqarorlik va versiyalash

Mahsulotlar

Buyurtmalar

Mijozlar

API Integratsiyasiga Umumiy Nazar ​

API nima uchun ​

To'rtta maydon ​

Autentifikatsiya ​

Brauzer maydonlari (Mijoz, Kompaniya, Platforma) ​

Native mobil (Mijoz) ​

Integratsiya (tashqi hamkorlar) ​

Javob konverti ​

Sahifalangan javoblar ​

Simdagi (Wire) pul ​

Standart REST fe'llari ​

Idempotentlik ​

Sahifalash ​

Xatolarni boshqarish ​

Birinchi chaqiruvingiz ​

1. Sog'liqni tekshirish ​

2. Mahsulotlar ro'yxati ​

3. Keyingi qadamlar ​

APIda NIMA YO'Q ​

Barqarorlik va versiyalash ​

API Integratsiyasiga Umumiy Nazar

API nima uchun

To'rtta maydon

Autentifikatsiya

Brauzer maydonlari (Mijoz, Kompaniya, Platforma)

Native mobil (Mijoz)

Integratsiya (tashqi hamkorlar)

Javob konverti

Sahifalangan javoblar

Simdagi (Wire) pul

Standart REST fe'llari

Idempotentlik

Sahifalash

Xatolarni boshqarish

Birinchi chaqiruvingiz

1. Sog'liqni tekshirish

2. Mahsulotlar ro'yxati

3. Keyingi qadamlar

APIda NIMA YO'Q

Barqarorlik va versiyalash