cargo.run-api-docs

Сценарий: заявка создаётся в CARGO.RUN

Этот сценарий описывает ситуацию, когда заявка (Bid) создаётся и редактируется в системе CARGO.RUN, а внешняя система (1С, ERP или другое приложение) должна получать эти данные, реагировать на изменения и использовать их в собственных процессах.

---

1. Структура процесса

Процесс синхронизации в этом сценарии включает три части:

1. CARGO.RUN создаёт и изменяет заявки.
2. Внешняя система регулярно запрашивает новые или обновлённые заявки.
3. Внешняя система сохраняет данные и обновляет статусы у себя.

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

---

2. Создание заявки в CARGO.RUN

Заявки формируются логистами CARGO.RUN:

• выбор контрагента,
• указание маршрута и точек,
• выбор водителя и автомобиля,
• назначение стоимости и НДС,
• уточнение условий перевозки.

После сохранения заявка получает статус New или Planned, в зависимости от процесса клиента.

---

3. Получение заявок внешней системой

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

Типовой алгоритм:

1. Хранить у себя timestamp последней успешной синхронизации.
2. Запрашивать: GET /bids?updatedAt>={lastSyncTimestamp} Или OData-стиль: GET /bids?$filter=updatedAt ge {lastSyncTimestamp}
3. Пробегать по массиву заявок в ответе.
4. Создавать или обновлять данные у себя.

Запросы могут использовать:

• page / pageSize
• $top / $skip
• $filter, $orderBy

в зависимости от особенностей метода.

---

4. Синхронизация справочников перед обработкой заявок

Перед обработкой новых заявок внешняя система должна обеспечить актуальность справочников:

• контрагенты,
• водители,
• автомобили,
• прицепы,
• организации.

Если у заявки указан водитель с driverId, который отсутствует в внешней базе, система должна либо:

• предварительно загрузить справочник водителей,
• либо запросить данные этого водителя.

---

5. Обработка статусов заявок

CARGO.RUN управляет статусами заявки (этапы выполнения рейса).
Внешняя система должна регулярно получать актуальные статусы:

GET /bids?updatedAt>=…

GET /bids/{id}

Статусы, которые важно отслеживать:

• Planned
• New
• Done
• Cancelled

Внешняя система должна обновлять свои записи в соответствии с полученными статусами.

---

6. Обработка событий перевозки

Дополнительно могут передаваться:

• фактические времена прибытия,
• времена начала/завершения погрузки/выгрузки,
• пробег,
• задержки,
• отклонения от маршрута.

Эти данные используются во внешних системах для:

• расчёта KPI,
• учёта времени,
• проверки SLA,
• расчётов с перевозчиком.

---

7. Частота синхронизации

Подходы:

• периодически — каждые 1–5 минут (рекомендуемый вариант),
• по расписанию — например, каждые 15 минут,
• только вручную — если система не требует оперативного обновления (не рекомендуется).

При высокой нагрузке возможно использовать:

• $top=500
• _orderBy=updatedAt desc
• инкрементальные загрузки.

---

8. Обработка ошибок и конфликтов

Внешняя система должна корректно обрабатывать:

• отсутствие данных,
• некорректные значения справочников,
• недоступность API,
• устаревшие timestamp (если синхронизация задержалась).

При ошибке желательно:

• повторить запрос,
• логировать ситуацию,
• не терять timestamp последней успешной синхронизации.

---

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

• Сценарий обратного направления:
  Внешняя система → CARGO.RUN

• Механизмы синхронизации:
  Синхронизация данных

• Минимальные требования к данным:
  Минимальные требования