Справочники

Справочники — источник ID, которые нужны при создании заказа: области, районы, филиалы (ПВЗ) и статусы отправлений.

1. Общее

Все запросы отправляются на {BASE_URL}/api/v2/dictionaries/... и требуют Bearer-токен.

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

Язык обязателен: справочники возвращаются только на uz и ru. Если передать Accept-Language: en (или не передать заголовок, когда на сервере выставлен en) — вернётся ошибка -210. Поэтому всегда явно указывайте Accept-Language.

Список методов:

Метод	Адрес	Назначение
GET	`/api/v2/dictionaries/regions`	Список областей
GET	`/api/v2/dictionaries/districts`	Районы выбранной области
GET	`/api/v2/dictionaries/branches`	Филиалы (ПВЗ)
GET	`/api/v2/dictionaries/states`	Список статусов отправлений

Обычная последовательность:

regions  →  districts (region_id)  →  branches (district_id)

2. Области

Возвращает список областей Узбекистана. Вызывается без параметров.

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

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

Ответ (200)

{
  "success": true,
  "data": [
    { "id": 1, "name": "город Ташкент" },
    { "id": 2, "name": "Самаркандская область" }
  ]
}

Поле	Тип	Описание
`id`	integer	ID области — используется в запросе `districts`
`name`	string\|null	Название области (на запрошенном языке)

3. Районы

Возвращает список районов, в которых есть хотя бы один филиал (ПВЗ). Если передан region_id — только районы этой области.

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

Параметр	Тип	Обяз.	Описание
`region_id`	integer	Нет	Фильтр по области (должна существовать). Без него — районы всех областей
`our`	integer\|boolean	Нет	Фильтр по принадлежности филиалов: `1`/`true` — районы, где есть хотя бы один собственный филиал Starex, `0`/`false` — районы, где есть хотя бы один партнёрский пункт. Без него — все
`page`	integer	Нет	Номер страницы (начиная с `1`)
`limit`	integer	Нет	Количество записей на странице. По умолчанию — `20`

Ответ приходит постранично: items, totalCount, limit, page. Размер страницы по умолчанию — 20 записей, меняется через limit.

В списке только районы, где есть хотя бы один филиал. Районы без филиалов не возвращаются вовсе.

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

Ответ (200)

{
  "success": true,
  "data": {
    "items": [
      { "id": 12, "regionId": 1, "name": "Чиланзарский район", "our": true },
      { "id": 13, "regionId": 1, "name": "Юнусабадский район", "our": false }
    ],
    "totalCount": 16,
    "limit": 20,
    "page": 1
  }
}

Поле	Тип	Описание
`items[].id`	integer	ID района — это `sender_district_id` / `receiver_district_id` в заказе
`items[].regionId`	integer\|null	ID области
`items[].name`	string\|null	Название района (на запрошенном языке)
`items[].our`	boolean	`true` — в районе есть хотя бы один собственный филиал Starex, `false` — только партнёрские пункты выдачи. Внимание: здесь `true/false`, а в ответе филиалов `our` — `1/0` (integer)
`totalCount`	integer	Всего районов, подходящих под фильтр
`limit`	integer	Количество записей на странице
`page`	integer	Текущая страница

Поле our и фильтр our — не одно и то же. Поле показывает фактическое состояние района и не зависит от фильтра: например, при ?our=0 район, где есть и партнёрский пункт, и филиал Starex, попадёт в список со значением our: true. Имена полей возвращаются в camelCase — например regionId.

4. Филиалы (ПВЗ)

Список филиалов, где можно забрать отправление. Этот ID используется как receiver_branch_id при создании заказа.

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

Параметр	Тип	Обяз.	Описание
`district_id`	integer	Нет	Фильтр по району. Без него — все филиалы
`our`	integer\|boolean	Нет	Фильтр по принадлежности филиала: `1` или `true` — только собственные филиалы Starex, `0` или `false` — только партнёрские пункты выдачи. Без него — все
`page`	integer	Нет	Номер страницы (начиная с `1`)
`limit`	integer	Нет	Количество записей на странице. По умолчанию — `20`

Ответ приходит постранично. Размер страницы по умолчанию — 20 записей, меняется через limit. Следующую страницу запрашивайте через page.

Значения our: принимаются только 0, 1, true, false. При другом значении вернётся ошибка 422. Если параметр не передан (или передан пустым), фильтр не применяется — в списке будут филиалы обоих типов.

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

Только собственные филиалы Starex:

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

Ответ (200)

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 7,
        "name": "STAREX CHILONZOR",
        "address": "Чиланзарский район, проспект Бунёдкор, 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
  }
}

Поле	Тип	Описание
`items[].id`	integer	ID филиала — для `receiver_branch_id`
`items[].name`	string	Название филиала
`items[].address`	string\|null	Адрес (на запрошенном языке)
`items[].lat`	string\|null	Широта
`items[].lon`	string\|null	Долгота
`items[].our`	integer	`1` — собственный филиал Starex, `0` — партнёрский пункт выдачи
`items[].phone`	string\|null	Телефон филиала. Приходит как есть из системы-источника — единый формат не гарантируется, может быть пустым
`items[].worktime`	string\|null	Часы работы, свободный текст (например, `09:00-18:00`). Не парсите — показывайте пользователю как есть
`totalCount`	integer	Общее количество записей
`limit`	integer	Записей на странице (`limit` из запроса, по умолчанию `20`)
`page`	integer	Текущая страница

Количество страниц: ceil(totalCount / limit).

5. Статусы

Полный список статусов отправления. Эти коды приходят в ответе статусов отправления и внутри webhook.

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

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

Ответ (200) — фрагмент списка

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

Поле	Тип	Описание
`code`	integer	Код статуса
`name`	string\|null	Название статуса — всегда на русском
`advanced`	string\|null	Стабильный языконезависимый мнемонический код (`NEW`, `COMPLETE` и т.д.)

Важно: список не является постоянным — могут добавляться новые статусы. Не полагайтесь только на известные коды: неизвестный код тоже должен обрабатываться корректно (например, показываться как «другой статус»).

6. Рекомендации и ошибки

Справочники регулярно обновляются на стороне Starex — запрашивайте их не при каждом обращении, а кэшируйте (например, обновляя раз в сутки).
Сохраняйте у себя ID районов и филиалов: именно они нужны при создании заказа.
Список статусов кэшируйте отдельно и будьте готовы к неизвестным кодам.

Код	HTTP	Причина
`422`	422	`region_id` не существует; `district_id` не существует; в `/branches` значение `our` отличается от `0/1/true/false` (в `/districts` неизвестное значение трактуется как `false`)
`401`	401	Токен не передан или недействителен
`-423`	423	Аккаунт заблокирован
`-210`	200	Язык не поддерживается (передайте `uz` или `ru`)
`100`	200	Непредвиденная внутренняя ошибка

Пример ответа с ошибкой:

{
  "success": false,
  "error": {
    "code": -210,
    "message": "Выбранный язык не поддерживается для этой операции"
  }
}