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

Синхронизация заявок API 2.0

Этот сценарий предназначен для 1С/ERP, которая должна получать изменения заявок из CARGO.RUN и надёжно подтверждать их обработку.

1. Какие каналы нужны

Канал Назначение
GET /api/bids/GetListForExternal Первичная загрузка, статусы, удаления, периодическая сверка
POST/GET /api/tasks/queue Оперативное асинхронное получение накопленных изменений

API 2.0 не заменяет GetListForExternal: он не гарантирует все смены статуса и удаления.

2. Первичная загрузка

  1. Зафиксируйте windowEnd перед началом выборки.
  2. Прочитайте все страницы GetListForExternal до windowEnd.
  3. Используйте $orderby=updatedAt,id, фиксированный $top и последовательный $skip.
  4. Сохраняйте заявки по id CARGO.RUN. externalId не уникален.
  5. Обрабатывайте isDeleted = true как изменение.
  6. Продвигайте курсор только после успешной обработки всех страниц.

3. Оперативный цикл

  1. Отдельный пользователь интеграции вызывает POST /api/tasks/queue с Read для Bid.
  2. Вызов выполняется чаще одного раза в час. Окно изменений в текущей реализации равно одному часу.
  3. Клиент сохраняет ID задания и ожидает Completed или Error.
  4. Клиент проверяет objects[].status и сохраняет каждый Success вместе с id и version.
  5. После фиксации в локальной транзакции клиент отправляет ReadConfirmation.
  6. При VersionMismatch клиент повторно читает объект и подтверждает уже новую версию.

Несколько быстрых изменений одной заявки могут объединиться. API 2.0 передаёт последнюю версию объекта, а не журнал всех промежуточных событий.

4. Защита от эха

Изменения, записанные тем же пользователем синхронизации, не ставятся ему в очередь входящих изменений. Поэтому:

  • используйте для интеграции отдельного пользователя;
  • не ожидайте, что собственная запись вернётся через Read;
  • после изменяющего запроса проверяйте ответ или повторно читайте объект по id.

5. Контрольная сверка

Выполняйте её:

  • по расписанию;
  • после перерыва в работе длиннее часа;
  • после ошибки Read, ReadConfirmation или локальной транзакции;
  • для получения гарантированных смен статуса и удалений.

Выборка должна иметь фиксированные границы по updatedAt, небольшое перекрытие и дедупликацию по id + updatedAt. Подробности: Синхронизация справочников и заявок.

6. Восстановление

Если курсор API 2.0 потерян, не пытайтесь восстановить его из ID последнего задания. Запустите контрольную выборку GetListForExternal от последней надёжно сохранённой границы.

Технический контракт очереди: Асинхронная очередь API 2.0.