Синхронизация записей через API: страницы данных и контроль полноты

Полнота всегда относится к области загрузки. Зафиксируйте организацию, филиалы, диапазон дат, часовой пояс, статусы и права доступа. Если токен видит только один филиал, успешный обход его страниц не означает полноту по всей компании. Изменение фильтра создаёт новую область сверки, а не продолжение прежнего набора.

Различайте три состояния: данные получены, данные применены и обход завершён. Запрос мог пройти успешно, но сохранение в CRM завершиться частично. Либо все полученные строки сохранены, но следующая страница ещё не загружена. Отчёт о завершении должен учитывать оба условия, а не только отсутствие ошибки сети.

У каждого запуска полезны идентификатор, исходные фильтры, число страниц, число уникальных записей, время начала и результат. Если источник предоставляет контрольный итог, его можно использовать с учётом документированных гарантий. Самостоятельно посчитанные строки подтверждают объём работы обработчика, но не доказывают, что источник не изменился во время обхода.

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

Повтор устраняется обновлением по устойчивому идентификатору, но пропуск этим не исправить. Нужна документированная стратегия: согласованный снимок, переход по устойчивому ключу с однозначным порядком или другой механизм источника. Сортировка только по времени может быть недостаточна, если несколько записей имеют одинаковую метку.

Если гарантий снимка нет, не объявляйте обход точным состоянием «на начало загрузки». Для отчёта можно явно указать период получения и выполнить дополнительную сверку. Для оперативного календаря после полного обхода полезен обмен изменениями, если API его поддерживает и позволяет согласовать границу без промежутка. Иначе потребуются повторные проходы с понятными ограничениями.

Контрольная точка отвечает на вопрос, откуда безопасно продолжить после остановки. Если сначала сохранить новый курсор, а затем упасть до записи данных, при восстановлении страница будет пропущена. Если сначала применить страницу и упасть до продвижения курсора, страница придёт повторно. Поэтому требуется согласованная фиксация либо безопасное повторное применение.

Для внешней CRM общая транзакция с локальным хранилищем часто недоступна. Тогда ведут журнал применения: какие идентификаторы обновлены, какие ждут повтора и какой переход ещё не подтверждён. Не продвигайте итоговую контрольную точку за незавершённые операции без явного механизма их восстановления. Ошибка одной строки должна оставаться видимой.

Следите и за пересечением полных выгрузок. Старый медленный запуск не должен завершиться позже нового и заменить его результаты устаревшими данными. Используйте согласованное ограничение параллельных обходов или проверку версии запуска. Технический статус «обработано» полезен только вместе с областью, к которой он относится.

В Microsoft Graph механизм delta query использует @odata.nextLink для продолжения и @odata.deltaLink для завершения раунда и последующего отслеживания изменений. Пустая страница может иметь продолжение; токены следует считать непрозрачными, а повторное появление данных — допустимым. Это пример документированного контракта, а не описание API MySlot.

Для вашей интеграции запросите соответствующие правила API и проведите тесты: больше одной страницы, пустая промежуточная страница при допустимом продолжении, повтор ответа, ошибка сохранения, новая запись во время обхода и истечение курсора. Отдельно проверьте снижение прав доступа: оно не должно становиться командой удалить ранее видимые визиты.

На демонстрации связки MySlot и CRM оцените восстановление после остановки посередине загрузки. Сравните уникальные идентификаторы и итоговые статусы в обоих направлениях. Журнал должен показать, где именно остановилась обработка, и отличать завершённый обмен от частичного, даже если последнее сетевое обращение было успешным.