cargo.run-api-docs

Справочники 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.

---

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

POST /api/driver/delete

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

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

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

---

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

POST /api/driver/restore

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

---

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

GET /api/driver/getlist

Метод возвращает список водителей с основными атрибутами.
Поддержка фильтрации и пагинации определяется по swagger.

---

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

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

POST /api/car/apply

Назначение:

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

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

---

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 — обновление.

---

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

POST /api/trailer/delete

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

---

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

GET /api/trailer/getlist

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

---

5. Контрагенты (справочник грузоотправителей/грузополучателей)

Работа с контрагентами выполняется через методы CargoOwnerDictionary.

5.1. Создание и обновление контрагента

POST /api/cargoownerdictionary/apply

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

Поле cargoOwnerDictionaryItemId используется в заявке для связи с этим справочником (см. minimal-requirements.md).

---

5.2. Удаление контрагента

POST /api/cargoownerdictionary/delete

Удаление возможно при отсутствии использования контрагента в активных заявках.

---

5.3. Получение контрагента

GET /api/cargoownerdictionary/get

Возвращает данные по одному элементу справочника по идентификатору.

---

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

Через параметры запроса (см. swagger) указывается, какой именно каталог требуется получить.

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

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

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

• Минимальные требования к запросам
• Синхронизация данных