Katalogni sinxronlash

Vazifa: tashqi tizimda (onlayn do’kon, marketpleys, BI) to’liq qayta o’qilmasdan yangilanib turadigan BILLZ katalogining nusxasi bo’lishi kerak.

Dastlabki yuklash

curl -X GET 'https://api-admin.billz.ai/v2/products?limit=100&page=1' \
  -H 'Authorization: Bearer TOKEN'

Barcha count tanlab olinmaguncha sahifalar aylanib chiqiladi. Sahifa hajmi — 100–200 yozuv.

Metodning qat’iy cheklovlari, belgilangan me’yordan oshib ketganda — 400:

Parametr	Yuqori chegara
limit	300
page	10 000
search	100 ta belgi

Inkremental yangilash

Keyin faqat o’zgargan ma’lumotlar so’raladi:

curl -X GET 'https://api-admin.billz.ai/v2/products?last_updated_date=2026-08-14%2000:00:00&limit=100' \
  -H 'Authorization: Bearer TOKEN'

UTC vaqti

last_updated_date — UTC da; so’nggi sinxronizatsiya belgisi UTC da saqlanadi.

Asosiy ishga tushirishdan oldin vaqt siljishi tekshiriladi: mahsulotni o’zgartirish, UTC da «o’zgarish vaqti minus bir daqiqa» belgisi bilan metodni chaqirish va mahsulot qaytganiga ishonch hosil qilish.

Sikl: so’rovning boshlanish vaqtini eslab qolish → o’zgarishlarni yuklab olish → muvaffaqiyatli bo’lsa, bu vaqtni yangi belgi sifatida yozib qo’yish.

Vitrina sinxronizatsiyasining ikkita rejimi

Vitrina bitta GET /v2/products ustidagi ikkita jadval orqali dolzarb holatda saqlanadi.

Rejim	Qanchalik tez-tez	Nima qiladi	Nimani qila olmaydi
Delta	odatda har soatda	oxirgi sinxronlashdan keyingi o’zgarishlarni oladi va faqat kelib tushgan mahsulotlarni yangilaydi	yo’qolgan mahsulotlarni sezmaydi
To’liq	sutkasiga bir marta	vitrina katalogini javobda kelgan holatga keltiradi	so’rovlar bo’yicha qimmatroq, tez-tez ishga tushirib bo’lmaydi

Delta

last_updated_date bilan so’rov — yuqoridagi bo’limdagidek. Faqat javobdagi mahsulotlar yangilanadi.

To’liq

Sutkasiga bir marta last_updated_date ko’rsatilmagan holda butun katalog yuklab olinadi va vitrina javob holatiga keltiriladi. Vitrinadagi har bir mahsulot uchun qoida:

Vitrina katalogida mavjud	API javobida mavjud	Qoldiq mavjud	Nima qilish kerak
ha	ha	ha	ko’rsatish
ha	ha	yo’q	sotuvdan olish yoki platforma mantig’iga ko’ra «mavjud emas» deb ko’rsatish
ha	yo’q	—	sotuvdan olish
yo’q	ha	ha	kartochka yaratish va ko’rsatish

Yo’qolgan mahsulot sotuvdan olinadi

Marketpleyslarda kartochkani o’chirishni orqaga qaytarib bo’lmaydi hamda tarix, sharhlar va reyting yo’qotiladi; sotuvdan olingan kartochka mahsulot qaytarilganda tiklanadi.

Natija faqat to’liq yuklangandan so’ng qo’llaniladi

To’xtab qolgan yuklash chala yuklangan butun katalogni sotuvdan olib tashlaydi. Natija faqat barcha sahifalar yuklanganda va miqdor avvalgi yuklash bilan solishtirilganda qo’llaniladi.

Murakkab tanlanma

Kategoriyalar, brendlar, yetkazib beruvchilar, narxlar diapazonlari bo’yicha filtrlar kerak bo’lganda POST /v2/product-search-with-filters qo’llaniladi. /v2/products dan farqlari:

• qoldiqlar tuzilishi boshqacha: total_active_measurement_value o’rniga active_measurement_value;
• kursorli sahifalash mavjud — har bir mahsulotda sort maydoni keladi va u keyingi so’rovga uzatiladi.

curl -X POST 'https://api-admin.billz.ai/v2/product-search-with-filters' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "all",
    "brand_ids": ["e158f882-d0e0-499d-b6f8-9029ac1886ca"],
    "shop_ids": ["6f244db4-75d6-4fac-9841-14867d45e36a"],
    "group_variations": false,
    "limit": 50,
    "page": 1
  }'

Atributlar va maxsus xususiyatlar bo’yicha filtr bitta product_field_filters parametri orqali ishlaydi, bu yerda field_type — attribute yoki custom:

{
  "product_field_filters": [
    { "field_id": "491e1d8a-...", "field_type": "attribute", "field_values": ["aee6d71d-..."] },
    { "field_id": "3b6db763-...", "field_type": "custom", "field_values": ["18"] }
  ]
}

Variantli mahsulotlar

"group_variations": true bo’lganda ro’yxatda asosiy mahsulot qaytariladi, variantlar esa variations maydonida joylashadi.

Ma’lumotnomalar

Mahsulotlarning kategoriyalari, brendlari, o’lchov birliklari, xususiyatlari va turlari alohida metodlar bilan yuklanadi: /v2/category, /v2/brand, /v2/measurement-unit, /v2/product-characteristic, /v2/product-type. Kuniga bir marta yangilanadi.

Atributlar o’qiladigan ko’rinishda keladi

product_attributes[] da identifikatorlar yonida attribute_name va attribute_value satr ko’rinishida beriladi. Atributlar ma’lumotnomalari faqat filtrlarni shakllantirish uchun kerak.

Har bir ma’lumotnomaning javob shakli o’ziga xos: {categories, count}, {brands, count}, {measurement_units, count}, xususiyatlarda esa count o’rniga active_count va deleted_count, /v2/product-type esa {product_types} ni hisoblagichsiz va sahifalashsiz beradi.

So’rovlar chastotasi

API soniyasiga 2 tagacha so’rov qabul qiladi; oshib ketganda — 429, eksponensial kechikish bilan takrorlash orqali qayta ishlanadi. Limit integratsiyaning umumiy oqimi bo’yicha hisoblanadi.

Nima qilmaslik kerak

• Mahsulot suratlarini to’g’ridan-to’g’ri CDN BILLZ orqali bermang; media o’z tomoningizda keshlanadi.