Перейти к содержанию

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. Хранить у себя последнее сохраненное значение updatedAt по заявке.
  2. Запрашивать новые и измененные заявки методом GET /api/bids/GetListForExternal.
  3. Получать данные порциями по 50 записей через $top=50 и $skip.
  4. Сортировать результат по updatedAt, чтобы последовательно обработать изменения.
  5. При сохранении заявки во внешней системе сохранять её updatedAt.
  6. При следующей синхронизации сравнивать updatedAt в CARGO.RUN и внешней системе: если значения отличаются, заявка изменилась и её нужно обновить.

Пример запроса:

GET /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

Подробное описание параметров приведено в разделе Синхронизация данных.

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

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

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

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

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

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

CARGO.RUN управляет статусами заявки (этапы выполнения рейса).
Внешняя система должна регулярно получать актуальные статусы через GET /api/bids/GetListForExternal, так как статус входит в данные заявки и меняется вместе с updatedAt.

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

  • Planned
  • New
  • Done
  • Cancelled

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

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

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

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

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

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

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

Подходы:

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

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

  • $top=50
  • $skip для перехода к следующей странице
  • $orderby=updatedAt
  • инкрементальные загрузки.

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

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

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

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

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

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

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