cargo.run-api-docs

Сценарий: заявка создаётся во внешней системе

Этот сценарий описывает процесс, в котором внешняя система (1С, ERP, WMS или другая учетная система) является источником создания заявок. CARGO.RUN принимает данные, формирует рейсы, управляет маршрутом, контролирует исполнение и возвращает статусы во внешнюю систему.

1. Общая последовательность процесса

Процесс включает следующие этапы:

Внешняя система формирует заявку или заказ.
Перед отправкой заявка проходит проверку данных.
Внешняя система отправляет заявку в CARGO.RUN.
CARGO.RUN создаёт заявку в статусе New (Черновик).
Внешняя система запускает заявку в работу.
CARGO.RUN планирует и исполняет рейс.
Внешняя система регулярно получает обновления статусов заявки.

2. Требования к данным перед отправкой

Перед тем как создать заявку в CARGO.RUN, внешняя система должна убедиться:

все необходимые справочники синхронизированы:
- контрагенты,
- водители,
- автомобили,
- прицепы,
- организации;
обязательные поля заполнены (см. раздел “Минимальные требования”):
- cargoOwnerId,
- paymentTypeId,
- ndsTypeId,
- carId,
- driverId,
- bidPoints.
значения идентификаторов (xxxId) существуют в системе.

Если справочники не синхронизированы, система вернет ошибку валидации.

3. Создание заявки во внешней системе

Обычно внешняя система формирует заявку на основе внутренних процессов:

формирование груза,
данные клиента,
информация по отправителю/получателю,
планируемая дата доставки,
параметры перевозки.

После формирования заявки данные приводятся к структуре JSON, соответствующей требованиям API CARGO.RUN.

4. Создание черновика заявки в CARGO.RUN

Отправка выполняется запросом:

POST /api/TruckingBids/Apply
Content-Type: application/json
Authorization: Bearer <token>

Требование к адресу (геокодирование)

Для корректности адресов рекомендуется использовать геокодер CARGO.RUN:

POST /api/Map/GetAddresses

Тело запроса:

{
  "address": "<string>"
}

Метод возвращает структурированные данные:

координаты,
регион,
город,
район,
улицу и номер дома,
федеральный округ.

Рекомендуется всегда использовать результаты геокодера для bidPoints.geozone.

Пример создания черновика заявки

{
  "id": 0,
  "cargoOwnerId": 12345,
  "cargoOwnerDictionaryItemId": 10638021,
  "paymentTypeId": 41,
  "ndsTypeId": 40,
  "price": "234000",
  "cargos": [
    {
      "name": "ТНП",
      "typeId": 707,
      "extendedProperties": []
    }
  ],
  "typeOptions": [
    {
      "entityOptionId": 14655740,
      "id": 14655282
    }
  ],
  "bidPoints": [
    {
      "order": 0,
      "type": "LoadPoint",
      "planEnterDate": "2021-01-07 04:33",
      "geozone": {
        "location": {
          "type": "Point",
          "coordinates": [
            52.41153359413148,
            55.71049164294613
          ]
        },
        "address": "Россия, Республика Татарстан, Набережные Челны, Транспортный проезд, 15",
        "city": "Набережные Челны",
        "state": "Республика Татарстан",
        "county": "городской округ Набережные Челны",
        "street": "Транспортный проезд",
        "houseNumber": "15",
        "federalDistrict": "Приволжский федеральный округ",
        "radius": 0
      }
    },
    {
      "order": 1,
      "type": "UnloadPoint",
      "planEnterDate": "2021-01-07 13:33",
      "geozone": {
        "location": {
          "type": "Point",
          "coordinates": [
            48.39303731918335,
            54.30654645200388
          ]
        },
        "address": "Россия, Ульяновск, улица Минаева, 48Б",
        "city": "Ульяновск",
        "state": "Ульяновская область",
        "county": "городской округ Ульяновск",
        "street": "улица Минаева",
        "houseNumber": "48Б",
        "federalDistrict": "Приволжский федеральный округ",
        "radius": 0
      },
      "cargoOwnerDictionaryItemId": null
    }
  ],
  "driver": {
    "id": 16309296
  },
  "carOption": {
    "carId": 10483431
  },
  "trailerOption": {
    "trailerId": 17758587
  }
}

Важные детали

Поле id должно быть равно 0.
Для передачи ID внешней системы используется:

"externalId": "string"

Порожняя заявка

{
  "emptyMileageBid": {
    "logisticReasonTypeId": 0,
    "technicalReason": "string"
  }
}

При порожней заявке:

стоимость = 1,
груз и контрагент не указываются.

5. Запуск заявки в работу

После создания черновика необходимо запустить заявку:

