API bilan ishlash

Integration API — bu integratsiyangiz mijoz ma'lumotini o'qiydigan va yozadigan yuza. Bitta bazaviy URL, bitta javob formati va 464 ta endpoint.

Muhit	Bazaviy URL
Prod	https://api.bito.uz/integration-api/integration/api/v2/
Dev	https://api.systematicdev.uz/integration-api/integration/api/v2/

To'liq endpointlar ro'yxati, har biri uchun so'rov va javob sxemalari bilan — API ma'lumotnomasida.

Avtorizatsiyaning ikki usuli

Ikkalasi ham bir xil endpointlarga va bir xil ma'lumotga olib boradi. Tanlov nechta mijozga xizmat qilishingizga bog'liq.

	API kalit	OAuth 2.0
Sarlavha	api-key: <username>:<secret>	Authorization: Bearer <access_token>
Nechta akkaunt	Bitta — o'zingizniki	Ko'p
Muddat	Cheksiz	Access 24 soat, refresh 90 kun
Sozlash	Integratsiyadan ko'chirib olish	Mijoz o'rnatadi va tasdiqlaydi
Qachon	O'z bekofisingiz, skriptlar, bitta mijoz uchun integratsiya	Marketplace integratsiyalari

API kalit

api_key'ni api-key sarlavhasida yuboring. Token almashish ham, amal qilish muddati ham yo'q.

POST https://api.bito.uz/integration-api/integration/api/v2/product/get-paging
api-key: mycompany:9ad41c0e7b3f28d5610ac94e7f1b26d8
Content-Type: application/json

{ "page": 1, "limit": 20 }

OAuth 2.0

Har bir o'rnatish o'z token juftligini beradi, token esa akkaunt kontekstini olib yuradi — shuning uchun har bir murojaat avtomatik ravishda kerakli mijoz ma'lumoti bilan cheklanadi va akkaunt identifikatorini yuborish shart emas.

POST https://api.bito.uz/integration-api/integration/api/v2/product/get-paging
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{ "page": 1, "limit": 20 }

Tokenni qanday olish — OAuth 2.0: umumiy bo'limida.

Oldindan bilishingiz kerak bo'lgan qoidalar

HTTP metodlar

Metod har bir endpoint shartnomasining bir qismi:

Metod	Nima uchun	Misol
POST	Yozuv yaratish va har qanday ro'yxat yoki filtr so'rovi	POST /product/create, POST /product/get-paging
PUT	Yozuvni yangilash yoki holatini o'zgartirish	PUT /product/update, PUT /production-operation/set-state
GET	Bitta yozuvni id bo'yicha o'qish va tanasiz so'rovlar	GET /product/get-by-id/{id}, GET /product/get-deleted
DELETE	Yozuvni o'chirish	DELETE /product/delete/{id}

Ro'yxatlar POST orqali ishlaydi, chunki filtrlar so'rov satrida emas, JSON tanasida yuboriladi. Har bir endpointning metodi API ma'lumotnomasidagi o'z sahifasida ko'rsatilgan.

WARNING

Bito'ning admin API'si — veb-panel murojaat qiladigani — faqat POST qabul qiladi. Integration API boshqacha, bu taxminni unga ko'chirmang.

So'rov sarlavhalari

Sarlavha	Majburiy	Tavsif
api-key yoki Authorization	Ha	Yuqoridagi ikki usuldan biri
Content-Type	Ha	application/json
Accept-Language	Yo'q	uz, uz_cyrillic, ru, en, kk, tg, ky. Standart — uz. message maydonining tilini belgilaydi.
organization_id	Yo'q	Akkaunt ichidagi tashkilot. Faqat integratsiya sozlamalarida (fields) organization_id maydoni bo'lsa ishlatiladi — aks holda sarlavha e'tiborga olinmaydi. Yuborilmasa, o'sha maydon qiymati olinadi.
warehouse_id	Yo'q	Ombor. Faqat integratsiya sozlamalarida (fields) warehouse_id maydoni bo'lsa ishlatiladi — aks holda sarlavha e'tiborga olinmaydi. Yuborilmasa, o'sha maydon qiymati olinadi.
price_id	Yo'q	Narxlar olinadigan narx ro'yxati. Faqat integratsiya sozlamalarida (fields) price_id maydoni bo'lsa ishlatiladi — aks holda sarlavha e'tiborga olinmaydi. Yuborilmasa, o'sha maydon qiymati olinadi.
role_id	Yo'q	So'rov bajariladigan rol. Faqat integratsiya sozlamalarida (fields) role_id maydoni bo'lsa ishlatiladi — aks holda sarlavha e'tiborga olinmaydi. Yuborilmasa, o'sha maydon qiymati olinadi.
user_id	Yo'q	So'rovni shu foydalanuvchi nomidan bajarish. Foydalanuvchi shu akkauntga tegishli va bloklanmagan bo'lishi shart, aks holda so'rov rad etiladi. Yuborilmasa — akkaunt egasi nomidan.

