Перейти к содержанию

Создание и обновление заявки

Партнёр может создать или полностью обновить заявку синхронно либо через очередь. В обоих вариантах используется одна модель ApplyBidFromIntegrationContext.

Предварительные условия

  • организация существует;
  • организация создана партнёрским сервисом или текущему партнёру явно выдан доступ;
  • Organizations/Check возвращает canCreateBids=true;
  • для создания переданы водитель, автомобиль, груз и минимум две точки;
  • среди точек есть хотя бы одна погрузка и одна выгрузка.

Организация задаётся обязательным полем inn: 10 цифр для юридического лица или 12 цифр для ИП. Это правило одинаково для синхронного и асинхронного вариантов.

Синхронный вариант

POST <baseUrl>/api/integrations/Bids/Apply
Authorization: Bearer <accessToken.token>
Content-Type: application/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"
    }
  }
}

Успешный ответ:

{
  "id": 12345,
  "isRouteBuilt": true
}

Заявка автоматически запускается в работу. Если найденная заявка ещё не запущена, обновление также запускает её.

Асинхронный вариант

POST <baseUrl>/api/integrations/Tasks/Queue
Authorization: Bearer <accessToken.token>
Content-Type: application/json
Idempotency-Key: create-order-2471970-v1

{
  "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.