КЛЕВЕР ЛОГИСТИК Документация API

Clever Public API

v1

Публичное API. Города и регионы адресуются по ФИАС; внутренние коды справочников наружу не отдаются. Все методы требуют заголовок Authorization: Bearer <токен>; токен выдаёт администратор и привязывает его к логину потребителя.

Базовый адрес: https://public-api.clever-logistics.ru/api/v1

Используемый протоколАвторизацияТипы данныхОшибкиОграниченияТехническая поддержкаИстория изменений

Используемый протокол

Общее описание

  • Запросы выполняются по протоколу HTTPS. Базовый адрес API: https://public-api.clever-logistics.ru/api/v1.
  • Формат входящих и исходящих данных — JSON, кодировка — UTF-8.
  • Параметры GET-запросов передаются в строке запроса, например ?page=1&limit=20. Параметры POST-запросов передаются в теле запроса строкой JSON.
  • В каждом запросе нужно передавать заголовки:
Content-Type: application/json; charset=utf-8
Accept: application/json
Authorization: Bearer <токен>
  • Все поля JSON-объекта в запросе обязательны, если в описании метода не указано обратное.
  • Передавать поля и параметры, которых нет в описании метода, нельзя: такой запрос отклоняется с кодом 400.

Спецификация OpenAPI

Описание всех методов в формате OpenAPI 3 доступно по адресу https://public-api.clever-logistics.ru/docs-json: по нему можно сгенерировать клиент или импортировать методы в Postman. Интерактивная версия — Swagger UI.

Авторизация

Все методы API требуют токен доступа. Токен передаётся в заголовке каждого запроса:

Authorization: Bearer <токен>

Токен выдаёт администратор Clever Logistics и привязывает его к вашей учётной записи. Токен имеет вид <префикс>_<случайная строка>, например pub_lE0xk8…: префикс помогает отличать токены разных интеграций. У токена может быть срок действия.

Храните токен как пароль: не публикуйте его в клиентском коде и репозиториях. Если токен скомпрометирован, обратитесь в поддержку — его отзовут и выпустят новый.

Если заголовка нет или он неверного формата, API отвечает кодом 401 с сообщением «Требуется токен доступа». Если токен неизвестен, отозван или истёк — кодом 401 с сообщением «Токен недействителен».

Типы данных

В примерах запросов и ответов тип каждого поля указан в квадратных скобках в конце комментария.

Обозначение Что означает
[String] Строка
[Integer] Целое число
[Number] Число, в том числе дробное; разделитель — точка
[Boolean] Логическое значение: true или false
[UUID] Идентификатор в формате UUID, например ФИАС: c2deb16a-0330-4f05-821f-1d09c93331e6
[Date] Дата в формате ISO 8601: 2026-09-14
[DateTime] Дата и время в формате ISO 8601 со смещением часового пояса: 2026-09-14T00:00:00+03:00
[URL] Абсолютная ссылка
[Array<…>] Массив; в угловых скобках — тип элементов
[Object] Вложенный объект

Если поле может принимать значение null, это указано в комментарии: «может быть null». Города и регионы адресуются идентификаторами ФИАС.

Ошибки

При ошибке API возвращает HTTP-код ошибки и JSON единого вида:

{
  "error": {
    "code": 404,
    "message": "Город с ФИАС 0c5b2444-70a0-4932-980c-b4dc0d3f02b5 не найден"
  }
}
  • code — HTTP-код ответа, продублирован в теле;
  • message — описание ошибки. Если запрос не прошёл проверку сразу по нескольким полям, сообщения перечисляются через «; ».
Код Когда возвращается
400 Некорректные параметры: поле не прошло проверку или передано лишнее поле
401 Токен не передан, неизвестен, отозван или истёк
404 Запрошенный объект не найден, например город по ФИАС
422 Расчёт для указанных параметров недоступен
429 Исчерпан месячный лимит запросов токена — см. раздел «Ограничения»
500 Внутренняя ошибка сервиса
503 Сервис расчёта временно недоступен — повторите запрос позже

Коды, которые возвращает конкретный метод, перечислены в его описании.

Ограничения

На токен может быть установлен лимит запросов в месяц. Лимит обнуляется 1-го числа каждого месяца в 00:00 по московскому времени.

В лимит засчитывается каждый запрос с действующим токеном, в том числе завершившийся ошибкой, например 400 или 404. Запросы, отклонённые из-за исчерпанного лимита, не засчитываются.

Если у токена есть лимит, в каждом ответе передаются заголовки:

