cargo.run-api-docs

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

В этом разделе приведены единые форматы данных, используемые во всех методах 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 — долгота

Формат:

{
  "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 поддерживают постраничную выборку.

Используются два механизма:

1. Классическая пагинация:
   • page — номер страницы (начиная с 1);
   • pageSize — количество элементов на странице.
2. OData-пагинация:
   • $top — максимальное количество записей;
   • $skip — количество записей, которые нужно пропустить.

Конкретный механизм для метода указан в описании эндпоинта (API Reference). Если метод принимает page/pageSize, их значения должны быть целыми числами ≥ 1. Если метод принимает $top/$skip, рекомендуется использовать их в духе OData:

• $top — ограничение выборки (например, 100);
• $skip — смещение (например, 0, 100, 200…).

---

12. Параметры OData

Ряд методов поддерживает фильтрацию и выборку данных в стиле OData.
В swagger используются следующие параметры:

• $filter — фильтрация по условиям;
• $select — выбор отдельных полей;
• $expand — раскрытие связанных сущностей;
• $orderBy — сортировка;
• $top — ограничение числа записей;
• $skip — пропуск указанного числа записей;
• $count — запрос количества записей.

Конкретный синтаксис выражений в $filter, $orderBy и правила комбинации параметров следует смотреть в описании соответствующих методов API.

---

13. Ошибки API

При ошибках бизнес-валидации API CARGO.RUN возвращает:

• HTTP-код 400 (Bad Request)
• тело ответа в виде обычного текстового сообщения, без JSON-структуры

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

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

Пример:

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