Справочники API CARGO.RUN¶

Этот раздел описывает методы работы со справочниками, которые участвуют в интеграции:

водители;
автомобили;
прицепы;
организации;
общие каталоги (типы, бренды и др.).

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

Синхронизация данных

Здесь описаны именно методы API для работы со справочниками.

1. Общие принципы¶

Для всех справочников используются общие правила:

формат данных — JSON;
авторизация — по токену (см. Auth API);
операции создания и обновления выполняются по паттерну Apply:
id = 0 — создание;
id > 0 — обновление;
операции удаления и восстановления выполняются через POST-методы (.../delete, .../restore);
при ошибках валидации возвращается HTTP 4xx и текстовое описание ошибки.

Минимальные требования к полям см. в:

Минимальные требования к запросам

2. Водители¶

2.1. Создание и обновление водителя¶

POST /api/driver/apply

Назначение:

создание нового водителя (id = 0);
обновление существующего водителя (id > 0).

Минимальные обязательные поля и структура объекта описаны в minimal-requirements.md.

Пример создания водителя¶

{
  "id": 0,
  "firstName": "Николай",
  "lastName": "Миклухо-Маклай",
  "patronymic": "Николаевич",
  "phoneNumber": "+73222323233",
  "comment": "Ссылка на яндекс-диск",
  "needsShiftChangeComment": "Произвольный текст",
  "needsUrgentShiftChange": true,
  "accessPermitIds": [
    5,
    16
  ]
}

Пример обновления паспортных данных и водительского удостоверения¶

Паспортные данные и данные водительского удостоверения передаются в модели водителя. Для обновления существующего водителя укажите его id.

{
  "id": 128943713,
  "passportSeries": "9292",
  "passportNumber": "122345",
  "passportGivenBy": "Электротехническим ОВД г. Кукуево",
  "passportGivenWhen": "2026-07-09",
  "departmentCode": "178-787",
  "driverLicenseSeries": "2323",
  "driverLicenseNumber": "123213",
  "driverLicenseGivenWhen": "2026-06-30",
  "driverLicenseValidUntil": "2026-06-30"
}

2.2. Удаление водителя¶

POST /api/driver/delete

Тело запроса содержит идентификатор водителя.

Особенности:

водитель не может быть удалён, если участвует в активных или запланированных заявках;
в случае бизнес-ошибки возвращается HTTP 4xx и текстовое пояснение.

2.3. Восстановление водителя¶

POST /api/driver/restore

Используется для восстановления ранее удалённого водителя.

2.4. Получение списка водителей¶

GET /api/driver/getlist

Метод возвращает список водителей с основными атрибутами.
Метод поддерживает стандартные параметры списков, если они включены для конкретного подключения:

Параметр	Описание
`$filter`	Фильтр по полям списка водителей
`$orderby`	Сортировка
`$top`	Ограничение количества записей
`$skip`	Смещение

3. Автомобили¶

3.1. Создание и обновление автомобиля¶

POST /api/car/apply

Назначение:

создание нового автомобиля (id = 0);
обновление существующего автомобиля (id > 0).

Минимальные поля и структура приведены в minimal-requirements.md.

Пример создания автомобиля¶

{
  "id": 0,
  "number": "А232ОО/122",
  "brandTypeId": 2716,
  "typeId": 164,
  "logistId": 1466813,
  "trackerId": 109918,
  "mechanic": {
    "name": "Максим Горький",
    "phoneNumber": "+7 (962) 568-00-89"
  },
  "columnDispatcher": {
    "name": "Владимир Набоков",
    "phoneNumber": "+7 (962) 6463232"
  },
  "comment": "Ссылка на яндекс-диск",
  "needsMaintenanceComment": "Произвольный текст",
  "needsUrgentMaintenance": true,
  "isInRefuelingSyncList": true,
  "accessPermitIds": [
    1,
    2
  ],
  "fuelTanks": [
    {
      "minimumVolume": 10,
      "currentVolume": 0,
      "totalVolume": 800,
      "fuelConsumption": 33,
      "minimumFuelTankVolume": 120,
      "type": "Diesel"
    }
  ]
}

3.2. Удаление автомобиля¶

POST /api/car/delete

Особенности:

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

3.3. Получение списка автомобилей¶

GET /api/car/getlist

Возвращает список автомобилей.

3.4. Получение автомобиля для редактирования¶

GET /api/car/getforedit

Метод возвращает подробные данные по одному автомобилю для редактирования.

4. Прицепы¶

4.1. Создание и обновление прицепа¶

POST /api/trailer/apply

По паттерну Apply:

id = 0 — создание прицепа;
id > 0 — обновление.

Пример создания прицепа¶

