Как загрузить все записи из API с пагинацией

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

Чтобы проверить полноту, заранее определите срез данных, способ перехода к следующей странице, документированный признак окончания и безопасную границу восстановления. Успешный ответ отдельного запроса не заменяет ни одно из этих условий.

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

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

Полезно различать четыре состояния:

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

В узле HTTP Request платформы n8n есть настройка Pagination для результатов, которые API не возвращает одним вызовом. Однако сама настройка не определяет контракт перехода, условие окончания или восстановление после сбоя. Эти правила проектируют для конкретного API.

Как определить, что означает полная загрузка

Фраза «получить все записи» недостаточна для технического задания. Набор может меняться, пока интеграция читает страницы. Зафиксируйте, к какому срезу относится слово «все»:

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

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

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

Как выбрать способ перехода между страницами

Способ задаёт API. Интеграция должна брать следующее значение из документации метода или предыдущего ответа, а не угадывать его.

HTTP Request в n8n поддерживает два относящихся к этой задаче режима: изменение параметра в каждом следующем запросе и переход по следующему URL из ответа. В первом случае отдельно задают выражение и начальное значение. Во втором проверяют, что фактический ответ действительно содержит нужный URL.

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

Как определить окончание выборки

Интеграция должна завершать чтение по признаку, который закреплён в документации или подтверждён контрактом метода. Возможные варианты:

• следующего маркера или URL больше нет;
• API вернул пустой результат;
• число записей меньше разрешённого размера страницы;
• ответ содержит специальный флаг окончания.

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

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

Что предусмотреть, если набор меняется во время чтения

Пока интеграция запрашивает страницы, сотрудник или другая система может добавить, удалить или изменить запись. Это способно повлиять на границы страниц, но конкретный риск определяется поведением API.

До разработки выясните:

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

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

Как продолжить после сбоя без пропуска страницы

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

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

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

• срок его действия;
• допускается ли повторное использование;
• связан ли он с исходным фильтром;
• поддерживает ли API продолжение после длительной паузы.

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

Документация REST API Битрикс24 рекомендует разбивать большие операции на несколько запросов и применять постраничную выборку. Эта рекомендация относится к Битрикс24 и не задаёт универсальный алгоритм восстановления, размер страницы или срок действия курсора для других API.

Условный маршрут полной выгрузки

Ниже — синтетический учебный пример по документированному контракту. Это не клиентский кейс Switch On AI и не результат выполненного теста.

Интеграция регулярно получает изменённые сделки из условного сервиса и сохраняет их в хранилище. API предоставляет документированный маркер продолжения и устойчивый идентификатор записи.

1. Процесс фиксирует фильтр, границы периода и поддерживаемый API порядок выдачи.
2. Запрашивает первую страницу и проверяет ожидаемую структуру ответа.
3. Сохраняет все записи страницы и завершает обязательные действия этой единицы фиксации.
4. Только после подтверждения сохранения обновляет точку продолжения.
5. Передаёт документированный маркер следующему запросу и повторяет цикл.
6. Завершает чтение только после документированного признака окончания и проверки состава среза.

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

Как принять чтение API и последующие действия

Приёмку разделяют на два независимых уровня. Сначала проверяют полноту чтения, затем — поведение системы назначения.

Контролируемый срез должен позволять определить состав записей в источнике. В журнале сохраняют запросы, маркеры, устойчивые ключи, исключения и состояния, но не секреты. Успешный HTTP-ответ, отсутствие технической ошибки и отдельное поле total сами по себе не доказывают полноту.

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

Что подготовить для обсуждения интеграции

Для предметного разбора соберите:

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

Также определите единицу фиксации: достаточно ли сохранить страницу в хранилище или до продвижения точки нужно подтвердить связанные рабочие действия.

Switch On AI разрабатывает и внедряет интеграции рабочих систем. Для такой задачи мы разберём маршрут данных, доступные методы, границу безопасного продолжения и критерии приёмки. Совместимость, права, ограничения и эксплуатационные расходы устанавливаются для конкретных систем.

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