# Katalogni sinxronlash

> BILLZ mahsulotlarini tashqi tizimga qanday yuklash va ularni dolzarb holatda saqlash mumkin.

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

## Dastlabki yuklash

```bash
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:

```bash
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.

```bash
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`:

```json
{
  "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.