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

Синхронизация

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

1. Основной метод синхронизации заказов

Для сценария грузоотправителя/экспедитора используется:

GET /api/Orders/GetIntegrationList

Метод поддерживает фильтрацию и пагинацию.

2. Рекомендуемый алгоритм polling

  1. Хранить максимальное updatedAt из последней успешно обработанной страницы.
  2. Запрашивать заказы, измененные после этого времени.
  3. Сортировать результат по updatedAt asc, чтобы обрабатывать изменения в хронологическом порядке.
  4. Обрабатывать страницу результатов.
  5. По каждому заказу запрашивать GET /api/Orders/GetInfo, если нужны полные данные заказа.
  6. Сохранять новую контрольную точку только после успешной обработки всей страницы.

Пример:

GET /api/Orders/GetIntegrationList?$filter=updatedAt gt 2026-06-30T16:37:14.138307%2B00:00&$orderby=updatedAt asc&$top=100&$skip=0

Если заказ изменился после сохраненной контрольной точки, он вернется в GetIntegrationList с новым updatedAt. Если изменения были в двух заказах, метод вернет оба заказа.

GetIntegrationList не заменяет GetInfo: в списке могут отсутствовать детальные данные по перевозчику, водителю, ТС, прицепу, названиям справочников и полному маршруту. Используйте список для обнаружения изменений, а GetInfo — для загрузки полной карточки заказа.

Если вместо gt используется ge, заказ с updatedAt, равным контрольной точке, может вернуться повторно. В этом случае внешняя система должна уметь безопасно обрабатывать дубли, например по паре id + updatedAt.

3. Что синхронизировать

Для внешней системы обычно важны:

  • ID заказа CARGO.RUN;
  • внешний ID заказа;
  • статус заказа;
  • статус заявки;
  • выбранный перевозчик;
  • ТС, прицеп и водитель;
  • плановые и фактические времена по точкам;
  • стоимость;
  • отмена и причина отмены.

4. Синхронизация справочников

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

Для справочников также поддерживаются:

  • $filter;
  • $orderby;
  • $top;
  • $skip.

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

GET /api/PackType/SelectList?$filter=contains(tolower(name),'паллет')

5. Обработка ошибок

При ошибках интеграции рекомендуется сохранять:

  • URL метода;
  • тело запроса;
  • HTTP-код;
  • тело ответа;
  • ID заказа или внешний ID;
  • дату и время ошибки.

Это особенно важно для ошибок 400, потому что они часто содержат конкретную причину валидации.