Обзор интеграции
Этот документ описывает архитектуру и общие принципы интеграции между CARGO.RUN Logistics 2.0 и внешними системами (1С, ERP, WMS, CRM, внешние логистические платформы).
Он служит отправной точкой перед изучением сценариев и конкретных методов API.
1. Общая архитектура интеграции
Интеграция выполняется через REST API:
- обмен осуществляется по HTTPS;
- данные передаются в формате JSON;
- доступ — по токену авторизации;
- для выборок и фильтрации используется система query-параметров (включая OData-стиль).
Архитектура интеграции предполагает два возможных источника данных:
-
CARGO.RUN → внешняя система
данные создаются в CARGO.RUN, внешняя система их получает;
-
Внешняя система → CARGO.RUN
данные создаются во внешней системе и передаются в CARGO.RUN для планирования и исполнения.
Обе модели полностью поддерживаются.
2. Роль CARGO.RUN в потоке данных
CARGO.RUN выступает как:
- система планирования маршрутов и рейсов,
- система контроля исполнения перевозок,
- система мониторинга транспорта,
- хранилище заявок и статусов,
- точка сборки всех событий по перевозке.
Внешние системы (ERP, 1С, WMS) обычно отвечают за:
- учёт грузов,
- расчёты и финансы,
- ведение справочников,
- учёт заказчиков и заказов.
3. Базовые интеграционные возможности
API CARGO.RUN предоставляет возможности:
- создавать заявки (Bid) и заказы (DistributionBids);
- обновлять статусы заявок и ЭТРН;
- передавать маршрутные точки и параметры груза;
- синхронизировать справочники:
- контрагенты,
- водители,
- автомобили,
- прицепы,
- организации;
- управлять трекерами (привязка/отвязка);
- получать данные о рейсах и событиях выполнения;
- получать статусы титулов ЭТРН.
4. Двусторонняя интеграция
Интеграция может быть:
4.1. Односторонняя
Только внешняя система отправляет данные в CARGO.RUN
Или наоборот, CARGO.RUN передаёт события во внешнюю систему.
4.2. Двусторонняя
Обе системы создают данные, обновляют статусы и синхронизируют справочники.
Типовой пример двусторонней интеграции:
- 1С создаёт заявку;
- заявка передаётся в CARGO.RUN;
- CARGO.RUN планирует и исполняет рейс;
- статусы и результаты выполнения возвращаются в 1С.
5. Основные потоки данных
Интеграция покрывает три больших направления:
5.1. Справочники
Передаются регулярно или по событию:
- контрагенты,
- водители,
- автомобили,
- прицепы,
- организации.
Справочники должны быть синхронизированы до создания заявок.
5.2. Документы (заявки и заказы)
Потоки данных:
- Внешняя система создаёт заявку/заказ → отправка в CARGO.RUN.
- CARGO.RUN создаёт заявку → внешняя система получает её через API.
- Обновление заявок обеими сторонами.
- Отслеживание статусов заявок.
5.3. События перевозки
CARGO.RUN может передавать или предоставлять:
- время прибытия/отъезда,
- времена начала/завершения погрузки/выгрузки,
- пробег,
- задержки,
- отклонения от маршрута.
Эти данные используются внешними системами для:
- аналитики,
- расчётов,
- контроля SLA,
- контроля выполнения перевозок.
6. Потоки статусов
Статусы меняются:
- со стороны логиста,
- со стороны ЭТРН-провайдера,
- со стороны исполнителя (водитель),
- автоматически (например, при успешном закрытии рейса).
Внешние системы могут:
- получать статусы через API,
- сверять статусы заявок,
- сохранять историю изменений у себя.
7. Требования к идентификаторам
Для корректной интеграции обязательны:
- единые ID справочников;
- фиксированные значения статусных моделей;
- строгое соответствие названий полей swagger.
Дубликаты или ошибки в идентификаторах приводят к конфликтам в данных.
8. Принципы синхронизации данных
- Данные синхронизируются по методу «запрос → ответ».
- Для выборок поддерживаются фильтры и пагинация.
- Для оптимизации могут использоваться:
updatedAt,$filter c условиями,$top / $skip,page / pageSize.
Синхронизация справочников и заявок описана в посвящённом разделе.
9. Что изучать дальше
Для продолжения работы:
-
Сценарий: заявка создаётся в CARGO.RUN
→ CARGO.RUN → внешняя система
-
Сценарий: заявка создаётся во внешней системе
→ Внешняя система → CARGO.RUN
-
Синхронизация справочников
→ Синхронизация данных