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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. Хранить границу последнего полностью обработанного окна синхронизации.
  2. Для оперативных изменений использовать POST/GET /api/tasks/queue и ReadConfirmation; вызывать чтение чаще одного раза в час.
  3. Зафиксировать новую верхнюю границу и выполнить первичную или контрольную выборку методом GET /api/bids/GetListForExternal.
  4. Получать фиксированное окно порциями по 50 записей через $top=50 и $skip.
  5. Сортировать результат по updatedAt,id и идемпотентно сохранять по id и updatedAt.
  6. Учитывать isDeleted = true, а не отбрасывать удалённые заявки.
  7. Продвигать границу только после успешной обработки всех страниц; следующее окно начинать с перекрытием для защиты от совпадающих меток времени.

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

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,id
  &$skip=0

Подробный алгоритм приведён в разделах Синхронизация данных и Синхронизация заявок API 2.0.

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

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

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

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

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

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

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

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

  • Planned
  • New
  • Done
  • Canceled

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

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

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

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

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

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

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

Подходы:

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

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

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

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

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

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

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

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

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

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