Ma'lumotnomalar

Ma'lumotnomalar — buyurtma yaratishda kerak bo'ladigan ID'lar manbai: viloyatlar, tumanlar, filiallar (PVZ) va jo'natma holatlari.

1. Umumiy

Barcha so'rovlar {BASE_URL}/api/v2/dictionaries/... manziliga yuboriladi va Bearer token talab qiladi.

Authorization: Bearer {TOKEN}
Accept: application/json
Accept-Language: uz

Til majburiy: ma'lumotnomalar faqat uz va ru tillarida qaytadi. Accept-Language: en yuborilsa yoki til ko'rsatilmagan holda server sozlamasi en bo'lsa — -210 xatoligi qaytadi. Shu sababli Accept-Language ni doim aniq yuboring.

Metodlar ro'yxati:

Metod	Manzil	Vazifasi
GET	`/api/v2/dictionaries/regions`	Viloyatlar ro'yxati
GET	`/api/v2/dictionaries/districts`	Viloyatga tegishli tumanlar
GET	`/api/v2/dictionaries/branches`	Filiallar (PVZ)
GET	`/api/v2/dictionaries/states`	Jo'natma holatlari ro'yxati

Odatiy ketma-ketlik:

regions  →  districts (region_id)  →  branches (district_id)

2. Viloyatlar

O'zbekiston viloyatlari ro'yxatini qaytaradi. Parametrlarsiz chaqiriladi.

GET {BASE_URL}/api/v2/dictionaries/regions

GET {BASE_URL}/api/v2/dictionaries/regions
Authorization: Bearer {TOKEN}
Accept-Language: uz

Javob (200)

{
  "success": true,
  "data": [
    { "id": 1, "name": "Toshkent shahri" },
    { "id": 2, "name": "Samarqand viloyati" }
  ]
}

Maydon	Tur	Tavsif
`id`	integer	Viloyat ID — `districts` so'rovida ishlatiladi
`name`	string\|null	Viloyat nomi (so'ralgan tilda)

3. Tumanlar

Filiali (PVZ) mavjud bo'lgan tumanlar ro'yxatini qaytaradi. region_id berilsa — faqat o'sha viloyat tumanlari.

GET {BASE_URL}/api/v2/dictionaries/districts

Parametr	Tur	Majburiy	Tavsif
`region_id`	integer	Yo'q	Viloyat bo'yicha filtr (mavjud bo'lishi shart). Berilmasa — barcha viloyatlar tumanlari
`our`	integer\|boolean	Yo'q	Filial egaligi bo'yicha filtr: `1`/`true` — kamida bitta Starex filiali bor tumanlar, `0`/`false` — kamida bitta hamkor punkti bor tumanlar. Berilmasa — barchasi
`page`	integer	Yo'q	Sahifa raqami (boshlanish qiymati `1`)
`limit`	integer	Yo'q	Sahifadagi yozuvlar soni. Berilmasa — `20`

Javob sahifalangan holda qaytadi: items, totalCount, limit, page. Odatiy sahifa hajmi — 20 ta yozuv, limit orqali o'zgartiriladi.

Ro'yxatda faqat kamida bitta filiali bor tumanlar bo'ladi. Filiali yo'q tumanlar umuman qaytmaydi.

GET {BASE_URL}/api/v2/dictionaries/districts?region_id=1&page=1
Authorization: Bearer {TOKEN}
Accept-Language: uz

Javob (200)

{
  "success": true,
  "data": {
    "items": [
      { "id": 12, "regionId": 1, "name": "Chilonzor tumani", "our": true },
      { "id": 13, "regionId": 1, "name": "Yunusobod tumani", "our": false }
    ],
    "totalCount": 16,
    "limit": 20,
    "page": 1
  }
}

Maydon	Tur	Tavsif
`items[].id`	integer	Tuman ID — buyurtmadagi `sender_district_id` / `receiver_district_id`
`items[].regionId`	integer\|null	Tegishli viloyat ID
`items[].name`	string\|null	Tuman nomi (so'ralgan tilda)
`items[].our`	boolean	`true` — tumanda kamida bitta Starex'ning o'z filiali bor, `false` — faqat hamkor topshirish punktlari. Diqqat: bu yerda `true/false`, filiallar javobidagi `our` esa `1/0` (integer)
`totalCount`	integer	Filtrga mos jami tumanlar soni
`limit`	integer	Sahifadagi yozuvlar soni
`page`	integer	Joriy sahifa

our maydoni va our filtri — bir xil narsa emas. Maydon tumanning haqiqiy holatini ko'rsatadi va filtrga bog'liq emas: masalan ?our=0 so'ralganda ham, tumanda ham hamkor punkti, ham Starex filiali bo'lsa — u ro'yxatga tushadi va our: true bo'ladi. Maydon nomlari regionId kabi camelCase ko'rinishida qaytadi.

4. Filiallar (PVZ)

Jo'natmani olib ketish mumkin bo'lgan filiallar ro'yxati. Bu ID buyurtmadagi receiver_branch_id uchun ishlatiladi.

GET {BASE_URL}/api/v2/dictionaries/branches

Parametr	Tur	Majburiy	Tavsif
`district_id`	integer	Yo'q	Tuman bo'yicha filtr. Berilmasa — barcha filiallar
`our`	integer\|boolean	Yo'q	Filial egaligi bo'yicha filtr: `1` yoki `true` — faqat Starex'ning o'z filiallari, `0` yoki `false` — faqat hamkor topshirish punktlari. Berilmasa — barchasi
`page`	integer	Yo'q	Sahifa raqami (boshlanish qiymati `1`)
`limit`	integer	Yo'q	Sahifadagi yozuvlar soni. Berilmasa — `20`

Javob sahifalangan holda qaytadi. Odatiy sahifa hajmi — 20 ta yozuv, limit orqali o'zgartiriladi. Keyingi sahifani page orqali oling.

our qiymatlari: faqat 0, 1, true, false qabul qilinadi. Boshqa qiymat yuborilsa — 422 xatoligi qaytadi. Parametr umuman yuborilmasa (yoki bo'sh yuborilsa) filtr qo'llanmaydi — ro'yxatda ikkala turdagi filiallar bo'ladi.

GET {BASE_URL}/api/v2/dictionaries/branches?district_id=12&page=1
Authorization: Bearer {TOKEN}
Accept-Language: uz

Faqat Starex'ning o'z filiallari:

GET {BASE_URL}/api/v2/dictionaries/branches?district_id=12&our=1&page=1
Authorization: Bearer {TOKEN}
Accept-Language: uz

Javob (200)

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 7,
        "name": "STAREX CHILONZOR",
        "address": "Chilonzor tumani, Bunyodkor shoh ko'chasi, 12",
        "lat": "41.2856",
        "lon": "69.2034",
        "our": 1,
        "phone": "+998 71 200-00-00",
        "worktime": "09:00-18:00"
      }
    ],
    "totalCount": 34,
    "limit": 20,
    "page": 1
  }
}

