Javob shakli va kelishuvlar

Bu yerda beshta narsa ko'pchilik API'lardan farq qiladi. Klient generatsiya qilishdan oldin shu sahifani o'qisangiz, quyida tasvirlangan to'rtta xatodan qutulasiz.

Har bir javob konvertga o'ralgan

So'ragan narsangiz data ichida. Yonidagi maydonlar natijani tavsiflaydi.

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

HTTP holati bo'yicha emas, code bo'yicha ish yuriting. 0 — muvaffaqiyat, qolgani xatolik; ro'yxati xatolik kodlari sahifasida. Kod relizlar orasida barqaror, xabar matni esa qayta yozilishi mumkin.

messages maydoni xuddi shu izohni Bione qo'llaydigan har bir tilda olib yuradi, shuning uchun foydalanuvchiga o'z tilida ko'rsatish uchun qo'shimcha so'rov kerak emas.

Har qanday muvaffaqiyat — HTTP 200, hatto yaratishda ham

Narsa yaratadigan POST ham 200 qaytaradi, 201 emas.

Aynan shu generatsiya qilingan klientlarni sindiradi. "201 — yaratildi" degan taxminga qurilgan klient har bir muvaffaqiyatli yaratishni ishlov berilmagan holat deb hisoblaydi: yo xato tashlaydi, yo javob tanasini jimgina yo'qotadi. Generatoringizda muvaffaqiyat qaysi holatda kelishini ko'rsatish imkoni bo'lsa, har bir amal uchun 200 deb belgilang.

Xatoliklar esa o'z holatini saqlaydi: 400, 401, 403, 404, 409, 429.

Pul — satr

{ "price": "9900", "total": "125000.5" }

Hech qachon son emas. Narxni float sifatida o'qish katta summalarda aniqlikni yo'qotadi, bu yerdagi summalar esa so'mda.

Kasr qismi to'ldirilmaydi. 9900.00 sifatida saqlangan narx "9900" bo'lib keladi, 9900.50 esa "9900.5". Ularni decimal kutubxona bilan tahlil qiling va tahlil qilingan qiymatlarni solishtiring — satrlarni solishtirmang va ikkita kasr xonasi bor deb hisoblamang.

Ro'yxatlar har doim bitta shaklda va sahifalangan

{
  "items": [ ... ],
  "total": 42,
  "page": 1,
  "pageSize": 20,
  "totalPages": 3
}

Sahifani ?page= va ?pageSize= bilan so'rang. Bu obyekt ushbu yuzadagi har bir ro'yxat uchun data ichida turadi.

Qayta urinish — so'rasangiz, xavfsiz

Har qanday GET bo'lmagan so'rovga Idempotency-Key sarlavhasini qo'shing — o'zingiz yaratgan istalgan noyob satr:

POST /integration/v1/products
Idempotency-Key: 6f1c9e2a-...

Keyin:

Nima bo'ldi	Nima qaytadi
Birinchi so'rov	Haqiqiy javob, 24 soatga saqlanadi
O'sha kalit, o'sha tana	Asl javob qaytariladi. Ish ikki marta bajarilmaydi
O'sha kalit, boshqa tana	409 — kalit allaqachon band
Birinchisi hali bajarilayotganda	425 — birozdan keyin urinib ko'ring

Muvaffaqiyatsiz tugagan so'rov kalitini bo'shatadi, ya'ni xatolikni o'sha kalit bilan qayta yuborsa bo'ladi.

Buyurtma yaratishda ikkinchi, kuchliroq kafolat bor. Uning requestId maydoni 24 soatlik keshda emas, buyurtmaning o'zi bilan saqlanadi — shuning uchun uni qancha vaqtdan keyin qaytarsangiz ham asl buyurtma qaytadi. Tayanch sifatida requestId dan foydalaning, sarlavhani esa qulaylik deb biling. Boshqa buyurtma uchun — boshqa mijozniki uchun — ishlatilgan requestId qaytarilmaydi, 409 (kod 10009) bilan rad etiladi.

Ba'zi maydonlar sotuvchining o'z tizimiga tegishli

Sotuvchi Bione bilan yonma-yon ERP yuritayotgan bo'lishi mumkin. Shunday bo'lganda, o'sha tizim uning ba'zi mahsulot maydonlariga egalik qiladi — odatda price, stockQty, name — va Bione ularni o'sha tizim bilan mos holda saqlaydi.

Bunday maydonga yozish rad etiladi: 409 bilan, hech narsa saqlanishidan oldin. Qisman qo'llanmaydi ham: butun yangilanish rad etiladi, sababchi maydonlar esa data.fields ichida sanaladi.

{
  "code": 12010,
  "message": "Bu maydonlar ulangan tashqi tizim tomonidan boshqariladi va bu yerda tahrirlab bo'lmaydi: price",
  "data": { "fields": ["price"] },
  "status_code": 409
}

Qaysi maydonlar ekanini kodga yozib qo'ymang. To'plam har bir sotuvchi uchun alohida va u tizimini ulaganda, uzganda yoki qayta sozlaganda o'zgaradi. Har bir mahsulot lockedFields massivini olib yuradi — u aynan shu sotuvchi uchun hozir qulflangan maydonlarni nomlaydi:

{ "id": "prod_1", "name": "Kofe", "lockedFields": ["price", "stockQty"] }

Yangilashga urinishdan oldin uni o'qing. Tashqi tizim ulanmagan sotuvchida — ular ko'pchilik — massiv bo'sh bo'ladi va hech narsa rad etilmaydi.

Qabul qilib keyin ustidan yozish o'rniga rad etish ataylab tanlangan. Ishlagandek ko'rinib, bir soatdan keyin jimgina orqaga qaytadigan yangilanish sizni to'g'ridek tuyuladigan, aslida esa yo'q integratsiyani chiqarishga majbur qilgan bo'lardi.

Hech narsa qaytarmaydigan amal "OK" deydi

Mahsulotni o'chirish bo'sh tanali 204 emas, data ichida "OK" satri bilan 200 qaytaradi. Shu tariqa har bir amalda javob shakli bitta bo'lib qoladi.