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

Этот раздел описывает архитектуру интеграции CARGO.RUN Загрузки с внешними системами: 1С, ERP, TMS, WMS и внутренними сервисами клиентов.

1. Основная модель интеграции¶

Интеграция строится вокруг заказа на перевозку.

Заказ может появиться двумя способами:

во внешней системе и затем быть передан в CARGO.RUN;
в интерфейсе CARGO.RUN и затем быть загружен во внешнюю систему.

Обе модели поддерживаются API.

2. Участники процесса¶

Грузоотправитель или экспедитор¶

Создает заказ, управляет видимостью, получает отклики перевозчиков и выбирает исполнителя.

Основные методы:

POST /api/Orders/Apply;
GET /api/Orders/GetIntegrationList;
GET /api/Orders/GetInfo;
POST /api/OrderTruckMatchings/Accept;
POST /api/Orders/StartOrder;
POST /api/Orders/CancelOrder — жизненный цикл заказа.

Перевозчик¶

Получает доступные заказы, отправляет отклики и передает данные по ТС, водителю и исполнению.

Основные методы:

GET /api/TransporterOrders/GetList;
GET /api/TransporterOrders/GetInfo;
POST /api/TransporterOrderTruckMatchings/ApplyMatching;
POST /api/TransporterOrderTruckMatchings/ApplyManualMatching;
GET /api/TransporterBids/GetInfo.

3. Основные потоки¶

Учетная система → CARGO.RUN¶

Внешняя система создает заказ и передает его в CARGO.RUN.

Дальше CARGO.RUN используется для:

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

Подробно: Учетная система → CARGO.RUN

CARGO.RUN → учетная система¶

Пользователь создает заказ в CARGO.RUN. Внешняя система периодически получает новые и измененные заказы, сохраняет их у себя и обновляет данные по мере исполнения.

Подробно: CARGO.RUN → учетная система

Интеграция перевозчика¶

Перевозчик работает со своей учетной записью и видит только доступные ему заказы.

Подробно: Интеграция перевозчика

Отслеживание перевозки экспедитором¶

Экспедитор вручную назначает внешнего перевозчика и ТС, после чего получает фактические даты и последнюю известную GPS-позицию в своей системе.

Подробно: Отслеживание грузоперевозки экспедитором

4. Рекомендуемая последовательность внедрения¶

Настроить авторизацию.
Синхронизировать или проверить справочники.
Реализовать создание или получение заказов.
Реализовать получение деталей заказа.
Реализовать обработку откликов.
Реализовать получение результатов выполнения.
Добавить обработку отмены и ошибок.

5. Важные ограничения¶

Не нужно запрашивать новый access token перед каждым методом. Используйте refresh token.
Частоту polling и доступные лимиты согласуйте при подключении. При 429 учитывайте Retry-After, если он возвращен.
Заказы и отклики нужно сопоставлять по ID CARGO.RUN и внешним ID, если они передаются.
При ошибках 400 нужно сохранять тело ответа: оно содержит причину валидации или бизнес-ошибки.

Подробно: Ошибки и ограничения.