Заказы

1. Общее

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

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

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

2. Тип доставки

Поле service определяет, куда доставляется отправление, и от него зависит, какие поля обязательны.

ID районов и филиалов берутся из раздела Справочники.

3. Расчёт стоимости

Позволяет узнать стоимость доставки до создания заказа.

POST {BASE_URL}/api/v2/orders/calculate

Параметры запроса

Пример запроса

POST {BASE_URL}/api/v2/orders/calculate
Authorization: Bearer {TOKEN}
Content-Type: application/json

{
  "sender_district_id": 12,
  "sender_address": "улица Амира Темура, 1",
  "receiver_district_id": 45,
  "receiver_address": "улица Мустакиллик, 20",
  "weight": 1.5,
  "service": 1
}

Ответ (200)

{
  "success": true,
  "data": {
    "price": 4500000,
    "from_town": { "code": 3922, "name": "TASHKENT" },
    "to_town": { "code": 3969, "name": "SAMARKAND" },
    "mass": 1.5,
    "service": { "code": 1, "name": "Курьерская доставка" }
  }
}

4. Создание заказа

Создаёт новое отправление и возвращает штрих-код (barcode).

POST {BASE_URL}/api/v2/orders/create

Параметры запроса

^* Технически поле можно не передавать, но тогда отправление уйдёт без адреса — всегда передавайте 1 или 2.

^** Должно быть заполнено хотя бы одно из полей receiver_person или receiver_company.

Пример запроса (до двери)

POST {BASE_URL}/api/v2/orders/create
Authorization: Bearer {TOKEN}
Content-Type: application/json

{
  "sender_district_id": 12,
  "sender_person": "Али Валиев",
  "sender_phone": "998901234567",
  "sender_address": "улица Амира Темура, 1",
  "receiver_district_id": 45,
  "receiver_person": "Вали Алиев",
  "receiver_phone": "998907654321",
  "receiver_address": "улица Мустакиллик, 20",
  "weight": 1.5,
  "service": 1
}

Пример запроса (до ПВЗ)

{
  "sender_district_id": 12,
  "sender_person": "Али Валиев",
  "sender_phone": "998901234567",
  "receiver_branch_id": 7,
  "receiver_person": "Вали Алиев",
  "receiver_phone": "998907654321",
  "weight": 1.5,
  "service": 2
}

Ответ (200)

{
  "success": true,
  "data": {
    "order_code": "AB123456789UZ",
    "price": 4500000,
    "api_response": {
      "orderNo": "123456",
      "barcode": "AB123456789UZ",
      "error": 0,
      "errorMessage": null,
      "errorMessageRu": null,
      "orderPrice": 45000
    }
  }
}

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

{
  "success": true,
  "data": {
    "order_code": null,
    "price": null,
    "api_response": {
      "orderNo": null,
      "barcode": null,
      "error": 1,
      "errorMessage": "Wrong town code",
      "errorMessageRu": "Неверный код города",
      "orderPrice": null
    }
  }
}

5. Статусы отправления

Возвращает историю статусов одного отправления по штрих-коду.

GET {BASE_URL}/api/v2/orders/trace

GET {BASE_URL}/api/v2/orders/trace?barcode=AB123456789UZ
Authorization: Bearer {TOKEN}
Accept: application/json

Ответ (200)

{
  "success": true,
  "data": {
    "barcode": "AB123456789UZ",
    "date": "2026-06-10 09:00:00",
    "weight": 1.5,
    "recipient": "Вали Алиев",
    "trace": [
      { "code": 1, "name": "Новый",     "advanced": "NEW",      "statetime": "2026-06-10 09:00:00", "branch": "Центральный склад Ташкента", "description": "Заказ принят" },
      { "code": 9, "name": "Доставлен", "advanced": "COMPLETE", "statetime": "2026-06-15 14:30:00", "branch": "Филиал Самарканд",          "description": "Вручено получателю" }
    ]
  }
}

Если штрих-код не найден:

{
  "success": false,
  "error": {
    "code": -404,
    "message": "Данные не найдены"
  }
}

6. Коды статусов

Каждый статус отправления обозначается числовым code. Эти коды используются в трёх местах в одном и том же значении:

• trace[].code в ответе статусов отправления;
• state внутри webhook;
• code в справочнике статусов.

Расшифровку кодов даёт запрос справочника:

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

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

7. Ошибки

При ошибке в ответе success = false и возвращается объект error:

{
  "success": false,
  "error": {
    "code": -2006,
    "message": "Необходимо выбрать район"
  }
}