API часто отдаёт данные порциями. Если забрать только первую страницу, получится аккуратная, но неполная выгрузка. Настроим встроенную пагинацию HTTP Request в n8n: получим три страницы, превратим их в пять заказов и отдельно проверим, что дошли до конца. Для упражнения используем свой локальный API, без ключей и настоящих заказов.
Результат инструкции
На выходе Ready Orders будут O1, O2, O3, O4 и O5 с суммами 100, 200, 300, 400 и 500. Всего пять записей на 1500. Если ограничить загрузку двумя страницами, четыре найденных заказа не станут ready: схема выдаст needs_review. При HTTP 500 на второй странице Fetch Pages остановится, а Ready Orders не выполнится.
Что понадобится
- Windows, работающий Docker Desktop и уже установленный локальный n8n.
- PowerShell, свободный порт 18112 и отдельная папка для двух учебных файлов.
- Возможность создать новый ручной workflow. AI-модель, API-ключ и платный сервис не нужны.
Шаг 1. Проверьте Docker и порт
Создайте отдельную папку ezgpt-pagination и откройте в ней PowerShell. Проверьте доступ к движку Docker и наличие слушателя на порту. docker version должен показать раздел Server, вторая команда - не показать занятого порта. Если Docker не запущен, дождитесь его готовности. Рабочие контейнеры не останавливайте.
docker version
Get-NetTCPConnection -LocalPort 18112 -State Listen -ErrorAction SilentlyContinueЕсли 18112 занят, выберите другой внешний порт. Одинаково замените его в пробросе Docker и адресе Fetch Pages. Внутренний порт контейнера 18112 оставьте как есть.
Шаг 2. Скачайте API и готовую схему
В новой папке выполните команды ниже. Не сохраняйте поверх одноимённых рабочих файлов. API - небольшой Node.js-сервер с вымышленными заказами; JSON - ручной workflow из шести узлов. Откройте файлы в редакторе перед запуском: ключей и credentials в них нет.
curl.exe --fail --location "https://ezgpt.ru/storage/article-files/n8n-pagination-mock-api.cjs" --output n8n-pagination-mock-api.cjs
curl.exe --fail --location "https://ezgpt.ru/storage/article-files/n8n-pagination-demo.json" --output n8n-pagination-demo.jsonШаг 3. Запустите API на локальном адресе
Из папки с файлами выполните команду. Образ n8n используется только как среда Node.js для маленького API, второй редактор не запускается. Папка подключена для чтения. Порт опубликован на 127.0.0.1; открывать его в интернет не нужно.
docker run --rm -d --name ezgpt-pagination-api -p 127.0.0.1:18112:18112 --mount "type=bind,source=$((Get-Location).Path),target=/demo,readonly" --entrypoint node n8nio/n8n:2.42.4 /demo/n8n-pagination-mock-api.cjs
docker logs ezgpt-pagination-apiВ журнале должна появиться строка Demo pagination API listening on container port 18112. Если имя контейнера уже занято, выясните, кому он принадлежит; не удаляйте неизвестный контейнер. Сервер слушает 0.0.0.0 внутри контейнера, но доступ с Windows ограничен локальным пробросом.
Шаг 4. Посмотрите первую и последнюю страницы
curl.exe --fail "http://127.0.0.1:18112/orders?page=1"
curl.exe --fail "http://127.0.0.1:18112/orders?page=3"У первой страницы два заказа и next_page = 2. У третьей один заказ O5 и next_page = null. Именно null в нашем API означает конец. Пустой объект, отсутствующее поле и текст "null" - другие значения; не подменяйте ими условие завершения.
{
"page": 1,
"orders": [
{
"order_id": "O1",
"amount": 100
},
{
"order_id": "O2",
"amount": 200
}
],
"next_page": 2
}В других API конец может обозначаться has_more = false, отсутствием next URL или другой структурой. Здесь мы проверяем конкретный контракт своего сервера, а не универсальный формат для любой CRM.
Шаг 5. Импортируйте workflow в отдельную схему
Создайте новый workflow в локальном редакторе n8n. В меню с тремя точками выберите Import from File и файл n8n-pagination-demo.json. Не импортируйте поверх рабочей схемы. Проверьте шесть узлов: Manual Trigger, Fetch Pages, Collection Complete, Split Orders, Ready Orders и Incomplete Fetch. Оставьте ручной запуск, Publish не нужен.
URL Fetch Pages: http://host.docker.internal:18112/orders. На Docker Desktop он обращается из контейнера к локальному порту Windows. localhost внутри контейнера указывает на сам контейнер n8n. Для n8n непосредственно в Windows нужен 127.0.0.1 вместо host.docker.internal. Linux и n8n Cloud в этом маршруте не проверялись.
Шаг 6. Проверьте обычные настройки HTTP Request
- Method: GET; Authentication: None.
- Response Format: JSON.
- Include Response Headers and Status: выключено. На выходе ожидается тело страницы, без дополнительной оболочки body.
- Never Error: выключено; Timeout: 3000 мс.
- Settings: On Error → Stop Workflow, Retry On Fail выключен.
Не добавляйте page одновременно в URL, обычные Query Parameters и настройки пагинации. В нашей схеме этот параметр задаёт только Pagination. При HTTP-ошибке загрузка останавливается: частичная выгрузка не должна незаметно продолжить обработку.
Базовая настройка HTTP Request
Шаг 7. Настройте изменение номера страницы
В Fetch Pages откройте Options → Pagination. Pagination Mode: Update a Parameter in Each Request. В Parameters добавьте Type: Query, Name: page, а Value переведите в Expression и вставьте формулу ниже.
{{ $pageCount + 1 }}$pageCount начинается с нуля, поэтому запросы получат page=1, затем page=2 и page=3. Это подходит нашему API с нумерацией от единицы. Не заменяйте Expression на Fixed: строка с фигурными скобками не должна уходить в API как номер страницы.
Примеры пагинации в официальной документации n8n
Шаг 8. Задайте конец загрузки и предохранитель
Pagination Complete When: Other. В Complete Expression включите Expression и вставьте проверку ниже. Дополнительно включите Limit Pages Fetched, укажите Max Pages: 10 и Interval Between Requests (ms): 100. Эти параметры есть в проверенном узле HTTP Request 4.2 на n8n 2.42.4.
{{ $response.body.next_page === null }}После каждого ответа условие читает его тело. На третьей странице оно станет true, и четвёртого запроса не потребуется. Лимит 10 защищает учебный запуск от слишком длинной загрузки, но достижение лимита само по себе не подтверждает полноту. Для этого ниже есть отдельная проверка. Пауза 100 мс - настройка упражнения, не подходящий лимит для любого внешнего API.
Шаг 9. Проверьте, что последняя страница подтверждена
Откройте If с именем Collection Complete. Добавлено одно Boolean-условие is true; его левое значение в Expression приведено ниже. Оно смотрит на последний item из всех страниц Fetch Pages, а не на очередной заказ. true соединён с Split Orders, false - с Incomplete Fetch.
{{ $input.all().at(-1).json.next_page === null }}Нельзя проверить только next_page текущего item: у первых двух страниц значение не null, но их заказы тоже нужны. Здесь проверка конца коллекции едина для всех полученных страниц. Если лимит оборвал загрузку раньше, все эти страницы идут в Incomplete Fetch.
Incomplete Fetch содержит String-поля status = needs_review и reason = last_page_not_confirmed, а также Number-поле page с Expression {{ $json.page }}. Это данные в OUTPUT, не постоянный журнал и не автоматическое уведомление оператору.
Шаг 10. Разделите массивы на отдельные заказы
В Split Orders выбран Split Out: Field to Split Out = orders, Include = No Other Fields, Destination Field Name не задано. Узел получает три item-страницы и разделяет массивы orders. Два заказа, ещё два и последний один превращаются в пять отдельных items.
Разделить JSON-массив через Split Out
В Ready Orders используется Edit Fields / Manual Mapping. order_id - String с Expression {{ $json.order_id }}, amount - Number с Expression {{ $json.amount }}, status - String с Fixed ready. Include Other Input Fields выключено.
Шаг 11. Выполните схему и проверьте неполную загрузку
Сначала оставьте URL /orders и Max Pages 10. Нажмите Execute workflow. В Fetch Pages должно быть три items с page 1/2/3, а в Ready Orders - пять записей O1-O5. Сумма: 100 + 200 + 300 + 400 + 500 = 1500. Это проверка вымышленного набора, не расчёт выручки компании.
- Нормальная загрузка: 3 страницы, 5 заказов ready, Incomplete Fetch не выполняется.
- Max Pages = 2: 2 страницы в Incomplete Fetch, status needs_review, Ready Orders не выполняется. Верните 10.
- URL /orders?mode=one: 1 страница и те же 5 заказов; возврат /orders восстановит обычные 3 страницы.
- URL /orders?mode=empty: 1 страница с пустым orders; готовых заказов нет. Не создавайте искусственный пустой заказ.
- URL /orders?mode=stuck, Max Pages = 3: API повторяет первую страницу; 3 items needs_review, готовых заказов нет. Верните 10.
- URL /orders?mode=fail: HTTP 500 на второй странице останавливает Fetch Pages, Ready Orders не выполняется. Восстановите URL /orders.
При каждом тесте запускайте всю схему, а не один старый OUTPUT. Удалите закрепление тестовых данных, если вы его включали. В последнем контрольном запуске с /orders и лимитом 10 снова должны появиться все пять заказов.
Зелёное завершение с needs_review означает, что схема обработала неполноту, а не собрала все заказы. HTTP 500 отдельно приводит к ошибке выполнения. Наши тесты проверили оба поведения, не объединяя их в один признак успеха.
Шаг 12. Остановите учебный сервер
Сохраните workflow ручным и неопубликованным. Остановите только контейнер, который создали в шаге 3. Благодаря --rm он удалится после остановки; файлы останутся в вашей папке. Основной n8n и другие контейнеры не трогайте.
docker stop ezgpt-pagination-apiЕсли результат отличается
| Симптом | Причина | Что проверить |
|---|---|---|
| Только O1 и O2 | Pagination выключена | Mode и параметр page |
| Ошибка номера страницы | Формула отправлена текстом | Expression и $pageCount + 1 |
| Запрос к четвёртой странице | Не распознан конец | next_page строго равен null |
| Неполнота названа ready | Нет проверки последнего item | Collection Complete перед Split Out |
| Не найден orders | Добавлена оболочка body | Полный HTTP-ответ выключен |
| Connection refused | API не запущен или неверный адрес | Контейнер, порт, host.docker.internal |
Что изменить перед настоящим API
Проверьте его документацию: имя параметра, нумерацию, размер страницы и признак конца. Если сервер отдаёт next URL или cursor, формула $pageCount + 1 не заменяет этот механизм. Используйте подходящий режим Pagination и отдельно проверьте разрешённый адрес назначения, credentials и перенаправления. Не отключайте проверку TLS-сертификатов.
Успешный обход страниц не гарантирует, что данные не менялись во время загрузки. В рабочей системе могут понадобиться стабильная сортировка, snapshot или фиксация временного диапазона, а также проверка ID и дублей. Этот учебный набор неизменный; такие механизмы здесь не реализованы.
Обработка HTTP-ошибок и тайм-аута
Не подключайте сразу платежи, удаление данных или массовые письма к Ready Orders. Здесь нет долговременного хранения, автоматических повторов, защиты от повторного запуска и проверки бизнес-полей настоящего сервиса. Обработка больших выгрузок тоже требует отдельного теста памяти: наш результат содержит только пять записей.
Что проверено редакцией
11 октября 2026 года workflow выполнен через CLI n8n 2.42.4 в отдельной тестовой базе с локальным учебным API. Шесть сценариев: три страницы 2/2/1, одна страница с пятью заказами, пустой набор, лимит двух страниц, повторяющаяся страница с лимитом три и HTTP 500 на второй странице. Точные ID, суммы, число страниц, отсутствие ready при неполной загрузке и сбое проверены. Учебный API остановлен; существующие workflows и основной контейнер n8n не менялись. Ручной запуск в редакторе, Cloud, реальные credentials, cursor/next URL, автоматические повторы, огромные выгрузки и меняющиеся данные не проверялись. Обложка - редакционная иллюстрация.
Частые вопросы
Чем Pagination отличается от Split Out?
Pagination получает несколько HTTP-страниц. Split Out разделяет уже полученные массивы orders на отдельные записи. В примере сначала собраны три страницы, затем из них получены пять заказов.
Почему Max Pages не означает, что скачаны все данные?
Это предел числа запросов. При Max Pages 2 API ещё обещает третью страницу, поэтому наш If отправляет результат в needs_review. Конец отдельно подтверждается next_page = null в последнем ответе.
Почему у первых страниц next_page не null, но их заказы проходят?
Collection Complete проверяет последний item из всей коллекции страниц через $input.all().at(-1). Если конец подтверждён, в Split Out проходят все страницы, а не только последняя.
Что происходит, если вторая страница вернула 500?
В нашем workflow Never Error выключен и выбран Stop Workflow. Fetch Pages завершился ошибкой, а Ready Orders не выполнился. Схема не выдаёт первые найденные заказы за полную выгрузку.
Можно ли использовать ту же формулу для cursor pagination?
Нет. Номер страницы и cursor - разные контракты API. Для cursor нужно переносить выданный сервером маркер и учитывать его правила завершения. Здесь протестирована только нумерация page от единицы.
