JSON API 1.2 (Remap): nimani qilish mumkin va qayerdan boshlanadi

Dasturchilar sayti MoySklad API sini shunday tanishtiradi: foydalanish bepul, alohida roʻyxatdan oʻtish shart emas, hisobning oʻzi yetarli, interfeysdagi deyarli hamma obyekt bilan ishlash mumkin. API barcha obuna turlarida ishlaydi, faqat bepul va dastlabki turlarda ayrim cheklovlar bor. Sayt cheklovni yashirmaydi: soʻrovlar soniga limit bor. Aynan shu limit 2026-yilda oʻzgardi, shuning uchun API bilan ishlaydigan integratsiyani tekshirib chiqishga arziydi. Sayt uchta odatiy vazifani misol qiladi: oʻz saytdan buyurtmalarni yuklash va katalogdagi baho hamda qoldiqni yangilash, mijozga yoki yigʻuvchiga xabar yuborish, kelgan buyurtmaga toifa yoki summa boʻyicha masʼul tayinlash. Maqola hujjatning asosiy qismini, yaʼni kirish, maʼlumot tuzilishi va cheklovlarni, hisob-kitob bilan koʻrsatadi.

API ning boshqa turlari ham bor: ilovalar doʻkoni, sodiqlik dasturlari, telefoniya, kassa, toʻlov, fiskal qurilma va elektron hujjat uchun alohida interfeyslar. Maqola faqat asosiy JSON API 1.2 ga toʻxtaladi.

Kirish: login-parol yoki token

MoySklad ikki usulni qoʻllab-quvvatlaydi. Birinchisida har soʻrov bilan login va parol jufti yuboriladi. Ikkinchisida token ishlatiladi. Token login va parol bilan soʻrab olinadi, yangisi berilganda foydalanuvchining oldingi tokenlari bekor boʻladi. Uchinchi tur ham bor: katalogdagi ilova oʻrnatilganda uning ishlab chiqaruvchisiga beriladigan yechim tokeni.

Bu usullar cheklovda ham farq qiladi, buni quyida koʻramiz. Hozircha amaliy xulosa shu: foydalanuvchi tokeni foydalanuvchiga bogʻlangan. Xodim ketsa va akkaunti oʻchirilsa, uning nomidan ishlagan integratsiya toʻxtaydi. Yordam markazi shuning uchun «API ishlatish statistikasi» hisobotini beradi: u API ni ishlatayotgan hamma yozuvni topishga yordam beradi va akkauntni oʻchirishdan oldin tekshirishni tavsiya qiladi.

Maʼlumot tuzilishi: havola, roʻyxat, sahifalash

Har obyektda havolalar bloki bor: u obyektning manzilini, turini va maʼlumot formatini koʻrsatadi. Boshqa obyektga ishora ham shu blok bilan beriladi. Roʻyxat javobida esa yana uch qiymat keladi: roʻyxat hajmi, bir sahifadagi eng koʻp element soni va siljish. Bir sahifada koʻpi bilan 1000 element boʻladi. Roʻyxat sigʻmasa, keyingi va oldingi sahifaga havolalar qoʻshiladi.

Hujjat mijoz dasturi uchun muhim vaʼda beradi: javob tuzilishi va maydon turlari oʻzgarmaydi, ammo yangi maydon yoki yangi resurs qoʻshilishi mumkin. Beta rejimida yoqiladigan funksiyalarga bu vaʼda tegishli emas. Demak, dastur nomaʼlum maydonni xatoga aylantirmasligi kerak.

Yana ikkita foydali qoida bor. Birinchisi, sinxronlash identifikatori maydoni bor obyektlarda mijoz dasturi oʻzi yaratgan identifikatorni yuborsa, soʻrov takrorlanganda nusxa yaratilmaydi, oldingi obyektning oʻzi qaytadi. Tarmoq uzilgan joyda bu juda qimmatli. Ikkinchisi, maydon qiymatini oʻchirish uchun boʻsh qiymat yuboriladi, ammo manzillar bundan mustasno: ularni boʻsh qator bilan tozalash kerak.

Hujjat pozitsiyasi bilan birga qoldiq va tannarxni ham olish mumkin, buning uchun alohida qoʻshimcha maydon soʻraladi, roʻyxat soʻrovida esa sahifa hajmi 100 dan oshmasligi kerak. Joʻnatish va qabul kabi hujjatlarda qiymatlar hujjat sanasi paytiga, buyurtma va hisoblarda esa hozirgi paytga hisoblanadi. Hujjatdagi misolda qoldiq 999, rezerv 90, kutilayotgan 9, mavjud 918 deb berilgan. Bu sonlar mavjud = qoldiq − rezerv + kutilayotgan formulasiga mos keladi: 999 − 90 + 9 = 918. Formulaning oʻzi bu joyda yozilmagan, u misoldan chiqarildi.

