Starex Client — API hujjati

Umumiy qoidalar

Bazaviy URL

Barcha so'rovlar {BASE_URL}/api/v2/... manzillariga yuboriladi. Bazaviy URL, token va kirish ma'lumotlari Starex tomonidan beriladi.

Avtorizatsiya

Har bir so'rovda Bearer token yuborilishi shart. Token Starex tomonidan sizga alohida beriladi va uni hech kimga bermang.

Authorization: Bearer {TOKEN}
Accept: application/json

Token bo'yicha xatoliklar:

Holat	HTTP	`error.code`
Token yuborilmagan	401	401
Token yaroqsiz	401	401
Akkaunt bloklangan	423	-423
Servisga ruxsat yo'q	200	-401

Har bir servis (Buyurtmalar, Webhook) alohida yoqiladi. Agar sizda kerakli servisga ruxsat bo'lmasa, so'rov -401 xatoligi bilan qaytadi — bu holda Starex bilan bog'laning.

Til

Javob matnlari (xato xabarlari, ma'lumotnoma nomlari) Accept-Language sarlavhasi orqali boshqariladi. Qo'llab-quvvatlanadigan qiymatlar: uz, ru, en.

Muhim: ma'lumotnomalar (viloyat, tuman, filial) faqat uz va ru tillarida qaytadi. en bilan so'ralsa -210 xatoligi qaytadi.

Javob formati

Muvaffaqiyatli javob:

{
  "success": true,
  "data": { }
}

Xatolik:

{
  "success": false,
  "error": {
    "code": -401,
    "message": "Sizda ushbu amalni bajarish uchun ruxsat yo'q"
  }
}

Diqqat: biznes-mantiq xatoliklari (masalan, tuman topilmadi, ruxsat yo'q) HTTP 200 bilan ham qaytishi mumkin. Shuning uchun javobni faqat HTTP status bo'yicha emas, doim success maydoni bo'yicha tekshiring.

Validatsiya xatoligi (HTTP 422) qo'shimcha details bilan qaytadi:

{
  "success": false,
  "error": {
    "code": 422,
    "message": "The given data was invalid.",
    "details": {
      "receiver_phone": ["Qabul qiluvchi telefoni kiritilishi shart"]
    }
  }
}

Xato kodlari

Kod	Ma'nosi
`422`	Maydonlar validatsiyasi xatoligi (`details` ichida tafsilotlar)
`401`	Token yuborilmagan yoki yaroqsiz
`-401`	Ushbu amal uchun ruxsat yo'q
`-423`	Akkaunt bloklangan
`-404`	Ma'lumot topilmadi
`-210`	Tanlangan til ushbu amal uchun qo'llab-quvvatlanmaydi
`-500`	Davom etish uchun ma'lumotlar yetarli emas (kirish sozlamalari to'liq emas)
`-2001`	Yuboruvchi tumani topilmadi
`-2002`	Qabul qiluvchi tumani topilmadi
`-2004`	Qabul qiluvchi filiali topilmadi
`-2005`	Qabul qiluvchi kompaniya yoki jismoniy shaxs nomi kiritilishi shart
`-2006`	Tuman tanlanishi shart
`-2007`	Filial tanlanishi shart
`100`	Kutilmagan ichki xatolik

Integratsiyani boshlash

Starex sizga token beradi va kerakli servislarni yoqadi.
Webhook kerak bo'lsa — Starex'ga webhook URL'ingizni berasiz.
Ma'lumotnomalardan tuman va filial ID'larini olasiz.
Buyurtmalar bo'limi orqali narx hisoblab, jo'natma yaratasiz.
Holat o'zgarishlarini webhook orqali yoki orders/trace so'rovi bilan kuzatasiz.