Javob formati

Har bir javob — muvaffaqiyatli yoki xatoli — bir xil tuzilishga ega.

{
    "code": 0,
    "message": "Success",
    "status_code": 200,
    "messages": { "uz": "Muvaffaqiyatli", "ru": "Успешно", "en": "Successful" },
    "data": { },
    "time": "2025-05-01T12:00:00Z"
}

Maydon	Ma'nosi
code	Muvaffaqiyatda 0, aks holda xato kodi. Mantiqni shu bo'yicha quring.
message	Accept-Language tilidagi matn. Uni tahlil qilmang.
messages	Xuddi shu matn uz, ru va en tillarida.
status_code	HTTP status.
data	Foydali yuk. Xatoda bo'lmaydi.
time	Server vaqti, ISO 8601.

Sahifalash

Har bir get-paging endpointi page va limit qabul qiladi va yozuvlar bilan birga umumiy sonni qaytaradi.

So'rov

{ "page": 1, "limit": 50 }

Maydon	Tur	Standart	Chegara
page	number	1	≥ 1
limit	number	20	1 – 200

Javob

{
    "code": 0,
    "message": "Success",
    "status_code": 200,
    "data": {
        "total": 1043,
        "data": [ { "_id": "6712f0a9c4d1e87b3a0f9911", "name": "Espresso" } ]
    },
    "time": "2025-05-01T12:00:00Z"
}

Ichma-ichlikka e'tibor bering: yozuvlar data.data da, soni data.total da. page * limit >= total bo'lguncha varaqlang.

TIP

Ko'pchilik get-paging endpointlari page/limit yonida filtrlarni ham qabul qiladi — xususan updated_at oxirgi sinxronizatsiyadan beri o'zgarganini olish imkonini beradi. Kerakli metodni API ma'lumotnomasida tekshiring.

O'chirish doim yumshoq

Bito yozuvlarni jismonan o'chirmaydi: delete chaqiruvi yozuvni o'chirilgan deb belgilaydi. Bu siz uchun ikki narsani anglatadi — ko'p resurslarda get-deleted endpointi bor va saqlab qo'ygan id yo'qolmasdan, o'chirilgan holatda qaytishi mumkin.

Identifikatorlar

Har bir _id — 24 belgili MongoDB ObjectId, masalan 6712f0a9c4d1e87b3a0f9911. Uni shunchaki satr deb qarang.

Xatolar

Xato javobida code noldan farqli bo'ladi va data bo'lmaydi.

{
    "code": 401,
    "message": "Unauthorized user",
    "status_code": 401,
    "messages": { "uz": "...", "ru": "...", "en": "Unauthorized user" },
    "time": "2025-05-01T12:00:00Z"
}

HTTP	Nima bo'ldi	Nima qilish kerak
400	Validatsiya o'tmadi yoki ko'rsatilgan yozuv yo'q	message'ni o'qing, so'rov tanasini tuzating
401	Kalit yo'q, noto'g'ri yoki muddati tugagan	Sarlavhani tekshiring, tokenni yangilang
403	Integratsiyada bu amal uchun huquq yo'q	Xabarda kerakli huquq kaliti ko'rsatilgan; uni required_permissions ga qo'shing
404	Bunday endpoint yo'q	Yo'lni API ma'lumotnomasi bilan solishtiring
429	So'rovlar chegarasi	Tezlikni pasaytiring va qayta urinib ko'ring
500	Bito tomonidagi nosozlik	Kechikish bilan qayta urinib ko'ring; takrorlansa — qo'llab-quvvatlashga yozing

WARNING

400 xatosini o'zgartirmasdan qayta yubormang va yozuv so'rovini ko'r-ko'rona takrorlamang: Bito'ning ko'p yozuv metodlari idempotent emas, shuning uchun takroriy create ikkinchi yozuv yaratadi.

Keyingi qadam

• Maxsus vidjetlar — Bito admin paneli ichida o'z ilovangiz
• Ma'lumot webhooklari — so'rov yuborib turish o'rniga o'zgarishlardan xabardor bo'ling
• API ma'lumotnomasi — barcha 464 metod