Форматы данных¶

В этом разделе приведены единые форматы данных, используемые во всех методах API CARGO.RUN Логистика.

1. Формат даты и времени¶

Основной формат¶

API использует ISO 8601, но трактовка часового пояса зависит от поля.

Категория	Формат	Трактовка
Технические метки (`createdAt`, `updatedAt`) и границы OData-фильтров	`YYYY-MM-DDTHH:mm:ssZ`	UTC
Поля с суффиксом `Offset`	`YYYY-MM-DDTHH:mm:ss±HH:mm`	Момент времени с явным смещением
`bidPoints[].planEnterDate` и другие явно локальные плановые даты	`YYYY-MM-DDTHH:mm:ss`	Локальное время адреса точки; зона определяется по геоданным точки

Примеры: - 2025-03-12T15:20:00Z - 2025-03-12T18:20:00+03:00 - 2025-03-12T18:20:00

Исключение: метод получения пробегов /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

Особенности¶

Для updatedAt и других технических меток используйте UTC с Z.
Для planEnterDate передавайте локальное время точки без Z; геозона должна позволять системе определить часовой пояс.
Не добавляйте Z к локальной дате: это изменит смысл времени.
Если конкретный метод задаёт другой формат, его описание имеет приоритет.
Доли секунды не используйте, если они не показаны в описании метода.

2. Числовые идентификаторы (ID)¶

Идентификаторы сущностей передаются только как целые числа.

Правильно:

12345

Неправильно:

"12345"

Это требование распространяется на:

заявки (bidId)
заказы (orderId)
контрагентов (counterpartyId)
водителей (driverId)
автомобили (carId)
прицепы (trailerId)
организации (organizationId)
сотрудников (employeeId)
трекеры (trackerId)

3. Телефонные номера¶

Телефон передаётся в международном формате:

+7XXXXXXXXXX

Где:

нет пробелов,
нет дефисов,
код страны обязательно +7.

Пример:

+79991234567

4. Координаты¶

Координаты передаются в виде двух числовых значений:

latitude — широта
longitude — долгота

Формат:

{
  "latitude": 55.7558,
  "longitude": 37.6176
}

Допускается использование вложенных структур (например, GeoJSON), если это описано в конкретном методе API.

5. Адреса¶

Адрес всегда содержит следующие элементы (если применимо):

строка адреса,
город,
регион,
страна,
геокоординаты,
дополнительные комментарии.

Используемые поля зависят от конкретного эндпоинта.

6. Денежные значения и ставки¶

Стоимость, суммы, ставки и другие денежные поля передаются как числа с фиксированной точностью:

только число, без строк;
без символа валюты;
разделитель — точка.

Примеры:

1000
12000.5
0.0

7. Boolean (логические значения)¶

Используются стандартные JSON-значения:

true
false

Недопустимо:

"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) - тело ответа в виде обычного текста либо объекта ValidationApiResult с полем errorMessage — в зависимости от метода

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

400 Bad Request
<текст ошибки>

Пример:

400 Bad Request
Driver cannot be deleted because he has active bids

Клиенту не следует предполагать единственный Content-Type ошибки. Сначала проверьте тип содержимого ответа; если получен JSON, прочитайте errorMessage, иначе сохраните текст ответа целиком.