# CARGO.RUN Загрузки > Полная машиночитаемая версия. Источник: https://cargorun-ru.github.io/cargo.run-api-docs/products/cargorun-loads/ --- Source: products/cargorun-loads/index.md

CARGO.RUN Logo

# **CARGO.RUN Загрузки** — Документация по API Документация описывает интеграцию внешних учетных систем с продуктом **CARGO.RUN Загрузки**. Основной сценарий интеграции: грузоотправитель или экспедитор подключает свою систему, например 1С или ERP, чтобы создавать заказы в CARGO.RUN, получать отклики перевозчиков и забирать результаты выполнения перевозок обратно в свою систему. Дополнительно описан сценарий перевозчика: получение доступных заказов, отправка отклика, работа со справочниками ТС, прицепов и водителей. --- ## 1. С чего начать 1. Прочитать общее назначение API: [Введение](./introduction.md) 2. Ознакомиться с базовыми терминами: [Глоссарий](./glossary.md) 3. Проверить форматы данных, авторизацию и фильтрацию: [Форматы данных](./formats.md) 4. Изучить статусы заказов, заявок и откликов: [Статусы](./statuses.md) 5. Посмотреть минимальный набор данных для создания заказа: [Минимальные требования](./minimal-requirements.md) 6. Для интеграции с ИИ-агентом использовать: [Раздел для LLM и ИИ-агентов](./for-ai.md) --- ## 2. Сценарии интеграции Раздел для аналитиков и интеграторов, которые проектируют обмен между **CARGO.RUN Загрузки** и внешней системой. - Общая архитектура интеграции [Обзор интеграции](./integration/overview.md) - Сценарий: заказ создается во внешней системе [Учетная система → CARGO.RUN](./integration/scenario-external-to-cr.md) - Сценарий: заказ создается в CARGO.RUN [CARGO.RUN → учетная система](./integration/scenario-cr-to-external.md) - Работа с откликами и выбор перевозчика [Отклики перевозчиков](./integration/order-responses.md) - Отслеживание перевозки внешнего перевозчика [Отслеживание грузоперевозки экспедитором](./integration/scenario-forwarder-tracking.md) - Отдельный сценарий перевозчика [Интеграция перевозчика](./integration/scenario-transporter.md) - Синхронизация данных [Синхронизация](./integration/sync.md) --- ## 3. API Reference Технический справочник методов API, сгруппированных по доменам. - Общие правила API, ошибки и заголовки [Обзор API](./api/overview.md) - Реакция на ошибки и ограничения повторов [Ошибки и ограничения](./api/errors-and-limits.md) - Авторизация и обновление токена [Авторизация](./api/auth.md) - Заказы грузоотправителя/экспедитора [Orders API](./api/orders.md) - Жизненный цикл заказа [Order Lifecycle API](./api/order-lifecycle.md) - Отклики и выбор перевозчика [Order Responses API](./api/order-responses.md) - Отчетные данные для BI [Reports API](./api/reports.md) - Контрагенты, адреса и контактные лица [Counterparties API](./api/counterparties.md) - Геокодирование и маршруты [Map API](./api/map.md) - Справочники [Directories API](./api/directories.md) - API перевозчика [Transporter API](./api/transporter.md) --- **Последнее обновление:** 2026-10-16 --- Source: products/cargorun-loads/introduction.md # Введение API **CARGO.RUN Загрузки** предназначен для обмена данными между CARGO.RUN и внешними учетными системами грузоотправителей, экспедиторов и перевозчиков. Документация разделена на три части: 1. общие правила работы с API; 2. сценарии интеграции; 3. технический справочник методов. --- ## 1. Основной сценарий API Основной сценарий интеграции связан с заказами грузоотправителя или экспедитора. Внешняя система может: - создавать заказы в CARGO.RUN; - получать список заказов и их изменения; - получать отклики перевозчиков; - принимать отклик выбранного перевозчика; - получать данные о перевозчике, ТС, водителе и исполнении заказа; - синхронизировать статусы и фактические времена по точкам маршрута. Типовые внешние системы: - 1С; - ERP; - TMS; - WMS; - корпоративные интеграционные сервисы. --- ## 2. Дополнительный сценарий перевозчика API также поддерживает сценарий перевозчика. Перевозчик может: - зарегистрировать организацию; - авторизоваться; - получать доступные заказы; - отправлять отклики; - управлять справочниками ТС, прицепов и водителей; - получать назначенные заявки; - передавать фактические времена по точкам маршрута. Этот сценарий описан отдельно, чтобы не смешивать действия владельца заказа и действия перевозчика. --- ## 3. Архитектура интеграции API работает как REST API: - обмен выполняется по HTTPS; - запросы и ответы передаются в JSON; - авторизация выполняется через JWT-токен; - для списков используется фильтрация и пагинация в query-параметрах; - большинство методов возвращают HTTP `200 OK` при успехе и ошибку `400`, `401` или `500` при проблеме. --- ## 4. Основные потоки данных Поддерживаются два основных потока. ### Учетная система → CARGO.RUN Заказ создается во внешней системе и передается в CARGO.RUN через API. Затем CARGO.RUN используется для публикации заказа, получения откликов, выбора перевозчика и контроля исполнения. ### CARGO.RUN → учетная система Пользователь создает заказ в интерфейсе CARGO.RUN. Внешняя система периодически получает новые и измененные заказы, сохраняет их у себя и забирает результаты выполнения. --- ## 5. Что изучать дальше Для начала интеграции рекомендуется: 1. изучить [глоссарий](./glossary.md); 2. настроить [авторизацию](./api/auth.md); 3. выбрать основной [сценарий интеграции](./integration/overview.md); 4. проверить [минимальные требования](./minimal-requirements.md) к созданию заказа; 5. перейти к [Orders API](./api/orders.md). --- Source: products/cargorun-loads/minimal-requirements.md # Минимальные требования Раздел описывает минимальный набор данных, который обычно нужен для создания заказа через [`POST /api/Orders/Apply`](./api/orders.md#orders-apply). Точная обязательность отдельных полей зависит от бизнес-правил заказа, типа цены, выбранной организации, настроек доступа и справочников. --- ## 1. Минимальные обязательные поля модели В модели `ApplyOrderModel` обязательны: | Поле | Тип | Назначение | |---|---|---| | `id` | `long` | `0` при создании нового заказа | | `organizationId` | `long` | ID организации владельца заказа | | `withoutMatching` | `boolean` | Признак заказа без подбора перевозчика | | `requireHealthBook` | `boolean` | Требуется медкнижка | | `carryingCapacity` | `int` | Грузоподъемность | На практике для полноценного заказа также нужны точки маршрута, тип цены, контактные данные и параметры видимости. --- ## 2. Рекомендуемый минимум для создания заказа ```json { "id": 0, "organizationId": 33249, "withoutMatching": false, "requireHealthBook": false, "carryingCapacity": 0, "trucksCount": 1, "orderPriceType": 10, "orderCost": 80000, "points": [], "accessType": 30, "visibleForOrganizationsIds": [], "trailerTypeIds": [], "ndsTypeId": 3, "paymentTypeId": 1, "contactPersonName": "Имя контактного лица", "contactPersonPhoneNumber": "79999999999", "cargoCost": 3000000, "isInternal": false } ``` --- ## 3. Точки маршрута Для обычного заказа нужно минимум две точки: - погрузка (`pointType = 10`); - выгрузка (`pointType = 20`). Минимальная структура точки: ```json { "id": 0, "index": 0, "pointType": 10, "location": { "id": 0, "latitude": 55.74703593862486, "longitude": 37.61660648499558, "state": "Москва", "city": "Москва", "address": "Москва, Софийская набережная, 14с1" }, "planEnterTime": "2026-07-01T10:00:00" } ``` Адрес можно подобрать через `GET /api/Map/ReverseSearchAddresses`. --- ## 4. Видимость заказа Если заказ должен быть доступен только выбранным перевозчикам, используйте: ```json { "accessType": 30, "visibleForOrganizationsIds": [33352, 33277] } ``` Список перевозчиков можно получить через `GET /api/Organization/SelectRelationsOrganizationsList`. --- ## 5. Тип цены | `orderPriceType` | Когда использовать | |---:|---| | `10` | Фиксированная стоимость | | `20` | Аукцион | | `30` | Перевозчики предлагают цену | Для аукциона дополнительно используется `auctionModel`. --- ## 6. Поля для синхронизации с внешней системой Для связи заказа с внешней системой рекомендуется заполнять: | Поле | Назначение | |---|---| | `externalId` | ID заказа во внешней системе | | `externalInternalId` | Внутренний номер или дополнительный ID | | `externalCreatedAt` | Дата создания во внешней системе | Эти поля помогают сопоставлять заказы при обратной синхронизации. --- Source: products/cargorun-loads/formats.md # Форматы данных В этом разделе собраны общие правила, которые применяются ко всем методам API **CARGO.RUN Загрузки**. --- ## 1. Формат запросов Запросы передаются в JSON: ```http Content-Type: application/json ``` Для методов списков параметры фильтрации, сортировки и пагинации передаются в query string. --- ## 2. Авторизация Все методы, кроме авторизации и отдельных публичных методов регистрации, требуют токен. Токен передается в заголовке: ```http Authorization: Bearer ``` Access token действует около 30 минут. После истечения срока действия нужно использовать `POST /api/Account/RefreshToken`, а не запрашивать новый токен перед каждым вызовом. --- ## 3. Даты и время Дата и время передаются в формате ISO 8601. Пример: ```json { "timestamp": "2026-06-22T17:05:00.123Z" } ``` В ответах API даты приходят в UTC или с явным смещением часового пояса. В точках маршрута также может возвращаться `timezoneId`, например `Europe/Moscow`. --- ## 4. Фильтрация и пагинация Для списков используется OData-подобный формат query-параметров: | Параметр | Назначение | |---|---| | `$filter` | Условие фильтрации | | `$orderby` | Сортировка | | `$top` | Количество возвращаемых записей | | `$skip` | Количество пропускаемых записей | Примеры: ```http GET /api/Orders/GetIntegrationList?$top=50&$skip=0 ``` ```http GET /api/Orders/GetIntegrationList?$filter=updatedAt ge 2026-06-01T00:00:00.000Z ``` ```http GET /api/TransporterOrders/GetList?$filter=loadStart ge 2026-06-24T21:00:00.000Z and loadStart le 2026-06-29T21:00:00.000Z ``` Для текстового поиска по справочникам можно использовать: ```http $filter=contains(tolower(name),'тент') ``` --- ## 5. Ответы списков Большинство методов списков возвращают объект: ```json { "data": [], "totalCount": 0 } ``` `data` содержит массив элементов, `totalCount` — общее количество записей с учетом фильтра. --- ## 6. Ошибки Типовые HTTP-коды: | Код | Значение | |---:|---| | `200` | Успешный запрос | | `400` | Ошибка валидации или бизнес-правила | | `401` | Ошибка авторизации | | `500` | Ошибка сервера | Рекомендуется логировать тело ответа при ошибках `400` и `500`, чтобы быстрее находить проблемы интеграции. --- ## 7. Рекомендации по частоте запросов Для polling рекомендуется ориентироваться на лимит до 10 запросов в секунду, если для конкретной интеграции не согласованы другие ограничения. --- Source: products/cargorun-loads/statuses.md # Статусы В этом разделе приведены основные enum-значения, которые используются в API **CARGO.RUN Загрузки**. --- ## 1. Статусы заказа (`OrderStatus`) | Код | Значение | Описание | |---:|---|---| | `5` | `Draft` | Черновик | | `10` | `New` | Новый заказ | | `20` | `InSearch` | Поиск перевозчика | | `25` | `HasResponses` | Есть отклики перевозчиков | | `30` | `InWork` | Заказ в работе | | `35` | `InProgress` | Исполняется | | `40` | `Completed` | Завершен | | `50` | `Canceled` | Отменен | В интерфейсе заказ со статусом `New` может отображаться как запущенный заказ в поиске ТС, если перевозчик еще не выбран и откликов нет. Для интеграции ориентируйтесь на числовой код `status` из API. --- ## 2. Тип цены заказа (`OrderPriceType`) | Код | Значение | Описание | |---:|---|---| | `10` | `Static` | Фиксированная стоимость | | `20` | `Auction` | Аукцион | | `30` | `Offer` | Предложение цены | Для `Auction` и `Offer` ставка перевозчика обязательна. Для фиксированной стоимости ставка может не требоваться. --- ## 3. Тип доступа к заказу (`OrderAccessType`) | Код | Значение | Описание | |---:|---|---| | `10` | `Public` | Публичный заказ | | `20` | `RelationsOrganizationsOnly` | Только связанные организации | | `30` | `SelectedRelationsOrganizationsOnly` | Только выбранные связанные организации | При `SelectedRelationsOrganizationsOnly` список организаций задается в `visibleForOrganizationsIds`. --- ## 4. Статусы отклика (`MatchingStatus`) | Код | Значение | Описание | |---:|---|---| | `10` | `AcceptedInTruckOwner` | Принят перевозчиком | | `20` | `DeclinedInTruckOwner` | Отклонен перевозчиком | | `30` | `AcceptedInOrderOwner` | Принят владельцем заказа | | `40` | `DeclinedInOrderOwner` | Отклонен владельцем заказа | | `50` | `Awaiting` | Ожидает решения | Для основного сценария грузоотправителя/экспедитора ключевой переход — принятие отклика владельцем заказа через `POST /api/OrderTruckMatchings/Accept`. --- ## 5. Статусы заявки перевозчика (`BidStatus`) | Код | Значение | Описание | |---:|---|---| | `20` | `Draft` | Черновик | | `25` | `Planned` | Запланирована | | `30` | `Started` | Запущена | | `40` | `AtLoading` | На погрузке | | `41` | `Loaded` | Загружена | | `42` | `AtUnloading` | На выгрузке | | `43` | `Unloaded` | Разгружена | | `50` | `Canceled` | Отменена | | `60` | `Done` | Выполнена | --- ## 6. Тип точки маршрута (`PointType`) | Код | Значение | Описание | |---:|---|---| | `0` | `Default` | Не задано | | `10` | `Load` | Погрузка | | `20` | `Unload` | Выгрузка | | `30` | `Transit` | Транзит | --- Source: products/cargorun-loads/glossary.md # Глоссарий В документации используются термины **CARGO.RUN Загрузки**. Их важно различать, потому что часть терминов в интерфейсе и API может звучать похоже. --- ## Заказ Потенциальная перевозка, которую грузоотправитель или экспедитор создает в CARGO.RUN. Заказ содержит: - маршрутные точки; - параметры груза; - требования к ТС; - стоимость или тип торгов; - видимость для перевозчиков; - контактные данные; - отклики перевозчиков. Основные методы: - [`POST /api/Orders/Apply`](./api/orders.md#orders-apply); - [`GET /api/Orders/GetIntegrationList`](./api/orders.md#orders-get-integration-list); - [`GET /api/Orders/GetInfo`](./api/orders.md#orders-get-info). --- ## Заявка Рейс, по которому перевозчик уже выбран и перевозка находится в исполнении или была выполнена. В API перевозчика для таких рейсов используются методы `TransporterBids`. --- ## Отклик Предложение перевозчика выполнить заказ. Отклик может содержать: - перевозчика; - ТС; - прицеп; - водителя; - логиста перевозчика; - предложенную ставку; - статус отклика. В деталях заказа отклики доступны в поле `matchingCars`. --- ## Матчинг Техническое представление отклика или назначения перевозчика на заказ. В документации термины "отклик" и "матчинг" могут использоваться рядом: - "отклик" — пользовательский термин; - "матчинг" — термин API и моделей данных. --- ## Владелец заказа Организация, которая создала заказ или отвечает за его обработку. Обычно это грузоотправитель или экспедитор. Владелец заказа получает отклики и принимает выбранного перевозчика. --- ## Перевозчик Организация, которая видит доступные заказы и отправляет отклики. Перевозчик работает со своими справочниками: - ТС; - прицепы; - водители. --- ## Технический пользователь Учетная запись, используемая внешней системой для авторизации в API. При интеграции перевозчика такая учетная запись может создаваться вместе с организацией. Это обычный пользователь организации с правами, достаточными для работы с API. --- ## Тип цены заказа Поле `orderPriceType` определяет механику цены: | Код | Значение | Описание | |---:|---|---| | `10` | `Static` | Фиксированная стоимость | | `20` | `Auction` | Аукцион | | `30` | `Offer` | Предложение цены | --- ## Точка маршрута Погрузка, выгрузка или транзитная точка. Поле `pointType`: | Код | Значение | Описание | |---:|---|---| | `0` | `Default` | Не задано | | `10` | `Load` | Погрузка | | `20` | `Unload` | Выгрузка | | `30` | `Transit` | Транзит | --- Source: products/cargorun-loads/integration/overview.md # Обзор интеграции Этот раздел описывает архитектуру интеграции **CARGO.RUN Загрузки** с внешними системами: 1С, ERP, TMS, WMS и внутренними сервисами клиентов. --- ## 1. Основная модель интеграции Интеграция строится вокруг заказа на перевозку. Заказ может появиться двумя способами: 1. во внешней системе и затем быть передан в CARGO.RUN; 2. в интерфейсе CARGO.RUN и затем быть загружен во внешнюю систему. Обе модели поддерживаются API. --- ## 2. Участники процесса ### Грузоотправитель или экспедитор Создает заказ, управляет видимостью, получает отклики перевозчиков и выбирает исполнителя. Основные методы: - [`POST /api/Orders/Apply`](../api/orders.md#orders-apply); - [`GET /api/Orders/GetIntegrationList`](../api/orders.md#orders-get-integration-list); - [`GET /api/Orders/GetInfo`](../api/orders.md#orders-get-info); - [`POST /api/OrderTruckMatchings/Accept`](../api/order-responses.md#order-truck-matchings-accept); - [`POST /api/Orders/StartOrder`](../api/order-lifecycle.md#orders-start-order); - `POST /api/Orders/CancelOrder` — [жизненный цикл заказа](../api/order-lifecycle.md). ### Перевозчик Получает доступные заказы, отправляет отклики и передает данные по ТС, водителю и исполнению. Основные методы: - `GET /api/TransporterOrders/GetList`; - `GET /api/TransporterOrders/GetInfo`; - `POST /api/TransporterOrderTruckMatchings/ApplyMatching`; - `POST /api/TransporterOrderTruckMatchings/ApplyManualMatching`; - `GET /api/TransporterBids/GetInfo`. --- ## 3. Основные потоки ### Учетная система → CARGO.RUN Внешняя система создает заказ и передает его в CARGO.RUN. Дальше CARGO.RUN используется для: - публикации заказа перевозчикам; - сбора откликов; - выбора перевозчика; - контроля выполнения; - возврата результата во внешнюю систему. Подробно: [Учетная система → CARGO.RUN](./scenario-external-to-cr.md) ### CARGO.RUN → учетная система Пользователь создает заказ в CARGO.RUN. Внешняя система периодически получает новые и измененные заказы, сохраняет их у себя и обновляет данные по мере исполнения. Подробно: [CARGO.RUN → учетная система](./scenario-cr-to-external.md) ### Интеграция перевозчика Перевозчик работает со своей учетной записью и видит только доступные ему заказы. Подробно: [Интеграция перевозчика](./scenario-transporter.md) ### Отслеживание перевозки экспедитором Экспедитор вручную назначает внешнего перевозчика и ТС, после чего получает фактические даты и последнюю известную GPS-позицию в своей системе. Подробно: [Отслеживание грузоперевозки экспедитором](./scenario-forwarder-tracking.md) --- ## 4. Рекомендуемая последовательность внедрения 1. Настроить авторизацию. 2. Синхронизировать или проверить справочники. 3. Реализовать создание или получение заказов. 4. Реализовать получение деталей заказа. 5. Реализовать обработку откликов. 6. Реализовать получение результатов выполнения. 7. Добавить обработку отмены и ошибок. --- ## 5. Важные ограничения - Не нужно запрашивать новый access token перед каждым методом. Используйте refresh token. - Частоту polling и доступные лимиты согласуйте при подключении. При `429` учитывайте `Retry-After`, если он возвращен. - Заказы и отклики нужно сопоставлять по ID CARGO.RUN и внешним ID, если они передаются. - При ошибках `400` нужно сохранять тело ответа: оно содержит причину валидации или бизнес-ошибки. Подробно: [Ошибки и ограничения](../api/errors-and-limits.md). --- Source: products/cargorun-loads/integration/scenario-cr-to-external.md # Сценарий: CARGO.RUN → учетная система В этом сценарии пользователь создает заказ в интерфейсе **CARGO.RUN Загрузки**, а внешняя система загружает заказ и дальнейшие изменения к себе. --- ## 1. Общий поток 1. Пользователь создает заказ в CARGO.RUN. 2. Внешняя система периодически запрашивает список заказов через [`GET /api/Orders/GetIntegrationList`](../api/orders.md#orders-get-integration-list). 3. По каждому новому или измененному заказу внешняя система запрашивает детали через [`GET /api/Orders/GetInfo`](../api/orders.md#orders-get-info). 4. Внешняя система сохраняет заказ у себя и сопоставляет его со своим внутренним идентификатором. 5. После выбора перевозчика и выполнения перевозки внешняя система забирает итоговые данные: статусы, фактические времена, перевозчика, ТС, водителя. --- ## 2. Получение списка заказов Основной метод: ```http GET /api/Orders/GetIntegrationList ``` Метод поддерживает: - `$filter`; - `$orderby`; - `$top`; - `$skip`. Рекомендуется использовать фильтр по дате изменения: ```http GET /api/Orders/GetIntegrationList?$filter=updatedAt gt 2026-06-30T16:37:14.138307%2B00:00&$orderby=updatedAt asc&$top=100 ``` [`GetIntegrationList`](../api/orders.md#orders-get-integration-list) рекомендуется использовать только для поиска новых и измененных заказов. Для сохранения заказа в учетной системе после получения `id` запрашивайте полную карточку через [`GET /api/Orders/GetInfo`](../api/orders.md#orders-get-info). Если заказ был изменен после сохраненной контрольной точки, он появится в списке с новым `updatedAt`. После успешной обработки страницы сохраните максимальное `updatedAt` как новую контрольную точку. --- ## 3. Получение деталей заказа ```http 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` может быть пустым массивом. ### Пример итоговых данных ```json { "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 заказов, которые не удалось обработать. --- Source: products/cargorun-loads/integration/scenario-external-to-cr.md # Сценарий: учетная система → CARGO.RUN В этом сценарии заказ создается во внешней системе, например в 1С, ERP или TMS, а затем передается в **CARGO.RUN Загрузки**. --- ## 1. Общий поток 1. Внешняя система получает токен авторизации. 2. При необходимости получает значения справочников. 3. Создает заказ через [`POST /api/Orders/Apply`](../api/orders.md#orders-apply). 4. Запускает заказ в работу через [`POST /api/Orders/StartOrder`](../api/order-lifecycle.md#orders-start-order), если заказ был создан как черновик. 5. Получает детали заказа через [`GET /api/Orders/GetInfo`](../api/orders.md#orders-get-info). 6. Отслеживает отклики перевозчиков в `matchingCars`. 7. Принимает выбранный отклик через [`POST /api/OrderTruckMatchings/Accept`](../api/order-responses.md#order-truck-matchings-accept). 8. Получает результат выполнения через [`GET /api/Orders/GetInfo`](../api/orders.md#orders-get-info) или список изменений через [`GET /api/Orders/GetIntegrationList`](../api/orders.md#orders-get-integration-list). --- ## 2. Подготовка справочников Перед созданием заказа получите ID справочных значений, которые будут переданы в [`POST /api/Orders/Apply`](../api/orders.md#orders-apply). | Что получить | Куда передать | |---|---| | Тип НДС | `ndsTypeId` | | Тип груза | `cargoTypeId` | | Тип упаковки | `packTypeIds` | | Типы полуприцепов | `trailerTypeIds` | | Заказчика/контрагента | `counterpartyId` | | Перевозчиков для видимости | `visibleForOrganizationsIds` | Методы получения справочников описаны в разделе [Справочники](../api/directories.md). --- ## 3. Создание заказа Заказ создается методом: ```http POST /api/Orders/Apply ``` Если `id = 0`, создается новый заказ. Если передан ID существующего заказа, метод обновляет заказ. Минимальные технически обязательные поля: - `id`; - `organizationId`; - `withoutMatching`; - `requireHealthBook`; - `carryingCapacity`. Для полноценного заказа обычно также нужны: - `points` — точки маршрута; - `orderPriceType` — тип цены; - `orderCost` — стоимость; - `accessType` — видимость заказа; - `visibleForOrganizationsIds` — перевозчики, которым виден заказ; - `trailerTypeIds` — требуемые типы прицепов; - `contactPersonName`, `contactPersonPhoneNumber` — контакт по заказу; - `externalId`, `externalInternalId` — идентификаторы внешней системы. Подробная модель запроса описана в разделе [`POST /api/Orders/Apply`](../api/orders.md#orders-apply). Минимальные требования описаны в разделе [Минимальные требования](../minimal-requirements.md). После успешного создания сохраните ID заказа CARGO.RUN. Он нужен для запуска, обновления и дальнейшей синхронизации. ### Обновление заказа Для обновления заказа используйте тот же метод [`POST /api/Orders/Apply`](../api/orders.md#orders-apply), но передайте существующий `id`. Перед обновлением рекомендуется: 1. Получить текущую карточку через [`GET /api/Orders/GetInfo?Id={order_id}`](../api/orders.md#orders-get-info). 2. Изменить нужные поля. 3. Отправить обновленную модель через [`POST /api/Orders/Apply`](../api/orders.md#orders-apply). Часть полей может быть недоступна для изменения после запуска заказа, выбора перевозчика или завершения перевозки. --- ## 4. Публикация и запуск Для запуска заказа используется: ```http POST /api/Orders/StartOrder?Id={order_id} ``` После запуска заказ становится доступен перевозчикам в соответствии с настройками видимости. --- ## 5. Получение откликов Детали заказа: ```http GET /api/Orders/GetInfo?Id={order_id} ``` Отклики перевозчиков находятся в поле `matchingCars`. Для заказов типа `Auction` часть информации по торгам также находится в объекте `auction`. --- ## 6. Принятие отклика Отклик принимает владелец заказа: ```http POST /api/OrderTruckMatchings/Accept ``` В запрос нужно передать идентификатор отклика. Точная модель тела запроса описана в разделе [Order Responses API](../api/order-responses.md). После принятия отклика заказ переходит дальше по жизненному циклу, а в деталях заказа появляются выбранный перевозчик, ТС, водитель и связанные данные. --- ## 7. Получение результата выполнения Для обратной синхронизации внешняя система может: - получать детали конкретного заказа через [`GET /api/Orders/GetInfo`](../api/orders.md#orders-get-info); - получать список измененных заказов через [`GET /api/Orders/GetIntegrationList`](../api/orders.md#orders-get-integration-list) с фильтром по `updatedAt`. Пример: ```http GET /api/Orders/GetIntegrationList?$filter=updatedAt gt 2026-06-30T16:37:14.138307%2B00:00&$orderby=updatedAt asc&$top=100 ``` --- Source: products/cargorun-loads/integration/scenario-forwarder-tracking.md # Сценарий: отслеживание грузоперевозки экспедитором Сценарий предназначен для экспедитора, который ведет заказ в своей системе и хочет получать данные об исполнении перевозки из **CARGO.RUN Загрузки**. Перевозчик при этом может не работать в **CARGO.RUN Логистика**. ## Предварительные условия - экспедитору создан кабинет в **CARGO.RUN Загрузки** и выданы права API; - для кабинета настроена интеграция с поддерживаемой системой мониторинга; - в системе мониторинга ТС определяется по госномеру; - справочные ID, используемые в запросах, заранее получены через API. Настройка кабинета и подключения к системе мониторинга выполняется при внедрении и не является операцией публичного API. ## Последовательность 1. Создайте заказ через [`POST /api/Orders/Apply`](../api/orders.md#orders-apply). 2. Если заказ сохранен как черновик, запустите его через [`POST /api/Orders/StartOrder`](../api/order-lifecycle.md#orders-start-order). 3. Назначьте перевозчика, ТС и водителя одним из методов ручного назначения. 4. После назначения CARGO.RUN пытается сопоставить госномер ТС с данными настроенной системы мониторинга. 5. В период исполнения запрашивайте [`GET /api/Orders/GetInfo?Id={order_id}`](../api/orders.md#orders-get-info). 6. После завершения заявки получение актуальной GPS-позиции в рамках заказа прекращается автоматически. ## Выбор метода ручного назначения | Исходные данные | Метод | |---|---| | Перевозчик, ТС и водитель уже заведены в справочниках | [`POST /api/Orders/MatchManually`](../api/order-responses.md#orders-match-manually) | | Нужно передать нового перевозчика или новый госномер и сведения о водителе вручную | [`POST /api/Orders/MatchManuallyExtended`](../api/order-responses.md#orders-match-manually-extended) | `MatchManually` нельзя использовать только с названием перевозчика и госномером: метод требует существующие `forwardingOrganizationId`, `truckId` и `driverId`. ### Пример назначения существующего ТС ```http POST /api/Orders/MatchManually Authorization: Bearer Content-Type: application/json ``` ```json { "id": 1552779, "forwardingOrganizationId": 95713, "truckId": 1001, "trailerId": null, "driverId": 3001, "orderCost": 129000, "invitedFleetPrice": 125600, "transporterNdsTypeId": 1, "reason": "Назначение по договоренности" } ``` ### Пример назначения с новым госномером ```http POST /api/Orders/MatchManuallyExtended Authorization: Bearer Content-Type: application/json ``` ```json { "id": 1552779, "organizationName": "ООО Перевозчик", "inn": "1650000000", "kpp": "165001001", "truckNumber": "А123ВС16", "truckModelTypeId": 10, "truckOwnershipTypeId": 20, "driverLastName": "Иванов", "driverFirstName": "Иван", "driverPatronymic": "Иванович", "driverPhoneNumber": "+79990000000", "orderCost": 129000, "invitedFleetPrice": 125600, "transporterNdsTypeId": 1, "reason": "Назначение внешнего перевозчика" } ``` Значения справочников в примере условные. Передавайте ID своей среды. ## Получение данных об исполнении ```http GET /api/Orders/GetInfo?Id=1552779 Authorization: Bearer ``` Проверяйте следующие поля ответа: | Данные | Поля | |---|---| | Состояние заказа | `status` | | Назначенное ТС | `truckNumber`, `truckOrganizationName`, `driverFullName` | | Текущее положение | `truckCurrentLocation.latitude`, `truckCurrentLocation.longitude` | | Актуальность положения | `truckCurrentLocation.fixedAt` | | Прогноз по точкам | `points[].predictionEnterTimeOffset`, `points[].predictionLeaveTimeOffset` | | Фактические даты | `points[].factEnterTimeOffset`, `points[].factLeaveTimeOffset` | Пример фрагмента ответа: ```json { "id": 1552779, "status": 40, "truckNumber": "А123ВС16", "truckCurrentLocation": { "latitude": 55.796127, "longitude": 49.106414, "fixedAt": "2026-10-16T09:42:18+03:00" }, "points": [ { "id": 501, "factEnterTimeOffset": "2026-10-16T08:10:00+03:00", "factLeaveTimeOffset": "2026-10-16T09:00:00+03:00" } ] } ``` ## Если координаты отсутствуют Пустое `truckCurrentLocation` не следует считать ошибкой API. Проверьте: 1. совпадает ли нормализованный госномер с номером в системе мониторинга; 2. настроена ли интеграция мониторинга для кабинета; 3. передает ли трекер свежие данные; 4. находится ли заказ в периоде исполнения. Не подменяйте последнюю известную позицию текущей без проверки `fixedAt`. ## Завершение Отдельный запрос для отключения GPS-трансляции не требуется. После завершения заявки система прекращает получать актуальную позицию в рамках заказа. Последнее возвращенное положение может оставаться историческим значением, поэтому всегда учитывайте `status` заказа и `truckCurrentLocation.fixedAt`. --- Source: products/cargorun-loads/integration/scenario-transporter.md # Сценарий: интеграция перевозчика Этот сценарий описывает работу внешней системы перевозчика с **CARGO.RUN Загрузки**. --- ## 1. Общий поток 1. Перевозчик получает или создает учетную запись. 2. Система перевозчика авторизуется через `POST /api/Account/GenerateToken`. 3. Перевозчик получает доступные заказы через `GET /api/TransporterOrders/GetList`. 4. По интересующему заказу получает детали через `GET /api/TransporterOrders/GetInfo`. 5. Отправляет отклик через `POST /api/TransporterOrderTruckMatchings/ApplyMatching` или `ApplyManualMatching`. 6. Отслеживает результат выбора перевозчика. 7. Если заказ назначен перевозчику, получает заявку через `GET /api/TransporterBids/GetInfo`. 8. Передает фактические времена по точкам через `POST /api/TransporterBids/ApplyOrderPointFactTimes`. --- ## 2. Регистрация организации перевозчика Для регистрации используется: ```http POST /api/Registration/Register ``` Метод создает организацию и пользователя. ИНН организации уникален. Для работы со списком заказов, откликами и справочниками пользователю перевозчика нужна роль менеджера. --- ## 3. Получение доступных заказов ```http GET /api/TransporterOrders/GetList ``` Метод возвращает только заказы, доступные текущей организации перевозчика. Список можно фильтровать, например по периоду погрузки: ```http GET /api/TransporterOrders/GetList?$filter=loadStart ge 2026-06-24T21:00:00.000Z and loadStart le 2026-06-29T21:00:00.000Z ``` Из ответа сохраните `data[].id`. Этот ID нужен для получения карточки заказа и отправки отклика. ```json { "data": [ { "id": 1552780, "addressFrom": "Ростовская область, Аксайский район, улица Логопарк, 5", "addressTo": "Ростовская область, Аксай, улица Авиаторов, 5", "orderCost": 25000, "trailerTypeNames": ["Рефрижератор"] } ], "totalCount": 1 } ``` --- ## 4. Создание отклика Есть два способа. ### Отклик с выбором из справочников ```http POST /api/TransporterOrderTruckMatchings/ApplyMatching ``` Используется, когда ТС, водитель и прицеп уже есть в справочниках. Перед вызовом получите ID сущностей из справочников перевозчика: | Данные | Метод | |---|---| | ТС | `GET /api/TransporterTruck/List` | | Прицеп | `GET /api/TransporterTrailer/List` | | Водитель | `GET /api/TransporterDriver/List` | Минимальный смысловой набор для отклика: - `orderId` — ID заказа из `TransporterOrders/GetList`; - `price` — ставка перевозчика; - `ndsTypeId` — тип НДС; - `truck.id`, `trailer.id`, `driver.id` — выбранные сущности перевозчика; - `logistFullName`, `logistPhoneNumber` — контакт перевозчика. ### Отклик с ручным заполнением ```http POST /api/TransporterOrderTruckMatchings/ApplyManualMatching ``` Используется, когда данные ТС, водителя или прицепа передаются вручную. При успешном выполнении метод может создать отсутствующие сущности. После успешной отправки отклика продолжайте проверять карточку заказа через `GET /api/TransporterOrders/GetInfo?id={order_id}`. Если владелец заказа выбрал другого перевозчика, заказ может исчезнуть из доступных. --- ## 5. Контактное лицо перевозчика Поля `logistFullName` и `logistPhoneNumber` обязательны. Это контактное лицо перевозчика по отклику. --- ## 6. Временные сущности Если передается признак временной сущности, например: ```json { "isTemporaryTruck": true } ``` то данные объекта `truck` не используются как ссылка на существующий тягач. Аналогично работают: - `isTemporaryDriver`; - `isTemporaryTrailer`. --- ## 7. Проверка результата выбора Если заказ еще доступен перевозчику, детали можно получать через: ```http GET /api/TransporterOrders/GetInfo?id={order_id} ``` Если перевозчик выбран и заказ стал заявкой, используется: ```http GET /api/TransporterBids/GetInfo?id={order_id} ``` Если заказ недоступен, вероятно был выбран другой перевозчик или заказ больше не виден текущей организации. --- ## 8. Передача фактических времен Когда заказ стал заявкой перевозчика, получите карточку через: ```http GET /api/TransporterBids/GetInfo?id={order_id} ``` В ответе найдите нужную точку маршрута в `points[]` и передайте ее `id` в метод: ```http POST /api/TransporterBids/ApplyOrderPointFactTimes ``` Пример тела: ```json { "id": 2435200, "factEnterTimeOffset": "2026-07-01T15:25:00+03:00", "factLeaveTimeOffset": "2026-07-01T16:10:00+03:00", "clearAllNextPoints": false } ``` После успешной передачи проверьте, что в карточке заявки обновились `points[].factEnterTimeOffset` и `points[].factLeaveTimeOffset`. --- Source: products/cargorun-loads/integration/order-responses.md # Работа с откликами перевозчиков Этот раздел описывает, как грузоотправитель или экспедитор получает отклики перевозчиков и выбирает исполнителя. --- ## 1. Где смотреть отклики Отклики возвращаются в деталях заказа: ```http GET /api/Orders/GetInfo?Id={order_id} ``` Основное поле: ```json { "matchingCars": [] } ``` Каждый элемент `matchingCars` содержит: - `id` — ID отклика; - `truckOrganizationName` — организация перевозчика; - `truckOrganizationId` — ID организации перевозчика; - `truckNumber` — номер ТС; - `trailerNumber` — номер прицепа; - `driverFullName` — водитель; - `logistFullName`, `logistPhoneNumber` — контакт перевозчика; - `price` — ставка; - `status` — статус отклика; - `gpsEnabled` — наличие GPS. --- ## 2. Особенности разных типов цены ### Фиксированная стоимость (`Static`, код `10`) Стоимость задана в заказе. Отклики перевозчиков находятся в `matchingCars`. ### Аукцион (`Auction`, код `20`) Данные аукциона находятся в объекте `auction`. Список организаций-участников может возвращаться в `auction.offerOrganizationNames`. ### Предложение цены (`Offer`, код `30`) Отклики перевозчиков и предложенные ставки находятся в `matchingCars`. --- ## 3. Принятие отклика Для принятия отклика владельцем заказа используется: ```http POST /api/OrderTruckMatchings/Accept ``` В запрос передается ID отклика из `matchingCars[].id`. После успешного принятия: - отклик получает статус `AcceptedInOrderOwner`; - заказ переходит дальше по жизненному циклу; - в заказе появляется выбранный перевозчик; - остальные отклики считаются невыбранными или становятся недоступны в зависимости от бизнес-логики заказа. --- ## 4. Статусы откликов | Код | Значение | Описание | |---:|---|---| | `10` | `AcceptedInTruckOwner` | Перевозчик отправил или подтвердил отклик | | `20` | `DeclinedInTruckOwner` | Перевозчик отклонил | | `30` | `AcceptedInOrderOwner` | Владелец заказа принял отклик | | `40` | `DeclinedInOrderOwner` | Владелец заказа отклонил | | `50` | `Awaiting` | Ожидает решения | --- ## 5. Ручное назначение перевозчика Если перевозчик не отправлял отклик, владелец заказа может использовать ручное назначение: - [`POST /api/Orders/MatchManually`](../api/order-responses.md#orders-match-manually); - [`POST /api/Orders/MatchManuallyExtended`](../api/order-responses.md#orders-match-manually-extended); - [`POST /api/Orders/MatchManuallyForCargorun`](../api/order-responses.md#orders-match-manually-for-cargorun). Эти методы не являются основным сценарием принятия уже созданного отклика. Их нужно использовать только в сценариях ручного назначения. --- ## 6. Отличие от API перевозчика Методы `TransporterOrderTruckMatchings/*` используются со стороны перевозчика: - создать отклик; - изменить ставку; - удалить отклик; - отклонить заказ. Метод `OrderTruckMatchings/Accept` используется со стороны владельца заказа. --- Source: products/cargorun-loads/integration/sync.md # Синхронизация Синхронизация нужна, чтобы внешняя система получала новые заказы, изменения, отклики, выбранного перевозчика и результаты выполнения. --- ## 1. Основной метод синхронизации заказов Для сценария грузоотправителя/экспедитора используется: ```http GET /api/Orders/GetIntegrationList ``` Метод поддерживает фильтрацию и пагинацию. --- ## 2. Рекомендуемый алгоритм polling 1. Хранить максимальное `updatedAt` из последней успешно обработанной страницы. 2. Запрашивать заказы, измененные после этого времени. 3. Сортировать результат по `updatedAt asc`, чтобы обрабатывать изменения в хронологическом порядке. 4. Обрабатывать страницу результатов. 5. По каждому заказу запрашивать [`GET /api/Orders/GetInfo`](../api/orders.md#orders-get-info), если нужны полные данные заказа. 6. Сохранять новую контрольную точку только после успешной обработки всей страницы. Пример: ```http GET /api/Orders/GetIntegrationList?$filter=updatedAt gt 2026-06-30T16:37:14.138307%2B00:00&$orderby=updatedAt asc&$top=100&$skip=0 ``` Если заказ изменился после сохраненной контрольной точки, он вернется в `GetIntegrationList` с новым `updatedAt`. Если изменения были в двух заказах, метод вернет оба заказа. `GetIntegrationList` не заменяет `GetInfo`: в списке могут отсутствовать детальные данные по перевозчику, водителю, ТС, прицепу, названиям справочников и полному маршруту. Используйте список для обнаружения изменений, а `GetInfo` — для загрузки полной карточки заказа. Если вместо `gt` используется `ge`, заказ с `updatedAt`, равным контрольной точке, может вернуться повторно. В этом случае внешняя система должна уметь безопасно обрабатывать дубли, например по паре `id` + `updatedAt`. --- ## 3. Что синхронизировать Для внешней системы обычно важны: - ID заказа CARGO.RUN; - внешний ID заказа; - статус заказа; - статус заявки; - выбранный перевозчик; - ТС, прицеп и водитель; - плановые и фактические времена по точкам; - стоимость; - отмена и причина отмены. --- ## 4. Синхронизация справочников Справочники можно запрашивать перед созданием заказа или обновлять по расписанию. Для справочников также поддерживаются: - `$filter`; - `$orderby`; - `$top`; - `$skip`. Пример поиска: ```http GET /api/PackType/SelectList?$filter=contains(tolower(name),'паллет') ``` --- ## 5. Обработка ошибок При ошибках интеграции рекомендуется сохранять: - URL метода; - тело запроса; - HTTP-код; - тело ответа; - ID заказа или внешний ID; - дату и время ошибки. Это особенно важно для ошибок `400`, потому что они часто содержат конкретную причину валидации. --- Source: products/cargorun-loads/integration/examples-1c.md # Примеры интеграции с 1С Раздел содержит типовые рекомендации для интеграции 1С с **CARGO.RUN Загрузки**. --- ## 1. Типовой обмен 1С может быть источником заказов или получателем заказов из CARGO.RUN. ### 1С создает заказы 1. Пользователь создает заказ в 1С. 2. 1С отправляет заказ в CARGO.RUN через [`POST /api/Orders/Apply`](../api/orders.md#orders-apply). 3. CARGO.RUN публикует заказ перевозчикам. 4. 1С получает отклики через [`GET /api/Orders/GetInfo`](../api/orders.md#orders-get-info). 5. После выбора перевозчика 1С получает исполнителя и дальнейшие статусы. ### CARGO.RUN создает заказы 1. Пользователь создает заказ в CARGO.RUN. 2. 1С получает новые и измененные заказы через [`GET /api/Orders/GetIntegrationList`](../api/orders.md#orders-get-integration-list). 3. 1С сохраняет ID заказа CARGO.RUN у себя. 4. 1С периодически обновляет статус и результат выполнения. --- ## 2. Хранение идентификаторов В 1С рекомендуется хранить: | Поле | Назначение | |---|---| | `cargorunOrderId` | ID заказа в CARGO.RUN | | `externalId` | ID заказа в 1С | | `updatedAt` | Дата последней синхронизации | | `status` | Последний полученный статус заказа | | `bidStatus` | Последний полученный статус заявки | --- ## 3. Обработка ошибок В журнале обмена рекомендуется хранить: - метод API; - тело запроса; - тело ответа; - HTTP-код; - ID заказа; - дату и время. Для ошибок `400` тело ответа нужно показывать администратору интеграции: обычно там указана причина, например неверное значение enum или отсутствующее обязательное поле. --- ## 4. Рекомендации - Не получать новый токен перед каждым запросом. - Использовать `RefreshToken`. - Делать polling по `updatedAt`. - Ограничивать размер страницы через `$top`. - Проверять справочники перед созданием заказа. - Для адресов использовать `GET /api/Map/ReverseSearchAddresses`. --- Source: products/cargorun-loads/api/overview.md # Обзор API API **CARGO.RUN Загрузки** работает по HTTP/HTTPS и использует JSON для запросов и ответов. --- ## 1. Базовый URL Фактический базовый URL предоставляется при подключении интеграции. В примерах используется: ```text ``` Итоговый URL метода: ```text /api/Orders/GetIntegrationList ``` --- ## 2. Авторизация В большинстве методов требуется заголовок: ```http Authorization: Bearer ``` Подробнее: [Авторизация](./auth.md) --- ## 3. Формат ошибок Типовые коды: | Код | Значение | |---:|---| | `200` | Успешное выполнение | | `400` | Ошибка валидации или бизнес-логики | | `401` | Нет авторизации или токен недействителен | | `500` | Внутренняя ошибка сервера | При ошибке `400` тело ответа может содержать подробности валидации. Правила повторов и ограничения описаны в разделе [Ошибки и ограничения](./errors-and-limits.md). --- ## 4. Списки Методы списков обычно поддерживают: - `$filter`; - `$orderby`; - `$top`; - `$skip`. Ответ: ```json { "data": [], "totalCount": 0 } ``` --- ## 5. Основные группы методов | Раздел | Назначение | |---|---| | [Авторизация](./auth.md) | Получение и обновление токена | | [Ошибки и ограничения](./errors-and-limits.md) | HTTP-ошибки, повторы, списки и GPS-данные | | [Orders API](./orders.md) | Создание и получение заказов | | [Order Lifecycle API](./order-lifecycle.md) | Запуск, отмена, возврат в черновик, удаление | | [Order Responses API](./order-responses.md) | Отклики и выбор перевозчика | | [Отчеты API](./reports.md) | Данные заказов для отчетности и BI | | [Counterparties API](./counterparties.md) | Контрагенты, адреса, контактные лица, надежность и лимиты | | [Map API](./map.md) | Адреса, координаты и маршруты | | [Directories API](./directories.md) | Справочники | | [Transporter API](./transporter.md) | Методы перевозчика | --- Source: products/cargorun-loads/api/errors-and-limits.md # Ошибки и ограничения ## HTTP-ошибки | Код | Причина | Повтор запроса | |---:|---|---| | `400` | Ошибка модели, бизнес-правила или доступа к объекту | Только после исправления запроса или состояния объекта | | `401` | Токен отсутствует, недействителен или истек | Обновить токен и повторить один раз | | `403` | Роль пользователя не разрешает метод | Только после изменения прав | | `404` | Неверный путь или ресурс не найден | Проверить базовый URL, регистр пути и ID | | `429` | Превышена допустимая частота запросов | После `Retry-After` или с экспоненциальной задержкой | | `5xx` | Временная серверная ошибка | Ограниченное число повторов с экспоненциальной задержкой и случайным сдвигом | Ответ `400` может содержать текст бизнес-ошибки. Сохраняйте тело ответа в техническом журнале без токенов и персональных данных. ## Ограничения повторов - Не повторяйте изменяющий запрос после неопределенного результата вслепую. Сначала прочитайте объект и проверьте, была ли операция применена. - [`POST /api/Orders/Apply`](./orders.md#orders-apply) не следует считать идемпотентным только по `externalId`. После создания сохраните возвращенный ID CARGO.RUN. - При `401` обновите access token и повторите исходный запрос не более одного раза. - Для `429` учитывайте `Retry-After`, если заголовок присутствует. ## Ограничения списков Методы списков могут поддерживать `$filter`, `$orderby`, `$top` и `$skip`. Набор доступных полей зависит от модели конкретного метода. Используйте стабильную сортировку и не увеличивайте `$skip`, пока текущая страница не обработана успешно. ## GPS и фактические данные - `truckCurrentLocation = null` не является ошибкой запроса. - Координаты считаются последними известными, а не гарантированно текущими; проверяйте `fixedAt`. - По завершенному заказу актуальная трансляция не продолжается, но последнее положение может оставаться в ответе. - Фактические даты точки могут быть `null`, пока соответствующее событие не зафиксировано. ## Безопасность Не помещайте пароль, access token, refresh token, паспортные данные и реальные телефоны в примеры, журналы или контекст ИИ-системы. Для диагностики используйте обезличенные значения. --- Source: products/cargorun-loads/api/auth.md # Авторизация API использует JWT-токены. Полученный access token передается в заголовке `Authorization`. --- ## 1. Получение токена ```http POST /api/Account/GenerateToken ``` ### Тело запроса ```json { "email": "user@example.com", "password": "password" } ``` ### Ответ ```json { "token": "string", "expires": 0, "refreshToken": "string" } ``` Access token действует около 30 минут. --- ## 2. Передача токена ```http Authorization: Bearer ``` Пример: ```http GET /api/Orders/GetIntegrationList Authorization: Bearer eyJhbGciOiJIUzI1... ``` --- ## 3. Обновление токена ```http POST /api/Account/RefreshToken ``` ### Тело запроса ```json { "token": "", "refreshToken": "" } ``` ### Ответ ```json { "token": "string", "expires": 0, "refreshToken": "string" } ``` --- ## 4. Рекомендации - Не запрашивайте новый токен перед каждым API-вызовом. - Используйте `RefreshToken` после истечения access token. - Не сохраняйте токены в открытых логах. - При ошибке `401` обновите токен и повторите запрос один раз. --- Source: products/cargorun-loads/api/orders.md # Orders API Раздел описывает основные методы работы с заказами экспедитора. --- ## 1. Получение списка заказов {#orders-get-list} ```http GET /api/Orders/GetList ``` Метод возвращает список заказов организации экспедитора. Используйте метод для получения списка заказов с фильтрацией, сортировкой и постраничной загрузкой. Для получения полной карточки конкретного заказа используйте `GET /api/Orders/GetInfo?Id={order_id}`. ### Query-параметры | Параметр | Описание | |---|---| | `$filter` | Фильтр по полям модели | | `$orderby` | Сортировка по полям модели | | `$top` | Ограничение количества записей | | `$skip` | Смещение | ### Пример ```http GET /api/Orders/GetList?$orderby=loadStart asc&$top=50&$skip=0 ``` Фильтрация по населенным пунктам доступна через строковые поля `locationFrom` и `locationTo`: ```http GET /api/Orders/GetList?$filter=contains(locationFrom,'Айдарово') and contains(locationTo,'Ильинское-Усово')&$top=50&$skip=0 ``` ### Ответ Метод возвращает объект со списком заказов и общим количеством найденных записей: | Поле | Тип | Описание | |---|---|---| | `data` | `OrderListModel[]` | Массив заказов | | `totalCount` | `long?` | Общее количество записей, подходящих под фильтр | Если заказов нет, `data` может быть пустым массивом. ### Поля заказа в `data[]` --8<-- "includes/cargorun-loads/api/orders-getlist-fields.md" --- ## 2. Получение карточки заказа {#orders-get-info} ```http GET /api/Orders/GetInfo?Id={order_id} ``` Метод возвращает подробную информацию о заказе экспедитора: - маршрут; - груз; - тип цены и стоимость; - отклики и назначение перевозчика; - статусы; - контактные данные; - ограничения и требования; - служебные данные интеграции. ### Query-параметры | Параметр | Описание | |---|---| | `Id` | ID заказа | | `IsNew` | Признак открытия новой карточки. Для чтения существующего заказа обычно не передается | ### Ответ Метод возвращает модель `OrderInfoModel`. Для контроля исполнения используйте: | Поле | Назначение | |---|---| | `status` | Текущее состояние заказа | | `truckNumber` | Госномер назначенного ТС | | `truckCurrentLocation.latitude`, `truckCurrentLocation.longitude` | Последние известные координаты ТС | | `truckCurrentLocation.fixedAt` | Время фиксации координат; проверяйте его перед использованием позиции | | `points[].predictionEnterTimeOffset`, `points[].predictionLeaveTimeOffset` | Прогноз прибытия и убытия | | `points[].factEnterTimeOffset`, `points[].factLeaveTimeOffset` | Фактическое прибытие и убытие | `truckCurrentLocation` может быть `null`, например если трекер не найден, ещё не передал координаты или трансляция для заказа недоступна. Метод не возвращает отдельный универсальный журнал событий: изменения исполнения определяются по статусу заказа, данным точек и текущему положению ТС. ### Дополнительные поля полной карточки --8<-- "includes/cargorun-loads/api/orders-getinfo-fields.md" --- ## 3. Создание и обновление заказа {#orders-apply} ```http POST /api/Orders/Apply ``` Метод используется для создания нового заказа или обновления существующего заказа. Для создания нового заказа передайте модель заказа без `id` или с `id = 0`. Для обновления передайте `id` существующего заказа и актуальные значения полей. Минимальный набор данных для создания заказа описан в разделе [Минимальные требования](../minimal-requirements.md). `Apply` создает или обновляет заказ. Если заказ создается как черновик, отдельно вызовите [`POST /api/Orders/StartOrder`](./order-lifecycle.md#orders-start-order). --- ## 4. Получение измененных заказов для интеграции {#orders-get-integration-list} ```http GET /api/Orders/GetIntegrationList ``` Метод используется для синхронизации с учетной системой: внешняя система получает заказы, измененные после сохраненной контрольной точки `updatedAt`. Подробный сценарий описан в разделе [Синхронизация данных](../integration/sync.md). --- Source: products/cargorun-loads/api/order-lifecycle.md # Order Lifecycle API Раздел описывает методы управления жизненным циклом заказа. --- ## 1. Запуск заказа в работу {#orders-start-order} ```http POST /api/Orders/StartOrder?Id={order_id} ``` Запускает заказ из черновика или подготовленного состояния. После запуска заказ становится доступен перевозчикам в соответствии с настройками видимости. ### Query-параметры | Параметр | Обязательность | Описание | |---|---|---| | `Id` | Да | ID заказа | | `IsNew` | Нет | Технический признак нового интерфейса, обычно не передается | ### Ответ При успехе метод возвращает `200 OK` без тела ответа. После запуска проверьте карточку заказа через [`GET /api/Orders/GetInfo?Id={order_id}`](./orders.md#orders-get-info). В API заказ может иметь статус `New` (`10`) или другой статус жизненного цикла в зависимости от состояния подбора перевозчика и откликов. --- ## 2. Отмена заказа ```http POST /api/Orders/CancelOrder ``` ### Тело запроса ```json { "id": 798805, "saveInDirectory": false, "fromBook": false, "cancellationReasonComment": "машина сломалась" } ``` Если причина выбирается из справочника: ```json { "id": 798805, "saveInDirectory": false, "fromBook": true, "cancellationReasonIds": [5, 6] } ``` Поля модели: | Поле | Обязательность | Описание | |---|---|---| | `id` | Да | ID заказа | | `saveInDirectory` | Да | Сохранить причину в справочник | | `fromBook` | Да | Причина выбрана из справочника | | `cancellationReasonComment` | Нет | Текстовая причина отмены | | `cancellationReasonIds` | Нет | ID причин из справочника | ### Справочник причин отмены ```http GET /api/CancellationReasons/SelectByOrderList?OrderId={order_id} ``` Метод поддерживает фильтрацию и пагинацию. ### Ответ При успехе метод возвращает `200 OK` без тела ответа. После отмены проверьте карточку заказа через [`GET /api/Orders/GetInfo?Id={order_id}`](./orders.md#orders-get-info). Ожидаемый статус отмененного заказа — `Canceled` (`50`). --- ## 3. Возврат в черновик ```http POST /api/Orders/OrderToDraft?Id={order_id} ``` Возвращает отмененный заказ в статус черновика. При возврате очищаются данные, присвоенные в ходе выполнения заказа, например выбранный перевозчик и фактические времена по точкам. ### Query-параметры | Параметр | Обязательность | Описание | |---|---|---| | `Id` | Да | ID заказа | | `IsNew` | Нет | Технический признак нового интерфейса, обычно не передается | ### Ответ При успехе метод возвращает `200 OK` без тела ответа. После возврата проверьте карточку заказа. Ожидаемый статус — `Draft` (`5`). --- ## 4. Удаление заказа ```http POST /api/Orders/Delete ``` ### Тело запроса ```json { "id": 798805 } ``` Поля модели: | Поле | Обязательность | Описание | |---|---|---| | `id` | Да | ID заказа | Удаление заказа является необратимым. Удаленный заказ не отражается в отчетах. ### Ответ При успехе метод возвращает `200 OK` без тела ответа. После удаления заказ не должен использоваться в синхронизации и отчетах. --- ## 5. Статусы заказа Основные статусы описаны в разделе [Статусы](../statuses.md). --- Source: products/cargorun-loads/api/order-responses.md # Order Responses API Раздел описывает методы работы с откликами перевозчиков со стороны владельца заказа. --- ## 1. Получение откликов {#order-responses-get-info} Отклики возвращаются в деталях заказа: ```http GET /api/Orders/GetInfo?Id={order_id} ``` Поле: ```json { "matchingCars": [ { "id": 43587716, "orderId": 1552779, "truckOrganizationId": 95713, "truckOrganizationName": "ООО \"Перевоз-Тентовоз\"", "truckNumber": "Х777ХХ16", "trailerNumber": "ХХ234556", "driverFullName": "Хузятов Шафик Шаехович", "logistFullName": "Иванов Иван", "logistPhoneNumber": "79999999999", "price": 125600, "status": 10, "matchingType": 40, "gpsEnabled": true } ] } ``` Основные поля `matchingCars[]`: | Поле | Описание | |---|---| | `id` | ID отклика. Его нужно передать в `OrderTruckMatchings/Accept` или `Decline` | | `orderId` | ID заказа | | `truckOrganizationId`, `truckOrganizationName` | Организация перевозчика | | `price` | Ставка перевозчика | | `status` | Статус отклика | | `matchingType` | Тип назначения/отклика | | `truckNumber`, `trailerNumber` | Номера ТС и прицепа | | `driverFullName` | Водитель | | `logistFullName`, `logistPhoneNumber` | Контакт перевозчика | | `gpsEnabled` | Признак доступности GPS | --- Полное описание метода: [`GET /api/Orders/GetInfo`](./orders.md#orders-get-info). ## 2. Принятие отклика {#order-truck-matchings-accept} ```http POST /api/OrderTruckMatchings/Accept ``` Метод принимает отклик перевозчика владельцем заказа. ### Тело запроса ```json { "id": 43587716, "ndsTypeId": 3, "reason": "Выбран перевозчик", "transporterContract": null } ``` | Поле | Тип | Обязательность | Описание | |---|---|---|---| | `id` | `long` | Да | ID отклика из `matchingCars[].id` | | `ndsTypeId` | `long?` | Нет | Тип НДС перевозчика | | `reason` | `string` | Нет | Комментарий или причина выбора | | `transporterContract` | `object` | Нет | Договор с перевозчиком | ### Ответ При успехе метод возвращает `200 OK` без тела ответа. После принятия отклика: - в карточке заказа появляется `orderTruckMatchingId`; - выбранный перевозчик появляется в `transporterInfo`; - ставка перевозчика доступна в `transporterInfo.price` и может дублироваться в `invitedFleetPrice`; - ТС, прицеп и водитель появляются в `truckNumber`, `trailerNumber`, `driverFullName`, `driverPhoneNumber`; - у заказа появляется или обновляется `bidStatus`. --- ## 3. Отклонение отклика ```http POST /api/OrderTruckMatchings/Decline ``` ### Тело запроса ```json { "id": 43587716, "reason": "Не подходит ставка" } ``` | Поле | Тип | Обязательность | Описание | |---|---|---|---| | `id` | `long` | Да | ID отклика | | `reason` | `string` | Нет | Причина отклонения | --- ## 4. Список откликов ```http GET /api/OrderTruckMatchings/List ``` Метод поддерживает `$filter`, `$orderby`, `$top`, `$skip`. ### Ответ ```json { "data": [ { "id": 43587716, "orderId": 1552779, "createdAt": "2026-06-30T16:35:50+00:00", "matchingType": 40, "status": 10, "logistFullName": "Иванов Иван", "logistPhoneNumber": "79999999999", "truckOrganizationName": "ООО \"Перевоз-Тентовоз\"", "truckNumber": "Х777ХХ16", "trailerNumber": "ХХ234556", "driverFullName": "Хузятов Шафик Шаехович", "price": 125600 } ], "totalCount": 1 } ``` Ключевые поля списка совпадают по смыслу с `matchingCars[]` в карточке заказа. Для принятия или отклонения используйте `data[].id`. --- ## 5. Ручное назначение перевозчика Если нужно назначить перевозчика вручную, используются методы `Orders`. ### Назначение существующего перевозчика, ТС и водителя {#orders-match-manually} ```http POST /api/Orders/MatchManually ``` Метод доступен пользователю с правами менеджера. Он назначает перевозчика и сразу создает принятый отклик. Заказ должен принадлежать текущей организации, оставаться активным, не иметь выбранного ТС или победителя аукциона и не должен покинуть первую точку. Поля запроса: | Поле | Тип | Обязательность | Описание | |---|---|---|---| | `id` | `long` | Да | ID заказа | | `transporterNdsTypeId` | `long` | Да | Существующий ID типа НДС перевозчика | | `forwardingOrganizationId` | `long` | Да | ID доступной организации перевозчика | | `truckId` | `long` | Да | ID ТС этой организации | | `trailerId` | `long?` | Нет | ID прицепа этой организации | | `driverId` | `long` | Да | ID водителя этой организации | | `orderCost` | `double` | Да | Стоимость заказчика, больше нуля | | `invitedFleetPrice` | `double` | Да | Стоимость перевозчика, больше нуля | | `reason` | `string?` | Условно | Причина назначения, если она обязательна в настройках организации | | `transporterContract` | `object?` | Нет | Договор с перевозчиком; доступность проверяется для текущей организации | Пример: ```json { "id": 1552779, "forwardingOrganizationId": 95713, "truckId": 1001, "trailerId": 2001, "driverId": 3001, "orderCost": 129000, "invitedFleetPrice": 125600, "transporterNdsTypeId": 1, "reason": "Назначение по договоренности" } ``` При успехе возвращается `200 OK` без тела. Возможные причины `400 Bad Request`: заказ недоступен или уже не допускает назначение, справочный ID не существует, ТС/прицеп/водитель не принадлежит перевозчику, цена неположительная либо не заполнена обязательная причина. ### Назначение с ручным заполнением данных {#orders-match-manually-extended} ```http POST /api/Orders/MatchManuallyExtended ``` Используется, когда перевозчик, ТС или водитель еще не заведены в справочниках и их данные нужно передать вручную. Метод доступен администратору организации. Основные поля: | Поле | Описание | |---|---| | `id` | ID заказа | | `organizationName`, `inn`, `kpp` | Данные перевозчика | | `truckNumber`, `truckModelTypeId`, `truckOwnershipTypeId` | Данные ТС | | `trailerNumber`, `trailerModelTypeId`, `trailerOwnershipTypeId` | Данные прицепа | | `driverLastName`, `driverFirstName`, `driverPatronymic`, `driverPhoneNumber` | Данные водителя | | `orderCost` | Стоимость заказчика | | `invitedFleetPrice` | Стоимость перевозчика | | `transporterNdsTypeId` | Тип НДС перевозчика | `truckModelTypeId` и `truckOwnershipTypeId` должны содержать ID существующих справочных значений. Обязательность реквизитов перевозчика и водителя зависит от правил организации; не отправляйте вымышленные значения для прохождения валидации. ### Назначение перевозчика CARGO.RUN {#orders-match-manually-for-cargorun} ```http POST /api/Orders/MatchManuallyForCargorun ``` Используется, когда нужно назначить перевозчика CARGO.RUN с ручным указанием водителя, ТС и прицепа. Все методы ручного назначения при успехе возвращают `200 OK` без тела ответа. После назначения проверяйте результат через [`GET /api/Orders/GetInfo?Id={order_id}`](./orders.md#orders-get-info). --- ## 6. Отличие от методов перевозчика | Сценарий | Методы | |---|---| | Перевозчик создает отклик | `TransporterOrderTruckMatchings/ApplyMatching` | | Перевозчик создает отклик вручную | `TransporterOrderTruckMatchings/ApplyManualMatching` | | Владелец заказа принимает отклик | `OrderTruckMatchings/Accept` | | Владелец заказа назначает вручную | `Orders/MatchManually*` | --- Source: products/cargorun-loads/api/reports.md # Отчеты API Раздел описывает методы для получения данных отчетности и бизнес-аналитики. --- ## Получение заказов для BI ```http GET /api/Orders/GetListForBI ``` Метод возвращает данные заказов для системы бизнес-аналитики экспедитора. Используйте метод, когда внешняя BI-система должна регулярно забирать измененные заказы из CARGO.RUN Загрузки и строить витрины, отчеты или аналитические показатели. ### Query-параметры | Параметр | Описание | |---|---| | `$filter` | Фильтр по полям модели. Для инкрементальной загрузки используйте фильтр по `updatedAt` | | `$orderby` | Сортировка по полям модели. Для стабильной инкрементальной выгрузки рекомендуется `updatedAt asc` | | `$top` | Ограничение количества записей | | `$skip` | Смещение | ### Пример запроса ```http GET /api/Orders/GetListForBI?$filter=updatedAt ge 2026-07-01T00:00:00Z&$top=30&$skip=0 ``` Для регулярной синхронизации рекомендуется дополнительно сортировать результат по `updatedAt asc`: ```http 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` | --- Source: products/cargorun-loads/api/counterparties.md # Counterparties API Раздел описывает работу с контрагентами в CARGO.RUN Загрузки. Контрагенты используются как заказчики и участники заказа: при создании заказа их ID передается в `counterpartyId`, а сохраненные адреса и контактные лица можно использовать для заполнения карточки заказа. --- ## 1. Контрагенты ### 1.1. Создание или обновление контрагента ```http POST /api/Counterparty/Apply ``` Метод создает нового контрагента или обновляет существующего. Если `id = 0`, создается новый контрагент. Если `id` содержит ID существующего контрагента, метод обновляет его данные. ### Важные правила - Для юридических лиц проверяется уникальность пары `inn + kpp`. - Для ИП проверяется уникальность по `inn`, поле `kpp` не используется. - Длина `inn` валидируется: - 10 символов для юридического лица; - 12 символов для ИП. - При создании или редактировании можно передать `responsibleId`. Если заказ по этому контрагенту создается из внешней торговой площадки, указанный сотрудник становится ответственным по заказу. ID ответственного сотрудника можно брать из справочника пользователей, например из `GET /api/Orders/SelectAuthorByOrganizationList`. ### Поля запроса `CounterpartyApplyModel` | Поле | Тип | Описание | |---|---|---| | `id` | `long` | `0` для создания, ID контрагента для обновления | | `name` | `string?` | Наименование контрагента | | `inn` | `string?` | ИНН | | `kpp` | `string?` | КПП. Для ИП не используется | | `isIndividualEntrepreneur` | `boolean?` | Контрагент является ИП | | `contactPersonName` | `string?` | Основное контактное лицо | | `contactPersonPhoneNumber` | `string?` | Телефон основного контактного лица | | `responsibleId` | `long?` | ID ответственного сотрудника | | `sourceType` | `SourceType?` | Источник контрагента | ### Пример ```json { "id": 0, "name": "ООО \"Делаем загрузки\"", "inn": "1234567890", "kpp": "123456789", "isIndividualEntrepreneur": false, "contactPersonName": "Иван Иванов", "contactPersonPhoneNumber": "79999999999", "responsibleId": 6092802, "sourceType": 90 } ``` ### 1.2. Получение списка контрагентов ```http GET /api/Counterparty/List ``` Метод возвращает список контрагентов текущей организации. ### Query-параметры | Параметр | Описание | |---|---| | `$filter` | Фильтр по полям модели | | `$orderby` | Сортировка | | `$top` | Количество записей | | `$skip` | Смещение | ### Поля ответа `CounterpartyListModel` | Поле | Тип | Описание | |---|---|---| | `id` | `long` | ID контрагента | | `inn` | `string?` | ИНН | | `kpp` | `string?` | КПП | | `name` | `string?` | Наименование | | `contactPersonName` | `string?` | Основное контактное лицо | | `contactPersonPhoneNumber` | `string?` | Телефон основного контактного лица | | `registeredOrganizationId` | `long?` | ID зарегистрированной организации CARGO.RUN | | `sourceType` | `SourceType` | Источник контрагента | | `isActive` | `boolean` | Контрагент активен | | `isIndividualEntrepreneur` | `boolean` | Контрагент является ИП | | `isInBlacklist` | `boolean` | Устаревший признак черного списка | | `trust` | `CounterpartyTrust?` | Надежность контрагента. Новое поле вместо `isInBlacklist` | | `cargorunId` | `long?` | ID контрагента в CARGO.RUN | ### 1.3. Получение одного контрагента ```http GET /api/Counterparty/GetForView?Id={counterparty_id} ``` Метод возвращает карточку контрагента для просмотра. ### Поля ответа `CounterpartyViewModel` | Поле | Тип | Описание | |---|---|---| | `id` | `long` | ID контрагента | | `inn` | `string?` | ИНН | | `kpp` | `string?` | КПП | | `name` | `string?` | Наименование | | `contactPersonName` | `string?` | Основное контактное лицо | | `contactPersonPhoneNumber` | `string?` | Телефон основного контактного лица | | `currentDebtLimit` | `double?` | Текущий лимит задолженности | | `isActive` | `boolean` | Контрагент активен | | `isIndividualEntrepreneur` | `boolean` | Контрагент является ИП | | `isInBlacklist` | `boolean` | Устаревший признак черного списка | | `trust` | `CounterpartyTrust?` | Надежность контрагента. Новое поле вместо `isInBlacklist` | Для получения модели редактирования используйте: ```http GET /api/Counterparty/GetForEdit?Id={counterparty_id} ``` Метод возвращает `CounterpartyApplyModel`. ### 1.4. Удаление контрагента ```http POST /api/Counterparty/Delete?Id={counterparty_id} ``` Метод удаляет контрагента по ID. Удаление может быть ограничено бизнес-правилами, если контрагент используется в заказах или связанных сущностях. --- ## 2. Адреса контрагентов Адреса контрагентов хранятся в `CounterpartyLocations`. Их можно использовать как сохраненные точки погрузки или выгрузки. ### 2.1. Создание или обновление адреса ```http POST /api/CounterpartyLocations/Apply ``` ### Поля запроса `CounterpartyLocationApplyModel` | Поле | Тип | Описание | |---|---|---| | `id` | `long` | `0` для создания, ID адреса для обновления | | `name` | `string?` | Название адреса | | `counterpartyId` | `long` | ID контрагента | | `location` | `MapObjectApplyModel?` | Адрес и координаты | ### Основные поля `location` | Поле | Тип | Описание | |---|---|---| | `id` | `long` | ID геообъекта | | `latitude` | `double?` | Широта | | `longitude` | `double?` | Долгота | | `state` | `string?` | Регион | | `county` | `string?` | Район | | `federalDistrict` | `string?` | Федеральный округ | | `city` | `string?` | Город | | `village` | `string?` | Населенный пункт | | `street` | `string?` | Улица | | `houseNumber` | `string?` | Дом | | `address` | `string?` | Полный адрес | ### Пример ```json { "id": 0, "name": "Склад Москва", "counterpartyId": 57398, "location": { "id": 0, "latitude": 55.747035, "longitude": 37.616606, "state": "Москва", "city": "Москва", "address": "Москва, Софийская набережная, 14с1" } } ``` ### 2.2. Получение списка адресов ```http GET /api/CounterpartyLocations/List ``` Для интеграционного сценария доступен отдельный список: ```http GET /api/CounterpartyLocations/ListForIntegrator ``` Оба метода поддерживают `$filter`, `$orderby`, `$top`, `$skip`. ### Поля ответа `CounterpartyLocationListModel` | Поле | Тип | Описание | |---|---|---| | `id` | `long` | ID адреса | | `counterpartyName` | `string?` | Наименование контрагента | | `name` | `string?` | Название адреса | | `location` | `MapObjectViewModel?` | Адрес и координаты | | `updatedAt` | `date-time` | Дата последнего изменения | | `isDeleted` | `boolean` | Адрес удален | | `organizationName` | `string?` | Организация, поле есть в интеграторской модели | ### 2.3. Получение одного адреса ```http GET /api/CounterpartyLocations/GetForView?Id={location_id} GET /api/CounterpartyLocations/GetForViewIntegrator?Id={location_id} ``` ### Поля ответа | Поле | Тип | Описание | |---|---|---| | `id` | `long` | ID адреса | | `counterpartyName` | `string?` | Наименование контрагента | | `name` | `string?` | Название адреса | | `address` | `string?` | Полный адрес | | `latitude` | `double` | Широта | | `longitude` | `double` | Долгота | | `updatedAt` | `date-time` | Дата изменения | | `createdAt` | `date-time` | Дата создания | | `isDeleted` | `boolean` | Адрес удален | | `organizationName` | `string?` | Организация, поле есть в интеграторской модели | ### 2.4. Удаление адреса ```http POST /api/CounterpartyLocations/Delete?Id={location_id} ``` --- ## 3. Контактные лица заказчика Контактные лица заказчика хранятся в `CounterpartyContactPeople`. ### 3.1. Создание или обновление контактного лица ```http POST /api/CounterpartyContactPeople/Apply ``` ### Поля запроса `CounterpartyContactPersonApplyModel` | Поле | Тип | Описание | |---|---|---| | `id` | `long` | `0` для создания, ID контактного лица для обновления | | `counterpartyId` | `long?` | ID контрагента | | `firstName` | `string?` | Имя | | `lastName` | `string?` | Фамилия | | `patronymic` | `string?` | Отчество | | `phoneNumber` | `string?` | Телефон | | `email` | `string?` | Email | | `position` | `string?` | Должность | | `order` | `int` | Порядок отображения | | `cargorunCounterparty` | `CargorunOrderCounterpartyModel?` | Связанный контрагент CARGO.RUN | ### 3.2. Получение списка контактных лиц ```http GET /api/CounterpartyContactPeople/List GET /api/CounterpartyContactPeople/SelectListByCounterpartyId?CounterpartyId={counterparty_id} ``` ### Поля ответа `CounterpartyContactPersonListModel` | Поле | Тип | Описание | |---|---|---| | `id` | `long` | ID контактного лица | | `counterpartyId` | `long` | ID контрагента | | `counterpartyOrganizationName` | `string?` | Организация контрагента | | `counterpartyName` | `string?` | Наименование контрагента | | `firstName` | `string?` | Имя | | `lastName` | `string?` | Фамилия | | `patronymic` | `string?` | Отчество | | `phoneNumber` | `string?` | Телефон | | `email` | `string?` | Email | | `position` | `string?` | Должность | | `order` | `int` | Порядок отображения | | `isDeleted` | `boolean` | Контакт удален | ### 3.3. Получение одного контактного лица ```http GET /api/CounterpartyContactPeople/GetForView?Id={contact_person_id}&IsNew=false ``` Для формы редактирования: ```http GET /api/CounterpartyContactPeople/GetForEdit?Id={contact_person_id}&IsNew=false ``` ### 3.4. Удаление контактного лица ```http POST /api/CounterpartyContactPeople/Delete?Id={contact_person_id}&IsNew=false ``` --- ## 4. Надежность контрагента Ранее для черного списка использовались методы: ```http POST /api/Counterparty/ApplyIsInBlacklist GET /api/Counterparty/GetIsInBlacklist?Id={counterparty_id} ``` Эти методы считаются устаревшими. Для управления показателями надежности контрагента используйте методы: ```http POST /api/Counterparty/ApplyTrust GET /api/Counterparty/GetTrust?Id={counterparty_id} ``` ### Тело запроса `ApplyTrust` ```json { "id": 12, "trust": 10 } ``` | Поле | Тип | Описание | |---|---|---| | `id` | `long` | ID контрагента | | `trust` | `CounterpartyTrust` | Надежность контрагента | ### Значения `trust` | Значение | Описание | |---:|---| | `0` | Надежный | | `10` | Требует проверки | | `20` | Ненадежный | Поле `isInBlacklist` в `List` и `GetForView` также считается устаревшим. Для новых интеграций используйте поле `trust`. --- ## 5. Лимиты задолженности ### 5.1. Установка лимита ```http POST /api/Counterparty/ApplyDebtLimit ``` ### Тело запроса `CounterpartyDebtLimitApplyModel` ```json { "id": 57398, "currentDebtLimit": 1000000 } ``` | Поле | Тип | Описание | |---|---|---| | `id` | `long` | ID контрагента | | `currentDebtLimit` | `double?` | Текущий лимит задолженности | ### 5.2. Получение лимита ```http GET /api/Counterparty/GetDebtLimit?Id={counterparty_id} ``` ### Ответ `CounterpartyDebtLimitModel` ```json { "currentDebtLimit": 1000000 } ``` | Поле | Тип | Описание | |---|---|---| | `currentDebtLimit` | `double?` | Текущий лимит задолженности | --- Source: products/cargorun-loads/api/transporter.md # Transporter API Раздел описывает основные методы для сценария перевозчика. --- ## 1. Получение доступных заказов ```http GET /api/TransporterOrders/GetList ``` Метод возвращает заказы, доступные текущей организации перевозчика. Используется для получения списка заказов, доступных перевозчику для выполнения: как заказов своей организации, так и чужих доступных заказов. В интерфейсе соответствует разделу **«Поиск заказов»**. Для получения полной карточки конкретного заказа используйте `GET /api/TransporterOrders/GetInfo?id={order_id}`. ### Query-параметры | Параметр | Описание | |---|---| | `$filter` | Фильтр по полям модели | | `$orderby` | Сортировка по полям модели | | `$top` | Ограничение количества записей | | `$skip` | Смещение | ### Пример ```http GET /api/TransporterOrders/GetList?$orderby=loadStart asc&$top=50&$skip=0 ``` Фильтрация по населенным пунктам доступна через строковые поля `locationFrom` и `locationTo`: ```http GET /api/TransporterOrders/GetList?$filter=contains(locationFrom,'Айдарово') and contains(locationTo,'Ильинское-Усово')&$top=50&$skip=0 ``` ### Ответ Метод возвращает объект со списком доступных заказов и общим количеством найденных записей: | Поле | Тип | Описание | |---|---|---| | `data` | `TransporterOrderWithMatchingsListModel[]` | Массив доступных заказов | | `totalCount` | `long?` | Общее количество записей, подходящих под фильтр | Если заказов нет, `data` может быть пустым массивом. ```json { "data": [ { "id": 1552780, "addressFrom": "Ростовская область, Аксайский район, улица Логопарк, 5", "addressTo": "Ростовская область, Аксай, улица Авиаторов, 5", "loadStart": "2026-07-01T15:15:00+03:00", "unloadStart": "2026-07-02T08:15:00+03:00", "organizationName": "ltgf", "organizationId": 95143, "distanceKm": 30.5, "trailerTypeNames": ["Рефрижератор"], "pointsCount": 2, "orderPriceType": 10, "orderCost": 25000, "accessType": 30, "output": 678.49, "subscribeFilterId": null } ], "totalCount": 1 } ``` ### Поля заказа в `data[]` В модели `TransporterOrderWithMatchingsListModel` доступны отдельные строковые поля населенных пунктов `locationFrom` и `locationTo`. Их можно использовать для фильтрации по точкам отправления и назначения. Для отображения полного маршрута также доступны полные адреса `addressFrom` и `addressTo`. | Поле | Тип | Описание | |---|---|---| | `id` | `long` | ID заказа | | `addressFrom` | `string?` | Адрес первой точки маршрута | | `addressTo` | `string?` | Адрес последней точки маршрута | | `locationFrom` | `string?` | Населенный пункт отправления | | `locationTo` | `string?` | Населенный пункт назначения | | `loadStart` | `date-time?` | Начало планового окна погрузки | | `loadFinish` | `date-time?` | Окончание планового окна погрузки | | `loadTimezoneId` | `string?` | Часовой пояс точки погрузки | | `unloadStart` | `date-time?` | Начало планового окна выгрузки | | `unloadFinish` | `date-time?` | Окончание планового окна выгрузки | | `unloadTimezoneId` | `string?` | Часовой пояс точки выгрузки | | `organizationName` | `string?` | Название организации владельца заказа | | `organizationId` | `long` | ID организации владельца заказа | | `distanceKm` | `double?` | Расстояние маршрута в километрах | | `trailerTypeNames` | `string[]?` | Названия требуемых типов полуприцепов | | `pointsCount` | `int?` | Количество точек маршрута | | `orderPriceType` | `OrderPriceType?` | Тип стоимости: `10` фиксированная, `20` аукцион, `30` предложение цены | | `offersFixAt` | `date-time?` | Время фиксации предложений | | `offersAreFixed` | `boolean?` | Признак, что предложения зафиксированы | | `accessType` | `OrderAccessType` | Видимость заказа: `10` всем, `20` связанным организациям, `30` выбранным связанным организациям | | `visibleForOrganizationsIds` | `long[]?` | ID организаций, которым виден заказ | | `visibleForOrganizationNames` | `string[]?` | Названия организаций, которым виден заказ | | `orderCost` | `double?` | Стоимость заказа для заказчика | | `orderCostDeviationPercent` | `double?` | Отклонение стоимости в процентах | | `output` | `double?` | Расчетный показатель вывода/результата | | `subscribeFilterId` | `long?` | ID фильтра подписки, по которому заказ попал в список | --- ## 2. Получение деталей доступного заказа ```http GET /api/TransporterOrders/GetInfo?id={order_id} ``` Метод возвращает подробную информацию о заказе для перевозчика: - маршрут; - груз; - тип цены; - стоимость; - отклики; - статус; - контактные данные; - ограничения и требования. Ответ использует модель `TransporterOrderInfoModel`: данные возвращаются с учетом прав текущей организации перевозчика. Если заказ больше не доступен перевозчику, метод может вернуть ошибку доступа или пустой результат в зависимости от бизнес-ситуации. --- ## 3. Создание отклика из справочников ```http POST /api/TransporterOrderTruckMatchings/ApplyMatching ``` Метод используется, если данные ТС, водителя или прицепа заполняются из справочников. Основные поля: | Поле | Описание | |---|---| | `orderId` | ID заказа | | `logistFullName` | ФИО контактного лица перевозчика | | `logistPhoneNumber` | Телефон контактного лица | | `price` | Ставка | | `truck` | Тягач | | `trailer` | Прицеп | | `driver` | Водитель | | `ndsTypeId` | Тип НДС | | `isTemporaryTruck` | Временный тягач | | `isTemporaryDriver` | Временный водитель | | `isTemporaryTrailer` | Временный прицеп | Пример: ```json { "id": 0, "orderId": 1552780, "logistFullName": "Иванов Иван", "logistPhoneNumber": "79999999999", "price": 23000, "truck": { "id": 1001, "organizationId": 95713, "sourceType": 10, "isRented": false }, "trailer": { "id": 2001, "organizationId": 95713, "isRented": false }, "driver": { "id": 3001, "organizationId": 95713 }, "ndsTypeId": 1, "isTemporaryTruck": false, "isTemporaryDriver": false, "isTemporaryTrailer": false, "isForwarding": false } ``` При успехе метод возвращает `200 OK` без тела ответа. После отправки отклика проверяйте заказ через `GET /api/TransporterOrders/GetInfo?id={order_id}`. --- ## 4. Создание отклика с ручным заполнением ```http POST /api/TransporterOrderTruckMatchings/ApplyManualMatching ``` Метод используется, если данные ТС, водителя или прицепа передаются вручную. При успешном выполнении отсутствующие сущности могут быть созданы. Основные поля: | Поле | Описание | |---|---| | `id` | `0` для нового отклика | | `orderId` | ID заказа | | `truckNumber`, `trailerNumber` | Номера ТС и прицепа | | `driverLastName`, `driverFirstName`, `driverPatronymic` | ФИО водителя | | `driverPhoneNumber` | Телефон водителя | | `logistFullName`, `logistPhoneNumber` | Контакт перевозчика | | `price` | Ставка перевозчика | | `ndsTypeId` | Тип НДС | | `truckTrailerTypeId`, `truckModelTypeId`, `truckOwnershipTypeId` | Справочные данные ТС | | `trailerOwnershipTypeId` | Справочные данные прицепа | При успехе метод возвращает `200 OK` без тела ответа. --- ## 5. Просмотр отклика ```http GET /api/TransporterOrderTruckMatchings/Get?orderTruckMatchingId={matching_id} ``` Метод возвращает созданный отклик перевозчика на заказ. Используйте его, когда нужно открыть уже отправленный отклик и получить сохраненные данные: контакт логиста, ставку, ТС, прицеп, водителя, НДС и признаки временно введенных сущностей. ### Query-параметры | Параметр | Тип | Описание | |---|---|---| | `orderTruckMatchingId` | `long` | ID отклика | ### Ответ ```json { "id": 43587716, "orderId": 1552780, "logistFullName": "Иванов Иван", "logistPhoneNumber": "79999999999", "price": 23000, "truck": { "id": 1001, "trailerTypeId": 1, "modelTypeId": 12, "number": "Х777ХХ16", "ownershipTypeId": 2, "ownerName": "ООО \"Перевозчик\"", "ownerInn": "1234567890", "sourceType": 10, "isRented": false, "organizationId": 95713 }, "trailer": { "id": 2001, "ownershipTypeId": 2, "ownerName": "ООО \"Перевозчик\"", "ownerInn": "1234567890", "number": "А123ВС77", "isRented": false, "organizationId": 95713 }, "driver": { "id": 3001, "lastName": "Петров", "firstName": "Петр", "patronymic": "Петрович", "phoneNumber": "79999999999", "organizationId": 95713 }, "ndsTypeId": 1, "isTemporaryTruck": false, "isTemporaryDriver": false, "isTemporaryTrailer": false, "isForwarding": false, "forwardingOrganizationId": null } ``` ### Поля отклика | Поле | Тип | Описание | |---|---|---| | `id` | `long` | ID отклика | | `orderId` | `long` | ID заказа | | `logistFullName` | `string?` | ФИО контактного лица перевозчика по отклику | | `logistPhoneNumber` | `string?` | Телефон контактного лица перевозчика | | `price` | `double?` | Ставка перевозчика | | `truck` | `TransporterOrderTruckMatchingTruckModel?` | Тягач | | `trailer` | `TransporterOrderTruckMatchingTrailerModel?` | Прицеп | | `driver` | `TransporterOrderTruckMatchingDriverModel?` | Водитель | | `ndsTypeId` | `long?` | Тип НДС | | `isTemporaryTruck` | `boolean` | Тягач введен вручную/временно | | `isTemporaryDriver` | `boolean` | Водитель введен вручную/временно | | `isTemporaryTrailer` | `boolean` | Прицеп введен вручную/временно | | `isForwarding` | `boolean` | Отклик создан как экспедирование | | `forwardingOrganizationId` | `long?` | ID экспедиторской организации | ### Поля `truck` | Поле | Тип | Описание | |---|---|---| | `id` | `long` | ID тягача | | `trailerTypeId` | `long?` | Тип полуприцепа/кузова | | `modelTypeId` | `long?` | Тип/модель ТС | | `number` | `string?` | Госномер тягача | | `ownershipTypeId` | `long?` | Тип владения | | `ownerName` | `string?` | Собственник | | `ownerInn` | `string?` | ИНН собственника | | `sourceType` | `SourceType` | Источник данных ТС | | `isRented` | `boolean` | ТС арендованное | | `organizationId` | `long` | ID организации перевозчика | ### Поля `trailer` | Поле | Тип | Описание | |---|---|---| | `id` | `long` | ID прицепа | | `ownershipTypeId` | `long?` | Тип владения | | `ownerName` | `string?` | Собственник | | `ownerInn` | `string?` | ИНН собственника | | `number` | `string?` | Госномер прицепа | | `isRented` | `boolean` | Прицеп арендованный | | `organizationId` | `long` | ID организации перевозчика | ### Поля `driver` | Поле | Тип | Описание | |---|---|---| | `id` | `long` | ID водителя | | `lastName` | `string?` | Фамилия | | `firstName` | `string?` | Имя | | `patronymic` | `string?` | Отчество | | `phoneNumber` | `string?` | Телефон | | `passportSeries` | `string?` | Серия паспорта | | `passportNumber` | `string?` | Номер паспорта | | `passportGivenBy` | `string?` | Кем выдан паспорт | | `passportGivenWhen` | `date-time?` | Когда выдан паспорт | | `organizationId` | `long` | ID организации перевозчика | Для получения данных, необходимых именно для формы редактирования отклика, используется: ```http GET /api/TransporterOrderTruckMatchings/GetForEditMatching?Id={matching_id}&IsNew=false ``` Метод возвращает `EditOrderTruckMatchingModel`: `id`, `truck`, `trailer`, `driver`, `isForwarding`. --- ## 6. Изменение и удаление отклика | Действие | Метод | |---|---| | Изменить ставку | `POST /api/TransporterOrderTruckMatchings/EditMatchingPrice` | | Удалить отклик | `POST /api/TransporterOrderTruckMatchings/Delete` | | Отклонить отклик со стороны перевозчика | `POST /api/TransporterOrderTruckMatchings/Decline` | ### Изменение ставки ```json { "id": 43587716, "price": 24000 } ``` ### Удаление отклика ```http POST /api/TransporterOrderTruckMatchings/Delete?Id={matching_id} ``` ### Отклонение отклика ```json { "id": 43587716 } ``` При успехе эти методы возвращают `200 OK` без тела ответа. --- ## 7. Получение назначенной заявки ```http GET /api/TransporterBids/GetInfo?id={order_id} ``` Если метод возвращает карточку заказа, значит заказ назначен текущему перевозчику и стал заявкой. Ответ использует модель `OrderInfoModel`. --- ## 8. Передача фактических времен по точкам ```http POST /api/TransporterBids/ApplyOrderPointFactTimes ``` Используется для передачи фактического времени въезда и выезда по точке маршрута. ### Тело запроса ```json { "id": 2435200, "factEnterTimeOffset": "2026-07-01T15:25:00+03:00", "factLeaveTimeOffset": "2026-07-01T16:10:00+03:00", "clearAllNextPoints": false } ``` | Поле | Обязательность | Описание | |---|---|---| | `id` | Да | ID точки маршрута из `points[].id` | | `factEnterTimeOffset` | Нет | Фактическое время прибытия | | `factLeaveTimeOffset` | Нет | Фактическое время выезда | | `clearAllNextPoints` | Да | Очистить фактические времена следующих точек | При успехе метод возвращает `200 OK` без тела ответа. Обновленные времена появятся в `points[].factEnterTimeOffset` и `points[].factLeaveTimeOffset`. --- ## 9. Справочники перевозчика | Сущность | Список | Создание/редактирование | Удаление | |---|---|---|---| | ТС | `GET /api/TransporterTruck/List` | `POST /api/TransporterTruck/Apply` | `POST /api/TransporterTruck/Delete` | | Прицепы | `GET /api/TransporterTrailer/List` | `POST /api/TransporterTrailer/Apply` | `POST /api/TransporterTrailer/Delete` | | Водители | `GET /api/TransporterDriver/List` | `POST /api/TransporterDriver/Apply` | `POST /api/TransporterDriver/Delete` | Удаление справочников перевозчика является мягким: данные остаются в базе, но становятся недоступны пользователям. Списки справочников возвращают стандартный ответ: ```json { "data": [ { "id": 1001, "number": "Х777ХХ16", "sourceType": 10, "updatedAt": "2026-06-30T16:30:00+00:00" } ], "totalCount": 1 } ``` --- Source: products/cargorun-loads/api/directories.md # Directories API Справочники используются при создании заказа и настройке фильтров интеграции. Большинство методов поддерживают: - `$filter`; - `$orderby`; - `$top`; - `$skip`. --- ## 1. Примеры фильтрации ```http GET /api/PackType/SelectList?$filter=name eq 'Тент' ``` ```http GET /api/PackType/SelectList?$filter=contains(tolower(name),'тент') ``` ```http GET /api/PackType/SelectList?$filter=id eq 42 ``` --- ## 2. Справочники для создания заказа Перед созданием заказа внешняя система обычно получает значения справочников и сохраняет у себя соответствие `id` и `name`. В заказ передается ID справочного значения. | Что нужно заполнить | Поле в заказе | Метод | |---|---|---| | Тип груза | `cargoTypeId` | `GET /api/CargoType/SelectByOrganizationList` | | Типы упаковки | `packTypeIds` | `GET /api/PackType/SelectList` | | Типы полуприцепов | `trailerTypeIds` | `GET /api/OrganizationAccount/GetAllowedTrailerTypeList` | | Тип загрузки/выгрузки в точке | `points[].loadUnloadTypeId` | `GET /api/LoadUnloadType/SelectList` | | [Заказчик/контрагент](./counterparties.md) | `counterpartyId` | `GET /api/Orders/SelectCounterpartyByOrganizationList` | | Автор заказа | `authorId` | `GET /api/Orders/SelectAuthorByOrganizationList` | | Перевозчики для видимости | `visibleForOrganizationsIds` | `GET /api/Organization/SelectRelationsOrganizationsList` | | Тип НДС заказчика | `ndsTypeId` | `GET /api/NdsType/SelectList` | | Тип НДС перевозчика | `transporterNdsTypeId` | `GET /api/NdsType/SelectList` | | Тип оплаты | `paymentTypeId` | `GET /api/PaymentType/SelectList` | | Причины отмены | `cancellationReasonIds` | `GET /api/CancellationReasons/SelectByOrderList?OrderId={order_id}` | Для обычной интеграции достаточно читать справочники. Методы создания и редактирования справочных значений не описаны в этом разделе, потому что они относятся к административным сценариям и могут быть недоступны интеграционному пользователю. Работа с контрагентами выделена в отдельный раздел: [Counterparties API](./counterparties.md). Там описаны создание, чтение, удаление, адреса, контактные лица, надежность и лимиты контрагентов. ### Пример: получить тип НДС ```http GET /api/NdsType/SelectList Authorization: Bearer ``` Ответ: ```json { "data": [ { "id": 1, "name": "Без НДС" }, { "id": 71, "name": "НДС 22%" } ], "totalCount": 2 } ``` Чтобы создать заказ без НДС, передайте: ```json { "ndsTypeId": 1 } ``` ### Пример: получить типы полуприцепов ```http GET /api/OrganizationAccount/GetAllowedTrailerTypeList?OrganizationId={organization_id} Authorization: Bearer ``` Ответ: ```json { "data": [ { "id": 122, "name": "Тент" }, { "id": 12, "name": "Рефрижератор" } ], "totalCount": 2 } ``` Чтобы создать заказ с требованием к тентованному полуприцепу, передайте: ```json { "trailerTypeIds": [122] } ``` --- ## 3. Справочники для расшифровки заказа Эти же справочники используются при чтении заказа из [`GET /api/Orders/GetInfo`](./orders.md#orders-get-info). | Поле заказа | Справочник | Пример значения | |---|---|---| | `ndsTypeId`, `ndsTypeName` | `GET /api/NdsType/SelectList` | `{"id": 71, "name": "НДС 22%"}` | | `trailerTypeNames` | `GET /api/OrganizationAccount/GetAllowedTrailerTypeList` | `{"id": 122, "name": "Тент"}` | | `packTypeNames` | `GET /api/PackType/SelectList` | `{"id": 811, "name": "Паллета"}` | | `cargoType` | `GET /api/CargoType/SelectByOrganizationList` | `{"id": 8791, "name": "Продукты питания"}` | | `points[].loadUnloadTypeName` | `GET /api/LoadUnloadType/SelectList` | Тип загрузки/выгрузки | В ответе заказа часто возвращаются и ID, и название справочного значения. Например, НДС заказчика возвращается как `ndsTypeId` и `ndsTypeName`, а НДС перевозчика может возвращаться как `transporterNdsType`. ### Пример справочника НДС ```json { "data": [ { "id": 1, "name": "Без НДС" }, { "id": 51, "name": "НДС 12%" }, { "id": 61, "name": "НДС 5%" }, { "id": 41, "name": "НДС 20%" }, { "id": 11, "name": "НДС 10%" }, { "id": 2, "name": "НДС 0%" }, { "id": 71, "name": "НДС 22%" } ], "totalCount": 7 } ``` ### Пример справочника типов полуприцепов ```json { "data": [ { "id": 122, "name": "Тент" }, { "id": 12, "name": "Рефрижератор" }, { "id": 121, "name": "Изотерм" }, { "id": 123, "name": "Термос" } ], "totalCount": 20 } ``` --- ## 4. Типовой ответ ```json { "data": [ { "id": 1, "name": "Тент" } ], "totalCount": 1 } ``` --- ## 5. Справочники перевозчика Справочники перевозчика описаны в разделе [Transporter API](./transporter.md): - `TransporterTruck`; - `TransporterTrailer`; - `TransporterDriver`. --- Source: products/cargorun-loads/api/map.md # Map API Методы `Map` используются для работы с адресами, координатами и маршрутами. --- ## 1. Получение адреса по координатам ```http GET /api/Map/ReverseSearchAddresses?Latitude={latitude}&Longitude={longitude} ``` ### Query-параметры | Параметр | Тип | Описание | |---|---|---| | `Latitude` | `double` | Широта | | `Longitude` | `double` | Долгота | | `Key` | `string` | Дополнительный ключ поиска, если используется | ### Пример ```http GET /api/Map/ReverseSearchAddresses?Latitude=55.74703593862486&Longitude=37.61660648499558 ``` ### Ответ Метод возвращает массив адресов: ```json [ { "latitude": 55.747084, "longitude": 37.616728, "county": null, "state": "Москва", "federalDistrict": "Центральный федеральный округ", "city": "Москва", "village": null, "street": "Софийская набережная", "houseNumber": "14с1", "address": "Москва, Софийская набережная, 14с1" } ] ``` Полученный адрес можно использовать в `points[].location` при создании заказа. --- ## 2. Связанные методы Также доступны методы: - `GET /api/Map/SearchAddresses`; - `GET /api/Map/GetTimezoneInfo`; - `GET /api/Map/GetRoute`; - `GET /api/Map/GetTravelTimePrediction`; - `GET /api/Map/GetPrice`. Они будут описаны отдельно, если станут частью публичного интеграционного сценария. --- Source: products/cargorun-loads/for-ai.md # Для LLM и ИИ-агентов Раздел задает правила для ИИ-агентов, которые анализируют интеграцию или формируют запросы к API **CARGO.RUN Загрузки**. ## Машиночитаемые материалы - [Краткий индекс `cargorun-loads-llms.txt`](../../cargorun-loads-llms.txt) — карта разделов и порядок чтения. - [Полная документация `cargorun-loads-llms-full.txt`](../../cargorun-loads-llms-full.txt) — раздел одним Markdown-документом. Начинайте с краткого индекса. Полную версию используйте для базы знаний, RAG или проверки связей между сценариями и моделями. ## Приоритет источников Если описания расходятся, используйте следующий порядок: 1. контракт конкретного метода в API Reference; 2. общие форматы, ошибки, статусы и минимальные требования; 3. интеграционный сценарий; 4. пример запроса. Пример не отменяет таблицу полей. Если расхождение влияет на изменяющий запрос, остановите автоматическое выполнение и запросите подтверждение владельца интеграции. ## Правила выполнения 1. Получайте `` и учетные данные из защищенной конфигурации. 2. Не передавайте секреты и персональные данные в промпт или журнал. 3. Передавайте в поля `...Id` только значения, полученные из справочников целевой среды. 4. После создания сохраните ID CARGO.RUN; не считайте `externalId` гарантированно уникальным ключом. 5. Перед изменением существующего заказа прочитайте его актуальную карточку. 6. Считайте создание, обновление, запуск, назначение перевозчика, отмену и удаление изменяющими операциями. 7. После изменяющей операции повторно прочитайте объект и проверьте результат. 8. Не считайте отсутствие `truckCurrentLocation` ошибкой и не называйте координаты текущими без проверки `fixedAt`. ## Минимальный контекст Для формирования запроса агенту достаточно передать: - целевой сценарий и разрешенные изменяющие действия; - базовый URL без секретов; - описание конкретного метода; - связанные модели, справочники и enum; - правила ошибок и форматов; - соответствие внешнего ID идентификатору CARGO.RUN.