Заголовок Что означает
X-RateLimit-Limit Лимит запросов в текущем месяце
X-RateLimit-Remaining Сколько запросов осталось до конца месяца
X-RateLimit-Reset Момент обнуления лимита — Unix-время в секундах

Когда лимит исчерпан, API отвечает кодом 429 с сообщением «Исчерпан месячный лимит запросов» до начала следующего месяца. Чтобы увеличить лимит, обратитесь в поддержку.

Техническая поддержка

По вопросам подключения и работы API пишите на seo@clever-logistics.ru.

В обращении укажите:

  • метод и время запроса;
  • тело запроса и полученный ответ;
  • префикс токена — символы до «_». Сам токен целиком не присылайте.

/cities/ Справочник городов

Метод GET /cities — Список городов

Постраничный справочник городов с необязательным фильтром по вхождению в название.

Доступ

  • По токену доступа, заголовок Authorization: Bearer <токен> — подробнее

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

ПараметрТипОписание
page
необязательный
 [Integer] Номер страницы
от 1 до 1000; по умолчанию 1
limit
необязательный
 [Integer] Размер страницы
от 1 до 100; по умолчанию 20
name
необязательный
 [String] Фильтр по названию города (вхождение, без учёта регистра). Пустое значение равносильно отсутствию фильтра.
длина от 1 до 255 символов; например: "Новосиб"

Пример вызова

curl -G 'https://public-api.clever-logistics.ru/api/v1/cities' \
  -H 'Authorization: Bearer <токен>' \
  -H 'Accept: application/json' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=20' \
  --data-urlencode 'name=Новосиб'

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

{
"data": [// города текущей страницы [Array]
{
"id": 1234,// внутренний идентификатор города [Integer]
"fias_id": "c2deb16a-0330-4f05-821f-1d09c93331e6",// ФИАС города [UUID]
"name": "Новосибирск",// название города [String]
"region": {// регион города [Object]
"fias_id": "1ac46b49-3209-4814-b7bf-a509ea1aecd9",// ФИАС региона. Может быть null: бэкфилл покрывает не все регионы [UUID]
"name": "Новосибирская"// название региона. Пустая строка, если регион не привязан [String]
}
}
],
"meta": {// пагинация [Object]
"page": 1,// текущая страница [Integer]
"limit": 20,// размер страницы [Integer]
"total": 145,// всего записей с учётом фильтра [Integer]
"total_pages": 8// всего страниц [Integer]
}
}

Коды ответа

  • 200Страница справочника
  • 400Некорректные параметры запроса
  • 401Токен отсутствует или недействителен
  • 429Исчерпан месячный лимит запросов токена; лимит обнуляется 1-го числа

Тело ответа с ошибкой описано в разделе «Ошибки».

↑ К списку методов

Метод GET /cities/{identifier} — Город по идентификатору

Принимает ФИАС города либо его внутренний числовой id.

Доступ

  • По токену доступа, заголовок Authorization: Bearer <токен> — подробнее

Параметры пути

ПараметрТипОписание
identifier
обязательный
 [String] ФИАС города или внутренний id
например: "c2deb16a-0330-4f05-821f-1d09c93331e6"

Пример вызова

curl 'https://public-api.clever-logistics.ru/api/v1/cities/c2deb16a-0330-4f05-821f-1d09c93331e6' \
  -H 'Authorization: Bearer <токен>' \
  -H 'Accept: application/json'

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

{
"id": 1234,// внутренний идентификатор города [Integer]
"fias_id": "c2deb16a-0330-4f05-821f-1d09c93331e6",// ФИАС города [UUID]
"name": "Новосибирск",// название города [String]
"region": {// регион города [Object]
"fias_id": "1ac46b49-3209-4814-b7bf-a509ea1aecd9",// ФИАС региона. Может быть null: бэкфилл покрывает не все регионы [UUID]
"name": "Новосибирская"// название региона. Пустая строка, если регион не привязан [String]
}
}

Коды ответа

  • 200Город
  • 400Идентификатор нераспознан
  • 401Токен отсутствует или недействителен
  • 404Город не найден
  • 429Исчерпан месячный лимит запросов токена; лимит обнуляется 1-го числа

Тело ответа с ошибкой описано в разделе «Ошибки».

↑ К списку методов

/vehicles/ Справочник транспортных средств

Метод GET /vehicles — Список типов транспортных средств

Доступные машины с характеристиками: грузоподъёмность, объём, габариты, типы кузова со способами загрузки, оснащением и признаком температурного режима.

