Форматы данных¶
В этом разделе приведены единые форматы данных, используемые во всех методах API CARGO.RUN Логистика.
1. Формат даты и времени¶
Основной формат¶
Во всех методах API используется единый стандарт ISO 8601 (UTC):
YYYY-MM-DDTHH:mm:ssZ
Примеры корректных значений:
- 2025-03-12T15:20:00Z
- 2024-11-01T00:00:00Z
Исключение: метод получения пробегов /api/car/getcarmileageforperiod
В нем используется формат без часового пояса: YYYY-MM-DDTHH:mm:ss
Пример: /api/car/getcarmileageforperiod?carid=694385&start=2025-10-31T21:00:00&end=2025-11-17T20:59:59
Особенности¶
- Часовой пояс всегда указывается как
Z(UTC). - Время передаётся без миллисекунд.
- Значения нельзя передавать в локальном времени без указания таймзоны.
2. Числовые идентификаторы (ID)¶
Идентификаторы сущностей передаются только как целые числа.
Правильно:
12345
Неправильно:
"12345"
Это требование распространяется на:
- заявки (
bidId) - заказы (
orderId) - контрагентов (
counterpartyId) - водителей (
driverId) - автомобили (
carId) - прицепы (
trailerId) - организации (
organizationId) - сотрудников (
employeeId) - трекеры (
trackerId)
3. Телефонные номера¶
Телефон передаётся в международном формате:
+7XXXXXXXXXX
Где:
- нет пробелов,
- нет дефисов,
- код страны обязательно
+7.
Пример:
+79991234567
4. Координаты¶
Координаты передаются в виде двух числовых значений:
- latitude — широта
- longitude — долгота
Формат:
Допускается использование вложенных структур (например, GeoJSON), если это описано в конкретном методе API.
5. Адреса¶
Адрес всегда содержит следующие элементы (если применимо):
- строка адреса,
- город,
- регион,
- страна,
- геокоординаты,
- дополнительные комментарии.
Используемые поля зависят от конкретного эндпоинта.
6. Денежные значения и ставки¶
Стоимость, суммы, ставки и другие денежные поля передаются как числа с фиксированной точностью:
- только число, без строк;
- без символа валюты;
- разделитель — точка.
Примеры:
100012000.50.0
7. Boolean (логические значения)¶
Используются стандартные JSON-значения:
truefalse
Недопустимо:
"true""yes""0""1"
8. Строки¶
Строки передаются в кодировке UTF-8. Допускается использование:
- точек,
- запятых,
- спецсимволов JSON,
- Unicode.
9. Enum-значения¶
Если поле принимает фиксированный набор значений (например, статус заявки или тип прицепа), то: - значение должно быть строго равно одному из элементов перечисления; - формат перечислений приведён в разделе "Статусы".
10. Списки и массивы¶
Если поле является массивом:
Особенности: - массив должен содержать однородные элементы; - порядок элементов — значимый, если указано в описании метода.
11. Пагинация¶
Некоторые методы API поддерживают постраничную выборку.
Используются два механизма:
- Классическая пагинация:
page— номер страницы (начиная с 1);-
pageSize— количество элементов на странице. -
OData-пагинация:
$top— максимальное количество записей;$skip— количество записей, которые нужно пропустить.
Конкретный механизм для метода указан в описании эндпоинта (API Reference).
Если метод принимает page/pageSize, их значения должны быть целыми числами ≥ 1.
Если метод принимает $top/$skip, рекомендуется использовать их в духе OData:
- $top — ограничение выборки (например, 100);
- $skip — смещение (например, 0, 100, 200...).
12. Параметры OData¶
Ряд методов поддерживает фильтрацию и выборку данных в стиле OData. В описаниях методов могут использоваться следующие параметры:
$filter— фильтрация по условиям;$select— выбор отдельных полей;$expand— раскрытие связанных сущностей;$orderBy— сортировка;$top— ограничение числа записей;$skip— пропуск указанного числа записей;$count— запрос количества записей.
Конкретный синтаксис выражений в $filter, $orderBy и правила комбинации параметров следует смотреть в описании соответствующих методов API.
13. Ошибки API¶
При ошибках бизнес-валидации API CARGO.RUN возвращает:
- HTTP-код 400 (Bad Request)
- тело ответа в виде обычного текстового сообщения, без JSON-структуры
Формат ответа:
Пример: