Перейти к содержанию

Отчеты API

Раздел описывает методы для получения данных отчетности и бизнес-аналитики.

Получение заказов для BI

GET /api/Orders/GetListForBI

Метод возвращает данные заказов для системы бизнес-аналитики экспедитора.

Используйте метод, когда внешняя BI-система должна регулярно забирать измененные заказы из CARGO.RUN Загрузки и строить витрины, отчеты или аналитические показатели.

Query-параметры

Параметр Описание
$filter Фильтр по полям модели. Для инкрементальной загрузки используйте фильтр по updatedAt
$orderby Сортировка по полям модели. Для стабильной инкрементальной выгрузки рекомендуется updatedAt asc
$top Ограничение количества записей
$skip Смещение

Пример запроса

GET /api/Orders/GetListForBI?$filter=updatedAt ge 2026-07-01T00:00:00Z&$top=30&$skip=0

Для регулярной синхронизации рекомендуется дополнительно сортировать результат по updatedAt asc:

GET /api/Orders/GetListForBI?$filter=updatedAt ge 2026-07-01T00:00:00Z&$orderby=updatedAt asc&$top=30&$skip=0

Правило инкрементальной загрузки

После обработки страницы BI-система должна сохранить самую позднюю дату updatedAt из полученных заказов и использовать ее в следующем запросе.

Не используйте время выполнения запроса как контрольную точку. Если взять текущее время клиента или сервера, можно пропустить заказ, который был обновлен до завершения запроса, но вернулся на текущей странице позже из-за пагинации или задержки обработки.

Рекомендуемый алгоритм:

  1. Выполнить запрос с фильтром по последней сохраненной контрольной точке updatedAt.
  2. Обработать все заказы из data.
  3. Найти максимальное значение updatedAt среди полученных заказов.
  4. Сохранить это значение как новую контрольную точку.
  5. Использовать сохраненное значение в следующем запросе.

Если используется оператор ge, заказ с updatedAt, равным контрольной точке, может вернуться повторно. BI-система должна безопасно обрабатывать такие дубли, например по паре id + updatedAt.

Ответ

Метод возвращает объект:

Поле Тип Описание
data OrderListForBIModel[] Массив заказов
totalCount long? Общее количество записей, подходящих под фильтр

Если данных нет, data может быть пустым массивом.

Поля элемента data[]

Поле Описание Тип
id ID заказа long
externalId Внешний ID заказа string
externalNumber Внешний номер заказа string
loadPlanEnterTime Плановое время прибытия на погрузку DateTimeOffset
loadMaxPlanEnterTime Максимально допустимое время прибытия на погрузку DateTimeOffset?
unloadPlanEnterTime Плановое время прибытия на выгрузку DateTimeOffset
unloadMaxPlanEnterTime Максимально допустимое время прибытия на выгрузку DateTimeOffset?
orderStatus Статус заказа OrderStatus
externalOrderStatus Внешний статус заказа ExternalOrderStatus?
sourceType Источник заказа SourceType
loadsParserSourceType Источник из сервиса парсинга SourceType?
counterpartyId ID контрагента long?
counterpartyName Наименование контрагента string
counterpartyInn ИНН контрагента string
distanceKm Расстояние, км double?
regionFromId ID региона отправления long?
regionFromName Наименование региона отправления string
regionToId ID региона назначения long?
regionToName Наименование региона назначения string
locationFrom Локация отправления string
locationTo Локация назначения string
districtFrom Район отправления string
districtTo Район назначения string
trailerTypes Список типов прицепов SelectListModel[]
trailerTypes.id ID типа прицепа long
trailerTypes.name Наименование типа прицепа string
cargoTypeId ID типа груза long?
cargoTypeName Наименование типа груза string
volume Объем double?
cargoWeight Вес груза double?
orderCost Стоимость заказа double?
isGuaranteed Признак гарантированного заказа bool?
createdById ID пользователя, создавшего заказ long
createdByName Имя/ФИО пользователя, создавшего заказ string
authorId ID автора заказа long?
authorName Имя/ФИО автора заказа string
createdAt Дата создания DateTimeOffset
updatedAt Дата обновления DateTimeOffset
respondedUserId ID пользователя, который откликнулся long?
respondedUserName Имя/ФИО пользователя, который откликнулся string