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

Этот документ описывает порядок синхронизации данных между внешней системой (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?$filter=externalId eq null&$orderby=id desc

Метод поддерживает 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 МСК (2024-01-23T21:00:00Z);
обновлённые не позже 25.01.2024 23:59:59 МСК (2024-01-25T20:59:59Z);
созданные после 01.10.2022 00:00 МСК (2022-09-30T21:00:00Z), если нужно ограничить выборку по дате создания;
первые 50 записей, начиная с позиции 0;
отсортированные по дате обновления updatedAt.

Все списки рекомендуется получать порциями по 50 записей. Не запрашивайте полный список без ограничения количества: тяжелые запросы увеличивают нагрузку на сервер и могут привести к временной блокировке пользователя системой.