Доступ

  • По токену доступа, заголовок Authorization: Bearer <токен> — подробнее

Пример вызова

curl 'https://public-api.clever-logistics.ru/api/v1/vehicles' \
  -H 'Authorization: Bearer <токен>' \
  -H 'Accept: application/json'

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

[
{
"uuid": "2f1c3c9e-3c5e-4d0a-9a53-1a2b3c4d5e6f",// идентификатор машины. Годится как truckId в POST /calculate/ftl [UUID]
"name": "20 тонн : 92 куба",// название машины [String]
"capacity_kg": 20000,// грузоподъёмность, кг [Number]
"volume_m3": 89.96,// объём кузова, м³ [Number]
"dimensions_m": {// габариты кузова, м [Object]
"length": 13.6,// длина кузова, м [Number]
"width": 2.45,// ширина кузова, м [Number]
"height": 2.7// высота кузова, м [Number]
},
"body_types": [// типы кузова, доступные для этой машины в расчёте. Кузова, которых нет в справочнике расчёта, в выдачу не попадают [Array]
{
"name": "Реф",// тип кузова. Значение годится как truckType в POST /calculate/ftl, значения: "Тент", "Борт", "Изотерм", "Реф" [String]
"temperature_controlled": true,// поддерживает температурный режим (рефрижератор или изотермический кузов) [Boolean]
"loading": ["Зад", "Зад/Бок"],// доступные комбинации загрузки. Значения годятся как load в POST /calculate/ftl, значения: "Зад", "Зад/Бок", "Зад/Верх", "Зад/Бок/Верх" [Array<String>]
"options": ["ремни", "Гидроборт"]// дополнительное оснащение. Значения годятся как dop в POST /calculate/ftl, значения: "ремни", "коники", "деревянный пол", "обрешетка", "Гидроборт" [Array<String>]
}
],
"limits": [// дополнительные ограничения и характеристики [Array]
{
"name": "Мест",// название характеристики [String]
"unit": "шт",// единица измерения [String]
"min": 1,// нижняя граница [Number]
"max": 33// верхняя граница. null — не ограничена [Number]
}
]
}
]

Коды ответа

  • 200Типы транспортных средств
  • 401Токен отсутствует или недействителен
  • 429Исчерпан месячный лимит запросов токена; лимит обнуляется 1-го числа

Тело ответа с ошибкой описано в разделе «Ошибки».

↑ К списку методов

/calculate/ Расчёт стоимости перевозки

Метод POST /calculate/ltl — Расчёт сборного груза (LTL)

Итоговая стоимость с учётом всех надбавок и коэффициентов клиента, даты подачи и доставки, детализация по услугам.

Доступ

  • По токену доступа, заголовок Authorization: Bearer <токен> — подробнее

Формат запроса

{
"points": [// ФИАС города отправления и города назначения, ровно 2 элемента [Array<UUID>]
"0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
"c2deb16a-0330-4f05-821f-1d09c93331e6"
],
"insurance": 0,// объявленная стоимость груза для страхования, ₽. 0 — оценивается по весу [Number]
"dimensions": [// грузовые места: габариты и вес каждого места, не менее 1 элемента [Array]
{
"height": 120,// высота места, см [Number]
"length": 120,// длина места, см [Number]
"width": 80,// ширина места, см [Number]
"places": 2,// количество мест [Number]
"weight": 300,// вес одного места, кг [Number]
"rotable": true,// можно ли поворачивать груз и класть на бок [Boolean]
"stackable": false// можно ли ставить на груз другой груз [Boolean]
}
]
}

Пример вызова

curl -X POST 'https://public-api.clever-logistics.ru/api/v1/calculate/ltl' \
  -H 'Authorization: Bearer <токен>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
  "points": [
    "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
    "c2deb16a-0330-4f05-821f-1d09c93331e6"
  ],
  "insurance": 0,
  "dimensions": [
    {
      "height": 120,
      "length": 120,
      "width": 80,
      "places": 2,
      "weight": 300,
      "rotable": true,
      "stackable": false
    }
  ]
}'

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

{
"total": 45000,// итоговая стоимость со всеми надбавками, ₽ [Number]
"currency": "RUB",// валюта, значения: "RUB" [String]
"loading_date": "2026-09-14T00:00:00+03:00",// плановая дата подачи транспорта под загрузку, ISO-8601, может быть null [DateTime]
"delivery_date": "2026-09-16T00:00:00+03:00",// плановая дата доставки, ISO-8601, может быть null [DateTime]
"delivery_days": 2,// срок в пути, сутки, может быть null [Integer]
"services": [// детализация по услугам; сумма строк равна total [Array]
{
"name": "Доставка",// название услуги [String]
"slug": "delivery",// код услуги [String]
"value": 45000// стоимость услуги, ₽. Скидки — отрицательным числом [Number]
}
]
}

