# Ma'lumotlar modeli

> BILLZ'da mahsulot, variatsiya, do'kon, qoldiq va narx qanday bog'langan.

**BILLZ’da deyarli barcha narsa do’kon kesimida mavjud.**

## Mahsulot

Katalog birligi. `product_type_id` uchta qiymatdan birini qabul qiladi: mahsulot, xizmat yoki to’plam; ma’lumotnoma — `GET /v2/product-type`. Variativlik — alohida bayroq `is_variative`; variativ mahsulot ham, uning variatsiyalari ham «mahsulot» turiga ega.

| Maydon                     | Ma’nosi                                                                                                                                                                                       |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                       | Mahsulot UUID’si                                                                                                                                                                              |
| `name`, `sku`, `barcode`   | nomi, artikuli, shtrix-kodi                                                                                                                                                                   |
| `is_variative`             | variatsiyali mahsulot belgisi                                                                                                                                                                 |
| `parent_id`                | variatsiyada ota-onasiga havola; mustaqil mahsulotda — bo’sh qator                                                                                                                            |
| `product_type_id`          | mahsulot / xizmat / to’plam (aniq uchta qiymat)                                                                                                                                               |
| `categories[]`, `brand_id` | tasnif                                                                                                                                                                                        |
| `custom_fields[]`          | kompaniyaning ixtiyoriy xususiyatlari: `custom_field_id`, `custom_field_name`, `custom_field_system_name`, `custom_field_value`, `from_parent` (qiymat asosiy elementdan meros qilib olingan) |
| `product_attributes[]`     | variatsiya atributlari: `attribute_id`, `attribute_name`, `attribute_value_id`, `attribute_value`                                                                                             |

## Variatsiya

O’z shtrix-kodi va atributlar to’plamiga ega bo’lgan sho’ba mahsulot. Asosiy elementga `parent_id` orqali havola qilinadi. Variatsiya nomi «asosiy element nomi / atribut qiymati / atribut qiymati» ko’rinishida yig’iladi; asl asosiy element nomi `base_name` da alohida saqlanadi.

`group_variations=true` guruhlash faqat `POST /v2/product-search-with-filters` da qo’llab-quvvatlanadi: u yerda ro’yxatda asosiy element qoladi, variatsiyalar esa `variations` ichida ichma-ich keladi. `GET /v2/products` da bunday parametr yo’q: variatsiyalar tekis ro’yxat bo’lib keladi.

Atribut va maxsus maydon — turli xil obyektlardir, garchi filtrlarda `product_field_filters`: `field_type` yoki `attribute` bo’yicha ajratiladigan umumiy `custom` parametridan foydalanilsa ham.

## Do’kon

Jismoniy sotuv nuqtasi. `shop_id` ga qoldiqlar, narxlar, kassalar, sotuvlar va ombor jarayonlari biriktirilgan. Foydalanuvchi «joriy do’kon» kontekstida ishlaydi.

## Qoldiq va narx

```json
// GET /v2/products
{
  "shop_measurement_values": [
    { "shop_id": "...", "shop_name": "Nike Store", "active_measurement_value": 5 }
  ],
  "shop_prices": [
    { "shop_id": "...", "shop_name": "Nike Store",
      "retail_price": 1000000, "retail_currency": "UZS",
      "supply_price": 600000, "supply_currency": "UZS",
      "promo_price": 500000, "promos": [ ] }
  ]
}
```

Struktura metodga bog’liq: `POST /v2/product-search-with-filters` da `active_measurement_value` o’rniga — `total_measurement_value`, `total_active_measurement_value`, `total_inactive_measurement_value`, `total_in_transfer_measurement_value` va boshqalar.

`promo_price` faqat `promos` bo’sh bo’lmagandagina hisobga olinadi; `promos` da faqat minimal narxli aksiya keladi.

`GET /v2/products` da, agar kalit roliga tannarxni ko’rish ruxsati berilmagan bo’lsa, `supply_price` va `supply_currency` maydonlari nollashtiriladi (0 va `""`). Javobga ko’ra, bu haqiqiy nol tannarxdan farq qilmaydi.

## Mijoz

Kompaniya xaridori: telefon, kartalar, keshbek, qarzlar. API’da ikkita metod to’plami mavjud — `client` (yaratish va qidirish, shu jumladan botlar uchun `chat_id` bo’yicha) va `customer` (tafsilotlar, balans). Modellar turlicha.

Integratsiya kaliti uchun quyidagilar ruxsat etilgan: `POST /v1/client`, `GET /v1/client`, `PUT /v1/client/:id`, `POST /v1/client-card`, `GET /v1/client-by-chat-id`, `GET /v1/customer/:id`, `PATCH /v1/customer/set-balance/:id`.

> **Mijoz kartasi va sodiqlik dasturi — turli xil obyektlar**
>
> `POST /v1/client-card` kassada mijozni aniqlash uchun «ism + kod» juftligini yaratadi: kartada na amal qilish muddati, na sodiqlik dasturiga havola bor. Sodiqlik dasturi kompaniya va mijozga biriktirilgan.

Har bir maydon tavsifi keltirilgan tuzilmalarning to’liq ro’yxati [ma’lumotnomada](/uz/reference/api/) joylashgan.