# CARGO.RUN — интеграция с партнёрскими сервисами > Полная машиночитаемая версия документации. Источник: https://cargorun-ru.github.io/cargo.run-api-docs/products/partner-integrations/ --- Source: products/partner-integrations/index.md # Интеграция с партнёрскими сервисами Раздел описывает интеграцию CARGO.RUN с партнёрскими сервисами, которым необходимо создавать заявки перевозчиков и получать сведения о ходе их исполнения. Документация охватывает: - подключение и machine-to-machine авторизацию; - проверку организаций и управление доступом; - создание и обновление заявок; - получение объединённого списка созданных партнёром и транслируемых ему заявок; - получение статусов, ETA, событий, маршрутов, сообщений и файлов; - синхронные и асинхронные способы взаимодействия; - подписки и webhook; - восстановление синхронизации после ошибок. ## Основные сценарии ### Партнёрский сервис создаёт заявку Партнёрский сервис получает доступ к организации перевозчика, создаёт или обновляет заявку и затем отслеживает её исполнение. ### Перевозчик связывает заявку с партнёрским сервисом Перевозчик создаёт заявку в CARGO.RUN и указывает партнёрский сервис и идентификатор заказа. Партнёр получает эту заявку и сведения о её исполнении без права создавать другие заявки организации. ## Способы взаимодействия | Способ | Назначение | |---|---| | Синхронное API | Простые вызовы с результатом в ответе на тот же запрос | | Асинхронная очередь | Пакетные и фоновые операции с получением результата по идентификатору задачи или через webhook | | Подписка | Оперативное уведомление партнёра об изменении связанной заявки | Рекомендуемая интеграция сочетает webhook для оперативных изменений с периодической контрольной синхронизацией. ## Для LLM и ИИ-агентов Для анализа и разработки интеграции с помощью ИИ используйте машиночитаемые версии документации: - [индекс документации для LLM](../../llms.txt); - [полная документация одним файлом](../../llms-full.txt). Рекомендации по выбору файла и передаче контекста приведены в разделе [Для LLM и ИИ-агентов](for-ai.md). --- Source: products/partner-integrations/getting-started.md # Быстрый старт Во всех примерах `` — адрес API CARGO.RUN, выданный при подключении. ## 1. Получить токен ```http POST /api/Account/Token Content-Type: application/json ``` ```json { "grantType": "client_credentials", "clientId": "partner-client-id", "clientSecret": "partner-client-secret" } ``` Сохраните `accessToken.token` из ответа и используйте его во всех последующих запросах: ```http Authorization: Bearer ``` ## 2. Выбрать сценарий === "Партнёр создаёт заявку" 1. Проверить организацию по ИНН через [`Organizations/Check`](reference/endpoints.md#get-apiintegrationsorganizationscheck). 2. При необходимости вызвать [`Organizations/Apply`](reference/endpoints.md#post-apiintegrationsorganizationsapply). 3. Создать заявку синхронным [`Bids/Apply`](reference/endpoints.md#post-apiintegrationsbidsapply) или асинхронным `Write`. 4. Сохранить ID заявки CARGO.RUN. === "Перевозчик связал заявку с партнёром" 1. Получить объединённый список собственных и транслируемых заявок через [`Bids/GetList`](reference/endpoints.md#get-apiintegrationsbidsgetlist) или асинхронный `ReadQuery`. 2. Сохранить ID заявок CARGO.RUN. 3. Получать полные данные синхронными методами или асинхронным `Read`. ## 3. Получить заявки Синхронно: ```http GET /api/integrations/Bids/GetList?$orderby=updatedAt,id&$top=100 Authorization: Bearer ``` Без `X-Organization-Id` метод возвращает заявки всех доступных организаций. Поле `isCreatedByPlatform` отличает созданные партнёром заявки от транслируемых перевозчиками. Асинхронно: ```http POST /api/integrations/Tasks/Queue Authorization: Bearer Content-Type: application/json Idempotency-Key: initial-sync-2026-10-07 ``` ```json { "commands": [ { "action": "ReadQuery", "objects": [ { "type": "Bid", "modelType": "Default", "query": "$filter=updatedAt gt 2026-10-06T08:00:00Z&$orderby=updatedAt,id&$top=100" } ] } ] } ``` После постановки задачи получите её результат по возвращённому `taskId` либо дождитесь webhook `queued-task.finished`. ## 4. Получить полные данные заявки Синхронно карточка, события, маршруты и сообщения запрашиваются отдельными [методами `Bids/Get*`](reference/endpoints.md#get-apiintegrationsbidsget). Через очередь используйте `Read / Bid / Default`: результат содержит карточку, плановый маршрут, события и сообщения. Фактический маршрут всегда запрашивается синхронным [`Bids/GetActualRoute`](reference/endpoints.md#get-apiintegrationsbidsgetactualroute). ## 5. Подключить оперативные уведомления CARGO.RUN настраивает для интеграционного клиента callback и подписку `Bid/Summary`. После этого партнёр получает webhook `entity.changed`, проверяет подпись, исключает повтор по `eventId` и запрашивает полные данные заявки по её ID. Даже при использовании webhook периодически выполняйте `ReadQuery` по `updatedAt`: это позволяет восстановить изменения после длительной недоступности callback. --- Source: products/partner-integrations/auth.md # Подключение и авторизация ## Что выдаёт CARGO.RUN Для партнёрского сервиса создаётся интеграционный клиент. CARGO.RUN передаёт: - `clientId`; - `clientSecret`; - `` тестового или промышленного API. Дополнительно CARGO.RUN настраивает платформу клиента, разрешения, callback и подписки. ## Получение токена ```http POST /api/Account/Token Content-Type: application/json ``` ```json { "grantType": "client_credentials", "clientId": "partner-client-id", "clientSecret": "partner-client-secret" } ``` | Поле | Тип | Обязательно | Значение | |---|---|---:|---| | `grantType` | string | Да | Всегда `client_credentials` | | `clientId` | string | Да | Идентификатор интеграционного клиента | | `clientSecret` | string | Да | Секрет интеграционного клиента | Из успешного ответа нужны: ```json { "accessToken": { "token": "", "expiresIn": 3600 } } ``` `expiresIn` задаётся в секундах. Поля пользовательской авторизации `refreshToken`, `twoFactorToken`, `twoFactorProvider`, `currentUser` и `requiresTwoFactor` не входят в публичный M2M-контракт и не должны использоваться. ## Использование токена Во всех методах, кроме получения токена, передавайте: ```http Authorization: Bearer ``` Для JSON-запросов: ```http Content-Type: application/json ``` Для `GET /api/integrations/Bids/GetList` можно передать `X-Organization-Id`. Заголовок ограничивает список одной доступной организацией; без него метод возвращает заявки всех организаций интеграционного клиента. Для остальных методов заголовок используйте только когда это прямо указано в контракте. ## Обновление токена - кешируйте токен до окончания `expiresIn`; - не запрашивайте новый токен перед каждым вызовом; - вызывайте [`Account/Token`](reference/endpoints.md#post-apiaccounttoken) не чаще двух раз за 30 секунд, иначе возможен `429 Too Many Requests`; - при `401 Unauthorized` один раз получите новый токен и повторите исходный запрос; - не записывайте `clientSecret` и токен в логи. ## Настройка callback Сотрудник CARGO.RUN указывает для интеграционного клиента: - `callbackTarget` — HTTPS URL партнёра; - `callbackSecret` — секрет HMAC-подписи; - платформу, которой соответствуют связанные заявки; - подписку `Bid/Summary` или `Bid/Default`. Партнёрский сервис не меняет эти настройки через M2M API. Формат запросов, подпись и правила повторной доставки описаны в разделе [Webhook и подписки](webhooks.md). ## Проверка callback ```http POST /api/integrations/Tasks/Ping Authorization: Bearer ``` CARGO.RUN отправит на callback тестовый webhook с заголовком: ```http X-Cargorun-Webhook-Event: ping ``` Метод позволяет проверить доступность endpoint и реализацию проверки подписи. --- Source: products/partner-integrations/access.md # Модель доступа Доступ к организации, разрешение создавать заявки и доступ к конкретной заявке — разные права. ## Идентификация партнёра CARGO.RUN определяет партнёрский сервис по `clientId` из M2M-токена. Для получения заявок перевозчика дополнительно используется платформа, настроенная у интеграционного клиента. ## Проверка организации ```http GET /api/integrations/Organizations/Check?inn={inn} Authorization: Bearer ``` Ответ: ```json { "exists": true, "canCreateBids": true, "hasAccess": false } ``` | Поле | Значение | |---|---| | `exists` | Организация с таким ИНН существует | | `canCreateBids` | Партнёрским сервисам разрешено создавать её заявки | | `hasAccess` | Текущий интеграционный клиент уже связан с организацией | | Результат | Действие | |---|---| | `exists=false` | Вызвать [`Organizations/Apply`](reference/endpoints.md#post-apiintegrationsorganizationsapply) | | `canCreateBids=true`, `hasAccess=true` | Можно создавать заявки | | `canCreateBids=true`, `hasAccess=false` | Вызвать [`Organizations/Apply`](reference/endpoints.md#post-apiintegrationsorganizationsapply) для получения доступа | | `canCreateBids=false` | Не создавать заявку; можно читать заявки, которые перевозчик связал с партнёром | ## Создание организации ```http POST /api/integrations/Organizations/Apply Authorization: Bearer Content-Type: application/json ``` ```json { "name": "ООО Ромашка", "inn": "7701234567", "kpp": "770101001", "ogrn": "1027700000000" } ``` Поля `name` и `inn` обязательны. Поиск организации выполняется по ИНН. Правила: - новая организация создаётся и связывается с текущим партнёром; - к организации, созданной другим партнёрским сервисом, текущему партнёру может быть выдан собственный доступ; - доступ к внутренней организации CARGO.RUN по умолчанию не выдаётся; - исключение возможно только при явной административной настройке. Успешный ответ содержит ID организации: ```json { "id": 12345 } ``` ## Доступ к заявке Партнёр может читать: 1. Заявку, созданную им в доступной организации. Проверяется источник заявки, внешний ID и технический пользователь организации. 2. Заявку перевозчика, у которой `ExternalPlatform` соответствует платформе партнёра и заполнен `ExternalPlatformOrderId`. Знание ID не предоставляет доступ к произвольной заявке. При синхронном чтении недоступной или несуществующей заявки возвращается `404 Not Found`. В асинхронной очереди HTTP-запрос задачи может завершиться успешно, а ошибка возвращается в `objects[].status="Error"` и `objects[].message`. ## Идентификаторы заявки | Идентификатор | Назначение | |---|---| | `id` | Внутренний ID заявки CARGO.RUN | | `bid.externalId` | ID заявки, созданной партнёрским сервисом | | `ExternalPlatformOrderId` | ID заказа партнёра, указанный перевозчиком в CARGO.RUN | | `IntegrationBidListModel.externalId` | Для связанной заявки содержит `ExternalPlatformOrderId`; для собственной — `bid.externalId` | | `objects[].key` | При `Write` используется как `bid.externalId`, если поле внутри `bid` не заполнено | ## Область объединённого списка Для `GET /api/integrations/Bids/GetList` заголовок `X-Organization-Id` необязателен: - с заголовком возвращаются доступные заявки только указанной организации; - без заголовка — заявки всех организаций интеграционного клиента. В обоих случаях список объединяет собственные и транслируемые заявки. Используйте `isCreatedByPlatform`, а не наличие `externalId`, чтобы определить источник. --- Source: products/partner-integrations/scenarios/create-update-bid.md # Создание и обновление заявки Партнёр может создать или полностью обновить заявку синхронно либо через очередь. В обоих вариантах используется одна модель `ApplyBidFromIntegrationContext`. ## Предварительные условия - организация существует; - организация создана партнёрским сервисом или текущему партнёру явно выдан доступ; - [`Organizations/Check`](../reference/endpoints.md#get-apiintegrationsorganizationscheck) возвращает `canCreateBids=true`; - для создания переданы водитель, автомобиль, груз и минимум две точки; - среди точек есть хотя бы одна погрузка и одна выгрузка. Организация задаётся обязательным полем `inn`: 10 цифр для юридического лица или 12 цифр для ИП. Это правило одинаково для синхронного и асинхронного вариантов. ## Синхронный вариант ```http POST /api/integrations/Bids/Apply Authorization: Bearer Content-Type: application/json ``` ```json { "inn": "7701234567", "bid": { "externalId": "ORDER-2471970", "comment": "Доставка груза", "counterparty": { "name": "ООО Ромашка", "inn": "7701234567" }, "vehicleType": { "name": "Рефрижератор", "tonnage": 20, "volume": 82 }, "temperatureRegime": { "minimum": 2, "maximum": 6 }, "cargos": [ { "name": "Паллетированный груз" } ], "bidPoints": [ { "externalId": "POINT-LOAD-1", "isLoadPoint": true, "planEnterDate": "2026-10-08T10:00:00", "geozone": { "location": { "coordinates": [37.6176, 55.7558] }, "address": "Москва, улица Примерная, 1" } }, { "externalId": "POINT-UNLOAD-1", "isLoadPoint": false, "planEnterDate": "2026-10-09T10:00:00", "geozone": { "address": "Казань, улица Примерная, 2" } } ], "car": { "number": "А123АА777", "brandName": "КАМАЗ" }, "driver": { "firstName": "Иван", "lastName": "Иванов", "phoneNumber": "+79991234567" } } } ``` Успешный ответ: ```json { "id": 12345, "isRouteBuilt": true } ``` Заявка автоматически запускается в работу. Если найденная заявка ещё не запущена, обновление также запускает её. ## Асинхронный вариант ```http POST /api/integrations/Tasks/Queue Authorization: Bearer Content-Type: application/json Idempotency-Key: create-order-2471970-v1 ``` ```json { "commands": [ { "action": "Write", "objects": [ { "type": "Bid", "modelType": "Default", "key": "ORDER-2471970", "body": { "inn": "7701234567", "bid": { "externalId": "ORDER-2471970", "counterparty": { "name": "ООО Ромашка", "inn": "7701234567" }, "vehicleType": { "name": "Рефрижератор", "tonnage": 20, "volume": 82 }, "temperatureRegime": { "minimum": 2, "maximum": 6 }, "cargos": [ { "name": "Паллетированный груз" } ], "bidPoints": [ { "externalId": "POINT-LOAD-1", "isLoadPoint": true, "planEnterDate": "2026-10-08T10:00:00", "geozone": { "location": { "coordinates": [37.6176, 55.7558] }, "address": "Москва, улица Примерная, 1" } }, { "externalId": "POINT-UNLOAD-1", "isLoadPoint": false, "planEnterDate": "2026-10-09T10:00:00", "geozone": { "address": "Казань, улица Примерная, 2" } } ], "car": { "number": "А123АА777", "brandName": "КАМАЗ" }, "driver": { "firstName": "Иван", "lastName": "Иванов", "phoneNumber": "+79991234567" } } } } ] } ] } ``` Поле `body` обязательно для `Write`. Если `bid.externalId` отсутствует, обработчик использует `objects[].key`. После завершения ID заявки находится в `objects[].id`. `isRouteBuilt` через очередь не возвращается. ## Создание связанных сущностей - водитель ищется в организации по `phoneNumber`; при отсутствии создаётся; - автомобиль ищется по `number`; при отсутствии создаётся; - прицеп необязателен; если он передан, `trailer.number` обязателен, а отсутствующий прицеп создаётся; - первый и второй водитель обрабатываются независимо. ### Контрагент перевозки `counterparty` необязателен. Если он передан: 1. `name` обязателен и не должен превышать 256 символов; 2. при наличии `inn` контрагент ищется в организации по ИНН; 3. без `inn` используется точное сравнение наименования без учёта регистра; 4. если совпадение не найдено, создаётся новый контрагент; 5. найденный или созданный контрагент становится заказчиком заявки. ИНН должен состоять из 10 или 12 цифр. При совпадении по ИНН уже существующий контрагент используется без переименования. ### Тип и вместимость ТС `vehicleType` необязателен, но переданный объект должен содержать хотя бы одно из полей `name`, `tonnage`, `volume`. Тип и характеристики записываются в прицеп, если он есть в заявке, иначе — в автомобиль. - `name` — не более 128 символов; - `tonnage` и `volume`, если переданы, должны быть больше нуля; - тип создаётся в отдельном справочнике организации без дублей; - при тоннаже название имеет вид `Рефрижератор, 20 т`; - если тоннажа нет, но есть объём — `Рефрижератор, 82 м3`; - если переданы тоннаж и объём, в название входит тоннаж, но обе характеристики записываются в ТС; - если `name` отсутствует, переданные тоннаж или объём обновляют характеристики, не изменяя существующий тип ТС. Это изменение данных справочника автомобиля или прицепа, а не только снимка заявки. ### Температурный режим `temperatureRegime` необязателен. Если объект передан, обязательны обе границы: - `minimum` и `maximum` находятся в диапазоне от −30 до 30 °C включительно; - `minimum` строго меньше `maximum`. Для новой организации, создаваемой партнёрским сервисом, модуль «Температурный режим» включается сразу. Для ранее созданной таким способом организации он включается при первой заявке с `temperatureRegime`. ## Требования к маршруту - минимум две точки; - среди точек должна быть хотя бы одна погрузка и одна выгрузка; - `planEnterDate` обязательно для каждой точки; - порядок маршрута определяется `planEnterDate`: CARGO.RUN сравнивает даты после приведения к UTC и сортирует точки по возрастанию; поле `order` во входной модели не передаётся; - время передаётся как локальное время точки без UTC-смещения; - `geozone.address` — обязательная непустая строка; - `geozone.location` необязателен: без координат CARGO.RUN геокодирует точку по адресу; - переданные части адреса сохраняются, а отсутствующие заполняются результатом геокодера; - если координаты переданы, они имеют формат `[долгота, широта]`; - часовой пояс определяется CARGO.RUN по итоговым координатам. Долгота должна находиться в диапазоне от −180 до 180, широта — от −90 до 90. Пара координат `[0, 0]` не принимается. ## Груз, стоимость и НДС - передайте как минимум один элемент `cargos[]`; - у каждого груза обязательно поле `name`; - если `price` не передана, CARGO.RUN создаёт заявку на порожний пробег; - если `price` передана, поле `vat` обязательно; - `vat` передаётся строкой со значением `0`, `10`, `20` или `22`. В основном сценарии используются погрузка (`isLoadPoint=true`) и выгрузка (`isLoadPoint=false`). ## Обновление Заявку можно идентифицировать по `externalId` партнёра или по внутреннему `bid.id`, ранее полученному от CARGO.RUN. Если передан `externalId`, CARGO.RUN сначала ищет заявку с таким идентификатором внутри организации, найденной по `inn`: - если заявка найдена, её внутренний `id` имеет приоритет над переданным `bid.id`; - если заявка по `externalId` не найдена, для обновления используется переданный `bid.id`; - если не найдена заявка по `externalId` и `bid.id` не указан, создаётся новая заявка. Для дальнейшей работы также сохраняйте внутренний `id`, возвращённый CARGO.RUN. Частичное обновление не поддерживается. Передавайте полную актуальную модель. При повторном `Apply` CARGO.RUN старается сохранить существующие точки, их `id`, статусы прохождения и фактические отметки: 1. точки с `externalId` сопоставляются по этому идентификатору; 2. точки без `externalId` — по порядковому номеру после сортировки и типу погрузки/выгрузки; 3. несопоставленная точка создаётся заново. Передавайте стабильный и уникальный внутри заявки `bidPoints[].externalId`. Если полагаться на порядок, изменение дат или состава маршрута может привести к сопоставлению с другой точкой. Уникальность собственной заявки определяется сочетанием организации, интеграционного клиента, источника и `externalId`. --- Source: products/partner-integrations/scenarios/receive-bids.md # Получение заявок `GET /api/integrations/Bids/GetList` возвращает единый список: - заявок, созданных текущим партнёром; - заявок перевозчиков, транслируемых платформе партнёра. Для транслируемой заявки перевозчик указывает в CARGO.RUN платформу `ExternalPlatform` и идентификатор заказа `ExternalPlatformOrderId`. Оба значения должны быть заполнены. !!! warning "Область выборки" Транслируемые заявки выбираются по платформе, а не непосредственно по `clientId`. Несколько активных интеграционных клиентов одной платформы могут получить одинаковые заявки. ## Синхронный список Все доступные организации: ```http GET /api/integrations/Bids/GetList?$filter=updatedAt%20gt%202026-10-06T08:00:00Z&$orderby=updatedAt,id&$top=100 Authorization: Bearer ``` Только одна организация: ```http GET /api/integrations/Bids/GetList?$filter=updatedAt%20gt%202026-10-06T08:00:00Z&$orderby=updatedAt,id&$top=100 Authorization: Bearer X-Organization-Id: 12345 ``` `X-Organization-Id` необязателен только как ограничитель области этого метода. Если заголовок передан, организация должна быть доступна интеграционному клиенту. !!! warning "Миграция" `GET /api/integrations/Bids/GetCurrentList` удалён. Не заменяйте его вызовом `GetList` вслепую: новый метод также возвращает заявки, созданные партнёром, а без `X-Organization-Id` охватывает все доступные организации. ## Источник и внешний идентификатор | `isCreatedByPlatform` | Источник | Значение `externalId` | |---:|---|---| | `true` | Заявку создал текущий партнёр | `bid.externalId`, переданный в `Apply` или `Write` | | `false` | Перевозчик транслирует заявку платформе | `ExternalPlatformOrderId`, указанный перевозчиком | Всегда сохраняйте внутренний `id` CARGO.RUN. `externalId` имеет разную семантику в зависимости от источника и не заменяет внутренний ID. ## Пример ответа ```json [ { "id": 12345, "externalId": "ORDER-2471970", "isCreatedByPlatform": false, "status": "Started", "isDeleted": false, "createdAt": "2026-10-06T10:00:00+03:00", "updatedAt": "2026-10-07T11:00:00+03:00", "points": [ { "id": 501, "order": 0, "externalId": "POINT-LOAD-1", "type": "LoadPoint", "planEnterDate": "2026-10-07T12:00:00+03:00", "estimatedEnterDate": "2026-10-07T12:25:00+03:00", "loadUnloadStatus": "AtLoading", "enteredAt": "2026-10-07T12:18:00+03:00", "loadUnloadedAt": null, "documentsReceivedAt": null } ], "events": [ { "type": "EnteredPointByDriver", "fixedAt": "2026-10-07T12:18:00+03:00", "bidPointId": 501, "bidPointOrder": 0, "bidPointExternalId": "POINT-LOAD-1" } ] } ] ``` ## Точки, события и часовые пояса - `points` содержит несервисные точки в порядке следования; - все даты в `points` возвращаются в часовом поясе соответствующей точки; - события самой заявки возвращаются в часовом поясе организации; - события точки возвращаются в часовом поясе точки; - `events` внутри `GetList` содержит события несервисных точек; - отдельный `Bids/GetEvents` дополнительно возвращает события сервисных точек, если у них есть фактические даты; - `events` вычисляется после основной выборки и не участвует в `$filter` и `$orderby`. `estimatedEnterDate` пересчитывается без изменения заявки и не сдвигает `updatedAt`. Поэтому курсорная выборка по `updatedAt` не гарантирует получение каждого изменения ETA. Если актуальная ETA нужна в интерфейсе, периодически перечитывайте интересующие заявки по ID или запрашивайте подходящее текущее окно. ## Асинхронный список Используйте `ReadQuery / Bid / Default`: ```json { "commands": [ { "action": "ReadQuery", "objects": [ { "type": "Bid", "modelType": "Default", "query": "$filter=updatedAt gt 2026-10-06T08:00:00Z&$orderby=updatedAt,id&$top=100" } ] } ] } ``` После завершения задачи `objects[0].body` содержит `IntegrationBidListModel[]`. `ReadQuery` эквивалентен `GetList` без `X-Organization-Id` и охватывает все доступные организации. Поля `id`, `version` и `key` в объекте команды должны отсутствовать, а `query` должен быть непустым. ## Первичная загрузка и пагинация Без непустого `$filter` сервер возвращает заявки, изменённые за последние 30 дней. Любой непустой `$filter`, даже не связанный с `updatedAt`, отменяет это окно. 1. Выберите начальное значение `updatedAt`. 2. Запрашивайте данные с `$orderby=updatedAt,id`. 3. Используйте `$top` и `$skip` либо собственный курсор. 4. Сохраняйте последний успешно обработанный `(updatedAt,id)`. 5. Следующий интервал начинайте на несколько секунд раньше. 6. Удаляйте дубли по `id`. 7. Разделяйте источники по `isCreatedByPlatform`, если для них нужны разные процессы. --- Source: products/partner-integrations/scenarios/track-execution.md # Отслеживание исполнения После получения `id` заявки CARGO.RUN партнёр может читать её текущие данные синхронно или через очередь. ## Синхронные методы | Данные | Метод | |---|---| | Карточка и ETA | [`GET /api/integrations/Bids/Get`](../reference/endpoints.md#get-apiintegrationsbidsget) | | События | [`GET /api/integrations/Bids/GetEvents`](../reference/endpoints.md#get-apiintegrationsbidsgetevents) | | Плановый маршрут | [`GET /api/integrations/Bids/GetPlannedRoute`](../reference/endpoints.md#get-apiintegrationsbidsgetplannedroute) | | Фактический маршрут | [`GET /api/integrations/Bids/GetActualRoute`](../reference/endpoints.md#get-apiintegrationsbidsgetactualroute) | | Сообщения и файлы | [`GET /api/integrations/Bids/GetDriverMessages`](../reference/endpoints.md#get-apiintegrationsbidsgetdrivermessages) | ## Статус и события — разные данные Поле `status` в карточке или краткой модели заявки содержит её текущее состояние: `New`, `Planned`, `Started`, `Canceled` или `Done`. Именно это поле используйте для синхронизации статуса заказа во внешней системе. `Bids/GetEvents` возвращает этапы исполнения, вычисленные по фактическим датам. Отмена и удаление представлены событиями `BidCanceled` и `BidDeleted`. Текущее состояние заявки всё равно определяйте по `BidStatus`, а события используйте как хронологию изменений. ## Полное чтение через очередь ```json { "commands": [ { "action": "Read", "objects": [ { "type": "Bid", "modelType": "Default", "id": 12345 } ] } ] } ``` `objects[].body` содержит `IntegrationBidDetailsModel`: - `externalId`; - `bid` — карточка заявки и ETA; - `plannedRoute`; - `events`; - `driverMessages`. Фактическая геометрия маршрута не включается из-за объёма. ## ETA ETA находится в `bid.estimation`: ```json { "estimatedDate": "2026-10-08T15:00:00+03:00", "manualEstimatedLeaveDate": null } ``` `estimatedDate` возвращается в часовом поясе последней точки заявки. Объединённый `GetList` также возвращает `points[].estimatedEnterDate` в часовом поясе соответствующей точки. ETA пересчитывается без изменения заявки и не сдвигает `updatedAt`, поэтому инкрементальный курсор не гарантирует получение каждого её изменения. Для оперативного экрана периодически перечитывайте интересующие заявки. Фрагмент ответа `Bids/Get`: ```json { "id": 12345, "status": "Started", "updatedAt": "2026-10-08T12:05:00+03:00", "externalId": "ORDER-2471970", "estimation": { "estimatedDate": "2026-10-08T15:00:00+03:00", "manualEstimatedLeaveDate": null } } ``` ## События ```json [ { "type": "EnteredPointByDriver", "fixedAt": "2026-10-08T12:00:00+03:00", "bidPointId": 456, "bidPointOrder": 1, "bidPointExternalId": "POINT-UNLOAD-1" } ] ``` Для события точки `fixedAt` использует часовой пояс этой точки, для остальных событий — часовой пояс организации. `GetList.events` содержит события несервисных точек. Отдельный `Bids/GetEvents` дополнительно возвращает события сервисных точек, если у них есть фактические даты. ## Плановый маршрут Содержит расстояния в метрах и продолжительность в секундах. Синхронный `GetPlannedRoute` возвращает расчётные показатели; асинхронный `IntegrationBidDetailsModel.plannedRoute` использует ту же модель. ```json { "id": 70001, "distance": 815000, "duration": 39600, "distanceWithoutEmptyMileage": 800000, "emptyMileageDistance": 15000, "durationWithoutEmptyMileage": 37800 } ``` ## Фактический маршрут ```http GET /api/integrations/Bids/GetActualRoute?id=12345&coordinateIntervalSeconds=60 Authorization: Bearer ``` `coordinateIntervalSeconds` задаёт минимальный интервал между координатами; значение по умолчанию — `60`, значение `0` отключает прореживание. `isMobile=true` означает мобильные координаты, `false` — другой источник, например телематика. ```json [ { "emptyMileageRoute": [], "mainRoute": [ { "coordinate": [37.6176, 55.7558], "fixedAt": "2026-10-08T12:00:00+03:00" } ], "carId": 501, "carNumber": "А123АА777", "hasActiveMileage": true, "isMobile": true } ] ``` ## Сообщения и файлы Синхронный метод поддерживает OData и `X-MetaCount`. Он возвращает расширенную `ChatMessageGetModel`, включая `type` и `flags`. В полном асинхронном ответе `driverMessages` содержит сокращённую модель без этих двух полей. `accessUrlLink` — временная ссылка на файл. Скачайте файл сразу либо повторно прочитайте заявку для получения новой ссылки. ```json [ { "id": 80001, "text": "Документы загружены", "createdAt": "2026-10-08T12:10:00+03:00", "chatId": 90001, "isDeleted": false, "files": [ { "id": 81001, "originalFileName": "documents.pdf", "accessUrlLink": "https://files.example/download/temporary-token" } ], "type": "User" } ] ``` --- Source: products/partner-integrations/scenarios/recovery.md # Восстановление синхронизации Webhook обеспечивает малую задержку, но не гарантирует хранение всех изменений во время длительной недоступности партнёра. Для восстановления используйте `ReadQuery` или объединённый `GetList`. ## Хранимое состояние Партнёру рекомендуется хранить: - внутренний `id` заявки CARGO.RUN; - партнёрский `externalId`; - последний принятый `updatedAt`; - обработанные `eventId` webhook; - курсор последней успешной сверки; - статус собственной обработки события. ## Алгоритм восстановления 1. Взять время последней успешной сверки. 2. Вычесть несколько секунд для перекрытия. 3. Выполнить список с фильтром `updatedAt gt ...`. 4. Использовать `$orderby=updatedAt,id`. 5. Обрабатывать страницы до пустого результата. 6. Удалять дубли по `id`. 7. Для изменившихся ID выполнить `Read / Bid / Default`. 8. Отдельно запросить фактический маршрут, если он нужен. 9. Обновить курсор только после успешной записи всех данных. `ReadQuery` эквивалентен `GetList` без `X-Organization-Id`. Если восстановление нужно выполнить отдельно по организации, используйте синхронный `GetList` с этим заголовком. ## Пример запроса ```text $filter=updatedAt gt 2026-10-07T07:59:55Z&$orderby=updatedAt,id&$top=100 ``` ## Периодическая сверка Даже при стабильной работе webhook выполняйте контрольную сверку по расписанию. Интервал выбирает партнёр с учётом допустимой задержки и нагрузки. ## Повтор задач Если ответ постановки задачи потерян, повторите тот же запрос с тем же `Idempotency-Key`. Сервер вернёт ранее созданные задачи в течение 24 часов. Если потерян только webhook `queued-task.finished`, получите результат задачи через [`GET /api/integrations/Tasks/Queue`](../reference/endpoints.md#get-apiintegrationstasksqueue), передав `taskId` в параметре `id`. --- Source: products/partner-integrations/sync-api.md # Синхронное API Синхронный метод возвращает результат обработки в ответе на тот же HTTP-запрос. Этот способ проще для одиночных операций и обязателен для получения фактического маршрута. ## Доступные операции | Задача | Метод | |---|---| | Получить токен | [`POST /api/Account/Token`](reference/endpoints.md#post-apiaccounttoken) | | Проверить организацию | [`GET /api/integrations/Organizations/Check`](reference/endpoints.md#get-apiintegrationsorganizationscheck) | | Создать организацию или получить доступ | [`POST /api/integrations/Organizations/Apply`](reference/endpoints.md#post-apiintegrationsorganizationsapply) | | Создать или обновить заявку | [`POST /api/integrations/Bids/Apply`](reference/endpoints.md#post-apiintegrationsbidsapply) | | Получить собственные и транслируемые заявки | [`GET /api/integrations/Bids/GetList`](reference/endpoints.md#get-apiintegrationsbidsgetlist) | | Получить карточку заявки | [`GET /api/integrations/Bids/Get`](reference/endpoints.md#get-apiintegrationsbidsget) | | Получить события | [`GET /api/integrations/Bids/GetEvents`](reference/endpoints.md#get-apiintegrationsbidsgetevents) | | Получить плановый маршрут | [`GET /api/integrations/Bids/GetPlannedRoute`](reference/endpoints.md#get-apiintegrationsbidsgetplannedroute) | | Получить фактический маршрут | [`GET /api/integrations/Bids/GetActualRoute`](reference/endpoints.md#get-apiintegrationsbidsgetactualroute) | | Получить сообщения и файлы | [`GET /api/integrations/Bids/GetDriverMessages`](reference/endpoints.md#get-apiintegrationsbidsgetdrivermessages) | ## OData-параметры Списковые методы поддерживают `$filter`, `$orderby`, `$top`, `$skip`, `$count`, `$select` и `$expand`. Общее количество записей передаётся в заголовке `X-MetaCount`. Для инкрементальной синхронизации используйте стабильную сортировку: ```http GET /api/integrations/Bids/GetList?$filter=updatedAt%20gt%202026-10-06T08:00:00Z&$orderby=updatedAt,id&$top=100 ``` `X-Organization-Id` ограничивает `GetList` одной доступной организацией. Без него метод охватывает все организации интеграционного клиента. `GetCurrentList` удалён. ## Форматы | Данные | Формат | |---|---| | Ответные дата и время | ISO 8601 с UTC-смещением | | Дата без времени | `YYYY-MM-DD`, без часового пояса | | Плановые даты точек | Локальное время координат точки без UTC-смещения | | Координаты | `[longitude, latitude]`, WGS 84, градусы | | Расстояние | Метры | | Продолжительность | Секунды | | Enum | Строковое имя значения | `updatedAt` представляет абсолютный момент времени. В OData-фильтрах рекомендуется приводить курсор к UTC и передавать его с суффиксом `Z`; значение со смещением и эквивалентное значение в UTC сравниваются одинаково. ## Ошибки Бизнес-ошибки синхронных команд могут возвращаться как обычный текст с HTTP `400`, а не как JSON. Не повторяйте `400` и `403` без изменения запроса или прав доступа. При чтении `404` означает, что заявка не существует либо недоступна текущему партнёру; различить эти случаи по HTTP-статусу нельзя. Полный контракт каждого метода приведён в [справочнике API](reference/endpoints.md). --- Source: products/partner-integrations/async-queue.md # Асинхронная очередь Асинхронная очередь позволяет создать одну или несколько фоновых задач и получить результат позднее. Для партнёрских сервисов доступны только заявки типа `Bid`. ## Методы - [`POST /api/integrations/Tasks/Queue`](reference/endpoints.md#post-apiintegrationstasksqueue) — поставить команды в очередь; - [`GET /api/integrations/Tasks/Queue`](reference/endpoints.md#get-apiintegrationstasksqueue) — получить состояние и результат задачи; - [`POST /api/integrations/Tasks/Ping`](reference/endpoints.md#post-apiintegrationstasksping) — проверить доставку webhook на настроенный `callbackTarget`. ```http POST /api/integrations/Tasks/Queue GET /api/integrations/Tasks/Queue?id={taskId} POST /api/integrations/Tasks/Ping ``` ## Поддерживаемые комбинации | `action` | `type` | `modelType` | Назначение | Результат `body` | |---|---|---|---|---| | `Write` | `Bid` | `Default` | Создать или обновить заявку | `body` не возвращается; ID находится в `objects[].id` | | `Read` | `Bid` | `Default` | Получить полные данные заявки | `IntegrationBidDetailsModel` | | `Read` | `Bid` | `Summary` | Получить краткие данные заявки | `IntegrationBidListModel` | | `ReadQuery` | `Bid` | `Default` | Получить собственные и транслируемые заявки всех доступных организаций | `IntegrationBidListModel[]` | `Delete` и `ReadConfirmation` для партнёрских сервисов не поддерживаются. `Write` использует ту же модель и валидацию, что синхронный `Bids/Apply`, включая `counterparty`, `vehicleType`, `temperatureRegime` и геокодирование точек без координат. `ReadQuery` эквивалентен `Bids/GetList` без `X-Organization-Id`. Поля `isCreatedByPlatform`, `points` и `events` гарантированы для результата `ReadQuery`. Прямой `Read / Bid / Summary` остаётся минимальной краткой моделью; не используйте его для определения источника заявки. Для этого выполните `ReadQuery`, а для полной карточки — `Read / Bid / Default`. ## Постановка задачи ```http POST /api/integrations/Tasks/Queue Authorization: Bearer Content-Type: application/json Idempotency-Key: read-bid-12345-v1 ``` ```json { "commands": [ { "action": "Read", "objects": [ { "type": "Bid", "modelType": "Default", "id": 12345 } ] } ] } ``` На каждый элемент `commands[]` создаётся отдельная задача. Ответ постановки содержит массив `commands` с `id`, `action`, `status` и ориентировочным `readyInMsec`. ## Жизненный цикл ```text Awaiting → InProgress → Completed ↘ Error ``` Статус `Completed` означает завершение задачи, но не гарантирует успех каждого объекта. Всегда проверяйте `objects[].status`. ## Получение результата ```http GET /api/integrations/Tasks/Queue?id={taskId} Authorization: Bearer ``` Пока задача выполняется, используйте `Retry-After` или `readyInMsec` как минимальную паузу до следующего запроса. Результат также может быть доставлен webhook `queued-task.finished`, если настроен callback. ## Два уровня ошибок Ниже показан сокращённый фрагмент ответа, содержащий только поля, важные для обработки ошибки объекта: ```json { "status": "Completed", "objects": [ { "type": "Bid", "id": 12345, "status": "Error", "message": "Заявка не найдена или недоступна интеграционному клиенту.", "body": null } ] } ``` HTTP-запрос и задача могут завершиться успешно, а отдельный объект — ошибкой. ## Идемпотентность `Idempotency-Key` необязателен, но рекомендуется для повторяемых запросов. - максимальная длина — 100 символов; - срок действия — 24 часа; - область уникальности — текущий `clientId`; - для нескольких команд сервер добавляет к ключу индекс команды; - повтор возвращает прежний `taskId`; - тело повторного запроса не сравнивается с первоначальным. Не используйте один ключ для разных логических операций. --- Source: products/partner-integrations/webhooks.md # Webhook и подписки Webhook отправляется методом `POST` на `callbackTarget` — HTTPS-адрес обработчика на стороне партнёрского сервиса. Партнёр передаёт этот адрес CARGO.RUN при подключении интеграции вместе с `callbackSecret`; CARGO.RUN сохраняет его в настройках интеграционного клиента. Например: ```text https://partner.example.com/webhooks/cargorun ``` Все webhook этого интеграционного клиента (`queued-task.finished`, `entity.changed` и `ping`) поступают на один настроенный адрес. Тип события определяется по заголовку `X-Cargorun-Webhook-Event`. Получатель должен вернуть любой HTTP-код `2xx`. Проверить доставку на настроенный адрес можно методом [`POST /api/integrations/Tasks/Ping`](reference/endpoints.md#post-apiintegrationstasksping). ## Типы webhook Значение передаётся в `X-Cargorun-Webhook-Event`: | Значение | Смысл | |---|---| | `queued-task.finished` | Завершилась задача, поставленная партнёром | | `entity.changed` | Изменилась заявка, связанная с партнёром | | `ping` | Тест callback | ## Заголовки | Заголовок | Описание | |---|---| | `X-Cargorun-Webhook-Event` | Тип webhook | | `X-Cargorun-Task-Id` | ID задачи; для `ping` — `0` | | `X-Cargorun-Webhook-Timestamp` | Unix timestamp в секундах | | `X-Cargorun-Webhook-Signature` | `sha256=`, если настроен `callbackSecret` | ## Подпись ```text HMAC_SHA256(callbackSecret, ".") ``` Проверяйте подпись по исходным байтам тела до десериализации. Рекомендуется также проверять допустимое расхождение времени и использовать постоянное по времени сравнение подписей. ## Модель тела События `queued-task.finished` и `entity.changed` используют модель [`QueuedApiTaskCallbackPayload`](reference/endpoints.md#queuedapitaskcallbackpayload). Поле `origin` определяет источник задачи: | Событие | `origin` | Назначение | |---|---|---| | `queued-task.finished` | `Request` | Результат команды, которую партнёр поставил через `POST /Tasks/Queue` | | `entity.changed` | `Subscription` | Данные заявки, задачу чтения которой CARGO.RUN создал по подписке | ### `queued-task.finished` ```json { "eventId": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee", "taskId": 123456, "action": "Read", "status": "Completed", "origin": "Request", "completedAt": "2026-10-07T10:00:00Z", "attemptCount": 1, "maxAttemptCount": 3, "message": null, "objects": [ { "status": "Success", "type": "Bid", "id": 12345, "key": null, "version": null, "query": null, "body": { "externalId": "ORDER-2471970", "bid": { "id": 12345, "status": "Started" } }, "message": null } ] } ``` Состав `objects[].body` определяется исходной командой: для `Read / Bid / Default` это `IntegrationBidDetailsModel`, для `Read / Bid / Summary` — `IntegrationBidListModel`. ### `entity.changed` ```json { "eventId": "bbbbbbbb-cccc-4ddd-8eee-ffffffffffff", "taskId": 123457, "action": "Read", "status": "Completed", "origin": "Subscription", "completedAt": "2026-10-07T10:05:00Z", "attemptCount": 1, "maxAttemptCount": 3, "message": null, "objects": [ { "status": "Success", "type": "Bid", "id": 12345, "key": null, "version": null, "query": null, "body": { "id": 12345, "externalId": "ORDER-2471970", "status": "Canceled", "isDeleted": false, "createdAt": "2026-10-06T10:00:00+03:00", "updatedAt": "2026-10-07T13:05:00+03:00" }, "message": null } ] } ``` В примере подписка настроена с `modelType=Summary`, поэтому `objects[].body` имеет модель `IntegrationBidListModel`. При `modelType=Default` в `body` приходит `IntegrationBidDetailsModel`. `Summary` в webhook предназначен для получения ID и сигнала об изменении. Не определяйте по нему `isCreatedByPlatform`: расширенные поля объединённого списка гарантированы в `GetList` и `ReadQuery`. После уведомления перечитайте список или полную заявку в соответствии со сценарием. `eventId` уникален для доставки и используется для дедупликации повторных webhook. `taskId` позволяет повторно получить тот же результат методом `GET /api/integrations/Tasks/Queue?id={taskId}`. `attemptCount` и `maxAttemptCount` относятся к обработке асинхронной задачи CARGO.RUN. Это не счётчики доставки webhook. Состояние доставки доступно при чтении задачи в полях `callbackStatus`, `callbackAttemptCount`, `callbackMaxAttemptCount`, `callbackNextRetryAt`, `callbackDeliveredAt` и `lastError`. ### `ping` `ping` — тест доставки на тот же `callbackTarget`. Не используйте его тело как бизнес-событие и не сохраняйте как изменение заявки. Получатель проверяет timestamp и подпись так же, как для остальных webhook, после чего возвращает `2xx`. ## Подписка на заявки CARGO.RUN настраивает подписку: ```json [ { "entityType": "Bid", "modelType": "Summary" } ] ``` Для партнёрских сервисов поддерживается только `Bid`. `entityType` определяет тип сущности подписки; в текущем партнёрском контракте единственное поддерживаемое значение — строка `Bid`. `modelType` определяет форму `objects[].body`: `Summary` или `Default`. ### `Summary` В `objects[].body` передаётся `IntegrationBidListModel`. Это рекомендуемый режим: партнёр получает ID и основные данные, затем выполняет `Read / Bid / Default`. ### `Default` В `objects[].body` передаётся полный `IntegrationBidDetailsModel`. Ответ значительно больше; фактический маршрут всё равно не включается. ## Какие изменения публикуются Реализация отправляет изменение при создании и редактировании заявки, смене статуса, возврате в работу, изменении автомобиля/водителя/прицепа, действиях водителя на точках, подтверждении получения документов и удалении заявки. Обычное новое сообщение или файл в чате само по себе не гарантирует `entity.changed`. Для получения сообщений используйте чтение полной заявки или [`GET /api/integrations/Bids/GetDriverMessages`](reference/endpoints.md#get-apiintegrationsbidsgetdrivermessages). ## Порядок обработки 1. Проверить timestamp и HMAC. 2. Проверить, не обработан ли `eventId`. 3. Надёжно сохранить событие во внутреннюю очередь партнёра. 4. Вернуть `2xx`. 5. Обработать `objects[]` и при необходимости запросить полную заявку. Порядок webhook не гарантируется. Несколько изменений одной заявки могут объединиться в одно событие. Не заменяйте более новые данные старыми — сравнивайте `updatedAt`. ## Повторная доставка Повторяются сетевые ошибки, `408`, `429` и `5xx`. Остальные `4xx` считаются окончательными. Выполняется до пяти попыток доставки. Перед повторными отправками используются интервалы 10, 20, 40 и 80 секунд. После пяти последовательных неудачных доставок уведомлений по подписке доставка приостанавливается. Во время приостановки CARGO.RUN выполняет проверочную доставку каждые 5 минут. Любая успешная доставка или успешный вызов [`Tasks/Ping`](reference/endpoints.md#post-apiintegrationstasksping) сбрасывает счётчик ошибок и возобновляет доставку. Отдельного публичного поля, показывающего приостановку подписки, нет. Пока доставка приостановлена, часть изменений может быть отброшена, поэтому webhook необходимо дополнять периодическим `ReadQuery` по `updatedAt`. --- Source: products/partner-integrations/reliability.md # Надёжность интеграции ## Рекомендуемая схема ```text Первоначальная загрузка → ReadQuery Оперативные изменения → entity.changed Полные данные → Read / Bid / Default Фактический маршрут → Bids/GetActualRoute Контрольная сверка → периодический ReadQuery ``` Webhook ускоряет доставку, но не является единственным источником восстановления. ## Курсор списка Используйте сортировку: ```text $orderby=updatedAt,id ``` Сохраняйте пару `(updatedAt, id)` последней успешно обработанной заявки. Следующий запрос выполняйте с небольшим перекрытием по времени и удаляйте дубли по `id`. Если `GetList` или `ReadQuery` не содержит непустого `$filter`, сервер ограничивает выборку заявками, изменёнными за последние 30 дней. Любой непустой `$filter` отменяет это окно, поэтому для синхронизации задавайте явную границу `updatedAt`. Пересчёт `points[].estimatedEnterDate` не изменяет `updatedAt`. Если партнёру нужна актуальная ETA, одного курсора изменений недостаточно: перечитывайте интересующие заявки по ID или подходящему текущему окну. ## Идемпотентность создания Для синхронного [`Bids/Apply`](reference/endpoints.md#post-apiintegrationsbidsapply) повторяйте запрос с тем же `externalId`. Для асинхронной очереди дополнительно используйте уникальный `Idempotency-Key`. Повтор с тем же ключом в течение 24 часов возвращает существующую задачу. ## Повторные запросы | Ситуация | Поведение | |---|---| | Сетевая ошибка или timeout | Повтор с увеличивающейся задержкой | | `401` | Один раз обновить токен и повторить | | `400` | Не повторять без исправления данных | | `403` | Не повторять без изменения доступа | | `404` | Проверить ID заявки и права доступа; без изменений не повторять | | `429` | Уважать `Retry-After`, снизить частоту | | `5xx` | Ограниченный повтор с jitter и exponential backoff | ## Защита от устаревших событий - дедуплицируйте webhook по `eventId`; - сравнивайте `updatedAt` заявки; - не рассчитывайте на порядок доставки; - считайте webhook сигналом перечитать объект, а не полным журналом переходов; - храните обработку события и изменение локальных данных атомарно либо используйте собственную очередь. ## Удаление и прекращение доступа При удалении или прекращении трансляции CARGO.RUN отправляет изменение прежней аудитории. Последующий `Read` может вернуть объектную ошибку о недоступности. Поле `isDeleted=true` в краткой модели означает, что партнёр должен прекратить отслеживание заявки. ```json { "id": 12345, "externalId": "ORDER-2471970", "status": "Canceled", "isDeleted": true, "createdAt": "2026-10-06T10:00:00+03:00", "updatedAt": "2026-10-08T14:30:00+03:00" } ``` ## Совместимость Клиент должен: - игнорировать неизвестные JSON-поля; - не завершать весь процесс из-за неизвестного enum; - сохранять исходное неизвестное значение для диагностики; - не полагаться на порядок полей JSON; - учитывать, что в ответы могут добавляться новые необязательные поля. Если неизвестное значение пришло в обязательном поле, включая `BidStatus`, сохраните исходную строку, продолжайте хранить и обновлять заявку, выполните следующую контрольную синхронизацию и сформируйте предупреждение для мониторинга. Не подменяйте неизвестное значение ближайшим известным статусом и не прекращайте обработку остальных заявок. --- Source: products/partner-integrations/reference/endpoints.md # Методы API, модели и значения Во всех путях `` — адрес API CARGO.RUN. Адреса тестовой и промышленной сред запрашиваются у команды CARGO.RUN при подключении. Все методы, кроме `Account/Token`, требуют `Authorization: Bearer `. ## Сводная таблица | Метод | Назначение | |---|---| | `POST /api/Account/Token` | Получить M2M-токен | | `GET /api/integrations/Organizations/Check` | Проверить организацию по ИНН | | `POST /api/integrations/Organizations/Apply` | Создать организацию или получить доступ | | `POST /api/integrations/Bids/Apply` | Создать или обновить заявку | | `GET /api/integrations/Bids/GetList` | Получить созданные партнёром и транслируемые ему заявки | | `GET /api/integrations/Bids/Get` | Получить карточку заявки | | `GET /api/integrations/Bids/GetEvents` | Получить события заявки | | `GET /api/integrations/Bids/GetPlannedRoute` | Получить плановый маршрут | | `GET /api/integrations/Bids/GetActualRoute` | Получить фактический маршрут | | `GET /api/integrations/Bids/GetDriverMessages` | Получить сообщения и файлы водителя | | `POST /api/integrations/Tasks/Queue` | Поставить команды в очередь | | `GET /api/integrations/Tasks/Queue` | Получить результат задачи | | `POST /api/integrations/Tasks/Ping` | Проверить callback | ## `POST /api/Account/Token` Получает токен по `client_credentials`. Авторизация не требуется. Тело: [`ClientCredentialsTokenModel`](#clientcredentialstokenmodel). Ответ: [`ClientCredentialsTokenResponse`](#clientcredentialstokenresponse). ```json { "grantType": "client_credentials", "clientId": "partner-client-id", "clientSecret": "partner-client-secret" } ``` Успех: `200 OK`. Используйте `accessToken.token` и `accessToken.expiresIn`. Не вызывайте метод чаще двух раз за 30 секунд. ## `GET /api/integrations/Organizations/Check` | Параметр | Где | Тип | Обязательно | Описание | |---|---|---|---:|---| | `inn` | query | string | Да | ИНН организации | Успех: `200 OK`, модель [`IntegrationOrganizationCheckModel`](#integrationorganizationcheckmodel). ## `POST /api/integrations/Organizations/Apply` Тело: [`CreateIntegrationOrganizationContext`](#createintegrationorganizationcontext). Поля `name` и `inn` обязательны. Поиск организации выполняется по `inn`. Для новой организации, создаваемой партнёрским сервисом, сразу включается модуль «Температурный режим». Успех: `200 OK`, модель [`OrganizationApplyResult`](#organizationapplyresult). ## `POST /api/integrations/Bids/Apply` Тело: [`ApplyBidFromIntegrationContext`](#applybidfromintegrationcontext). Результат: [`ApplyBidResultModel`](#applybidresultmodel). Создаёт или полностью обновляет заявку, создаёт недостающие транспорт, водителей и контрагента, применяет характеристики ТС и температурный режим и запускает заявку в работу. Если координаты точки не переданы, CARGO.RUN определяет их по обязательному адресу. Успех: `200 OK`: ```json { "id": 12345, "isRouteBuilt": true } ``` При нарушении валидации возвращается `400 Bad Request` с текстовым сообщением. ## `GET /api/integrations/Bids/GetList` Возвращает [`IntegrationBidListModel[]`](#integrationbidlistmodel): - заявки, созданные текущим партнёром; - заявки перевозчиков, транслируемые платформе партнёра. Поле `isCreatedByPlatform` различает эти виды. Для собственной заявки `externalId` содержит ID, переданный в `Apply`; для транслируемой — ID заказа, указанный перевозчиком для платформы. | Заголовок | Обязательно | Поведение | |---|---:|---| | `X-Organization-Id` | Нет | Если передан, возвращаются заявки только этой доступной организации. Без заголовка возвращаются заявки всех организаций, доступных интеграционному клиенту. | Без непустого `$filter` сервер ограничивает список заявками, изменёнными за последние 30 дней. Любой явно переданный непустой `$filter` отменяет это окно, поэтому для инкрементальной синхронизации всегда указывайте границу по `updatedAt`. Сортировка по умолчанию — `updatedAt,id`. Ответ также содержит несервисные точки `points` и их события `events`. События вычисляются после основной выборки и не участвуют в `$filter` и `$orderby`. Поддерживает OData-параметры и заголовок `X-MetaCount`. !!! warning "Миграция с GetCurrentList" `GET /api/integrations/Bids/GetCurrentList` удалён. Используйте `GetList` и определяйте источник заявки по `isCreatedByPlatform`. Отсутствие `X-Organization-Id` означает выборку по всем доступным организациям, а не по одной текущей организации. ## `GET /api/integrations/Bids/Get` | Параметр | Где | Тип | Обязательно | Описание | |---|---|---|---:|---| | `id` | query | int64 | Да | ID заявки CARGO.RUN | Успех: `200 OK`, модель [`BidForExternalSyncModel`](#bidforexternalsyncmodel). ## `GET /api/integrations/Bids/GetEvents` Параметр `id` — обязательный ID заявки CARGO.RUN. Успех: [`IntegrationBidEventModel[]`](#integrationbideventmodel). Значения `type`: [`IntegrationBidEventType`](#integrationbideventtype). События самой заявки возвращаются в часовом поясе организации, события точек — в часовом поясе соответствующей точки. В отличие от `GetList.events`, отдельный метод включает события сервисных точек, если у них есть фактические даты. ## `GET /api/integrations/Bids/GetPlannedRoute` Параметр `id` — обязательный ID заявки. Успех: [`RouteSimpleModel`](#routesimplemodel). Модель содержит расчётные показатели; геометрия планового маршрута в базовом синхронном ответе не используется партнёрским сценарием. ```http GET /api/integrations/Bids/GetPlannedRoute?id=12345 Authorization: Bearer ``` ```json { "id": 98765, "distance": 820000, "duration": 43200, "distanceWithoutEmptyMileage": 820000, "emptyMileageDistance": 0, "durationWithoutEmptyMileage": 43200 } ``` Расстояния указаны в метрах, продолжительность — в секундах. ## `GET /api/integrations/Bids/GetActualRoute` | Параметр | Тип | Обязательно | По умолчанию | Описание | |---|---|---:|---:|---| | `id` | int64 | Да | — | ID заявки CARGO.RUN | | `coordinateIntervalSeconds` | int32 | Нет | `60` | Минимальный интервал между координатами; `0` отключает прореживание | Успех: [`CarRouteForExternalModel[]`](#carrouteforexternalmodel). ## `GET /api/integrations/Bids/GetDriverMessages` Параметр `id` — обязательный ID заявки. Возвращает [`ChatMessageGetModel[]`](#chatmessagegetmodel), поддерживает OData и `X-MetaCount`. Ссылки `files[].accessUrlLink` временные; не храните их как постоянные. ## `POST /api/integrations/Tasks/Queue` Тело: [`QueuedApiTaskCommandsCollectionModel`](#queuedapitaskcommandscollectionmodel). Ответ: [`EnqueueApiTasksResponseModel`](#enqueueapitasksresponsemodel). Необязательный заголовок: | Заголовок | Ограничение | Назначение | |---|---|---| | `Idempotency-Key` | До 100 символов | Возвращает те же задачи при повторе в течение 24 часов | Поддерживаются только комбинации `Write/Read/ReadQuery` для `Bid`, перечисленные в разделе [Асинхронная очередь](../async-queue.md). `Write` использует тот же контракт, что `Bids/Apply`. `ReadQuery` эквивалентен `Bids/GetList` без `X-Organization-Id`. Успешная постановка возвращает сведения о созданных задачах и их `id`. Для каждой команды может быть `status="Success"` или `status="Failed"`. ## `GET /api/integrations/Tasks/Queue` | Параметр | Тип | Обязательно | Описание | |---|---|---:|---| | `id` | int64 | Да | ID задачи текущего интеграционного клиента | Успех: [`QueuedApiTaskGetResultsModel`](#queuedapitaskgetresultsmodel). Пока задача выполняется, ответ содержит `Retry-After`. ## `POST /api/integrations/Tasks/Ping` Не принимает тело. Отправляет тестовый подписанный webhook на настроенный callback и возвращает результат доставки. ## Общие HTTP-коды | Код | Значение | |---:|---| | `200` | Успешное чтение или синхронная команда | | `202` | Асинхронная команда принята в обработку; фактическое поведение постановки задач | | `400` | Ошибка формата, валидации или бизнес-правила | | `401` | Токен отсутствует, недействителен или истёк | | `403` | Нет доступа к операции или организации | | `404` | Заявка не существует или недоступна текущему партнёру | | `429` | Превышена допустимая частота запросов | ## Дополнительные интеграционные методы Методы `Organizations/GetClients`, `Organizations/MarkClientPaid` и `Drivers/ConfirmAuthorization` относятся к привлечению клиентов и подтверждению авторизации водителей, а не к основному сценарию обмена заявками. Их нельзя включать в реализацию партнёра без отдельного согласования бизнес-сценария и прав с CARGO.RUN. --- # Модели запросов и ответов Колонка «Обязательно» отражает контракт партнёрского API с учётом бизнес-валидации конкретных операций. Все enum в JSON передаются строковыми значениями из раздела «Возможные значения полей». ## Результаты операций ### `ClientCredentialsTokenResponse` | Поле | Тип | Обязательно | `null` | Описание | |---|---|---:|---:|---| | `accessToken` | `AccessToken` | Да | Нет | Токен доступа и срок действия | ### `AccessToken` | Поле | Тип | Обязательно | `null` | Описание | |---|---|---:|---:|---| | `token` | `string` | Да | Нет | JWT для заголовка `Authorization` | | `expiresIn` | `int32` | Да | Нет | Срок действия в секундах | ### `ApplyBidResultModel` | Поле | Тип | Обязательно | `null` | Описание | |---|---|---:|---:|---| | `id` | `int64` | Да | Нет | ID созданной или обновлённой заявки CARGO.RUN | | `isRouteBuilt` | `boolean` | Да | Нет | Маршрут успешно построен | ### `OrganizationApplyResult` | Поле | Тип | Обязательно | `null` | Описание | |---|---|---:|---:|---| | `id` | `int64` | Да | Нет | ID созданной или найденной организации | ### `EnqueueApiTasksResponseModel` | Поле | Тип | Обязательно | `null` | Описание | |---|---|---:|---:|---| | `latencyMsec` | `int32` | Да | Нет | Оценка задержки очереди в миллисекундах | | `enqueuedInMsec` | `int32` | Да | Нет | Время постановки команд в миллисекундах | | `commands` | `EnqueuedApiTaskResponseModel[]` | Да | Нет | Результат постановки каждой команды | ### `EnqueuedApiTaskResponseModel` | Поле | Тип | Обязательно | `null` | Описание | |---|---|---:|---:|---| | `id` | `int64` | Нет | Да | ID задачи; отсутствует, если команда не поставлена | | `action` | `QueuedApiTaskAction` | Да | Нет | Действие задачи | | `status` | `QueuedApiTaskEnqueueStatus` | Да | Нет | Результат постановки | | `readyInMsec` | `int64` | Да | Нет | Ориентировочная задержка до готовности | | `message` | `string` | Нет | Да | Причина отказа в постановке | ### `QueuedApiTaskEnqueueStatus` Возможные результаты постановки команды перечислены в разделе «Возможные значения полей». ### `QueuedApiTaskCallbackPayload` | Поле | Тип | Обязательно | `null` | Описание | |---|---|---:|---:|---| | `eventId` | `uuid` | Да | Нет | Уникальный ID события для дедупликации | | `taskId` | `int64` | Да | Нет | ID задачи | | `action` | `QueuedApiTaskAction` | Да | Нет | Действие задачи | | `status` | `QueuedApiTaskStatus` | Да | Нет | Статус задачи | | `origin` | `QueuedApiTaskOrigin` | Да | Нет | Запрос партнёра или подписка | | `completedAt` | `date-time` | Нет | Да | Время завершения | | `attemptCount` | `int32` | Да | Нет | Число попыток обработки задачи | | `maxAttemptCount` | `int32` | Да | Нет | Максимум попыток обработки | | `message` | `string` | Нет | Да | Сообщение задачи | | `objects` | `QueuedApiTaskObjectResultModel[]` | Нет | Да | Результаты объектов | ## Основные модели запросов и ответов ### `ClientCredentialsTokenModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `grantType` | `string` | Да | Нет | значение: `client_credentials` | Тип выдачи токена. Передавайте фиксированное значение `client_credentials`. | | `clientId` | `string` | Да | Нет | — | Идентификатор интеграционного клиента, выданный CARGO.RUN. | | `clientSecret` | `string` | Да | Нет | — | Секрет интеграционного клиента, выданный CARGO.RUN. | ### `IntegrationOrganizationCheckModel` Результат проверки доступности организации для партнёрского сервиса. | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `exists` | `boolean` | Да | Нет | — | Организация с указанным ИНН существует. | | `canCreateBids` | `boolean` | Да | Нет | — | Для организации разрешено создавать заявки партнёрским сервисам. | | `hasAccess` | `boolean` | Да | Нет | — | Текущий партнёрский сервис уже имеет доступ к организации. | ### `CreateIntegrationOrganizationContext` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `name` | `string` | Да | Нет | — | Название организации. | | `inn` | `string` | Да | Нет | — | ИНН организации. | | `kpp` | `string` | Нет | Да | — | КПП | | `ogrn` | `string` | Нет | Да | — | ОГРН | ### `ApplyBidFromIntegrationContext` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `bid` | `IntegrationBidEditModel` | Да | Нет | — | Данные заявки. | | `inn` | `string` | Да | Нет | — | ИНН организации перевозчика: 10 цифр для организации или 12 цифр для ИП. Обязателен при синхронном и асинхронном создании или обновлении заявки. | ### `IntegrationBidEditModel` Данные заявки, полученные от партнёрского сервиса. | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Нет | Нет | — | Внутренний идентификатор заявки CARGO.RUN. Не указывается при создании. При обновлении используется, если поиск по `externalId` не нашёл заявку; найденная по `externalId` заявка имеет приоритет. | | `externalId` | `string` | Нет | Да | max length: `72` | Идентификатор заявки в партнёрском сервисе. | | `comment` | `string` | Нет | Да | max length: `4096` | Комментарий. | | `clientBidNumber` | `string` | Нет | Да | max length: `256` | Номер заявки клиента. | | `clientBidDate` | `date-time` | Нет | Да | — | Дата заявки клиента. | | `price` | `double` | Нет | Да | min: `0`; max: `9999999999` | Стоимость перевозки.
Если не указана, заявка создаётся как заявка на порожний пробег. | | `isVatTop` | `boolean` | Нет | Да | — | НДС начисляется сверху. | | `vat` | `string` | Нет | Да | — | Ставка НДС: текст должен содержать 0, 10, 20 или 22.
Обязательна, если указана стоимость перевозки. | | `bidPoints` | `IntegrationBidPointModel[]` | Да | Нет | min items: `2` | Точки маршрута: минимум одна точка погрузки и одна точка выгрузки. CARGO.RUN сортирует точки по `planEnterDate`. | | `cargos` | `CargoModel[]` | Да | Нет | — | Грузы. Передайте как минимум один груз; у каждого груза обязательно поле `name`. | | `car` | `IntegrationVehicleModel` | Да | Нет | — | ТС. | | `trailer` | `IntegrationVehicleModel` | Нет | Нет | — | Прицеп. Необязателен; если объект передан, поле `number` обязательно. | | `driver` | `IntegrationDriverModel` | Да | Нет | — | Водитель. | | `secondaryDriver` | `IntegrationDriverModel` | Нет | Нет | — | Второй водитель. | | `counterparty` | `IntegrationCounterpartyModel` | Нет | Нет | — | Заказчик перевозки. Если передан, `name` обязателен. Контрагент ищется в организации по ИНН, а без ИНН — по наименованию без учёта регистра; при отсутствии создаётся. | | `temperatureRegime` | `IntegrationTemperatureRegimeModel` | Нет | Нет | — | Температурный режим перевозки, °C. Если объект передан, обязательны обе границы. | | `vehicleType` | `IntegrationVehicleTypeModel` | Нет | Нет | — | Тип и вместимость ТС. Значения записываются в прицеп, а при его отсутствии — в автомобиль. | ### `IntegrationCounterpartyModel` Контрагент во внешней заявке. | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `name` | `string` | Да | Нет | max length: `256` | Наименование контрагента. | | `inn` | `string` | Нет | Да | 10 или 12 цифр | ИНН организации или ИП. | ### `IntegrationTemperatureRegimeModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `minimum` | `float` | Да | Нет | от `-30` до `30` | Минимальная температура, °C; должна быть меньше `maximum`. | | `maximum` | `float` | Да | Нет | от `-30` до `30` | Максимальная температура, °C; должна быть больше `minimum`. | ### `IntegrationVehicleTypeModel` Хотя бы одно из полей `name`, `tonnage` и `volume` должно быть заполнено. | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `name` | `string` | Нет | Да | max length: `128` | Тип ТС, например `Рефрижератор`. | | `tonnage` | `double` | Нет | Да | `> 0` | Грузоподъёмность, т. | | `volume` | `double` | Нет | Да | `> 0` | Объём кузова, м³. | ### `IntegrationBidListModel` Краткие данные заявки, созданной партнёрским сервисом или транслируемой ему перевозчиком. | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | Идентификатор заявки Cargo.Run. | | `externalId` | `string` | Нет | Да | — | Для собственной заявки — идентификатор, переданный партнёром при создании; для транслируемой — идентификатор заказа, указанный перевозчиком для платформы партнёра. | | `isCreatedByPlatform` | `boolean` | Да | Нет | — | `true`, если заявку создал текущий партнёр; `false`, если перевозчик транслирует её платформе. | | `status` | `BidStatus` | Да | Нет | — | Статус заявки BidStatus | | `isDeleted` | `boolean` | Да | Нет | — | Заявка удалена. Данные удалённой заявки не читаются, партнёрскому сервису следует прекратить её отслеживание | | `createdAt` | `date-time` | Да | Нет | — | Дата создания в часовом поясе организации | | `updatedAt` | `date-time` | Да | Нет | — | Дата последнего изменения заявки. Для курсорной выборки используйте `$filter=updatedAt gt {курсор}&$orderby=updatedAt,id` и небольшое перекрытие интервалов. Пересчёт `points[].estimatedEnterDate` не изменяет это поле. | | `points` | `IntegrationBidListPointModel[]` | Да | Нет | — | Несервисные точки маршрута в порядке следования. Даты представлены в часовом поясе точки. | | `events` | `IntegrationBidEventModel[]` | Да | Нет | — | События заявки и несервисных точек. Не участвуют в `$filter` и `$orderby`. | ### `IntegrationBidListPointModel` Точка маршрута в объединённом списке заявок. Сервисные точки в массив не включаются. | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | ID точки CARGO.RUN; совпадает с `bidPointId` связанного события. | | `order` | `int32` | Да | Нет | — | Порядок точки в маршруте. | | `externalId` | `string` | Нет | Да | — | Идентификатор точки в партнёрском сервисе. | | `type` | `BidPointType` | Да | Нет | — | Тип точки. | | `planEnterDate` | `date-time` | Да | Нет | — | Плановое время прибытия в часовом поясе точки. | | `estimatedEnterDate` | `date-time` | Нет | Да | — | Расчётное время прибытия в часовом поясе точки. Может меняться без изменения `updatedAt` заявки. | | `loadUnloadStatus` | `BidPointLoadUnloadStatus` | Нет | Да | — | Статус погрузки или выгрузки. | | `enteredAt` | `date-time` | Нет | Да | — | Время прибытия, отмеченное водителем, в часовом поясе точки. | | `loadUnloadedAt` | `date-time` | Нет | Да | — | Время погрузки или выгрузки, отмеченное водителем, в часовом поясе точки. | | `documentsReceivedAt` | `date-time` | Нет | Да | — | Время получения документов, отмеченное водителем, в часовом поясе точки. | ### `BidForExternalSyncModel` Модель заявки для синхронизации с внешними сервисами | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `price` | `double` | Нет | Да | — | Цена | | `priceWithoutVatOnTop` | `double` | Нет | Да | — | Цена без НДС. Будет null, если isVatTop = false | | `status` | `BidStatus` | Да | Нет | — | Статус заявки | | `createdAt` | `date-time` | Да | Нет | — | Дата создания заявки | | `externalUpdatedAt` | `date-time` | Нет | Да | — | Дата обновления из внешней системы | | `acceptedByDriverForwarderAt` | `date-time` | Нет | Да | — | Дата принятия водителем-экспедитором | | `hasFactoring` | `boolean` | Да | Нет | — | Заявка отправлена на факторинг? | | `createdById` | `int64` | Да | Нет | — | Идентификатор пользователя, кто создал заявку | | `paymentTypeId` | `int64` | Нет | Да | — | Идентификатор Типа оплаты | | `ndsTypeId` | `int64` | Нет | Да | — | Идентификатор Типа ндс | | `isVatTop` | `boolean` | Да | Нет | — | НДС сверху | | `counterpartyId` | `int64` | Нет | Да | — | Контрагент | | `contractId` | `int64` | Нет | Да | — | Договор контрагента | | `isEmptyMileageBid` | `boolean` | Да | Нет | — | Порожняя заявка? | | `driverId` | `int64` | Нет | Да | — | Текущий водитель заявки | | `isDriverForwarder` | `boolean` | Да | Нет | — | Является ли водитель экспедитором? | | `secondaryDriverId` | `int64` | Нет | Да | — | Второй водитель заявки | | `approvedById` | `int64` | Нет | Да | — | Идентификатор пользователя-оператора, который согласовал заявку
(используется если у организации включен модуль согласования заявок) | | `approvedAt` | `date-time` | Нет | Да | — | Дата согласования оператором (используется если у организации включен модуль согласования заявок) | | `responsibleId` | `int64` | Нет | Да | — | Идентификатор ответственного | | `salesManagerId` | `int64` | Нет | Да | — | Идентификатор менеджера по продажам | | `carLogistId` | `int64` | Нет | Да | — | Идентификатор логиста, который был привязан к машине на момент создания заявки | | `distributionBidId` | `int64` | Нет | Да | — | Идентификатор заказа, из которого создана эта заявка | | `routeId` | `int64` | Нет | Да | — | Идентификатор маршрута | | `planMileage` | `double` | Да | Нет | — | Плановый пробег (метры) | | `factMileage` | `double` | Да | Нет | — | Фактический пробег (метры) | | `planEmptyMileageBefore` | `double` | Да | Нет | — | Плановый порожний пробег до текущей заявки от предыдущей (метры) | | `factEmptyMileageBefore` | `double` | Да | Нет | — | Фактический порожний пробег до первой точки текущей заявки, включая пробег предыдущей порожней заявки (метры) | | `factEmptyMileageFromStartPoint` | `double` | Да | Нет | — | Фактический порожний пробег внутри заявки. Включает в себя пробег от нулевой до первой точки текущей заявки (метры) | | `factEmptyOdometerMileageBefore` | `double` | Да | Нет | — | Фактический порожний пробег по одометру до первой точки текущей заявки, включая пробег предыдущей порожней заявки (метры) | | `factEmptyOdometerMileageFromStartPoint` | `double` | Да | Нет | — | Фактический порожний пробег по одометру внутри заявки. Включает в себя пробег от нулевой до первой точки текущей заявки (метры) | | `updatedAt` | `date-time` | Да | Нет | — | Дата обновления | | `car` | `CarSimpleModel` | Нет | Нет | — | Машина | | `trailer` | `TrailerListViewModel` | Нет | Нет | — | Прицеп | | `legalPerson` | `IdNameModel` | Нет | Нет | — | Юр. лицо | | `estimation` | `BidEstimationModel` | Нет | Нет | — | Расчетная информация | | `bidPointLoadUnloadStatus` | `BidPointLoadUnloadStatus` | Нет | Да | — | — | | `bidPoints` | `BidPointViewModel[]` | Нет | Да | — | Точки загрузки | | `cargos` | `CargoModel[]` | Нет | Да | — | Грузы | | `typeOptions` | `TypeOptionModel[]` | Нет | Да | — | Дополнительные опции типов для заявки | | `temperatureRegime` | `BidTemperatureRegimeModel` | Нет | Нет | — | Температурный режим заявки | | `temperature` | `TemperatureValueModel` | Нет | Нет | — | Текущая информация о температуре | | `isInternational` | `boolean` | Да | Нет | — | — | | `documents` | `RelatedDocumentModel[]` | Нет | Да | — | Список документов | | `extendedProperties` | `PropertyNameValueJsonObject[]` | Нет | Да | — | Дополнительные поля заявки | | `externalId` | `string` | Нет | Да | — | — | | `contractNumber` | `string` | Нет | Да | — | Номер договора | | `comment` | `string` | Нет | Да | — | Комментарий | | `clientBidNumber` | `string` | Нет | Да | — | Номер заявки клиента | | `clientBidDate` | `date-time` | Нет | Да | — | Дата заявки клиента | | `paymentPeriodInDays` | `int32` | Нет | Да | — | Срок оплаты в днях | | `paymentPeriodType` | `PaymentPeriodType` | Нет | Да | — | — | | `invoiceTriggerType` | `InvoiceTriggerType` | Нет | Да | — | — | | `sourceType` | `SourceType` | Да | Нет | — | Источник заявки в CARGO.RUN. Поле возвращается сервером; партнёр его не задаёт. | | `acceptedByDriverAt` | `date-time` | Нет | Да | — | Дата принятия заявки водителем | | `hasItemsChange` | `boolean` | Да | Нет | — | true если есть перецепка/пересменка | | `isDeleted` | `boolean` | Да | Нет | — | Является ли сущность удаленной? | | `createDocumentAssignment` | `boolean` | Да | Нет | — | Нужно ли создавать задание сдачи документов водителю после завершения заявки? | | `hasServicePoints` | `boolean` | Да | Нет | — | true если есть точки сервисных работ | | `isPreBid` | `boolean` | Да | Нет | — | Предзаявка | | `payment` | `BidPaymentGetModel` | Нет | Нет | — | Информация об оплате заявки | | `accessPermitIds` | `int64[]` | Нет | Да | — | Допуски и разрешения | ### `IntegrationBidDetailsModel` Все данные заявки для партнёрского сервиса одним телом. Возвращается при чтении заявки через очередь заданий (Read). Фактический маршрут не включается из-за объёма, он доступен методом Bids/GetActualRoute. | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `externalId` | `string` | Нет | Да | — | Идентификатор заявки на стороне партнёрского сервиса: внешний идентификатор для собственных заявок
или идентификатор заказа в партнёрском сервисе для транслируемых. | | `bid` | `IntegrationBidDetailsModel.bid` | Нет | Нет | — | Модель заявки для синхронизации с внешними сервисами | | `plannedRoute` | `IntegrationBidDetailsModel.plannedRoute` | Нет | Нет | — | — | | `events` | `IntegrationBidDetailsModel.events[]` | Нет | Да | — | События по заявке, вычисленные из фактических дат, как в методе Bids/GetEvents. | | `driverMessages` | `IntegrationBidDetailsModel.driverMessages[]` | Нет | Да | — | Сокращённые сообщения водителя. Поля `type` и `flags` доступны только в синхронной модели `ChatMessageGetModel`. | ### `IntegrationBidEventModel` Событие по заявке, вычисленное из фактических дат заявки и ее точек. | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `type` | `IntegrationBidEventType` | Да | Нет | — | Тип события. | | `fixedAt` | `date-time` | Да | Нет | — | Дата события. | | `bidPointId` | `int64` | Нет | Да | — | Идентификатор точки заявки, если событие относится к точке. | | `bidPointOrder` | `int32` | Нет | Да | — | Порядок точки в маршруте. | | `bidPointExternalId` | `string` | Нет | Да | — | Идентификатор точки в партнёрском сервисе, если событие относится к точке. | ### `RouteSimpleModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `distance` | `double` | Да | Нет | — | Дистанция маршрута в метрах | | `duration` | `double` | Да | Нет | — | Продолжительность маршрута в секундах | | `distanceWithoutEmptyMileage` | `double` | Да | Нет | — | Дистанция маршрута от первой точки до последней, в метрах | | `emptyMileageDistance` | `double` | Да | Нет | — | Дистанция маршрута от нулевой точки до первой точки, в метрах | | `durationWithoutEmptyMileage` | `double` | Да | Нет | — | Продолжительность маршрута от первой точки до последней, в секундах | | `routeOptions` | `RouteOptions` | Нет | Нет | — | Опции графхоппера | ### `CarRouteForExternalModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `emptyMileageRoute` | `TraveledRouteFixedAtPartModel[]` | Нет | Да | — | Пройденный маршрут от точки 0 до точки А (координаты + время фиксации) | | `mainRoute` | `TraveledRouteFixedAtPartModel[]` | Нет | Да | — | Пройденный маршрут от точки А до конца маршрута (координаты + время фиксации) | | `carId` | `int64` | Да | Нет | — | Идентификатор машины | | `carNumber` | `string` | Нет | Да | — | Номер машины | | `hasActiveMileage` | `boolean` | Да | Нет | — | У заявки есть активный пробег (заехала в первую точку по заявке) | | `isMobile` | `boolean` | Да | Нет | — | Данная часть маршрута построена из мобильных координат | ### `ChatMessageGetModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `text` | `string` | Нет | Да | — | Текст | | `createdAt` | `date-time` | Да | Нет | — | Дата написания | | `chatId` | `int64` | Да | Нет | — | — | | `createdById` | `int64` | Нет | Да | — | — | | `fileId` | `int64` | Нет | Да | — | Устаревшее поле. В новой интеграции используйте `files[]`. | | `fileIds` | `int64[]` | Нет | Да | — | Устаревшее поле. В новой интеграции используйте `files[]`. | | `file` | `FileModel` | Нет | Нет | — | Устаревшее поле. В новой интеграции используйте `files[]`. | | `createdBy` | `UserChatModel` | Нет | Нет | — | Профиль того, кто написал сообщение | | `isDeleted` | `boolean` | Да | Нет | — | — | | `userMessagesInfo` | `UserMessageInfoModel[]` | Нет | Да | — | — | | `files` | `FileModel[]` | Нет | Да | — | Авторитетный список файлов сообщения для новой интеграции. | | `type` | `UserMessageType` | Нет | Нет | — | — | ### `QueuedApiTaskCommandsCollectionModel` Коллекция команд на выполнение | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `commands` | `QueuedApiTaskAddCommandsModel[]` | Нет | Да | — | Команды | ### `QueuedApiTaskAddCommandsModel` Модель задания с указанным типом действия и объектами | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `action` | `QueuedApiTaskAction` | Да | Нет | — | Действие | | `objects` | `QueuedApiTaskObjectAddModel[]` | Нет | Да | — | Объекты | ### `QueuedApiTaskObjectAddModel` Модель объекта задания со статусом | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `modelType` | `QueuedApiTaskModelType` | Да | Нет | — | Тип модели объекта | | `status` | `QueuedApiTaskObjectStatusJson` | Нет | Нет | — | Диагностический статус. В документированных партнёрских командах не передаётся. | | `body` | `JsonObject` | Нет | Нет | — | Тело объекта. Обязательно для `action=Write`; для `Read` и `ReadQuery` не передаётся. | | `key` | `string` | Нет | Да | — | Внешний ключ объекта | | `type` | `InternalEntityType` | Да | Нет | — | Тип объекта | | `sourceType` | `SourceType` | Нет | Да | — | Служебное поле. В документированных партнёрских командах не передаётся. | | `id` | `int64` | Нет | Да | — | Внутренний идентификатор объекта, если null или 0, то будет создан новый объект | | `version` | `uuid` | Нет | Да | — | Версия объекта. Если указано `id`, а `version` не передан, проверка версии не выполняется. | | `query` | `string` | Нет | Да | — | OData-запрос для `ReadQuery`. При его использовании поля `id`, `version` и `key` не передаются. | ### `QueuedApiTaskGetResultsModel` Модель для получения результатов | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `message` | `string` | Нет | Да | — | Сообщение | | `status` | `QueuedApiTaskStatus` | Да | Нет | — | Статус задания | | `origin` | `QueuedApiTaskOrigin` | Да | Нет | — | Источник задания: запрос клиента или подписка на изменения | | `readyInMsec` | `int64` | Да | Нет | — | Примерное время, через которое можно будет получить результат | | `remainingObjectCount` | `int32` | Да | Нет | — | Оставшееся количество объектов на выполнение | | `attemptCount` | `int32` | Да | Нет | — | Текущая попытка обработки | | `maxAttemptCount` | `int32` | Да | Нет | — | Максимально допустимое количество попыток | | `nextRetryAt` | `date-time` | Нет | Да | — | Следующее запланированное время повтора | | `callbackStatus` | `QueuedApiTaskCallbackStatus` | Да | Нет | — | Статус доставки webhook | | `callbackAttemptCount` | `int32` | Да | Нет | — | Текущая попытка доставки задачи | | `callbackMaxAttemptCount` | `int32` | Да | Нет | — | Максимально допустимое количество попыток доставки | | `callbackNextRetryAt` | `date-time` | Нет | Да | — | Следующее запланированное время повтора доставки | | `callbackDeliveredAt` | `date-time` | Нет | Да | — | Дата успешной доставки | | `lastError` | `string` | Нет | Да | — | Последняя ошибка доставки | | `objects` | `QueuedApiTaskObjectResultModel[]` | Нет | Да | — | Объекты | ### `QueuedApiTaskObjectResultModel` Модель для элемента объекта при получении сформированных данных | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `message` | `string` | Нет | Да | — | Сообщение | | `status` | `QueuedApiTaskObjectResultStatus` | Да | Нет | — | Статус | | `body` | `JsonObject` | Нет | Нет | — | Данные | | `key` | `string` | Нет | Да | — | Внешний ключ объекта | | `type` | `InternalEntityType` | Да | Нет | — | Тип объекта | | `sourceType` | `SourceType` | Нет | Да | — | — | | `id` | `int64` | Нет | Да | — | Внутренний идентификатор обработанного объекта CARGO.RUN. | | `version` | `uuid` | Нет | Да | — | Версия объекта. Если указано `id`, а `version` отсутствует, проверка версии не выполнялась. | | `query` | `string` | Нет | Да | — | OData-запрос задачи `ReadQuery`; поля `id`, `version` и `key` для такой задачи отсутствуют. | ## Связанные модели ### `AverageAxisLoadValueModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `averageValue` | `double` | Нет | Да | — | Среднее значение | ### `AvoidSpecialRoadFlags` Схема не содержит именованных полей. ### `AvoidTollRoadFlags` Схема не содержит именованных полей. ### `BidEstimationModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `estimatedDate` | `date-time` | Нет | Да | — | Расчётная дата въезда | | `manualEstimatedLeaveDate` | `date-time` | Нет | Да | — | Ручная дата выезда из точки | ### `BidPaymentGetModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `documentsTrackingStatus` | `DocumentsTrackingStatus` | Нет | Да | — | — | | `plannedArrivalDate` | `date` | Нет | Да | — | — | | `documentsReceiptDate` | `date` | Нет | Да | — | — | | `invoiceDate` | `date` | Нет | Да | — | — | | `planPaymentDate` | `date` | Нет | Да | — | — | | `factPaymentDate` | `date` | Нет | Да | — | — | | `paymentStatus` | `BidPaymentStatus` | Да | Нет | — | — | | `isPaymentOverdue` | `boolean` | Да | Нет | — | — | | `remainingPayment` | `double` | Нет | Да | — | — | | `comment` | `string` | Нет | Да | — | — | | `updatedAt` | `date-time` | Да | Нет | — | — | ### `BidPaymentStatus` Схема не содержит именованных полей. ### `BidPointLoadUnloadStatus` Схема не содержит именованных полей. ### `BidPointType` Схема не содержит именованных полей. ### `BidPointViewModel` Точка маршрута | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `order` | `int32` | Да | Нет | — | Порядок точки | | `type` | `BidPointType` | Да | Нет | — | Тип точки | | `counterpartyPointId` | `int64` | Нет | Да | — | — | | `customPointTypeId` | `int64` | Нет | Да | — | — | | `enteredAt` | `date-time` | Нет | Да | — | Дата въезда в геозону от водителя | | `loadUnloadedAt` | `date-time` | Нет | Да | — | Дата загрузки/выгрузки от водителя | | `documentsReceivedAt` | `date-time` | Нет | Да | — | Дата получения документов, от водителя | | `autoEnteredAt` | `date-time` | Нет | Да | — | Автоматическая дата въезда в точку | | `autoLeavedAt` | `date-time` | Нет | Да | — | Автоматическая дата выезда из точки | | `enteredAtByLogist` | `date-time` | Нет | Да | — | Дата въезда в точку, проставленная логистом | | `loadUnloadedAtByLogist` | `date-time` | Нет | Да | — | Дата выгрузки/выезда из точки, проставленная логистом | | `axisLoadAfterLeaving` | `AverageAxisLoadValueModel` | Нет | Нет | — | Нагрузка на ось после выезда из точки | | `servicePoint` | `ServicePointViewModel` | Нет | Нет | — | Точка сервисных работ | | `scenarioId` | `int64` | Нет | Да | — | Сценарий для водителя | | `planDistance` | `double` | Нет | Да | — | Плановое расстояние от предыдущей точки до текущей (метры) | | `factDistance` | `double` | Нет | Да | — | Фактическое расстояние от предыдущей точки до текущей (метры) | | `intOptions` | `int32` | Нет | Да | — | Опции точки | | `client` | `string` | Нет | Да | — | — | | `comment` | `string` | Нет | Да | — | Комментарий к точке | | `externalId` | `string` | Нет | Да | — | Внешний ид точки | | `externalCity` | `string` | Нет | Да | — | Город для внешних систем | | `planEnterDate` | `date-time` | Да | Нет | — | Плановая локальная дата загрузки/выгрузки (по местному времени адреса точки). | | `planEnterDateOffset` | `date-time` | Да | Нет | — | Плановая дата загрузки/выгрузки, вычисленная по плановой локальной дате, учитывая часовой пояс точки. | | `planLeaveDateOffset` | `date-time` | Нет | Да | — | Плановая дата выезда. Если модуль планирования включен, вычисляется как плановая дата въезда + X часов. | | `secondaryPlanEnterDate` | `date-time` | Нет | Да | — | Вторая плановая дата въезда | | `secondaryPlanEnterDateOffset` | `date-time` | Нет | Да | — | Вторая плановая дата загрузки/выгрузки, вычисленная по плановой локальной дате, учитывая часовой пояс точки. | | `planLeaveDate` | `date-time` | Нет | Да | — | Плановая дата выезда | | `createdById` | `int64` | Да | Нет | — | — | | `geozone` | `MapObjectModel` | Нет | Нет | — | Геозона | | `contactPerson` | `ContactPersonModel` | Нет | Нет | — | Контактное лицо | | `counterparty` | `CounterpartyViewModel` | Нет | Нет | — | Контрагент | | `loadOptions` | `IdModel[]` | Нет | Да | — | Типы загрузок/выгрузок на точке | | `typeOptions` | `TypeOptionModel[]` | Нет | Да | — | Дополнительные опции типов для точки | | `extendedProperties` | `PropertyNameValueJsonObject[]` | Нет | Да | — | Дополнительные поля точки заявки | | `customPointType` | `CustomPointTypeModel` | Нет | Нет | — | Тип произвольной точки | ### `BidStatus` Схема не содержит именованных полей. ### `BidTemperatureRegimeModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `temperatureMinimum` | `float` | Нет | Да | — | — | | `temperatureMaximum` | `float` | Нет | Да | — | — | ### `CarSimpleModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `number` | `string` | Нет | Да | — | — | | `typeId` | `int64` | Да | Нет | — | — | | `trackerId` | `int64` | Нет | Да | — | — | ### `CargoModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `name` | `string` | Да | Нет | — | Наименование | | `weight` | `double` | Нет | Да | — | Вес | | `volume` | `double` | Нет | Да | — | Объём | | `length` | `double` | Нет | Да | — | Длина | | `height` | `double` | Нет | Да | — | Высота | | `width` | `double` | Нет | Да | — | Ширина | | `price` | `double` | Нет | Да | — | Стоимость | | `comment` | `string` | Нет | Да | — | Комментарий | | `description` | `string` | Нет | Да | — | Описание | | `typeId` | `int64` | Нет | Да | — | Идентификатор типа Тип груза | | `loadingTypeId` | `int64` | Нет | Да | — | Идентификатор типа Тип загрузки | | `unloadingTypeId` | `int64` | Нет | Да | — | Идентификатор типа Тип выгрузки | | `packType` | `string` | Нет | Да | — | Тип упаковки | | `placesCount` | `int16` | Нет | Да | — | Количество грузовых мест | | `unitOfMeasure` | `UnitOfMeasure` | Нет | Да | — | — | | `extendedProperties` | `PropertyNameValueJsonObject[]` | Нет | Да | — | Дополнительные поля груза заявки | | `typeOptions` | `TypeOptionModel[]` | Нет | Да | — | Дополнительные опции типов для груза | ### `ContactPersonModel` Контактное лицо | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `phoneNumber` | `string` | Нет | Да | — | Номер телефона, если такой контакт был введен ранее, существующие данные будут использованы | | `name` | `string` | Нет | Да | — | Имя | ### `CounterpartyRegistryEntryViewModel` Запись реестра недобросовестных контрагентов | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `inn` | `string` | Нет | Да | — | — | | `ratings` | `CounterpartyRegistryRatingViewModel[]` | Нет | Да | — | — | | `insolvencyRank` | `int32` | Да | Нет | — | — | | `comments` | `string[]` | Нет | Да | — | — | ### `CounterpartyRegistryRatingViewModel` Оценка контрагента в реестре | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `organizationName` | `string` | Нет | Да | — | — | | `comment` | `string` | Нет | Да | — | — | ### `CounterpartyViewModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `name` | `string` | Нет | Да | — | — | | `insolvencyRegistryEntry` | `CounterpartyRegistryEntryViewModel` | Нет | Нет | — | — | ### `CustomPointTypeModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `name` | `string` | Нет | Да | — | — | | `planStayPeriod` | `int32` | Да | Нет | — | Плановое время нахождения на точке (ч) | | `isVisitOptional` | `boolean` | Да | Нет | — | — | ### `DocumentsTrackingStatus` Схема не содержит именованных полей. ### `FileModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `originalFileName` | `string` | Нет | Да | — | — | | `fileName` | `string` | Нет | Да | — | — | | `extension` | `string` | Нет | Да | — | — | | `size` | `int64` | Да | Нет | — | — | | `accessUrlLink` | `string` | Нет | Да | — | — | | `hashsum` | `string` | Нет | Да | — | — | | `mountPoint` | `string` | Нет | Да | — | — | | `relativePath` | `string` | Нет | Да | — | — | | `storageType` | `int32` | Да | Нет | — | — | | `lastAccessedAt` | `date-time` | Нет | Да | — | — | ### `IdModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | ### `IdNameModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `name` | `string` | Нет | Да | — | — | ### `IntegrationBidEventType` Схема не содержит именованных полей. ### `IntegrationBidPointAddressModel` Адрес точки маршрута во внешней заявке. | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `location` | `PointEditModel` | Нет | Да | — | Координаты точки: `[долгота, широта]`. Если не переданы, CARGO.RUN определяет их по адресу. | | `city` | `string` | Нет | Да | — | — | | `address` | `string` | Да | Нет | Непустая строка | Адрес точки; обязателен даже при переданных координатах. | | `village` | `string` | Нет | Да | — | — | | `state` | `string` | Нет | Да | — | — | | `county` | `string` | Нет | Да | — | — | | `street` | `string` | Нет | Да | — | — | | `houseNumber` | `string` | Нет | Да | — | — | | `federalDistrict` | `string` | Нет | Да | — | — | ### `IntegrationBidPointModel` Точка маршрута во внешней заявке. | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `isLoadPoint` | `boolean` | Да | Нет | — | Признак точки погрузки. Если false — точка выгрузки. | | `planEnterDate` | `date-time` | Да | Нет | — | Плановая локальная дата прибытия. | | `planLeaveDate` | `date-time` | Нет | Да | — | Плановая локальная дата выезда. | | `secondaryPlanEnterDate` | `date-time` | Нет | Да | — | Вторая граница диапазона плановой даты прибытия. | | `externalId` | `string` | Нет | Да | max length: `72` | Идентификатор точки в партнёрском сервисе. | | `client` | `string` | Нет | Да | — | Клиент. | | `comment` | `string` | Нет | Да | max length: `8092` | Комментарий. | | `geozone` | `IntegrationBidPointAddressModel` | Да | Нет | — | Адрес и координаты точки. | | `contactPerson` | `IntegrationContactPersonModel` | Нет | Нет | — | Контактное лицо. | ### `IntegrationContactPersonModel` Контактное лицо точки маршрута. | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `phoneNumber` | `string` | Нет | Да | — | Номер телефона. | | `name` | `string` | Нет | Да | — | Имя. | ### `IntegrationDriverModel` Водитель во внешней заявке. | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `firstName` | `string` | Нет | Да | — | Имя. | | `lastName` | `string` | Нет | Да | — | Фамилия. | | `patronymic` | `string` | Нет | Да | — | Отчество. | | `phoneNumber` | `string` | Да | Да | — | Номер телефона. | ### `IntegrationVehicleModel` Транспортное средство во внешней заявке. | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `number` | `string` | Да | Да | — | Государственный номер. | | `brandName` | `string` | Нет | Да | — | Марка транспортного средства. | ### `InternalEntityType` Тип внутренней сущности Схема не содержит именованных полей. ### `InvoiceTriggerType` Схема не содержит именованных полей. ### `JsonObject` Схема не содержит именованных полей. ### `MapObjectModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `city` | `string` | Нет | Да | — | — | | `address` | `string` | Нет | Да | — | — | | `village` | `string` | Нет | Да | — | — | | `state` | `string` | Нет | Да | — | — | | `county` | `string` | Нет | Да | — | — | | `street` | `string` | Нет | Да | — | — | | `houseNumber` | `string` | Нет | Да | — | — | | `federalDistrict` | `string` | Нет | Да | — | — | | `radius` | `double` | Нет | Да | — | — | | `type` | `MapObjectType` | Да | Нет | — | — | | `coordinates` | `double[][]` | Нет | Нет | min items: `3` | Координаты полигона как массив точек: [[долгота, широта], ...]. | | `location` | `Point` | Да | Нет | — | — | ### `MapObjectType` Схема не содержит именованных полей. ### `PaymentPeriodType` Схема не содержит именованных полей. ### `Point` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `type` | `string` | Нет | Нет | — | Тип геометрии (`Point`). Поле возвращается сервером и не передаётся в `PointEditModel`. | | `coordinates` | `double[]` | Да | Нет | — | Координаты точки в формате `[долгота, широта]`, WGS 84. | ### `PointEditModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `coordinates` | `double[]` | Да | Нет | min items: `2`; max items: `2` | Координаты точки в формате `[долгота, широта]`, WGS 84. | ### `PropertyNameValueJsonObject` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `propertyName` | `string` | Нет | Да | — | — | | `value` | `string` | Нет | Да | — | Строковое значение дополнительного поля. Числа, даты и boolean передаются в строковом представлении. | ### `QueuedApiTaskAction` Схема не содержит именованных полей. ### `QueuedApiTaskCallbackStatus` Схема не содержит именованных полей. ### `QueuedApiTaskModelType` Схема не содержит именованных полей. ### `QueuedApiTaskObjectResultStatus` Статус результата обработки объекта Схема не содержит именованных полей. ### `QueuedApiTaskObjectStatusJson` Статус очереди заданий | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `message` | `string` | Нет | Да | — | — | | `type` | `QueuedApiTaskSyncStatus` | Да | Нет | — | — | ### `QueuedApiTaskOrigin` Источник задания Схема не содержит именованных полей. ### `QueuedApiTaskStatus` Статус очереди заданий Схема не содержит именованных полей. ### `QueuedApiTaskSyncStatus` Статус очереди заданий Схема не содержит именованных полей. ### `RecipientInfoModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `fullName` | `string` | Нет | Да | — | — | | `bidRoles` | `string[]` | Нет | Да | — | — | | `isIntegrationAccount` | `boolean` | Да | Нет | — | — | ### `RelatedDocumentModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `name` | `string` | Нет | Да | — | — | | `count` | `int32` | Да | Нет | — | — | ### `ResourceInactivityInfoJsonObject` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `inactivityReason` | `string` | Нет | Да | — | — | | `inactiveSince` | `date-time` | Да | Нет | — | — | | `inactiveUntil` | `date-time` | Да | Нет | — | — | ### `RouteOptions` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `avoidTollRoadFlags` | `AvoidTollRoadFlags` | Да | Нет | — | — | | `avoidSpecialRoadFlags` | `AvoidSpecialRoadFlags` | Да | Нет | — | — | | `disallowToll` | `boolean` | Да | Нет | — | — | | `disallowTollExceptM4` | `boolean` | Да | Нет | — | — | | `disallowTollExceptM12DRT` | `boolean` | Да | Нет | — | — | | `allowFerry` | `boolean` | Да | Нет | — | — | | `calcTolls` | `boolean` | Да | Нет | — | — | | `country` | `RouterCountryType` | Нет | Да | — | — | | `routerProfile` | `RouterProfile` | Нет | Да | — | — | | `useSpecialProfileForEmptyRoute` | `boolean` | Да | Нет | — | — | ### `RouterCountryType` Схема не содержит именованных полей. ### `RouterProfile` Схема не содержит именованных полей. ### `ServicePointViewModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `serviceStationName` | `string` | Нет | Да | — | Наименование СТО | | `serviceType` | `string` | Нет | Да | — | Тип сервисной работы | | `phoneNumber` | `string` | Нет | Да | — | Cотовый телефон | | `initiator` | `string` | Нет | Да | — | Инициатор | | `withoutCargo` | `boolean` | Да | Нет | — | Опция "Без груза" | | `externalId` | `string` | Нет | Да | — | Идентификатор сервисной работы в Эксплуатации | ### `SourceType` Схема не содержит именованных полей. ### `TemperatureValueModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `values` | `float[]` | Нет | Да | — | Значения | | `fixedAt` | `date-time` | Да | Нет | — | Дата и время фиксации | ### `TrailerListFuelTankModel` Топливный бак прицепа | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `totalVolume` | `double` | Да | Нет | — | Общий объём | | `fuelConsumption` | `double` | Да | Нет | — | Расход топлива | ### `TrailerListViewModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `trackerId` | `int64` | Нет | Да | — | Идентификатор трекера | | `typeId` | `int64` | Нет | Да | — | Тип прицепа. | | `brandTypeId` | `int64` | Нет | Да | — | Марка прицепа. | | `number` | `string` | Нет | Да | — | Номер. | | `trackerDeviceNumber` | `string` | Нет | Да | — | Номер трекера | | `comment` | `string` | Нет | Да | — | — | | `loadUnloadOptions` | `IdModel[]` | Нет | Да | — | Типы загрузки/выгрузки | | `isActive` | `boolean` | Да | Нет | — | Признак активности | | `resourceInactivityInfo` | `ResourceInactivityInfoJsonObject` | Нет | Нет | — | Сведения о неактивности | | `transportColumn` | `IdNameModel` | Нет | Нет | — | Транспортная колонна | | `mechanic` | `IdNameModel` | Нет | Нет | — | Механик | | `isDeleted` | `boolean` | Да | Нет | — | Признак удаления | | `isInRefuelingSyncList` | `boolean` | Да | Нет | — | Участвует в планировании заправок? | | `fuelTank` | `TrailerListFuelTankModel` | Нет | Нет | — | Данные бака | | `lastDieselSensorValueFixedAt` | `date-time` | Нет | Да | — | Время последней фиксации ДУТ | | `accessPermitIds` | `int64[]` | Нет | Да | — | Допуски и разрешения | ### `TraveledRouteFixedAtPartModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `coordinate` | `double[]` | Нет | Да | min items: `2`; max items: `2` | Координата фактического маршрута в формате `[долгота, широта]`, WGS 84. | | `fixedAt` | `date-time` | Да | Нет | — | — | ### `TypeOptionModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | Идентификатор типа | | `entityOptionId` | `int64` | Да | Нет | — | Идентификатор опции сущности | ### `UnitOfMeasure` Схема не содержит именованных полей. ### `UserChatModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `fullName` | `string` | Нет | Да | — | — | ### `UserMessageFlag` Схема не содержит именованных полей. ### `UserMessageInfoModel` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `createdAt` | `date-time` | Да | Нет | — | — | | `readAt` | `date-time` | Нет | Да | — | — | | `isRead` | `boolean` | Да | Нет | — | — | | `isDeleted` | `boolean` | Да | Нет | — | — | | `type` | `UserMessageType` | Да | Нет | — | — | | `flags` | `UserMessageFlag` | Да | Нет | — | — | | `recipient` | `RecipientInfoModel` | Нет | Нет | — | — | ### `UserMessageType` Схема не содержит именованных полей. ## Вложенные модели ### `IntegrationBidDetailsModel.bid` Модель заявки для синхронизации с внешними сервисами | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `price` | `double` | Нет | Да | — | Цена | | `priceWithoutVatOnTop` | `double` | Нет | Да | — | Цена без НДС. Будет null, если isVatTop = false | | `status` | `BidStatus` | Да | Нет | — | — | | `createdAt` | `date-time` | Да | Нет | — | Дата создания заявки | | `externalUpdatedAt` | `date-time` | Нет | Да | — | Дата обновления из внешней системы | | `acceptedByDriverForwarderAt` | `date-time` | Нет | Да | — | Дата принятия водителем-экспедитором | | `hasFactoring` | `boolean` | Да | Нет | — | Заявка отправлена на факторинг? | | `createdById` | `int64` | Да | Нет | — | Идентификатор пользователя, кто создал заявку | | `paymentTypeId` | `int64` | Нет | Да | — | Идентификатор Типа оплаты | | `ndsTypeId` | `int64` | Нет | Да | — | Идентификатор Типа ндс | | `isVatTop` | `boolean` | Да | Нет | — | НДС сверху | | `counterpartyId` | `int64` | Нет | Да | — | Контрагент | | `contractId` | `int64` | Нет | Да | — | Договор контрагента | | `isEmptyMileageBid` | `boolean` | Да | Нет | — | Порожняя заявка? | | `driverId` | `int64` | Нет | Да | — | Текущий водитель заявки | | `isDriverForwarder` | `boolean` | Да | Нет | — | Является ли водитель экспедитором? | | `secondaryDriverId` | `int64` | Нет | Да | — | Второй водитель заявки | | `approvedById` | `int64` | Нет | Да | — | Идентификатор пользователя-оператора, который согласовал заявку
(используется если у организации включен модуль согласования заявок) | | `approvedAt` | `date-time` | Нет | Да | — | Дата согласования оператором (используется если у организации включен модуль согласования заявок) | | `responsibleId` | `int64` | Нет | Да | — | Идентификатор ответственного | | `salesManagerId` | `int64` | Нет | Да | — | Идентификатор менеджера по продажам | | `carLogistId` | `int64` | Нет | Да | — | Идентификатор логиста, который был привязан к машине на момент создания заявки | | `distributionBidId` | `int64` | Нет | Да | — | Идентификатор заказа, из которого создана эта заявка | | `routeId` | `int64` | Нет | Да | — | Идентификатор маршрута | | `planMileage` | `double` | Да | Нет | — | Плановый пробег (метры) | | `factMileage` | `double` | Да | Нет | — | Фактический пробег (метры) | | `planEmptyMileageBefore` | `double` | Да | Нет | — | Плановый порожний пробег до текущей заявки от предыдущей (метры) | | `factEmptyMileageBefore` | `double` | Да | Нет | — | Фактический порожний пробег до первой точки текущей заявки, включая пробег предыдущей порожней заявки (метры) | | `factEmptyMileageFromStartPoint` | `double` | Да | Нет | — | Фактический порожний пробег внутри заявки. Включает в себя пробег от нулевой до первой точки текущей заявки (метры) | | `factEmptyOdometerMileageBefore` | `double` | Да | Нет | — | Фактический порожний пробег по одометру до первой точки текущей заявки, включая пробег предыдущей порожней заявки (метры) | | `factEmptyOdometerMileageFromStartPoint` | `double` | Да | Нет | — | Фактический порожний пробег по одометру внутри заявки. Включает в себя пробег от нулевой до первой точки текущей заявки (метры) | | `updatedAt` | `date-time` | Да | Нет | — | Дата обновления | | `car` | `IntegrationBidDetailsModel.bid.car` | Нет | Нет | — | — | | `trailer` | `IntegrationBidDetailsModel.bid.trailer` | Нет | Нет | — | — | | `legalPerson` | `IntegrationBidDetailsModel.bid.legalPerson` | Нет | Нет | — | — | | `estimation` | `IntegrationBidDetailsModel.bid.estimation` | Нет | Нет | — | — | | `bidPointLoadUnloadStatus` | `BidPointLoadUnloadStatus` | Нет | Нет | — | — | | `bidPoints` | `IntegrationBidDetailsModel.bid.bidPoints[]` | Нет | Да | — | Точки загрузки | | `cargos` | `IntegrationBidDetailsModel.bid.cargos[]` | Нет | Да | — | Грузы | | `typeOptions` | `IntegrationBidDetailsModel.bid.typeOptions[]` | Нет | Да | — | Дополнительные опции типов для заявки | | `temperatureRegime` | `IntegrationBidDetailsModel.bid.temperatureRegime` | Нет | Нет | — | — | | `temperature` | `IntegrationBidDetailsModel.bid.temperature` | Нет | Нет | — | — | | `isInternational` | `boolean` | Да | Нет | — | — | | `documents` | `IntegrationBidDetailsModel.bid.documents[]` | Нет | Да | — | Список документов | | `extendedProperties` | `IntegrationBidDetailsModel.bid.extendedProperties[]` | Нет | Да | — | Дополнительные поля заявки | | `externalId` | `string` | Нет | Да | — | — | | `contractNumber` | `string` | Нет | Да | — | Номер договора | | `comment` | `string` | Нет | Да | — | Комментарий | | `clientBidNumber` | `string` | Нет | Да | — | Номер заявки клиента | | `clientBidDate` | `date-time` | Нет | Да | — | Дата заявки клиента | | `paymentPeriodInDays` | `int32` | Нет | Да | — | Срок оплаты в днях | | `paymentPeriodType` | `PaymentPeriodType` | Нет | Нет | — | — | | `invoiceTriggerType` | `InvoiceTriggerType` | Нет | Нет | — | — | | `sourceType` | `SourceType` | Да | Нет | — | Источник заявки в CARGO.RUN. Поле возвращается сервером; партнёр его не задаёт. | | `acceptedByDriverAt` | `date-time` | Нет | Да | — | Дата принятия заявки водителем | | `hasItemsChange` | `boolean` | Да | Нет | — | true если есть перецепка/пересменка | | `isDeleted` | `boolean` | Да | Нет | — | Является ли сущность удаленной? | | `createDocumentAssignment` | `boolean` | Да | Нет | — | Нужно ли создавать задание сдачи документов водителю после завершения заявки? | | `hasServicePoints` | `boolean` | Да | Нет | — | true если есть точки сервисных работ | | `isPreBid` | `boolean` | Да | Нет | — | Предзаявка | | `payment` | `IntegrationBidDetailsModel.bid.payment` | Нет | Нет | — | — | | `accessPermitIds` | `int64[]` | Нет | Да | — | Допуски и разрешения | ### `IntegrationBidDetailsModel.plannedRoute` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `distance` | `double` | Да | Нет | — | Дистанция маршрута в метрах | | `duration` | `double` | Да | Нет | — | Продолжительность маршрута в секундах | | `distanceWithoutEmptyMileage` | `double` | Да | Нет | — | Дистанция маршрута от первой точки до последней, в метрах | | `emptyMileageDistance` | `double` | Да | Нет | — | Дистанция маршрута от нулевой точки до первой точки, в метрах | | `durationWithoutEmptyMileage` | `double` | Да | Нет | — | Продолжительность маршрута от первой точки до последней, в секундах | | `routeOptions` | `IntegrationBidDetailsModel.plannedRoute.routeOptions` | Нет | Нет | — | — | ### `IntegrationBidDetailsModel.events` Событие по заявке, вычисленное из фактических дат заявки и ее точек. | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `type` | `IntegrationBidEventType` | Да | Нет | — | — | | `fixedAt` | `date-time` | Да | Нет | — | Дата события. | | `bidPointId` | `int64` | Нет | Да | — | Идентификатор точки заявки, если событие относится к точке. | | `bidPointOrder` | `int32` | Нет | Да | — | Порядок точки в маршруте. | ### `IntegrationBidDetailsModel.driverMessages` Сообщение водителя по заявке. | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | Идентификатор сообщения. | | `text` | `string` | Нет | Да | — | Текст сообщения. | | `createdAt` | `date-time` | Да | Нет | — | Дата отправки сообщения. | | `displayName` | `string` | Нет | Да | — | Имя водителя, отправившего сообщение. | | `files` | `IntegrationBidDetailsModel.driverMessages.files[]` | Нет | Да | — | Прикреплённые файлы. | ### `IntegrationBidDetailsModel.bid.car` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `number` | `string` | Нет | Да | — | — | | `typeId` | `int64` | Да | Нет | — | — | | `trackerId` | `int64` | Нет | Да | — | — | ### `IntegrationBidDetailsModel.bid.trailer` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `trackerId` | `int64` | Нет | Да | — | Идентификатор трекера | | `typeId` | `int64` | Нет | Да | — | Тип прицепа. | | `brandTypeId` | `int64` | Нет | Да | — | Марка прицепа. | | `number` | `string` | Нет | Да | — | Номер. | | `trackerDeviceNumber` | `string` | Нет | Да | — | Номер трекера | | `comment` | `string` | Нет | Да | — | — | | `loadUnloadOptions` | `IntegrationBidDetailsModel.bid.trailer.loadUnloadOptions[]` | Нет | Да | — | Типы загрузки/выгрузки | | `isActive` | `boolean` | Да | Нет | — | Признак активности | | `resourceInactivityInfo` | `IntegrationBidDetailsModel.bid.trailer.resourceInactivityInfo` | Нет | Нет | — | — | | `transportColumn` | `IntegrationBidDetailsModel.bid.trailer.transportColumn` | Нет | Нет | — | — | | `mechanic` | `IntegrationBidDetailsModel.bid.trailer.mechanic` | Нет | Нет | — | — | | `isDeleted` | `boolean` | Да | Нет | — | Признак удаления | | `isInRefuelingSyncList` | `boolean` | Да | Нет | — | Участвует в планировании заправок? | | `fuelTank` | `IntegrationBidDetailsModel.bid.trailer.fuelTank` | Нет | Нет | — | Топливный бак прицепа | | `lastDieselSensorValueFixedAt` | `date-time` | Нет | Да | — | Время последней фиксации ДУТ | | `accessPermitIds` | `int64[]` | Нет | Да | — | Допуски и разрешения | ### `IntegrationBidDetailsModel.bid.legalPerson` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `name` | `string` | Нет | Да | — | — | ### `IntegrationBidDetailsModel.bid.estimation` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `estimatedDate` | `date-time` | Нет | Да | — | Расчётная дата въезда | | `manualEstimatedLeaveDate` | `date-time` | Нет | Да | — | Ручная дата выезда из точки | ### `IntegrationBidDetailsModel.bid.bidPoints` Точка маршрута | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `order` | `int32` | Да | Нет | — | Порядок точки | | `type` | `BidPointType` | Да | Нет | — | — | | `counterpartyPointId` | `int64` | Нет | Да | — | — | | `customPointTypeId` | `int64` | Нет | Да | — | — | | `enteredAt` | `date-time` | Нет | Да | — | Дата въезда в геозону от водителя | | `loadUnloadedAt` | `date-time` | Нет | Да | — | Дата загрузки/выгрузки от водителя | | `documentsReceivedAt` | `date-time` | Нет | Да | — | Дата получения документов, от водителя | | `autoEnteredAt` | `date-time` | Нет | Да | — | Автоматическая дата въезда в точку | | `autoLeavedAt` | `date-time` | Нет | Да | — | Автоматическая дата выезда из точки | | `enteredAtByLogist` | `date-time` | Нет | Да | — | Дата въезда в точку, проставленная логистом | | `loadUnloadedAtByLogist` | `date-time` | Нет | Да | — | Дата выгрузки/выезда из точки, проставленная логистом | | `axisLoadAfterLeaving` | `IntegrationBidDetailsModel.bid.bidPoints.axisLoadAfterLeaving` | Нет | Нет | — | — | | `servicePoint` | `IntegrationBidDetailsModel.bid.bidPoints.servicePoint` | Нет | Нет | — | — | | `scenarioId` | `int64` | Нет | Да | — | Сценарий для водителя | | `planDistance` | `double` | Нет | Да | — | Плановое расстояние от предыдущей точки до текущей (метры) | | `factDistance` | `double` | Нет | Да | — | Фактическое расстояние от предыдущей точки до текущей (метры) | | `intOptions` | `int32` | Нет | Да | — | Опции точки | | `client` | `string` | Нет | Да | — | — | | `comment` | `string` | Нет | Да | — | Комментарий к точке | | `externalId` | `string` | Нет | Да | — | Внешний ид точки | | `externalCity` | `string` | Нет | Да | — | Город для внешних систем | | `planEnterDate` | `date-time` | Да | Нет | — | Плановая локальная дата загрузки/выгрузки (по местному времени адреса точки). | | `planEnterDateOffset` | `date-time` | Да | Нет | — | Плановая дата загрузки/выгрузки, вычисленная по плановой локальной дате, учитывая часовой пояс точки. | | `planLeaveDateOffset` | `date-time` | Нет | Да | — | Плановая дата выезда. Если модуль планирования включен, вычисляется как плановая дата въезда + X часов. | | `secondaryPlanEnterDate` | `date-time` | Нет | Да | — | Вторая плановая дата въезда | | `secondaryPlanEnterDateOffset` | `date-time` | Нет | Да | — | Вторая плановая дата загрузки/выгрузки, вычисленная по плановой локальной дате, учитывая часовой пояс точки. | | `planLeaveDate` | `date-time` | Нет | Да | — | Плановая дата выезда | | `createdById` | `int64` | Да | Нет | — | — | | `geozone` | `IntegrationBidDetailsModel.bid.bidPoints.geozone` | Нет | Нет | — | — | | `contactPerson` | `IntegrationBidDetailsModel.bid.bidPoints.contactPerson` | Нет | Нет | — | Контактное лицо | | `counterparty` | `IntegrationBidDetailsModel.bid.bidPoints.counterparty` | Нет | Нет | — | — | | `loadOptions` | `IntegrationBidDetailsModel.bid.bidPoints.loadOptions[]` | Нет | Да | — | Типы загрузок/выгрузок на точке | | `typeOptions` | `IntegrationBidDetailsModel.bid.bidPoints.typeOptions[]` | Нет | Да | — | Дополнительные опции типов для точки | | `extendedProperties` | `IntegrationBidDetailsModel.bid.bidPoints.extendedProperties[]` | Нет | Да | — | Дополнительные поля точки заявки | | `customPointType` | `IntegrationBidDetailsModel.bid.bidPoints.customPointType` | Нет | Нет | — | — | ### `IntegrationBidDetailsModel.bid.cargos` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `name` | `string` | Да | Нет | — | Наименование | | `weight` | `double` | Нет | Да | — | Вес | | `volume` | `double` | Нет | Да | — | Объём | | `length` | `double` | Нет | Да | — | Длина | | `height` | `double` | Нет | Да | — | Высота | | `width` | `double` | Нет | Да | — | Ширина | | `price` | `double` | Нет | Да | — | Стоимость | | `comment` | `string` | Нет | Да | — | Комментарий | | `description` | `string` | Нет | Да | — | Описание | | `typeId` | `int64` | Нет | Да | — | Идентификатор типа Тип груза | | `loadingTypeId` | `int64` | Нет | Да | — | Идентификатор типа Тип загрузки | | `unloadingTypeId` | `int64` | Нет | Да | — | Идентификатор типа Тип выгрузки | | `packType` | `string` | Нет | Да | — | Тип упаковки | | `placesCount` | `int16` | Нет | Да | — | Количество грузовых мест | | `unitOfMeasure` | `UnitOfMeasure` | Нет | Нет | — | — | | `extendedProperties` | `IntegrationBidDetailsModel.bid.cargos.extendedProperties[]` | Нет | Да | — | Дополнительные поля груза заявки | | `typeOptions` | `IntegrationBidDetailsModel.bid.cargos.typeOptions[]` | Нет | Да | — | Дополнительные опции типов для груза | ### `IntegrationBidDetailsModel.bid.typeOptions` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | Идентификатор типа | | `entityOptionId` | `int64` | Да | Нет | — | Идентификатор опции сущности | ### `IntegrationBidDetailsModel.bid.temperatureRegime` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `temperatureMinimum` | `float` | Нет | Да | — | — | | `temperatureMaximum` | `float` | Нет | Да | — | — | ### `IntegrationBidDetailsModel.bid.temperature` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `values` | `float[]` | Нет | Да | — | Значения | | `fixedAt` | `date-time` | Да | Нет | — | Дата и время фиксации | ### `IntegrationBidDetailsModel.bid.documents` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `name` | `string` | Нет | Да | — | — | | `count` | `int32` | Да | Нет | — | — | ### `IntegrationBidDetailsModel.bid.extendedProperties` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `propertyName` | `string` | Нет | Да | — | — | | `value` | `string` | Нет | Да | — | Строковое значение дополнительного поля. Числа, даты и boolean передаются в строковом представлении. | ### `IntegrationBidDetailsModel.bid.payment` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `documentsTrackingStatus` | `DocumentsTrackingStatus` | Нет | Нет | — | — | | `plannedArrivalDate` | `date` | Нет | Да | — | — | | `documentsReceiptDate` | `date` | Нет | Да | — | — | | `invoiceDate` | `date` | Нет | Да | — | — | | `planPaymentDate` | `date` | Нет | Да | — | — | | `factPaymentDate` | `date` | Нет | Да | — | — | | `paymentStatus` | `BidPaymentStatus` | Да | Нет | — | — | | `isPaymentOverdue` | `boolean` | Да | Нет | — | — | | `remainingPayment` | `double` | Нет | Да | — | — | | `comment` | `string` | Нет | Да | — | — | | `updatedAt` | `date-time` | Да | Нет | — | — | ### `IntegrationBidDetailsModel.plannedRoute.routeOptions` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `avoidTollRoadFlags` | `AvoidTollRoadFlags` | Да | Нет | — | — | | `avoidSpecialRoadFlags` | `AvoidSpecialRoadFlags` | Да | Нет | — | — | | `disallowToll` | `boolean` | Да | Нет | — | — | | `disallowTollExceptM4` | `boolean` | Да | Нет | — | — | | `disallowTollExceptM12DRT` | `boolean` | Да | Нет | — | — | | `allowFerry` | `boolean` | Да | Нет | — | — | | `calcTolls` | `boolean` | Да | Нет | — | — | | `country` | `RouterCountryType` | Нет | Нет | — | — | | `routerProfile` | `RouterProfile` | Нет | Нет | — | — | | `useSpecialProfileForEmptyRoute` | `boolean` | Да | Нет | — | — | ### `IntegrationBidDetailsModel.driverMessages.files` Файл для партнёрского сервиса. | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | Идентификатор файла. | | `originalFileName` | `string` | Нет | Да | — | Исходное имя файла. | | `accessUrlLink` | `string` | Нет | Да | — | Временная ссылка для скачивания файла.
Срок действия ссылки ограничен, после его истечения данные нужно прочитать заново. | ### `IntegrationBidDetailsModel.bid.trailer.loadUnloadOptions` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | ### `IntegrationBidDetailsModel.bid.trailer.resourceInactivityInfo` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `inactivityReason` | `string` | Нет | Да | — | — | | `inactiveSince` | `date-time` | Да | Нет | — | — | | `inactiveUntil` | `date-time` | Да | Нет | — | — | ### `IntegrationBidDetailsModel.bid.trailer.transportColumn` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `name` | `string` | Нет | Да | — | — | ### `IntegrationBidDetailsModel.bid.trailer.mechanic` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `name` | `string` | Нет | Да | — | — | ### `IntegrationBidDetailsModel.bid.trailer.fuelTank` Топливный бак прицепа | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `totalVolume` | `double` | Да | Нет | — | Общий объём | | `fuelConsumption` | `double` | Да | Нет | — | Расход топлива | ### `IntegrationBidDetailsModel.bid.bidPoints.axisLoadAfterLeaving` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `averageValue` | `double` | Нет | Да | — | Среднее значение | ### `IntegrationBidDetailsModel.bid.bidPoints.servicePoint` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `serviceStationName` | `string` | Нет | Да | — | Наименование СТО | | `serviceType` | `string` | Нет | Да | — | Тип сервисной работы | | `phoneNumber` | `string` | Нет | Да | — | Cотовый телефон | | `initiator` | `string` | Нет | Да | — | Инициатор | | `withoutCargo` | `boolean` | Да | Нет | — | Опция "Без груза" | | `externalId` | `string` | Нет | Да | — | Идентификатор сервисной работы в Эксплуатации | ### `IntegrationBidDetailsModel.bid.bidPoints.geozone` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `city` | `string` | Нет | Да | — | — | | `address` | `string` | Нет | Да | — | — | | `village` | `string` | Нет | Да | — | — | | `state` | `string` | Нет | Да | — | — | | `county` | `string` | Нет | Да | — | — | | `street` | `string` | Нет | Да | — | — | | `houseNumber` | `string` | Нет | Да | — | — | | `federalDistrict` | `string` | Нет | Да | — | — | | `radius` | `double` | Нет | Да | — | — | | `type` | `MapObjectType` | Да | Нет | — | — | | `coordinates` | `double[][]` | Нет | Нет | min items: `3` | Координаты полигона как массив точек: [[долгота, широта], ...]. | | `location` | `IntegrationBidDetailsModel.bid.bidPoints.geozone.location` | Да | Нет | — | — | ### `IntegrationBidDetailsModel.bid.bidPoints.contactPerson` Контактное лицо | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `phoneNumber` | `string` | Нет | Да | — | Номер телефона, если такой контакт был введен ранее, существующие данные будут использованы | | `name` | `string` | Нет | Да | — | Имя | ### `IntegrationBidDetailsModel.bid.bidPoints.counterparty` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `name` | `string` | Нет | Да | — | — | | `insolvencyRegistryEntry` | `IntegrationBidDetailsModel.bid.bidPoints.counterparty.insolvencyRegistryEntry` | Нет | Нет | — | Запись реестра недобросовестных контрагентов | ### `IntegrationBidDetailsModel.bid.bidPoints.loadOptions` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | ### `IntegrationBidDetailsModel.bid.bidPoints.typeOptions` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | Идентификатор типа | | `entityOptionId` | `int64` | Да | Нет | — | Идентификатор опции сущности | ### `IntegrationBidDetailsModel.bid.bidPoints.extendedProperties` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `propertyName` | `string` | Нет | Да | — | — | | `value` | `string` | Нет | Да | — | Строковое значение дополнительного поля. Числа, даты и boolean передаются в строковом представлении. | ### `IntegrationBidDetailsModel.bid.bidPoints.customPointType` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | — | | `name` | `string` | Нет | Да | — | — | | `planStayPeriod` | `int32` | Да | Нет | — | Плановое время нахождения на точке (ч) | | `isVisitOptional` | `boolean` | Да | Нет | — | — | ### `IntegrationBidDetailsModel.bid.cargos.extendedProperties` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `propertyName` | `string` | Нет | Да | — | — | | `value` | `string` | Нет | Да | — | Строковое значение дополнительного поля. Числа, даты и boolean передаются в строковом представлении. | ### `IntegrationBidDetailsModel.bid.cargos.typeOptions` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `id` | `int64` | Да | Нет | — | Идентификатор типа | | `entityOptionId` | `int64` | Да | Нет | — | Идентификатор опции сущности | ### `IntegrationBidDetailsModel.bid.bidPoints.geozone.location` | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `type` | `string` | Нет | Нет | — | Тип геометрии (`Point`). Поле возвращается сервером. | | `coordinates` | `double[]` | Нет | Нет | — | Координата (долгота, широта) | ### `IntegrationBidDetailsModel.bid.bidPoints.counterparty.insolvencyRegistryEntry` Запись реестра недобросовестных контрагентов | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `inn` | `string` | Нет | Да | — | — | | `ratings` | `IntegrationBidDetailsModel.bid.bidPoints.counterparty.insolvencyRegistryEntry.ratings[]` | Нет | Да | — | — | | `insolvencyRank` | `int32` | Да | Нет | — | — | | `comments` | `string[]` | Нет | Да | — | — | ### `IntegrationBidDetailsModel.bid.bidPoints.counterparty.insolvencyRegistryEntry.ratings` Оценка контрагента в реестре | Поле | Тип | Обязательно | `null` | Ограничения | Описание | |---|---|---:|---:|---|---| | `organizationName` | `string` | Нет | Да | — | — | | `comment` | `string` | Нет | Да | — | — | --- # Возможные значения полей Все enum в запросах, синхронных ответах, результатах очереди и webhook передаются в JSON строковыми именами, указанными в колонке `JSON`. Числовые коды приведены только как справочная информация и не являются wire-форматом API. ## `BidStatus` | JSON | Код в реализации | Значение | |---|---:|---| | `New` | 0 | Черновик | | `Planned` | 5 | Запланирована, но ещё не запущена | | `Started` | 10 | Запущена в работу | | `Canceled` | 20 | Отменена | | `Done` | 30 | Выполнена | ### Жизненный цикл заявки Для заявки, успешно созданной через `Bids/Apply`, основной наблюдаемый путь выглядит так: ```text Started → Done └──→ Canceled ``` `New` означает черновик, `Planned` — запланированную заявку до запуска, `Started` — заявку в работе, `Done` — завершённую, `Canceled` — отменённую. Метод `Bids/Apply` после успешного создания запускает заявку в работу, поэтому партнёр обычно получает `Started`. CARGO.RUN может вернуть заявку в работу, поэтому обработчик партнёра не должен считать статусы монотонными. Диаграмма описывает партнёрский сценарий, а не полный перечень разрешённых переходов пользовательского интерфейса CARGO.RUN. Текущий статус всегда определяется по полю `status` карточки или краткой модели заявки. Изменение статуса также может поступить через `entity.changed`. ## `IntegrationBidEventType` | JSON | Код | Значение | |---|---:|---| | `BidStarted` | 1 | Заявка запущена | | `AcceptedByDriver` | 2 | Принята водителем | | `AcceptedByDriverForwarder` | 3 | Принята водителем-экспедитором | | `EnteredPointByDriver` | 4 | Водитель отметил прибытие на точку | | `LoadUnloadedByDriver` | 5 | Водитель отметил погрузку/выгрузку и выезд | | `DocumentsReceivedByDriver` | 6 | Водитель подтвердил получение документов | | `BidCompleted` | 7 | Заявка завершена | | `BidCanceled` | 8 | Заявка отменена | | `BidDeleted` | 9 | Заявка удалена | `IntegrationBidEventType` описывает этапы исполнения, вычисленные по фактическим датам заявки и её точек, включая отмену и удаление. ## `QueuedApiTaskAction` | JSON | Код | Доступность партнёру | |---|---:|---| | `Write` | 0 | Да, для `Bid` | | `Read` | 1 | Да, для `Bid` с указанным `id` | | `ReadConfirmation` | 2 | Нет | | `ReadQuery` | 3 | Да, для `Bid` | | `Delete` | 4 | Нет | ## `QueuedApiTaskStatus` | JSON | Код | Значение | |---|---:|---| | `Awaiting` | 0 | Ожидает выполнения | | `InProgress` | 1 | Выполняется | | `Completed` | 2 | Завершена; нужно проверить каждый объект | | `Error` | 3 | Задача завершилась системной ошибкой | ## `QueuedApiTaskEnqueueStatus` | JSON | Код | Значение | |---|---:|---| | `Success` | 0 | Команда поставлена в очередь; поле `id` заполнено | | `Failed` | 1 | Команда не поставлена; причина находится в `message` | ## `QueuedApiTaskOrigin` | JSON | Код | Значение | |---|---:|---| | `Request` | 0 | Задача создана запросом партнёра | | `Subscription` | 1 | Задача создана CARGO.RUN по подписке | ## `QueuedApiTaskCallbackStatus` | JSON | Код | Значение | |---|---:|---| | `None` | 0 | Callback отсутствует или доставка ещё не назначена | | `Awaiting` | 1 | Ожидает доставки | | `InProgress` | 2 | Выполняется попытка доставки | | `Delivered` | 3 | Доставлен успешно | | `Error` | 4 | Доставка завершилась ошибкой | ## `QueuedApiTaskObjectResultStatus` | JSON | Код | Значение | |---|---:|---| | `Created` | 0 | Результат создан, обработка не завершена | | `Success` | 1 | Объект обработан успешно | | `Error` | 2 | Ошибка конкретного объекта | | `VersionMismatch` | 3 | Версия не совпала; относится к недоступному партнёру действию `ReadConfirmation` | ## Значения ошибок в разных enum Одинаковое имя `Error` относится к разным уровням обработки: | Поле | Enum | Что означает `Error` | |---|---|---| | `QueuedApiTaskGetResultsModel.status` | `QueuedApiTaskStatus` | Системная ошибка задачи целиком; результат мог не быть сформирован | | `objects[].status` | `QueuedApiTaskObjectResultStatus` | Ошибка обработки конкретного объекта; остальные объекты задачи могут быть успешны | | `callbackStatus` | `QueuedApiTaskCallbackStatus` | Все предусмотренные попытки доставки webhook для задачи завершились ошибкой | | `QueuedApiTaskObjectStatusJson.type` | `QueuedApiTaskSyncStatus` | Диагностический уровень статуса синхронизации объекта | Проверяйте эти поля независимо. Например, задача может иметь `status=Completed`, один объект — `status=Error`, а webhook — `callbackStatus=Delivered`. ## `QueuedApiTaskModelType` | JSON | Код | Доступность партнёру | |---|---:|---| | `Default` | 0 | Полная модель или стандартная модель операции | | `BidSharedInfoForForwardingModel` | 1 | Не используется партнёрским API | | `Summary` | 2 | Краткая карточка заявки | ## `InternalEntityType` | JSON | Код | Доступность в партнёрской очереди | |---|---:|---| | `Bid` | 1 | Поддерживается | | `DistributionBid` | 2 | Не поддерживается | | `Car` | 3 | Не поддерживается | | `Trailer` | 4 | Не поддерживается | | `Driver` | 5 | Не поддерживается | | `Counterparty` | 6 | Не поддерживается | ## `SourceType` Поле является выходным признаком источника заявки. Партнёр не передаёт `sourceType` при `Bids/Apply` и в документированных командах очереди. Для заявки, созданной партнёрской интеграцией, CARGO.RUN устанавливает `ExternalIntegration`; у связанной заявки, созданной перевозчиком, может вернуться другой источник. | JSON | Код | |---|---:| | `Web` | 0 | | `Enterprise` | 1 | | `Forwarding` | 2 | | `Exploitation` | 3 | | `Kontur` | 4 | | `ExternalIntegration` | 5 | ## Типы webhook Это строковые значения заголовка, а не enum JSON: | Значение | Смысл | |---|---| | `queued-task.finished` | Завершение задачи партнёра | | `entity.changed` | Изменение связанной заявки | | `ping` | Тест callback | ## `UserMessageType` Поле присутствует в синхронной модели сообщений. Для основного сценария достаточно обрабатывать текст, дату и файлы. | JSON | Код | Значение | |---|---:|---| | `User` | 0 | Сообщение пользователя | | `System` | 10 | Системное уведомление | | `BidStart` | 20 | Запуск заявки | | `BidApproved` | 21 | Согласование заявки | | `DriverControlPoints` | 22 | Задание водителю | | `BidLateness` | 30 | Опоздание по заявке | | `BidPointLateness` | 31 | Опоздание на точку | | `TrackerLogsStopped` | 32 | Нет данных трекера | | `CarStopped` | 33 | Длительная стоянка | | `RouteEvents` | 34 | Отклонение от маршрута | | `AxisLoadMonitoring` | 35 | Отклонение нагрузки на ось | | `CarStaysAtBidPoint` | 36 | Задержка на точке | | `BidAcceptLateness` | 37 | Заявка не принята вовремя | | `TemperatureMonitoring` | 38 | Отклонение температуры | | `BidRefuelingPointArrival` | 40 | Прибытие/выезд с заправки | | `BidPlannedRefuelings` | 41 | Планирование заправок | | `RefuelingSkipped` | 42 | Пропуск заправки | | `PointVisiting` | 50 | Прибытие/выезд с точки | | `LoadLateness` | 60 | Опоздание на загрузку | | `ServicePoints` | 70 | Сервисная точка | | `Waybills` | 80 | Электронные путевые документы | | `EmergencyAreaVisit` | 90 | Посещение аварийной зоны | | `DocumentStatus` | 100 | Изменение статуса документа | | `DocumentFile` | 101 | Файл документа | | `RouteControlPoints` | 102 | Контроль планового маршрута | ## Остальные enum моделей заявки Эти перечисления встречаются во вложенных полях полной карточки заявки. ### `BidPointType` | JSON | Код | Значение | |---|---:|---| | `StartPoint` | 0 | Начальная, или нулевая, точка | | `LoadPoint` | 1 | Погрузка | | `UnloadPoint` | 2 | Выгрузка | | `CustomPoint` | 3 | Пользовательская точка | | `ServicePoint` | 4 | Сервисная точка | ### `BidPointLoadUnloadStatus` | JSON | Код | Значение | |---|---:|---| | `AtLoading` | 0 | Автомобиль находится на погрузке | | `Loaded` | 10 | Погрузка завершена | | `AtUnloading` | 20 | Автомобиль находится на выгрузке | | `Unloaded` | 30 | Выгрузка завершена | ### `BidPaymentStatus` | JSON | Код | Значение | |---|---:|---| | `NotPaid` | 0 | Не оплачено | | `Paid` | 1 | Оплачено полностью | | `PartiallyPaid` | 2 | Оплачено частично | ### `DocumentsTrackingStatus` | JSON | Код | Значение | |---|---:|---| | `NotShipped` | 0 | Документы не отправлены | | `InTransit` | 10 | Документы в пути | | `Delivered` | 20 | Документы доставлены | ### `InvoiceTriggerType` | JSON | Код | Значение | |---|---:|---| | `ByOriginal` | 1 | Счёт выставляется после получения оригиналов | | `ByScan` | 2 | Счёт выставляется по скан-копиям | | `AtUnloading` | 3 | Счёт выставляется после выгрузки | ### `PaymentPeriodType` | JSON | Код | Значение | |---|---:|---| | `InCalendarDays` | 1 | Срок в календарных днях | | `InBankingDays` | 2 | Срок в банковских днях | ### `MapObjectType` Классификация возвращаемых объектов карты и геозон. В текущем сценарии создания заявки партнёр передаёт адрес и точечные координаты, но не задаёт `MapObjectType`. | JSON | Код | |---|---:| | `None` | 0 | | `BidPoint` | 10 | | `RouteSupportPoint` | 20 | | `GasStation` | 21 | | `StartBidPoint` | 40 | | `PostamatPoint` | 50 | | `ItemChangePoint` | 60 | | `ItemChangePointAddress` | 61 | | `ServicePoint` | 70 | | `CounterpartyPoint` | 80 | | `TripCouplingPoint` | 90 | | `PlatonPoint` | 100 | | `EmergencyAreaPoint` | 110 | | `RouteControlPoint` | 120 | ### `RouterCountryType` | JSON | Код | Значение | |---|---:|---| | `Russia` | 1 | Россия; поле относится к параметрам рассчитанного маршрута | ### `RouterProfile` | JSON | Код | Значение | |---|---:|---| | `HgvOptimal` | 1 | Оптимальный маршрут для грузового автомобиля | | `HgvShortest` | 2 | Кратчайший маршрут для грузового автомобиля | | `Hgv15tOptimal` | 3 | Оптимальный маршрут для грузового автомобиля массой до 15 тонн | | `Lcv` | 4 | Маршрут для лёгкого коммерческого транспорта | ### `QueuedApiTaskSyncStatus` | JSON | Код | Значение | |---|---:|---| | `Info` | 0 | Информационное сообщение, действий не требуется | | `Warn` | 1 | Предупреждение: обработка продолжена, сообщение следует записать в журнал | | `Error` | 2 | Ошибка синхронизации объекта | ### `UserMessageFlag` В JSON поле передаётся строковым именем. В текущем партнёрском сценарии используются `None` и `Mentioned`; числовые комбинации партнёру формировать не требуется. ### `UnitOfMeasure` В JSON передаётся строковое имя из первой колонки. Числовой классификационный код приведён только для справки. | JSON | Классификационный код | |---|---:| | `None` | 0 | | `Piece` | 796 | | `Kilogram` | 166 | | `Gram` | 163 | | `Tonne` | 168 | | `Litre` | 112 | | `Millilitre` | 111 | | `Meter` | 6 | | `Centimeter` | 4 | | `Millimeter` | 3 | | `LinearMeter` | 18 | | `SquareMeter` | 55 | | `CubicMeter` | 113 | | `Package` | 778 | | `Box` | 8751 | | `Bottle` | 868 | | `Can` | 881 | | `Pack` | 728 | | `Set` | 839 | | `Pair` | 715 | | `Hour` | 356 | | `Minute` | 355 | | `Day` | 359 | | `Month` | 362 | | `Year` | 366 | | `ConditionalUnit` | 876 | | `HorsePower` | 251 | --- Source: products/partner-integrations/reference/errors-and-limits.md # Ошибки и ограничения ## HTTP-ошибки | Код | Причина | Повтор | |---:|---|---| | `400` | Неверные поля или бизнес-правило | Только после исправления | | `401` | Недействительный или истёкший токен | Один раз обновить токен | | `403` | Нет доступа к операции или организации | Только после изменения прав | | `404` | Заявка не существует или недоступна текущему партнёру | Не повторять без проверки ID или изменения доступа | | `429` | Слишком частые запросы | После `Retry-After` или паузы | | `5xx` | Временная серверная ошибка | Ограниченно, с exponential backoff и jitter | Синхронные бизнес-ошибки могут возвращаться как `text/plain`. Иллюстративный пример ошибки валидации; конкретный текст зависит от нарушенного правила: ```http HTTP/1.1 400 Bad Request Content-Type: text/plain; charset=utf-8 Для заявки необходимо указать не менее двух точек маршрута. ``` Методы чтения возвращают одинаковый статус `404 Not Found`, если заявка не существует или недоступна текущему интеграционному клиенту. По HTTP-статусу различить эти случаи нельзя. ## Ошибки очереди | Уровень | Поле | Успех | Ошибка | Где читать причину | |---|---|---|---|---| | Постановка команды | `commands[].status` | `Success` | `Failed` | `commands[].message` | | Задача целиком | `QueuedApiTaskGetResultsModel.status` | `Completed` | `Error` | `message` | | Объект задачи | `objects[].status` | `Success` | `Error` или `VersionMismatch` | `objects[].message` | | Доставка webhook | `callbackStatus` | `Delivered` | `Error` | `lastError` | | Диагностика синхронизации | `QueuedApiTaskObjectStatusJson.type` | `Info` | `Warn` или `Error` | `QueuedApiTaskObjectStatusJson.message` | Эти уровни независимы. `Completed` означает, что обработка задачи закончена, но не гарантирует успех каждого элемента `objects[]`. Аналогично, `callbackStatus=Delivered` подтверждает только доставку webhook и ничего не говорит об успешности объектов. `VersionMismatch` используется механизмом `ReadConfirmation`, который партнёрским интеграционным клиентам недоступен. В документированных командах `Write`, `Read` и `ReadQuery` партнёр не должен получать этот статус. Если он всё же появился, не подтверждайте локальную версию объекта, зарегистрируйте диагностическое событие и заново прочитайте актуальные данные. ## Подтверждённые ограничения | Ограничение | Значение | |---|---| | Получение токена | Не чаще двух запросов за 30 секунд | | `Idempotency-Key` | Не более 100 символов, действует 24 часа | | Точки заявки | Минимум 2 | | Состав маршрута | Хотя бы одна погрузка и одна выгрузка | | `planEnterDate` | Обязателен для каждой точки | | Порядок точек | Строгий хронологический после приведения к UTC | | Адрес точки | Обязательная непустая строка, даже если координаты переданы | | Координаты точки | Необязательны; если переданы — `[долгота, широта]`, кроме `[0, 0]`; если отсутствуют — определяются по адресу | | ИНН | Обязателен; 10 цифр для организации или 12 для ИП | | Автомобиль, водитель и груз | Обязательны | | Прицеп | Необязателен; если передан, обязателен номер | | Асинхронные типы | Только `Bid` | | Асинхронные действия | `Write`, `Read`, `ReadQuery` | | Фактический маршрут | Только синхронный метод | | Автоматический пакет подписки | До 100 объектов в одной задаче по текущей конфигурации | | Список без `$filter` | Последние 30 дней для `GetList` и `ReadQuery`; любой непустой `$filter` отменяет окно по умолчанию | | Ссылки на файлы | Временные; файл нужно скачать сразу или повторно запросить данные для новой ссылки | ## Webhook - порядок не гарантируется; - возможны повторы; - несколько изменений одной заявки могут объединяться; - повторяются сеть, `408`, `429`, `5xx`; - остальные `4xx` не повторяются; - не более пяти попыток с интервалами 10, 20, 40 и 80 секунд перед повторными отправками; - после пяти последовательных неудачных доставок подписка приостанавливается; - во время приостановки проверочная доставка выполняется каждые 5 минут; - успешная доставка или `Tasks/Ping` возобновляет подписку; - отдельного публичного статуса приостановки нет, а накопившиеся изменения могут быть отброшены; - необходим периодический контрольный `ReadQuery`. ## Неподдерживаемые операции - `Delete` через партнёрскую очередь; - `ReadConfirmation`; - асинхронная работа с `Car`, `Trailer`, `Driver`, `Counterparty`, `DistributionBid`; - фактический маршрут внутри `IntegrationBidDetailsModel`; - частичное обновление заявки. ## Валидация новых полей заявки | Поле | Правило | Ошибка | |---|---|---| | `counterparty.name` | Обязательно при переданном `counterparty` | `Не указано наименование контрагента.` | | `counterparty.name` | Не более 256 символов | `Наименование контрагента не должно превышать 256 символов.` | | `counterparty.inn` | Если передан — 10 или 12 цифр | `ИНН контрагента … некорректен: ожидается 10 или 12 цифр.` | | `vehicleType` | Хотя бы одно из `name`, `tonnage`, `volume` | `Не указаны тип ТС, тоннаж или объем.` | | `vehicleType.name` | Не более 128 символов | `Тип ТС не должен превышать 128 символов.` | | `vehicleType.tonnage` | Если передан — больше 0 | `Грузоподъемность должна быть больше 0.` | | `vehicleType.volume` | Если передан — больше 0 | `Объем должен быть больше 0.` | | `temperatureRegime` | Обязательны `minimum` и `maximum` | `Не указаны минимальная и максимальная температура.` | | `temperatureRegime.*` | Каждая граница от −30 до 30 °C включительно | `Температура должна быть в диапазоне от -30 до 30 °C.` | | `temperatureRegime` | `minimum < maximum` | `Минимальная температура должна быть меньше максимальной.` | | `bidPoints[].geozone.address` | Обязательная непустая строка | `Не указан адрес точки N.` | | Геокодирование | По адресу должна определиться точка | `Не удалось определить координаты точки N по адресу «…».` | --- Source: products/partner-integrations/examples.md # Полные примеры ## Синхронное создание и отслеживание ```text 1. POST /api/Account/Token → сохранить accessToken.token и expiresIn 2. GET /api/integrations/Organizations/Check?inn=7701234567 → проверить canCreateBids и hasAccess 3. POST /api/integrations/Organizations/Apply → при необходимости создать организацию или получить доступ 4. POST /api/integrations/Bids/Apply → сохранить id заявки CARGO.RUN 5. GET /api/integrations/Bids/Get?id={id} → карточка, статус и ETA 6. GET /api/integrations/Bids/GetEvents?id={id} → события исполнения 7. GET /api/integrations/Bids/GetActualRoute?id={id}&coordinateIntervalSeconds=60 → фактические координаты 8. GET /api/integrations/Bids/GetDriverMessages?id={id} → сообщения и временные ссылки на файлы ``` ## Асинхронное создание ### Поставить задачу ```http POST /api/integrations/Tasks/Queue Authorization: Bearer Content-Type: application/json Idempotency-Key: write-order-2471970-v1 ``` ```json { "commands": [ { "action": "Write", "objects": [ { "type": "Bid", "modelType": "Default", "key": "ORDER-2471970", "body": { "inn": "7701234567", "bid": { "externalId": "ORDER-2471970", "counterparty": { "name": "ООО Ромашка", "inn": "7701234567" }, "vehicleType": { "name": "Рефрижератор", "tonnage": 20, "volume": 82 }, "temperatureRegime": { "minimum": 2, "maximum": 6 }, "cargos": [ { "name": "Паллетированный груз" } ], "bidPoints": [ { "externalId": "POINT-LOAD-1", "isLoadPoint": true, "planEnterDate": "2026-10-08T10:00:00", "geozone": { "address": "Москва, улица Примерная, 1", "location": { "coordinates": [37.6176, 55.7558] } } }, { "externalId": "POINT-UNLOAD-1", "isLoadPoint": false, "planEnterDate": "2026-10-09T10:00:00", "geozone": { "address": "Казань, улица Примерная, 2" } } ], "car": { "number": "А123АА777", "brandName": "КАМАЗ" }, "driver": { "firstName": "Иван", "lastName": "Иванов", "phoneNumber": "+79991234567" } } } } ] } ] } ``` Ответ постановки задачи: ```json { "latencyMsec": 25, "enqueuedInMsec": 8, "commands": [ { "id": 90001, "action": "Write", "status": "Success", "readyInMsec": 100, "message": null } ] } ``` Если отдельная команда не поставлена в очередь, для неё возвращается `status="Failed"`, поле `id` отсутствует, а причина находится в `message`. ### Получить результат ```http GET /api/integrations/Tasks/Queue?id=90001 Authorization: Bearer ``` ```json { "status": "Completed", "origin": "Request", "readyInMsec": 100, "remainingObjectCount": 0, "attemptCount": 1, "maxAttemptCount": 3, "callbackStatus": "Delivered", "callbackAttemptCount": 1, "callbackMaxAttemptCount": 5, "objects": [ { "key": "ORDER-2471970", "type": "Bid", "id": 12345, "status": "Success", "body": null, "message": null } ] } ``` ## Обработка `entity.changed` ```text 1. Прочитать raw body и заголовки. 2. Проверить допустимость X-Cargorun-Webhook-Timestamp. 3. Рассчитать HMAC_SHA256(secret, timestamp + "." + rawBody). 4. Сравнить с X-Cargorun-Webhook-Signature. 5. Проверить eventId на повтор. 6. Сохранить событие во внутреннюю очередь. 7. Вернуть HTTP 204. 8. Для каждого успешного объекта взять id. 9. Выполнить Read / Bid / Default. 10. Если нужны координаты — вызвать Bids/GetActualRoute. ``` ## Восстановление после недоступности webhook ```json { "commands": [ { "action": "ReadQuery", "objects": [ { "type": "Bid", "modelType": "Default", "query": "$filter=updatedAt gt 2026-10-07T07:59:55Z&$orderby=updatedAt,id&$top=100" } ] } ] } ``` Интервал начинается немного раньше последнего курсора. Повторные записи удаляются по `id`, а более новые версии определяются по `updatedAt`. --- Source: products/partner-integrations/launch-checklist.md # Чек-лист запуска ## Настройки CARGO.RUN - [ ] Создан активный интеграционный клиент. - [ ] Назначена правильная платформа. - [ ] Выданы `clientId` и `clientSecret` отдельно для теста и production. - [ ] Разрешено упрощённое создание заявок, если партнёр их создаёт. - [ ] Настроен HTTPS `callbackTarget`. - [ ] Настроен уникальный `callbackSecret`. - [ ] Включена подписка `Bid/Summary`. - [ ] Выдан доступ к необходимым организациям. ## Авторизация - [ ] Токен получается через `client_credentials`. - [ ] Токен кешируется до истечения `expiresIn`. - [ ] Реализовано однократное обновление после `401`. - [ ] Секреты и токены не попадают в логи. - [ ] Метод токена не вызывается чаще двух раз за 30 секунд. ## Заявки - [ ] Проверено создание заявки с двумя точками. - [ ] Проверено обновление по `externalId`. - [ ] Проверено повторение запроса после сетевой ошибки. - [ ] Корректно обрабатываются локальные даты точек. - [ ] У каждой точки передан непустой адрес. - [ ] Проверено создание точки без координат и её геокодирование по адресу. - [ ] Если координаты передаются, используется порядок `[долгота, широта]`. - [ ] При обновлении передаются стабильные `externalId` точек и сохраняются их статусы. - [ ] Проверены `counterparty`, `vehicleType` и `temperatureRegime`, если они используются. - [ ] Сохраняется ID заявки CARGO.RUN. ## Очередь - [ ] Обрабатывается результат каждой команды постановки. - [ ] Сохраняются `taskId`. - [ ] Учитываются `Retry-After` и `readyInMsec`. - [ ] Проверяются статус задачи и статусы всех объектов. - [ ] Для повторов используется уникальный `Idempotency-Key`. - [ ] Один ключ не переиспользуется с другим телом. ## Webhook - [ ] [`Tasks/Ping`](reference/endpoints.md#post-apiintegrationstasksping) доставляется успешно. - [ ] HMAC проверяется по raw body. - [ ] Проверяется timestamp. - [ ] События дедуплицируются по `eventId`. - [ ] Callback быстро сохраняет событие и отвечает `2xx`. - [ ] Обработчик допускает нарушение порядка доставки. - [ ] Более старые `updatedAt` не перезаписывают новые данные. ## Восстановление - [ ] Выполнена первоначальная загрузка через `ReadQuery` или объединённый `GetList`. - [ ] Обрабатываются оба значения `isCreatedByPlatform`. - [ ] Учтено, что `GetList` без `X-Organization-Id` возвращает все доступные организации. - [ ] Хранится курсор `(updatedAt,id)`. - [ ] Используется перекрытие интервалов. - [ ] Реализована периодическая контрольная сверка. - [ ] Проверено восстановление после временного отключения callback. ## Данные исполнения - [ ] События заявки обрабатываются как строковые enum. - [ ] Фактический маршрут запрашивается синхронно. - [ ] Настроено разумное прореживание координат. - [ ] Файлы скачиваются до истечения временной ссылки. - [ ] Неизвестные поля и enum не останавливают синхронизацию. - [ ] Учтено, что изменение ETA не обязательно меняет `updatedAt`. --- Source: products/partner-integrations/for-ai.md # Для LLM и ИИ-агентов Документация доступна в двух машиночитаемых представлениях. ## Индекс документации [Открыть `llms.txt`](../../llms.txt) Краткий индекс содержит ссылки на разделы документации и поясняет назначение каждого раздела. Используйте его, если ИИ-агент может самостоятельно открывать ссылки и загружать необходимые материалы. ## Полная документация [Открыть `llms-full.txt`](../../llms-full.txt) Файл содержит весь раздел интеграции с партнёрскими сервисами в одном документе. Используйте его для систем без доступа к сайту, подготовки базы знаний или передачи полного контекста модели. ## Рекомендации - Начинайте с `llms.txt`, чтобы не загружать лишний контекст. - Используйте `llms-full.txt`, если агенту требуется анализ всей интеграции или проверка связей между сценариями, методами и моделями. - Считайте опубликованную документацию источником требований к интеграции. Секреты, токены и реальные персональные данные в контекст модели не передавайте. ## Правила для агентов - Не вызывайте удалённый `Bids/GetCurrentList`; используйте объединённый `Bids/GetList`. - Определяйте источник записи по `isCreatedByPlatform`, а не по наличию `externalId`. - Перед вызовом `GetList` явно решите, нужна одна организация или все доступные: отсутствие `X-Organization-Id` расширяет область выборки. - Для обновления заявки сохраняйте `id` CARGO.RUN и стабильные `externalId` точек. - Не считайте `updatedAt` курсором ETA: `estimatedEnterDate` может измениться без изменения заявки. - Передавайте непустой адрес каждой точки. Координаты можно опустить, но ошибка геокодирования требует исправления адреса, а не слепого повтора.