{
  "id": 0,
  "number": "КК2323/232",
  "brandTypeId": 2720,
  "typeId": 15470,
  "loadUnloadOptions": [
    {
      "id": 4612889
    },
    {
      "id": 4612891
    },
    {
      "id": 4612890
    }
  ],
  "mechanic": {
    "name": "Максим Горький",
    "phoneNumber": "+7 (927) 200-66-00"
  },
  "comment": "Ссылка на яндекс-диск",
  "trackerId": 4137,
  "isInRefuelingSyncList": true,
  "accessPermitIds": [
    4,
    7
  ],
  "fuelTanks": [
    {
      "minimumVolume": 0,
      "currentVolume": 0,
      "totalVolume": 120,
      "fuelConsumption": 33,
      "minimumFuelTankVolume": 120,
      "type": "Diesel"
    }
  ]
}

4.2. Удаление прицепа¶

POST /api/trailer/delete

Удаление возможно только при отсутствии использования в активных заявках.
При нарушении этого ограничения возвращается бизнес-ошибка.

4.3. Получение списка прицепов¶

GET /api/trailer/getlist

Возвращает список прицепов.

5. Контрагенты, договоры и адреса¶

Контрагенты вынесены в отдельный раздел, потому что кроме самой карточки контрагента там описаны договоры и адреса/точки контрагентов.

Контрагенты API

6. Организации¶

6.1. Создание и обновление организации¶

POST /api/legalpersons/apply

Применяется для создания/обновления юридических лиц, используемых в CARGO.RUN.

6.2. Удаление организации¶

POST /api/legalpersons/delete

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

6.3. Получение списка организаций¶

GET /api/legalpersons/getlist

Возвращает список юридических лиц.

7. Общие каталоги (типы, бренды и др.)¶

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

GET /api/catalogs/getSimple

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

GET /api/catalogs/getSimple?$filter=externalId eq null&$orderby=id desc

В URL пробелы кодируются как %20:

https://app.cargorun.ru/api/catalogs/getSimple?$filter=externalId%20eq%20null&$orderby=id%20desc

externalId eq null возвращает общие справочники CARGO.RUN, а $orderby=id desc сортирует их по ID в обратном порядке. Набор доступных каталогов зависит от подключения клиента.

Минимальный набор параметров:

Параметр	Описание
`$filter`	Фильтр по элементам каталога
`$orderby`	Сортировка
`$top`	Ограничение количества записей
`$skip`	Смещение

Примеры каталогов:

типы оплаты;
типы НДС;
типы машин;
типы прицепов;
бренды машин;
бренды прицепов;
типы грузов.

Пример ответа¶

Ниже показан сокращенный пример ответа: в реальном ответе может быть больше справочников и больше элементов внутри каждого справочника.

[
  {
    "id": 30,
    "displayName": "НДС",
    "propertyName": "NDSType",
    "type": "NDSType",
    "externalId": null,
    "items": [
      {
        "id": 38,
        "displayName": "Без НДС",
        "propertyName": "Without",
        "isDeleted": false,
        "isHidden": false
      },
      {
        "id": 39,
        "displayName": "10%",
        "propertyName": "10%",
        "isDeleted": false,
        "isHidden": false
      },
      {
        "id": 40,
        "displayName": "20%",
        "propertyName": "20%",
        "isDeleted": false,
        "isHidden": false
      }
    ]
  },
  {
    "id": 25,
    "displayName": "Типы прицепов/полуприцепов",
    "propertyName": "TrailerType",
    "type": "TrailerType",
    "externalId": null,
    "items": [
      {
        "id": 44,
        "displayName": "Бензовоз",
        "propertyName": "Gasoline",
        "isDeleted": false,
        "isHidden": false
      },
      {
        "id": 45,
        "displayName": "Автоцистерна",
        "propertyName": "Tank",
        "isDeleted": false,
        "isHidden": false
      },
      {
        "id": 46,
        "displayName": "Цементовоз",
        "propertyName": "Cement",
        "isDeleted": false,
        "isHidden": false
      }
    ]
  },
  {
    "id": 31,
    "displayName": "Тип оплаты",
    "propertyName": "PaymentType",
    "type": "PaymentType",
    "externalId": null,
    "items": [
      {
        "id": 41,
        "displayName": "Безналичный",
        "propertyName": "NonCash",
        "isDeleted": false,
        "isHidden": false
      },
      {
        "id": 42,
        "displayName": "Наличный",
        "propertyName": "Cash",
        "isDeleted": false,
        "isHidden": false
      },
      {
        "id": 88752941,
        "displayName": "Платежная карта",
        "propertyName": "Платежная карта",
        "isDeleted": false,
        "isHidden": false
      }
    ]
  }
]

Использование этих каталогов описано в: