Сценарий: CARGO.RUN → учетная система¶

В этом сценарии пользователь создает заказ в интерфейсе CARGO.RUN Загрузки, а внешняя система загружает заказ и дальнейшие изменения к себе.

1. Общий поток¶

Пользователь создает заказ в CARGO.RUN.
Внешняя система периодически запрашивает список заказов через GET /api/Orders/GetIntegrationList.
По каждому новому или измененному заказу внешняя система запрашивает детали через GET /api/Orders/GetInfo.
Внешняя система сохраняет заказ у себя и сопоставляет его со своим внутренним идентификатором.
После выбора перевозчика и выполнения перевозки внешняя система забирает итоговые данные: статусы, фактические времена, перевозчика, ТС, водителя.

2. Получение списка заказов¶

Основной метод:

GET /api/Orders/GetIntegrationList

Метод поддерживает:

$filter;
$orderby;
$top;
$skip.

Рекомендуется использовать фильтр по дате изменения:

GET /api/Orders/GetIntegrationList?$filter=updatedAt gt 2026-06-30T16:37:14.138307%2B00:00&$orderby=updatedAt asc&$top=100

GetIntegrationList рекомендуется использовать только для поиска новых и измененных заказов. Для сохранения заказа в учетной системе после получения id запрашивайте полную карточку через GET /api/Orders/GetInfo.

Если заказ был изменен после сохраненной контрольной точки, он появится в списке с новым updatedAt. После успешной обработки страницы сохраните максимальное updatedAt как новую контрольную точку.

3. Получение деталей заказа¶

GET /api/Orders/GetInfo?Id={order_id}

Метод возвращает:

маршрутные точки;
параметры груза;
стоимость и тип цены;
статус заказа;
статус заявки;
отклики перевозчиков;
выбранного перевозчика;
ТС, прицеп и водителя;
фактические времена по точкам;
внешние идентификаторы;
данные аукциона или предложений цены.

Минимальная карта полей для учетной системы¶

Что сохранить	Где взять
ID заказа CARGO.RUN	`id`
Статус заказа	`status`
Статус выполнения	`bidStatus`
Дата создания	`createdAt`
Стоимость заказчика	`orderCost`
НДС заказчика	`ndsTypeId`, `ndsTypeName`
Заказчик	`counterpartyId`, `counterpartyName`
Экспедитор	`organizationId`, `organizationName`
Перевозчик	`transporterInfo.organizationId`, `transporterInfo.organizationName`
Стоимость перевозчика	`transporterInfo.price` или `invitedFleetPrice`
НДС перевозчика	`transporterNdsType`
Машина и прицеп	`truckNumber`, `trailerNumber`
Водитель	`driverFullName`, `driverPhoneNumber`
Комментарий	`comment`
Груз	`cargoCost`, `cargoType`, `cargoWeight`, `packTypeNames`, `packCount`
Тип полуприцепа	`trailerTypeNames`
Тип стоимости	`orderPriceType`
Маршрут	`points[]`

Для завершенной перевозки обычно используются status = 40 (Completed) и bidStatus = 60 (Done). Если нужно загружать заказы в работе, используйте и промежуточные значения bidStatus, например 41 (Loaded).

4. Сопоставление с внешней системой¶

Если заказ был создан в CARGO.RUN, внешняя система должна сохранить ID заказа CARGO.RUN.

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

Поле	Назначение
`id`	ID заказа CARGO.RUN
`externalId`	ID во внешней системе, если передан
`externalInternalId`	Дополнительный номер внешней системы
`updatedAt`	Дата последнего изменения

5. Получение результата выполнения¶

После выбора перевозчика и запуска в работу в заказе появляются:

transporterInfo;
truckNumber;
trailerNumber;
driverFullName;
driverPhoneNumber;
orderTruckMatchingId;
bidStatus;
фактические времена в points.

Эти поля используются для загрузки результатов работы с заказом во внешнюю систему.

Если перевозчик еще не выбран, например заказ находится в состоянии нового запущенного заказа без откликов, transporterInfo, truckNumber, trailerNumber и телефон водителя могут быть null, а matchingCars может быть пустым массивом.

Пример итоговых данных¶

{
  "id": 1552749,
  "status": 40,
  "bidStatus": 60,
  "orderCost": 24400,
  "ndsTypeName": "НДС 22%",
  "counterpartyName": "ООО \"Делаем загрузки\"",
  "organizationName": "ltgf",
  "transporterInfo": {
    "organizationId": 95714,
    "organizationName": "ООО \"Перевоз-Холодос\"",
    "price": 22000
  },
  "transporterNdsType": "НДС 22%",
  "truckNumber": "А001АА116",
  "trailerNumber": "АА123456",
  "driverFullName": "Морозов Иван Афанасьевич",
  "driverPhoneNumber": "72441262995",
  "points": [
    {
      "index": 0,
      "pointType": 10,
      "location": {
        "address": "Республика Мордовия, рабочий посёлок Атяшево",
        "latitude": 54.588027,
        "longitude": 46.077537
      },
      "planEnterTimeOffset": "2026-06-30T06:10:00+03:00",
      "factEnterTimeOffset": "2026-06-30T08:30:00+03:00",
      "factLeaveTimeOffset": "2026-06-30T08:35:00+03:00"
    }
  ]
}

6. Рекомендации по polling¶

Используйте фильтр по updatedAt, чтобы не забирать все заказы каждый раз.
Ограничивайте размер страницы через $top.
Сохраняйте последнее успешно обработанное время синхронизации.
Логируйте ошибки и ID заказов, которые не удалось обработать.