Работа с заявками (Bids)¶
Этот раздел описывает методы API CARGO.RUN, использующиеся для создания, обновления, получения, удаления и управления статусами заявок.
Общие правила работы API, в том числе паттерн Apply, приведены в файле:
Минимальные обязательные поля заявки — в:
Сценарии интеграции описаны в:
- CARGO.RUN → учетная система
- Учетная система → CARGO.RUN
- Синхронизация данных
- Синхронизация заявок API 2.0
1. Создание и обновление заявки¶
1.1. Полное создание или обновление заявки¶
Назначение¶
- Создание новой заявки (
id = 0) - Полное обновление существующей заявки (
id > 0)
В теле запроса передается полная модель заявки. При каждом вызове Apply модель
перезаписывает сохранённое состояние заявки. Для обновления (id > 0) сначала
получите актуальную карточку, объедините изменения и передайте все значения, которые
должны сохраниться. Для изменения отдельных полей используйте Patch.
externalId не уникален и не обеспечивает идемпотентность. После создания сохраните
возвращённый id CARGO.RUN и используйте именно его для всех последующих операций.
Основные поля тела запроса¶
| Поле | Тип | Обязательность | Описание |
|---|---|---|---|
id |
long |
Да | 0 для создания новой заявки, ID существующей заявки для обновления |
cargoOwnerDictionaryItemId |
long? |
Да, кроме порожней заявки | ID заказчика/контрагента |
paymentTypeId |
long? |
Да | Тип оплаты; для порожней заявки требуется валидный технический ID, значение игнорируется |
ndsTypeId |
long? |
Да | Тип НДС; для порожней заявки требуется валидный технический ID, значение игнорируется |
price |
double? |
Да | Стоимость заявки; для порожней заявки передайте техническое значение, например 1, оно игнорируется |
driver |
object? |
Да | Водитель |
carOption |
object? |
Да | Автомобиль/тягач |
trailerOption |
object? |
Да | Прицеп |
bidPoints |
BidPointEditModel[] |
Да | Маршрутные точки, минимум две: погрузка и выгрузка |
cargos |
CargoModel[]? |
Да | Грузы; для порожней заявки нужен непустой технический массив, значения игнорируются |
typeOptions |
TypeOptionModel[]? |
Нет | Пользовательские справочники и дополнительные опции |
externalId |
string? |
Нет | Внешний ID заявки; не уникален и не заменяет id CARGO.RUN |
comment |
string? |
Нет | Комментарий |
clientBidNumber |
string? |
Нет | Номер заявки клиента |
clientBidDate |
date-time? |
Нет | Дата заявки клиента |
isEmptyMileageBid |
boolean? |
Нет | Признак порожней заявки |
emptyMileageBid |
EmptyMileageBidModel? |
Условно | Причина порожнего пробега; обязательна, если в организации включён учёт причин |
Поля bidPoints[]¶
| Поле | Тип | Обязательность | Описание |
|---|---|---|---|
id |
long |
Да | 0 для новой точки, ID существующей точки для обновления |
order |
int |
Да | Порядковый номер точки в маршруте |
type |
BidPointType |
Да | Тип точки, например погрузка или выгрузка |
customPointTypeId |
long? |
Нет | Тип пользовательской точки, если type = CustomPoint |
planEnterDate |
date-time? |
Нет | Плановое время прибытия |
secondaryPlanEnterDate |
date-time? |
Нет | Дополнительное плановое время |
geozone |
MapObjectEditModel? |
Да | Геозона/адрес точки |
counterpartyId |
long? |
Нет | Контрагент точки |
contactPerson |
object? |
Нет | Контактное лицо точки |
comment |
string? |
Нет | Комментарий к точке |
loadOptions |
object[]? |
Нет | Опции погрузки/выгрузки |
Значения BidPointType¶
| Значение | Код | Описание |
|---|---|---|
StartPoint |
0 |
Стартовая точка маршрута |
LoadPoint |
1 |
Точка погрузки |
UnloadPoint |
2 |
Точка выгрузки |
CustomPoint |
3 |
Пользовательская точка маршрута. Для нее можно передать customPointTypeId |
Поля bidPoints[].geozone¶
geozone описывает адрес и географию точки маршрута.
| Поле | Тип | Обязательность | Описание |
|---|---|---|---|
id |
long |
Да | ID геообъекта. Для новой точки обычно передается 0 |
location |
PointEditModel |
Да | Координаты точки |
city |
string? |
Нет | Город |
address |
string? |
Нет | Полный адрес |
village |
string? |
Нет | Населенный пункт |
state |
string? |
Нет | Регион |
county |
string? |
Нет | Район |
street |
string? |
Нет | Улица |
houseNumber |
string? |
Нет | Номер дома |
federalDistrict |
string? |
Нет | Федеральный округ |
radius |
double? |
Нет | Радиус геозоны |
type |
MapObjectType |
Да | Тип геообъекта |
Поля bidPoints[].geozone.location¶
| Поле | Тип | Обязательность | Описание |
|---|---|---|---|
coordinates |
double[]? |
Нет | Координаты точки. Обычно передаются в формате [долгота, широта] |
Значения MapObjectType¶
| Значение | Код | Описание |
|---|---|---|
None |
0 |
Тип не задан |
BidPoint |
1 |
Точка заявки |
RouteSupportPoint |
2 |
Опорная точка маршрута |
GasStation |
3 |
АЗС |
StartBidPoint |
4 |
Стартовая точка заявки |
PostamatPoint |
5 |
Постамат |
ItemChangePoint |
6 |
Точка перецепки или пересменки |
ServicePoint |
7 |
Сервисная точка |
CounterpartyPoint |
8 |
Точка контрагента |
TripCouplingPoint |
9 |
Точка сцепки рейса |
Поля bidPoints[].contactPerson¶
| Поле | Тип | Обязательность | Описание |
|---|---|---|---|
id |
long |
Да | ID контактного лица |
name |
string? |
Нет | Имя контактного лица |
phoneNumber |
string? |
Нет | Телефон контактного лица |
Поля bidPoints[].loadOptions[]¶
| Поле | Тип | Обязательность | Описание |
|---|---|---|---|
id |
long |
Да | ID опции погрузки или выгрузки |
Как читать массивы, справочники и перечисления¶
| Признак в поле | Что означает | Примеры |
|---|---|---|
Тип заканчивается на [] |
Поле содержит массив объектов или значений | bidPoints, cargos, typeOptions, loadOptions, accessPermitIds |
Название заканчивается на Id или Ids |
Поле ссылается на существующий объект или элемент справочника | counterpartyId, paymentTypeId, ndsTypeId, driverId, accessPermitIds |
Тип указан как отдельная модель с обязательным id |
Нужно передать ссылку на существующий объект и, если требуется, дополнительные поля модели | contactPerson, loadOptions |
| Тип имеет фиксированный список значений | Это перечисление, а не справочник | BidPointType, MapObjectType |
Поля cargos[]¶
| Поле | Тип | Обязательность | Описание |
|---|---|---|---|
id |
long |
Да | 0 для нового груза, ID существующего груза для обновления |
typeId |
long? |
Нет | Тип груза |
name |
string? |
Нет | Наименование груза |
weight |
double? |
Нет | Вес |
volume |
double? |
Нет | Объем |
length |
double? |
Нет | Длина |
width |
double? |
Нет | Ширина |
height |
double? |
Нет | Высота |
loadingTypeId |
long? |
Нет | Тип погрузки |
unloadingTypeId |
long? |
Нет | Тип выгрузки |
comment |
string? |
Нет | Комментарий к грузу |
Поля typeOptions[]¶
| Поле | Тип | Обязательность | Описание |
|---|---|---|---|
id |
long |
Да | ID элемента пользовательского справочника |
entityOptionId |
long |
Да | ID настройки/свойства справочника |
Поля emptyMileageBid¶
Используются только при isEmptyMileageBid = true.
| Поле | Тип | Описание |
|---|---|---|
logisticReasonTypeId |
long? |
Причина из справочника EmptyMileageBidReasonType для обычной порожней заявки |
technicalReason |
string? |
Текст технической причины, не более 256 символов, для технической порожней заявки |
Передавайте одно из этих полей в соответствии с типом заявки. Для обычной
порожней заявки technicalReason должен быть null; для технической заявки
logisticReasonTypeId должен быть null. Если у организации отключён учёт причин,
объект может быть опущен.
Особенности¶
- поддерживает как создание, так и полное обновление;
- при создании статус заявки —
New(черновик); - при ошибках валидации API возвращает HTTP 4xx с текстом ошибки.
Пример создания заявки¶
В примере показан запрос на создание черновика заявки. Он адаптирован из payload фронта: служебные поля интерфейса и поля состояния не передаются, а id новых объектов указаны как 0.
{
"id": 0,
"cargoOwnerDictionaryItemId": 129647034,
"legalPersonId": 127039077,
"paymentTypeId": 41,
"ndsTypeId": 129493473,
"price": 45000,
"isVatTop": false,
"contractNumber": "324352352352",
"paymentPeriodType": "InCalendarDays",
"responsibleId": 1466813,
"isDriverForwarder": false,
"isEmptyMileageBid": false,
"createDocumentAssignment": false,
"driver": {
"id": 1478168
},
"carOption": {
"carId": 1465629
},
"trailerOption": {
"trailerId": 128820197
},
"bidPoints": [
{
"id": 0,
"order": 0,
"type": "LoadPoint",
"comment": "Комментарий к первой точке",
"planEnterDate": "2026-07-15T10:58:00",
"cargoOwnerDictionaryItemId": 129647035,
"geozone": {
"id": 0,
"location": {
"type": "Point",
"coordinates": [
47.4720139,
55.86623
]
},
"city": "Цивильск",
"address": "Россия, Чувашская Республика — Чувашия, Цивильск, улица Гагарина",
"state": "Чувашская Республика — Чувашия",
"county": "Цивильский муниципальный округ",
"street": "улица Гагарина",
"houseNumber": null,
"federalDistrict": "Приволжский федеральный округ",
"radius": 2000,
"type": "BidPoint"
},
"contactPerson": {
"id": 129417981,
"phoneNumber": "+7 964 781-40-98",
"name": "Александр Пушкин"
},
"loadOptions": [
{
"id": 4612889
}
],
"typeOptions": [],
"extendedProperties": []
},
{
"id": 0,
"order": 1,
"type": "UnloadPoint",
"comment": "Комментарий к выгрузке",
"planEnterDate": "2026-07-16T11:10:00",
"cargoOwnerDictionaryItemId": 129647014,
"geozone": {
"id": 0,
"location": {
"type": "Point",
"coordinates": [
55.9507846,
54.7017154
]
},
"city": "Уфа",
"address": "Россия, Республика Башкортостан, Уфа, Сарапульская улица, 35",
"state": "Республика Башкортостан",
"county": "городской округ Уфа",
"street": "Сарапульская улица",
"houseNumber": "35",
"federalDistrict": "Приволжский федеральный округ",
"radius": 1999,
"type": "BidPoint"
},
"contactPerson": {
"id": 129417982,
"phoneNumber": "8 914 781 07 01",
"name": "Михаил Лермонтов"
},
"loadOptions": [
{
"id": 4612889
}
],
"typeOptions": [],
"extendedProperties": []
}
],
"cargos": [
{
"id": 0,
"name": "Крышки",
"weight": 20,
"volume": 5,
"length": 6,
"height": 8,
"width": 7,
"typeId": 712,
"packType": "Паллеты",
"comment": "Комментарий к грузу",
"extendedProperties": [],
"typeOptions": []
}
],
"extendedProperties": [
{
"propertyName": "CustomeFieldForDemo",
"value": "Пример заполнения кастомного поля"
}
],
"typeOptions": [],
"documents": [],
"accessPermitIds": []
}
Успешный ответ¶
При успехе метод возвращает служебный результат сохранения, включая идентификатор заявки и ее статус. Набор полей может быть шире примера, поэтому интеграция должна читать нужные поля и допускать появление дополнительных.
Сохраните entityId как ID заявки CARGO.RUN. Перед запуском при необходимости перечитайте заявку, затем измените статус отдельным методом.
1.2. Частичное обновление заявки (Patch)¶
Назначение¶
- обновление только изменённых полей заявки.
Ограничения¶
- нельзя частично изменить вложенные структуры (
bidPoints,cargos,typeOptionsи др.); - если нужно изменить маршрутные точки — необходимо передать весь массив
bidPoints, включая неизменённые точки.
2. Управление статусами и жизненным циклом¶
2.1. Запуск заявки в работу¶
Тело запроса¶
bidId — фактический идентификатор существующей заявки.
Вручную поддерживается запуск со значением Started. Если машина занята и для
организации включено планирование, система может сохранить заявку как Planned.
Значение Planned нельзя устанавливать этим методом напрямую.
При успехе метод возвращает:
2.2. Отмена заявки¶
Тело запроса¶
2.3. Закрытие заявки вручную¶
Тело запроса¶
{
"bidId": 123456,
"reason": "string",
"mileage": 0,
"useOdometerMileage": true,
"bidPoints": [
{
"id": 654321,
"enteredAtByLogist": "2025-05-07T07:15:04Z",
"loadUnloadedAtByLogist": "2025-05-07T07:15:04Z",
"loadUnloadStatus": "AtLoading"
}
]
}
2.4. Возврат заявки в черновик¶
Тело запроса¶
3. Удаление и восстановление¶
3.1. Удаление заявки¶
Тело запроса¶
Заявка должна быть предварительно переведена в статус New (через /api/truckingbids/revert).
3.2. Восстановление удалённой заявки¶
Тело запроса¶
4. Получение заявок¶
4.1. Получение заявки для редактирования¶
Параметры:
id— идентификатор заявки.
4.2. Получение списка заявок (инкрементальная синхронизация)¶
Метод возвращает список заявок по фильтру для внешних сервисов с более подробной информацией. Используется OData-формат параметров.
У каждой заявки есть поле updatedAt — дата последнего изменения заявки в CARGO.RUN.
Для инкрементальной синхронизации обрабатывайте фиксированные окна времени с
перекрытием и дедупликацией по id и updatedAt. Не продвигайте границу окна до
успешной обработки всех страниц. Подробный алгоритм приведён в разделе
Синхронизация данных.
Поддерживает:
$filter$orderby$top$skip
Пример запроса:
GET /api/bids/GetListForExternal
?$filter=updatedAt ge 2024-01-23T21:00:00Z
and updatedAt le 2024-01-25T20:59:59Z
and createdAt ge 2022-09-30T21:00:00Z
&$top=50
&$orderby=updatedAt
&$skip=0
Запрос возвращает заявки:
- дата обновления которых больше или равна
24.01.2024 00:00 МСК(2024-01-23T21:00:00Z); - дата обновления которых меньше или равна
25.01.2024 23:59:59 МСК(2024-01-25T20:59:59Z); - дата создания которых больше или равна
01.10.2022 00:00 МСК(2022-09-30T21:00:00Z), если нужно ограничить выборку по дате создания; - первые 50 записей, начиная с позиции 0;
- отсортированные по дате обновления
updatedAt.
Все списки необходимо получать порциями по 50 записей для минимизации нагрузки на сервер. Если получать полные списки без ограничения количества, пользователь может быть временно заблокирован системой.
Подробное описание в:
Основные поля ответа BidForExternalSyncModel¶
Метод возвращает массив заявок. Общее количество записей передается в заголовке X-MetaCount.
| Поле | Тип | Описание |
|---|---|---|
id |
long |
ID заявки |
status |
BidStatus |
Статус заявки |
price |
double? |
Цена |
priceWithoutVatOnTop |
double? |
Цена без НДС, если НДС сверху |
createdAt |
date-time |
Дата создания заявки |
updatedAt |
date-time |
Дата последнего изменения |
externalUpdatedAt |
date-time? |
Дата обновления из внешней системы |
createdById |
long |
ID пользователя, создавшего заявку |
approvedById |
long? |
ID пользователя, согласовавшего заявку |
approvedAt |
date-time? |
Дата согласования |
responsibleId |
long? |
ID ответственного |
salesManagerId |
long? |
ID менеджера по продажам |
carLogistId |
long? |
ID логиста автомобиля на момент создания заявки |
paymentTypeId |
long |
Тип оплаты |
ndsTypeId |
long |
Тип НДС |
isVatTop |
boolean |
НДС начисляется сверху |
counterpartyId |
long? |
ID контрагента |
contractId |
long? |
ID договора контрагента |
distributionBidId |
long? |
ID заказа, из которого создана заявка |
routeId |
long? |
ID маршрута |
driverId |
long? |
ID текущего водителя |
secondaryDriverId |
long? |
ID второго водителя |
isDriverForwarder |
boolean |
Водитель является экспедитором |
acceptedByDriverAt |
date-time? |
Дата принятия заявки водителем |
acceptedByDriverForwarderAt |
date-time? |
Дата принятия водителем-экспедитором |
car |
CarSimpleModel? |
Автомобиль |
trailer |
TrailerListViewModel? |
Прицеп |
legalPerson |
IdModel? |
Юридическое лицо |
bidPoints |
BidPointViewModel[]? |
Точки маршрута |
cargos |
CargoModel[]? |
Грузы |
typeOptions |
TypeOptionModel[]? |
Пользовательские справочники и дополнительные опции |
temperatureRegime |
BidTemperatureRegimeModel? |
Температурный режим |
temperature |
TemperatureValueModel? |
Текущая температура |
documents |
RelatedDocumentModel[]? |
Документы |
extendedProperties |
ExtendedPropertyJsonObject[]? |
Дополнительные поля заявки |
externalId |
string? |
Внешний ID |
contractNumber |
string? |
Номер договора |
comment |
string? |
Комментарий |
clientBidNumber |
string? |
Номер заявки клиента |
clientBidDate |
date-time? |
Дата заявки клиента |
paymentPeriodInDays |
int? |
Срок оплаты в днях |
paymentPeriodType |
PaymentPeriodType? |
Вариант срока оплаты |
sourceType |
SourceType |
Источник заявки |
hasFactoring |
boolean |
Заявка отправлена на факторинг |
isEmptyMileageBid |
boolean |
Порожняя заявка |
isInternational |
boolean |
Международная заявка |
hasItemsChange |
boolean |
Есть перецепка/пересменка |
isDeleted |
boolean |
Заявка удалена |
createDocumentAssignment |
boolean |
Создавать задание сдачи документов после завершения |
hasServicePoints |
boolean |
Есть точки сервисных работ |
isPreBid |
boolean |
Предзаявка |
payment |
BidPaymentGetModel? |
Информация об оплате |
accessPermitIds |
long[]? |
Допуски и разрешения |
Поля extendedProperties[]¶
extendedProperties содержит пользовательские дополнительные поля заявки.
| Поле | Тип | Описание |
|---|---|---|
propertyName |
string |
Имя пользовательского поля |
value |
string? |
Значение, заданное пользователем |
Поля typeOptions[]¶
| Поле | Тип | Описание |
|---|---|---|
id |
long |
ID элемента пользовательского справочника |
entityOptionId |
long |
ID настройки/свойства справочника |
Чтобы получить человекочитаемое значение элемента, запросите GET /api/Catalogs/GetItems?$filter=id eq {typeOptions[].id}. Подробнее: Пользовательские справочники.
5. Получение связанных данных¶
5.1. Связанные документы¶
Возвращает связанные документы (внешние файлы) по заявке.
5.2. Данные по точкам заявки¶
Изменение точек выполняется:
- через
/apply— полная передача модели, - через
/patch— но с передачей всего массиваbidPoints.
5.3. Получение данных по перецепкам в заявке¶
Назначение¶
Получение данных о перецепках (замене прицепа) в рамках конкретной заявки.
Параметры¶
bidId— идентификатор заявки (query-параметр).
Комментарии¶
Метод возвращает список всех событий замены прицепа, зафиксированных по заявке: старый и новый прицеп, время замены, источник данных и комментарий (если задан).
Основные поля ответа¶
| Поле | Тип | Описание |
|---|---|---|
id |
long |
ID события замены |
bidId |
long |
ID заявки |
oldTrailerId |
long? |
ID старого прицепа |
oldTrailerNumber |
string? |
Номер старого прицепа |
newTrailerId |
long? |
ID нового прицепа |
newTrailerNumber |
string? |
Номер нового прицепа |
replacedAt |
date-time? |
Дата и время замены |
sourceType |
SourceType? |
Источник данных |
comment |
string? |
Комментарий |
5.4. Обновление данных по оплате заявки¶
Назначение¶
Установка или изменение данных по оплате заявки.
Используйте ApplyBidPayment, если внешняя система (например, 1С) фиксирует оплату по заявке и должна передать в CARGO.RUN статус оплаты, дату оплаты, плановую дату оплаты, сумму остатка или комментарий.
Тело запроса¶
Тело описано моделью BidPaymentWrapperModel:
{
"bidId": 123456,
"payment": {
"paymentStatus": "Paid",
"factPaymentDate": "2026-06-30",
"planPaymentDate": "2026-07-05",
"invoiceDate": "2026-06-29",
"remainingPayment": 0,
"comment": "Оплата получена"
}
}
Поля:
bidId— идентификатор заявки;payment— данные оплаты (BidPaymentModel);payment.paymentStatus— статус оплаты, обязательное поле;payment.factPaymentDate— фактическая дата оплаты;payment.planPaymentDate— плановая дата оплаты;payment.invoiceDate— дата счёта;payment.remainingPayment— остаток к оплате;payment.comment— комментарий по оплате.
Поддерживаемые значения¶
Поддерживаемые значения payment.paymentStatus:
NotPaidPartiallyPaidPaidExpired
6. Ошибки¶
Возможные ошибки:
- невалидные данные (
paymentTypeId,ndsTypeId, элементы геозон и т.д.); - попытка удалить заявку без предварительного
revert; - частичное обновление вложенных структур через
/patch.
Поведение API:
- ошибки бизнес-валидации возвращаются с HTTP-статусом
400; - тело ошибки может быть обычным текстом или JSON-объектом
ValidationApiResult; - не повторяйте запрос с теми же данными после
400: сначала исправьте payload; - при
401обновите токен и повторите запрос один раз; - при
429или временной ошибке5xxиспользуйте ограниченные повторы с увеличивающейся задержкой.
Общий формат обработки ошибок описан в разделе Форматы данных.