Starex Client — документация API

Общие правила

Базовый URL

Все запросы отправляются на {BASE_URL}/api/v2/.... Базовый URL, токен и параметры доступа предоставляет Starex.

Авторизация

В каждом запросе обязателен Bearer-токен. Токен выдаётся Starex индивидуально — не передавайте его третьим лицам.

Authorization: Bearer {TOKEN}
Accept: application/json

Ошибки, связанные с токеном:

Ситуация	HTTP	`error.code`
Токен не передан	401	401
Токен недействителен	401	401
Аккаунт заблокирован	423	-423
Нет доступа к сервису	200	-401

Каждый сервис (Заказы, Webhook) включается отдельно. Если доступа к нужному сервису нет, запрос вернёт ошибку -401 — в этом случае свяжитесь со Starex.

Язык

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

Важно: справочники (области, районы, филиалы) доступны только на uz и ru. При запросе с en вернётся ошибка -210.

Формат ответа

Успешный ответ:

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

Ошибка:

{
  "success": false,
  "error": {
    "code": -401,
    "message": "У вас нет прав на выполнение этого действия"
  }
}

Внимание: ошибки бизнес-логики (например, район не найден, нет прав) могут возвращаться и с HTTP 200. Поэтому проверяйте ответ не только по HTTP-статусу, а всегда по полю success.

Ошибка валидации (HTTP 422) содержит дополнительный блок details:

{
  "success": false,
  "error": {
    "code": 422,
    "message": "The given data was invalid.",
    "details": {
      "receiver_phone": ["Необходимо указать телефон получателя"]
    }
  }
}

Коды ошибок

Код	Значение
`422`	Ошибка валидации полей (детали в `details`)
`401`	Токен не передан или недействителен
`-401`	Нет прав на выполнение действия
`-423`	Аккаунт заблокирован
`-404`	Данные не найдены
`-210`	Выбранный язык не поддерживается для этой операции
`-500`	Недостаточно данных для продолжения (не заполнены параметры доступа)
`-2001`	Район отправителя не найден
`-2002`	Район получателя не найден
`-2004`	Филиал получателя не найден
`-2005`	Необходимо указать компанию или ФИО получателя
`-2006`	Необходимо выбрать район
`-2007`	Необходимо выбрать филиал
`100`	Непредвиденная внутренняя ошибка

С чего начать

Starex выдаёт вам токен и включает нужные сервисы.
Если нужен webhook — передаёте Starex свой webhook URL.
Получаете ID районов и филиалов из справочников.
Через раздел Заказы рассчитываете стоимость и создаёте отправление.
Отслеживаете смену статусов через webhook или запрос orders/trace.