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

В этом разделе собраны общие правила, которые применяются ко всем методам API CARGO.RUN Загрузки.

1. Формат запросов¶

Запросы передаются в JSON:

Content-Type: application/json

Для методов списков параметры фильтрации, сортировки и пагинации передаются в query string.

2. Авторизация¶

Все методы, кроме авторизации и отдельных публичных методов регистрации, требуют токен.

Токен передается в заголовке:

Authorization: Bearer <access_token>

Access token действует около 30 минут. После истечения срока действия нужно использовать POST /api/Account/RefreshToken, а не запрашивать новый токен перед каждым вызовом.

3. Даты и время¶

Дата и время передаются в формате ISO 8601.

Пример:

{
  "timestamp": "2026-06-22T17:05:00.123Z"
}

В ответах API даты приходят в UTC или с явным смещением часового пояса. В точках маршрута также может возвращаться timezoneId, например Europe/Moscow.

4. Фильтрация и пагинация¶

Для списков используется OData-подобный формат query-параметров:

Параметр	Назначение
`$filter`	Условие фильтрации
`$orderby`	Сортировка
`$top`	Количество возвращаемых записей
`$skip`	Количество пропускаемых записей

Примеры:

GET /api/Orders/GetIntegrationList?$top=50&$skip=0

GET /api/Orders/GetIntegrationList?$filter=updatedAt ge 2026-06-01T00:00:00.000Z

GET /api/TransporterOrders/GetList?$filter=loadStart ge 2026-06-24T21:00:00.000Z and loadStart le 2026-06-29T21:00:00.000Z

Для текстового поиска по справочникам можно использовать:

$filter=contains(tolower(name),'тент')

5. Ответы списков¶

Большинство методов списков возвращают объект:

{
  "data": [],
  "totalCount": 0
}

data содержит массив элементов, totalCount — общее количество записей с учетом фильтра.

6. Ошибки¶

Типовые HTTP-коды:

Код	Значение
`200`	Успешный запрос
`400`	Ошибка валидации или бизнес-правила
`401`	Ошибка авторизации
`500`	Ошибка сервера

Рекомендуется логировать тело ответа при ошибках 400 и 500, чтобы быстрее находить проблемы интеграции.

7. Рекомендации по частоте запросов¶

Для polling рекомендуется ориентироваться на лимит до 10 запросов в секунду, если для конкретной интеграции не согласованы другие ограничения.