Коды ответа

  • 200Результат расчёта
  • 400Некорректные параметры запроса
  • 401Токен отсутствует или недействителен
  • 404Город или машина не найдены
  • 422Расчёт для указанных параметров недоступен
  • 429Исчерпан месячный лимит запросов токена; лимит обнуляется 1-го числа
  • 503Сервис расчёта недоступен

Тело ответа с ошибкой описано в разделе «Ошибки».

↑ К списку методов

Метод POST /calculate/ftl — Расчёт выделенного транспорта (FTL)

Итоговая стоимость с учётом всех надбавок и коэффициентов клиента, даты подачи и доставки, детализация по услугам. Машина и тип кузова — из справочника GET /vehicles.

Доступ

  • По токену доступа, заголовок Authorization: Bearer <токен> — подробнее

Формат запроса

{
"points": [// ФИАС города отправления и города назначения, ровно 2 элемента [Array<UUID>]
"0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
"c2deb16a-0330-4f05-821f-1d09c93331e6"
],
"insurance": 0,// объявленная стоимость груза для страхования, ₽. 0 — оценивается по весу [Number]
"truckId": "2f1c3c9e-3c5e-4d0a-9a53-1a2b3c4d5e6f",// идентификатор машины — поле uuid из GET /vehicles [UUID]
"truckType": "Тент",// тип кузова. Должен быть среди body_types выбранной машины в GET /vehicles, значения: "Тент", "Борт", "Изотерм", "Реф" [String]
"dop": ["ремни"],// дополнительное оснащение. Пустая строка — без дополнений, значения: "ремни", "коники", "деревянный пол", "обрешетка", "Гидроборт" [Array<String>]
"load": "Зад",// способ загрузки. Пустая строка — без требований, значения: "Зад", "Зад/Бок", "Зад/Верх", "Зад/Бок/Верх", "" [String]
"weight": 5000// вес груза, кг [Number]
}

Пример вызова

curl -X POST 'https://public-api.clever-logistics.ru/api/v1/calculate/ftl' \
  -H 'Authorization: Bearer <токен>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
  "points": [
    "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
    "c2deb16a-0330-4f05-821f-1d09c93331e6"
  ],
  "insurance": 0,
  "truckId": "2f1c3c9e-3c5e-4d0a-9a53-1a2b3c4d5e6f",
  "truckType": "Тент",
  "dop": [
    "ремни"
  ],
  "load": "Зад",
  "weight": 5000
}'

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

{
"total": 45000,// итоговая стоимость со всеми надбавками, ₽ [Number]
"currency": "RUB",// валюта, значения: "RUB" [String]
"loading_date": "2026-09-14T00:00:00+03:00",// плановая дата подачи транспорта под загрузку, ISO-8601, может быть null [DateTime]
"delivery_date": "2026-09-16T00:00:00+03:00",// плановая дата доставки, ISO-8601, может быть null [DateTime]
"delivery_days": 2,// срок в пути, сутки, может быть null [Integer]
"services": [// детализация по услугам; сумма строк равна total [Array]
{
"name": "Доставка",// название услуги [String]
"slug": "delivery",// код услуги [String]
"value": 45000// стоимость услуги, ₽. Скидки — отрицательным числом [Number]
}
]
}

Коды ответа

  • 200Результат расчёта
  • 400Некорректные параметры запроса
  • 401Токен отсутствует или недействителен
  • 404Город или машина не найдены
  • 422Расчёт для указанных параметров недоступен
  • 429Исчерпан месячный лимит запросов токена; лимит обнуляется 1-го числа
  • 503Сервис расчёта недоступен

Тело ответа с ошибкой описано в разделе «Ошибки».

↑ К списку методов

История изменений

1 октября 2026 г.

  • несовместимоGET /cities: из ответа удалено поле data[].kladr_idк методу
  • несовместимоGET /cities/search: из ответа удалено поле [].kladr_idк методу
  • несовместимоGET /cities/{identifier}: из ответа удалено поле kladr_idк методу
  • несовместимоPOST /calculate/ftl: в запросе добавлено обязательное поле weight [Number]к методу
  • несовместимоPOST /calculate/ftl: из запроса удалено поле weigthк методу