Filtr va kengaytirish: soʻrovlar sonini kamaytirish

Filtr shartlari nuqta-vergul bilan ajratiladi. Bir maydonga bir necha marta «teng» sharti berilsa, ular «yoki» bilan birlashadi, bir necha marta «teng emas» sharti berilsa «va» bilan. Teng sharti va undan keyin katta-kichik sharti bitta maydonga berilsa, xato chiqadi. Turli maydonlar esa doim «va» bilan birlashadi.

Kengaytirish havola oʻrniga bogʻlangan obyektning oʻzini beradi. Masalan, buyurtmada mijozning havolasi emas, toʻliq kartochkasi keladi. Qoidalari qatʼiy: kengaytirish faqat 100 tagacha elementlik tanlovda ishlaydi, koʻproq soʻralsa, jimgina eʼtiborga olinmaydi, ichma-ich daraja esa koʻpi bilan uchta. «Jimgina» soʻzi muhim: xato chiqmaydi, ammo kengaytirilgan maʼlumot kelmaydi.

Hisob-kitob misoli. 5000 ta buyurtmani mijoz maʼlumoti bilan oʻqish kerak, deylik. Kengaytirishsiz 5 ta roʻyxat soʻrovi boʻladi, har buyurtmaning mijozi esa alohida soʻraladi. Eng yomon holda, yaʼni mijozlar hammasi har xil boʻlsa, 5005 ta soʻrov kerak. Kengaytirish bilan 100 talik sahifalar uchun 50 ta soʻrov yetadi. Hozirgi login va parol limiti sekundiga besh soʻrov boʻlgani uchun birinchisi taxminan 17 daqiqa, ikkinchisi 10 soniya oladi. Misol gipotetik, ammo hisob hujjatdagi qoidalardan olingan.

Cheklovlar: 2026-yilda nima oʻzgardi

Asosiy limit 3 soniyada 45 birlik. Har soʻrov bir yoki bir necha birlik sarflaydi, bu uning ogʻirligi. 2026-yil 16-fevraldan limit butun hisob uchun emas, har foydalanuvchi va har yechim uchun alohida hisoblanadi, shu sababli bir hisobdagi integratsiyalar bir-biri bilan raqobatlashmaydi. Fevraldan boshlab qoldiq hisobotlariga soʻrov 5 birlik sarflaydi, bu haqda xabar 2026-yil 11-yanvarda eʼlon qilingan.

Eng muhim oʻzgarish login va parol yoki foydalanuvchi tokeni bilan ishlaydigan integratsiyalarga tegadi. Ularning soʻrovi bosqichma-bosqich ogʻirlashadi.

Bugun, 23-oktyabrda bunday integratsiya uchun amalda 15 soʻrov qoladi. Dekabrdan esa 11 ga tushadi. Chop etilgan va shaxsiy yechim tokenida limit 45 soʻrov, qoralama yoki moderatsiyadagi yechimlarda esa 13-apreldan 11 soʻrov. Demak, yechim tokeni login va parolga qaraganda ancha keng limit oladi. Shaxsiy yechim yaratish shartlari hujjatning boshqa boʻlimida, shuning uchun bu yoʻlni dasturchi bilan baholash kerak. Bu tahririyat xulosasi, ammo u jadvaldan toʻgʻridan-toʻgʻri chiqadi.

Hisob-kitob misoli. 3000 ta tovar kartochkasini yangilash kerak. Alohida soʻrovlar bilan, hozirgi sekundiga besh soʻrov limitida, bu 3000 ni 5 ga boʻlganda 600 soniya, yaʼni 10 daqiqa. Dekabrda sekundiga taxminan 3,7 soʻrov boʻladi va vaqt 14 daqiqaga yaqinlashadi. Bir soʻrovda 1000 tagacha obyektni oʻzgartirish mumkin, shuning uchun uch soʻrov yetadi. Yaʼni 600 soniya oʻrniga bir necha soniya ketadi.

Boshqa chegaralar ham bor. Bir foydalanuvchi yoki yechimdan 5 ta, butun hisobdan 20 ta parallel soʻrov mumkin. Soʻrov sarlavhalari 8 KB, soʻrov tanasi 20 MB dan oshmasligi kerak, navbatdagi asinxron vazifalar esa hisobga koʻpi bilan 4 ta. Ommaviy soʻrov 5 daqiqadan uzoq bajarilsa, vaqt tugaydi va partiyani kichraytirish kerak. Javob siqilishi majburiy: siqish talab qilinmasa, server 415 xato qaytaradi va tana bermaydi.