POST /api/TruckingBids/SetStatus

Тело запроса:

{
  "bidId": 0,
  "status": "Started"
}

6. Получение статусов и списка заявок во внешней системе

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

GET /api/bids/GetListForExternal

Метод возвращает HTTP-статус 200 и массив заявок.

Принцип работы синхронизации

У каждой заявки в CARGO.RUN есть поле:

updatedAt

Это дата последнего обновления заявки.
В процессе синхронизации используется следующий алгоритм:

Внешняя система запрашивает заявки, у которых updatedAt попадает в заданный интервал.
При сохранении заявки во внешней системе сохраняется её updatedAt.
При следующей синхронизации значения updatedAt в CARGO.RUN и внешней системе сравниваются:
- если даты различаются — заявка изменилась и должна быть перезаписана;
- если совпадают — заявка не изменилась и может быть пропущена.

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

http://app.cargorun.ru/api/bids/GetListForExternal
  ?$filter=updatedAt ge 2024-01-23T21:00:00Z
           and updatedAt le 2024-01-25T20:59:59Z
           and createdAt ge 2022-09-30T21:00:00Z
  &$top=50
  &$orderby=updatedAt
  &$skip=0

Запрос вернёт список заявок:

с датой обновления больше 24.01.2024 00:00 (МСК)
(23.01.2024 21:00:00 UTC);
с датой обновления меньше 25.01.2024 23:59 (МСК)
(25.01.2024 20:59:59 UTC);
с датой создания больше 30.09.2022 (если необходимо ограничение по дате создания);
первые 50 заявок (параметр $top), начиная с 0 ($skip=0);
отсортированные по полю updatedAt.

7. Обработка ошибок и корректировка данных

Типовые причины ошибок при создании и обновлении заявок:

несоответствие идентификаторов справочников (водители, автомобили, прицепы, контрагенты);
некорректные адреса и геозоны;
некорректная структура массива bidPoints;
отсутствие обязательных полей.

Рекомендуется:

логировать все ошибки на стороне внешней системы;
отображать текст ошибки операторам;
повторять запрос после исправления данных.

8. Обновление заявки

Для обновления заявки поддерживаются два подхода.

8.1. Полное обновление заявки

POST /api/TruckingBids/Apply

Правила:

в запросе должны быть переданы все поля заявки;
в поле id указывается фактический идентификатор существующей заявки;
данные заявки в CARGO.RUN полностью перезаписываются переданным состоянием.

8.2. Частичное обновление заявки

POST /api/TruckingBids/Patch

Правила:

в запросе указываются только поля, которые требуется изменить;
частичное изменение вложенных объектов (например, bidPoints) не поддерживается;
если требуется изменить маршрутные точки, необходимо передать полный массив bidPoints, включая неизменённые точки.

9. Отмена, удаление, восстановление и принудительное закрытие заявки

9.1. Отмена заявки

Для отмены заявки используется:

POST /api/bids/cancel

Тело запроса:

{
  "bidId": 0
}

Заявка переходит в статус «Отменена».

9.2. Возврат заявки в черновик

Для возврата активной, выполненной или отменённой заявки в статус черновика используется:

POST /api/TruckingBids/Revert

Тело запроса:

{
  "bidId": 0
}

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

9.3. Удаление заявки

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

POST /api/bids/delete

Тело запроса:

{
  "bidId": 0
}

Рекомендуемый сценарий:

При необходимости перевести заявку в черновик через /api/TruckingBids/Revert.
Выполнить удаление через /api/bids/delete.

9.4. Восстановление удалённой заявки

Для восстановления ранее удалённой заявки используется:

POST /api/bids/Restore

Тело запроса:

{
  "bidId": 0
}

9.5. Ручное закрытие заявки (принудительное завершение)

Для принудительного закрытия заявки (в том числе с указанием факта выполнения и пробега) используется метод:

POST /api/truckingbids/forceComplete

Тело запроса:

{
  "bidId": 0,
  "reason": "string",
  "mileage": 0,
  "useOdometerMileage": true,
  "bidPoints": [
    {
      "id": 0,
      "enteredAtByLogist": "2025-05-07T07:15:04.555Z",
      "loadUnloadedAtByLogist": "2025-05-07T07:15:04.555Z",
      "loadUnloadStatus": "AtLoading"
    }
  ]
}

Требуется передавать фактические данные по точкам заявки.

10. Что изучать дальше

Для дальнейшей настройки интеграции рекомендуется:

ознакомиться с противоположным сценарием:
CARGO.RUN → внешняя система;
изучить общие правила синхронизации:
Синхронизация данных;
проверить минимальные требования к данным:
Минимальные требования.