Starex bilan integratsiya

Ushbu hujjat Starex bilan integratsiya qilmoqchi bo'lgan tashqi tizimlar uchun. U webhook bildirishnomalari va jo'natma holatlarini olish uchun API'larni tavsiflaydi.

Bazaviy URL va Basic-Auth (login/parol) ma'lumotlari Starex tomonidan beriladi. Quyida bazaviy URL {BASE_URL} deb belgilangan.

1. Webhook haqida

Jo'natmaning holati (status) o'zgarganda Starex siz bergan URL ga avtomatik HTTP POST so'rov yuboradi. Shu orqali siz holat o'zgarishlarini real vaqtda olasiz.

Integratsiyani boshlash uchun Starex'ga quyidagini taqdim etasiz:

Webhook URL — bildirishnomalar yuboriladigan manzilingiz (masalan https://sizning-domeningiz.uz/starex/webhook).

Javob: so'rovni qabul qilganingizni bildirish uchun HTTP 200 qaytaring. 200 dan boshqa har qanday javob (4xx, 5xx, timeout) muvaffaqiyatsiz deb hisoblanadi va Starex bir necha marta qayta urinadi.

2. Webhook ichidagi ma'lumot

Starex sizning URL'ingizga quyidagi so'rovni yuboradi:

POST {SIZNING_WEBHOOK_URL}
Content-Type: application/json

Tana (JSON):

{
  "barcode": "AB123456789UZ",
  "state": 12,
  "statetime": "2026-06-15 14:30:00"
}

Maydon	Tur	Tavsif
`barcode`	string	Jo'natmaning shtrix-kodi
`state`	integer	Holat kodi (kodlarning ma'nosi — 3-bo'lim: Statuslar ro'yxati API)
`statetime`	string	Holat o'zgargan sana-vaqt

3. Statuslar ro'yxati API

Webhook'dagi state kodlarining ma'nosini bilish uchun barcha mavjud holatlar ro'yxatini qaytaradi.

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

Avtorizatsiya: Basic Auth.

GET {BASE_URL}/api/v1/dictionaries/states
Authorization: Basic base64(login:parol)
Accept: application/json

Javob (200) — namuna (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 (webhook'dagi `state` bilan bir xil)
`name`	string	Holat nomi (rus tilida qaytadi)
`advanced`	string	Barqaror, til-neytral kod (mashina kodi)

Muhim: statuslar ro'yxati doimiy emas — yangi holatlar qo'shilishi yoki o'zgarishi mumkin. Shuning uchun ro'yxatni bu hujjatga "qotirib" qo'ymang; har doim shu API'dan joriy ro'yxatni oling.

advanced — har bir holatga biriktirilgan matnli (mnemonik) kod, masalan NEW, PICKUP, DELIVERY, COMPLETE. U code bilan birga holatni dasturiy aniqlash uchun qulay; name esa ko'rsatish uchun (rus tilida).

4. Zakaz statuslari API

Bitta jo'natma (zakaz) bo'yicha holatlar tarixini shtrix-kod orqali qaytaradi.

GET {BASE_URL}/api/v1/order/trace

Avtorizatsiya: Basic Auth.

Parametr	Tur	Majburiy	Tavsif
`barcode`	string	Ha	Jo'natmaning shtrix-kodi

GET {BASE_URL}/api/v1/order/trace?barcode=AB123456789UZ
Authorization: Basic base64(login:parol)
Accept: application/json

Javob (200):

{
  "success": true,
  "data": {
    "barcode": "AB123456789UZ",
    "date": "2026-06-10 09:00:00",
    "weight": 1.5,
    "recipient": "Ism Familiya",
    "trace": [
      { "code": 1, "name": "Новый",     "advansed": "NEW",      "statetime": "2026-06-10 09:00:00" },
      { "code": 9, "name": "Доставлен", "advansed": "COMPLETE", "statetime": "2026-06-15 14:30:00" }
    ]
  }
}

Maydon	Tur	Tavsif
`barcode`	string	Jo'natmaning shtrix-kodi
`date`	string\|null	Qabul qilingan sana
`weight`	number\|null	Og'irligi
`recipient`	string\|null	Qabul qiluvchi
`trace[]`	array	Holatlar tarixi (vaqt bo'yicha)
`trace[].code`	integer	Holat kodi
`trace[].name`	string\|null	Holat nomi
`trace[].advansed`	string\|null	Qo'shimcha izoh
`trace[].statetime`	string\|null	Holat vaqti

Xatolik (masalan shtrix-kod topilmasa) quyidagi ko'rinishda qaytadi:

{
  "success": false,
  "error": { "code": 422, "message": "..." }
}