Xato chiqsa nima qilinadi

Limit oshsa, 429 xato keladi. Javob sarlavhalari qancha soʻrov qolganini va limit qachon tiklanishini koʻrsatadi, parallel soʻrovlar chegarasi esa sarlavhada koʻrinmaydi, u alohida xato bilan bildiriladi. Boshqa kodlar tushunarli: 401 login yoki parol notoʻgʻri, 403 koʻrishga huquq yoʻq, 409 obyekt ishlatilayotgani uchun oʻchirilmaydi, 413 soʻrov yoki elementlar soni juda katta.

Takroriy xatolar uchun himoya ham bor. MoySklad foydalanuvchining API ga kirishini avtomatik oʻchiradi, agar oxirgi soatda daqiqasiga 200 dan ortiq bir xil muvaffaqiyatsiz soʻrov, 200 dan ortiq 429 yoki bir obyektga daqiqasiga 100 dan ortiq oʻzgartirish soʻrovi yuborilgan boʻlsa. Xabar hisob egasining pochtasiga ketadi, tiklash uchun esa yordamga murojaat qilinadi. Bunday holat xatoda toʻxtamaydigan sikl yozilgan dasturlarda yuzaga keladi. Shuning uchun xato kelganda toʻxtab, kutib turish shart.

Vebxuk soʻrov limitini tejaydi

Dastur MoySklad dagi oʻzgarishni bilish uchun har soniyada soʻrov yuborib turishi mumkin. Bu limitni tez yeydi. Hozirgi hisobda login va parol bilan har soʻrov 3 birlik sarflaydi, 3 soniyada esa 45 birlik bor. Sekundiga bitta tekshiruv uch soniyada 3 soʻrov, yaʼni 9 birlik, limitning beshdan bir qismi. Dekabrda soʻrov 4 birlik boʻladi, bir xil tekshiruv esa 12 birlikka, yaʼni limitning toʻrtdan bir qismiga yaqinlashadi. Hisob gipotetik, ammo u jadvaldagi ogʻirlikdan olingan.

Yordam markazi boshqa yoʻlni koʻrsatadi: vebxuk. MoySklad oʻzgargan hujjatning identifikatorini va turini tashqi tizimga oʻzi yuboradi, qolgan qadamlarni, yaʼni nima oʻzgargani va unga qanday javob berishni, dasturchi yozadi. Hujjat turlari roʻyxati uzun: buyurtmalar, joʻnatishlar, qabullar, toʻlovlar, qaytarishlar, koʻchirishlar, kontragentlar va boshqalar. Vebxuk faqat pullik obunada va sinov muddatida ishlaydi.

Uzoq hisobotlar: asinxron soʻrov

Baʼzi hisobotlar va roʻyxatlar navbatga qoʻyiladi: qoldiq, foyda, pul, savdo koʻrsatkichlari, kontragentlar roʻyxati va assortiment. Natija bir soat saqlanadi. Navbatda ishlayotganda yangi element qoʻshilsa, nusxa chiqishi, parallel oʻchirilsa, element tushmay qolishi mumkin. Shu sababli bunday natijani tekshirib olish kerak, bu tahririyat ogohlantirishi.

Qayerda xato qilinadi

• Kengaytirish 100 dan katta tanlovda soʻraladi va jimgina eʼtiborga olinmaydi.
• Doimiy integratsiya xodimning login va parolida qoladi, xodim ketgach toʻxtaydi.
• Limit 2026-yilning oʻzgarishlaridan oldingi qiymat boʻyicha hisoblanadi.
• Siqish talab qilinmaydi va server 415 xato qaytaradi.
• Xatolar ketma-ket takrorlanadi, natijada API ga kirish oʻchiriladi.

Amalda nima qilish mumkin

1. Birinchi navbatda API ni ishlatayotgan hamma integratsiyani topib, roʻyxatini tuzing. Buning uchun statistika hisobotidan foydalaning.
2. Har integratsiya uchun kirish usulini tekshiring va katta yuklama boʻlsa, yechim tokeniga oʻtish imkonini dasturchi bilan baholang.
3. Ommaviy ishni partiyaga boʻling: 1000 tagacha obyekt bir soʻrovda ketadi, ammo 5 daqiqadan oshmasin.
4. Roʻyxatni boʻlaklab oʻqishda kengaytirishdan foydalaning va sahifa hajmini 100 ga tushiring.
5. 429 kelsa toʻxtab turing, takroriy soʻrov siklini yozmang.