cargo.run-api-docs

Синхронизация справочников и заявок

Этот документ описывает порядок синхронизации данных между внешней системой (1С/ERP/WMS) и CARGO.RUN.
Синхронизация одинакова для обоих сценариев интеграции: когда заявка создаётся в CARGO.RUN и когда она создаётся во внешней системе.

1. Общие принципы синхронизации

Синхронизация выполняется через REST API CARGO.RUN по протоколу HTTPS с использованием токена авторизации.

Каждый объект (водитель, машина, прицеп, контрагент, организация, заявка):

имеет уникальный идентификатор id в CARGO.RUN;
при создании в CARGO.RUN возвращает этот id, который должен быть сохранён во внешней системе;
содержит поле updatedAt, отражающее дату и время последнего изменения.

Поле updatedAt используется как основа для инкрементальной синхронизации.

2. Справочники, подлежащие синхронизации

2.1. Справочники, данные которых поступают из внешней системы

Эти справочники всегда считаются первичными во внешней системе:

Водители
Машины
Прицепы
Контрагенты
Организации

Для них внешний идентификатор является источником истины, а CARGO.RUN — получателем.

Синхронизация выполняется через методы:

/api/Driver/Apply, /api/Driver/Delete, /api/Driver/Restore, /api/Driver/GetList
/api/Car/Apply, /api/Car/Delete, /api/Car/GetList, /api/Car/GetForEdit
/api/Trailer/Apply, /api/Trailer/Delete, /api/Trailer/GetList
/api/CargoOwnerDictionary/Apply, /api/CargoOwnerDictionary/Delete, /api/CargoOwnerDictionary/Get
/api/LegalPersons/Apply, /api/LegalPersons/Delete, /api/LegalPersons/GetList

Рекомендуемая частота синхронизации: не больше чем раз в 1 минуту.

2.2. Ограничения на удаление водителей, машин и прицепов

При удалении объектов-справочников (водителей, машин, прицепов) действуют бизнес-ограничения.

Система не позволяет удалить объект, если он используется в актуальных данных, например:

водитель назначен на активную или запланированную заявку;
машина участвует в активной заявке;
прицеп привязан к активной заявке или рейсу.

В этих случаях:

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

Рекомендуется при интеграции:

логировать текст ошибки;
отображать комментарий пользователю внешней системы;
при необходимости реализовать бизнес-процесс «вывода из эксплуатации» (деактивацию) вместо физического удаления.

2.3. Справочники, данные которых поступают из CARGO.RUN

Тип оплаты (PaymentType)
Тип НДС (NDSType)
Тип груза (CargoType)
Типы машин (CarType)
Типы прицепов (TrailerType)
Бренды машин (CarBrandType)
Бренды прицепов (TrailerBrandType)

Получение выполняется методом:

GET /api/catalogs/getSimple

Метод поддерживает OData-фильтры.

3. Использование справочников при создании заявок

Поля, заканчивающиеся на TypeId (например, paymentTypeId, ndsTypeId, typeId, brandTypeId) должны заполняться значениями из общих справочников.

Некорректные идентификаторы приведут к ошибке валидации.

4. Синхронизация заявок (Bid)

Заявка — основной объект интеграции.
Синхронизация выполняется по полю:

updatedAt

Существует два направления синхронизации:

Внешняя система → CARGO.RUN
(создание/обновление через /api/TruckingBids/Apply или /api/TruckingBids/Patch)
CARGO.RUN → внешняя система
(получение обновлений через /api/bids/GetListForExternal)

5. Обработка `updatedAt`

При сохранении заявки внешней системе необходимо:

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

6. Получение списка заявок из CARGO.RUN

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

GET /api/bids/GetListForExternal

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

/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);
отсортированные по дате обновления ($orderby=updatedAt).

7. Обратная синхронизация: внешняя система → CARGO.RUN

Полное создание/обновление заявки

POST /api/truckingbids/Apply

Частичное обновление

POST /api/truckingbids/Patch

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

POST /api/truckingbids/SetStatus

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

POST /api/bids/cancel

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

POST /api/truckingbids/Revert

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

POST /api/bids/delete

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

POST /api/bids/Restore

Принудительное закрытие заявки вручную

POST /api/truckingbids/forceComplete

8. Рекомендуемые интервалы синхронизации

Справочники — 1–2 минуты
Заявки (Bid) — каждая минута
Исторические данные — каждые 10–15 минут
Статусы/фактические данные — по необходимости или в реальном времени

9. Конфликты данных

При конфликте обновлений возможны режимы:

9.1. Автоматический

Приоритет задаётся настройками:

CARGO.RUN → внешняя система
внешняя система → CARGO.RUN

9.2. Ручной

Внешняя система должна поддерживать разрешение конфликтов пользователем.