Обзор интеграции¶

Этот документ описывает архитектуру и общие принципы интеграции между 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 справочников;
фиксированные значения статусных моделей;
строгое соответствие названий полей, указанным в API Reference.

Дубликаты или ошибки в идентификаторах приводят к конфликтам в данных.

8. Принципы синхронизации данных¶

Данные синхронизируются по методу «запрос → ответ».
Для выборок поддерживаются фильтры и пагинация.
Для оптимизации могут использоваться:
updatedAt,
$filter c условиями,
$top / $skip,
$orderby.

Синхронизация справочников и заявок описана в посвящённом разделе.

9. Что изучать дальше¶

Для продолжения работы:

Сценарий: заявка создаётся в CARGO.RUN
→ CARGO.RUN → внешняя система
Сценарий: заявка создаётся во внешней системе
→ Внешняя система → CARGO.RUN
Синхронизация справочников
→ Синхронизация данных