Loop Over Items в n8n: Split in Batches, Merge, лимиты API и обработка массивов ¶

Обновлено: 2026-05-29

Loop Over Items — нода для обработки входящих items пачками. Раньше её часто называли Split in Batches, и этот старый термин до сих пор встречается в запросах и старых workflow. Нода помогает пройти большой список аккуратно: по одному лиду, по 10 строк, по 50 товаров или любым batch size, который не ломает внешний API.

Главная идея

Loop Over Items нужен, когда у вас уже есть набор items и его нужно обработать частями. Если внутри одного item лежит массив, сначала используйте Split Out или Code node, чтобы превратить элементы массива в отдельные items.

Loop Over Items, Split Out и Merge: в чём разница ¶

Нода	Для чего нужна	Пример
Split Out	разбить массив внутри одного item на много items	список товаров из одного JSON
Loop Over Items	обработать items пачками	по 5 лидов за раз отправлять в CRM
Merge	объединить две ветки данных	соединить данные заявки и результат проверки DaData
Aggregate/Summarize	собрать items обратно в сводку	сделать один отчёт из 100 строк

Простой сценарий: отправить строки в API без 429 ¶

Получите список строк из Google Sheets, CRM или HTTP Request.
Отфильтруйте уже обработанные записи.
Передайте items в Loop Over Items.
Выберите batch size: 1, 5, 10 или больше, в зависимости от лимитов API.
Внутри loop-входа выполните HTTP Request или CRM-ноду.
Добавьте Wait, если API требует паузу.
После done output соберите итоговый отчёт или отправьте уведомление.

Как выбрать batch size ¶

API/задача	Batch size	Почему
Telegram уведомления	1–5	лучше не слать всплеском в один чат
CRM создание лидов	1–10	ошибку одной записи проще отловить
Google Sheets чтение/обновление	10–100	зависит от операции и лимитов
AI-запросы	1–3	дорого, медленно и зависит от модели
внутренняя БД	50–500	если база и индексы выдерживают

Если не знаете лимит — начните с 1 или 5, добавьте лог статусов и только потом увеличивайте batch size.

Done output: что делать после цикла ¶

У Loop Over Items есть выход для обработки текущей пачки и выход после завершения всех items. Частая ошибка — отправить итоговое уведомление из loop-ветки, и тогда оно улетает много раз. Итоги, summary, отчёт об ошибках и финальное сообщение менеджеру отправляйте после done output.

Дедупликация в цикле ¶

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

external_id из ID заявки, заказа или платежа;
хеш из телефона + услуги + даты;
запись в PostgreSQL/Data Table о том, что событие уже принято;
проверка статуса перед отправкой в CRM.

Merge после проверки данных ¶

Merge полезен, когда нужно соединить исходную запись и результат внешней проверки. Например, Tilda прислала телефон и имя, DaData вернула нормализованный телефон, а CRM требует оба набора данных. В таком workflow важно сохранить ID исходной записи, чтобы после Merge не перепутать, к какой заявке относится enriched-поле.

Ошибки и частые ловушки ¶

Симптом	Причина	Что сделать
цикл никогда не заканчивается	ветка loop неправильно возвращается к ноде или данные генерируются заново	проверить схему и done output
финальное сообщение приходит много раз	уведомление стоит внутри loop-ветки	перенести уведомление на done output
API отвечает 429	слишком большой batch size	уменьшить batch size и добавить Wait
после Merge данные перемешались	нет стабильного ключа для сопоставления	сохранять external_id до Split/Loop/Merge
обрабатывается только первый item	Code node вернул один item вместо массива items	проверить формат возвращаемых данных

Связанные материалы ¶

Wait node — пауза между пачками.
Merge node — объединение веток данных.
Code node — правильный формат items.
Webhook idempotency — защита от повторной обработки.

Production-паттерн использования ноды

Материал «Loop Over Items в n8n: Split in Batches, Merge, лимиты API и обработка массивов ¶» стоит применять как чеклист для ревью workflow. Перед использованием ноды в production уточните, какой item приходит на вход, какие поля обязательны, что происходит с пустыми значениями и как downstream-ноды узнают, что шаг завершился успешно.

Типичная ошибка в n8n — проверить ноду на одном happy-path примере и не прогнать массив items, пустой массив, дубли и ошибку внешнего сервиса. Для надежного сценария добавьте явную ветку обработки ошибок, понятное имя execution, ограничение на размер payload и логирование ключевых диагностических полей без секретов.

Чеклист ревью

Проверьте, сохраняется ли структура items после этой ноды.
Опишите, какие поля добавляются, перезаписываются или удаляются.
Добавьте тест на пустой вход, повтор и частичный сбой.
Свяжите ноду с error branch, retry policy и наблюдаемостью.

Если нода участвует в платежах, CRM, рассылках или AI-ответах, перед включением автоматического write-действия лучше добавить dry-run режим и ручное подтверждение для спорных случаев.

Ноды n8n — открыть связанный материал для проверки контекста.
Items и JSON — открыть связанный материал для проверки контекста.
Диагностика — открыть связанный материал для проверки контекста.
Review workflow — открыть связанный материал для проверки контекста.