Maydon	Tur	Tavsif
`items[].id`	integer	Filial ID — `receiver_branch_id` uchun
`items[].name`	string	Filial nomi
`items[].address`	string\|null	Manzil (so'ralgan tilda)
`items[].lat`	string\|null	Kenglik (koordinata)
`items[].lon`	string\|null	Uzunlik (koordinata)
`items[].our`	integer	`1` — Starex'ning o'z filiali, `0` — hamkor topshirish punkti
`items[].phone`	string\|null	Filial telefoni. Manba tizimidan boricha olinadi — yagona format kafolatlanmaydi, bo'sh bo'lishi mumkin
`items[].worktime`	string\|null	Ish vaqti, erkin matn (masalan, `09:00-18:00`). Parse qilmang — foydalanuvchiga boricha ko'rsating
`totalCount`	integer	Jami yozuvlar soni
`limit`	integer	Sahifadagi yozuvlar soni (so'rovdagi `limit`, odatiy `20`)
`page`	integer	Joriy sahifa

Sahifalar soni: ceil(totalCount / limit).

5. Holatlar

Jo'natma holatlarining to'liq ro'yxati. Bu kodlar jo'natma holatlari javobida va webhook ichida keladi.

GET {BASE_URL}/api/v2/dictionaries/states

GET {BASE_URL}/api/v2/dictionaries/states
Authorization: Bearer {TOKEN}
Accept: application/json

Javob (200) — ro'yxatning bir qismi

{
  "success": true,
  "data": [
    { "code": 0, "name": "Ожидает синхронизации", "advanced": "AWAITING_SYNC" },
    { "code": 1, "name": "Новый",                  "advanced": "NEW" },
    { "code": 9, "name": "Доставлен",              "advanced": "COMPLETE" }
  ]
}

Maydon	Tur	Tavsif
`code`	integer	Holat kodi
`name`	string\|null	Holat nomi — doim rus tilida qaytadi
`advanced`	string\|null	Barqaror, til-neytral mnemonik kod (`NEW`, `COMPLETE` va h.k.)

Muhim: ro'yxat doimiy emas — yangi holatlar qo'shilishi mumkin. Kodda faqat ma'lum kodlarga tayanmang, noma'lum kodni ham to'g'ri qayta ishlang (masalan, "boshqa holat" sifatida ko'rsating).

6. Tavsiyalar va xatoliklar

Ma'lumotnomalar Starex tomonidan muntazam yangilanadi — ularni har so'rovda emas, keshlab (masalan, kuniga bir marta yangilab) ishlating.
Tuman va filial ID'larini o'zingizda saqlab qo'ying: buyurtma yaratishda aynan shu ID'lar kerak bo'ladi.
Holatlar ro'yxatini alohida keshlang va noma'lum kodlarga tayyor bo'ling.

Kod	HTTP	Sabab
`422`	422	`region_id` mavjud emas; `district_id` mavjud emas; `/branches` da `our` qiymati `0/1/true/false` dan boshqa (`/districts` da noma'lum qiymat `false` deb qabul qilinadi)
`401`	401	Token yuborilmagan yoki yaroqsiz
`-423`	423	Akkaunt bloklangan
`-210`	200	Til qo'llab-quvvatlanmaydi (`uz` yoki `ru` yuboring)
`100`	200	Kutilmagan ichki xatolik

Xatolik javobi namunasi:

{
  "success": false,
  "error": {
    "code": -210,
    "message": "Tanlangan til ushbu amal uchun qo'llab-quvvatlanmaydi"
  }
}