n8n как код: генератор сценариев вместо редактора

Сценарий в n8n удобно собирать мышью, пока он один и пока вы его помните. Дальше появляются две проблемы, которые редактор не решает.

Первая — через полгода никто не скажет, почему фильтр настроен именно так. В бесплатной версии n8n истории изменений нет — сравнивать не с чем, а человек, который это делал, уже не помнит.

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

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

#Что именно описывают кодом

Не весь n8n, а один сценарий. Скрипт строит тот же JSON, который редактор отдаёт при экспорте: список нод, их параметры и связи между ними.

const node = (name, type, params, pos) => ({
  id: nodeId(name),
  name, type, position: pos,
  parameters: params,
  typeVersion: 1,
})

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

Результат заливают через публичный API:

curl -X PUT "$BASE/api/v1/workflows/$ID" \
     -H "X-N8N-API-KEY: $KEY" \
     -H 'Content-Type: application/json' \
     --data @workflow.json

#Почему id нод должны быть детерминированными

Это главная деталь, без которой подход не работает.

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

Исправляют это одной строкой — id становится хешем от названия ноды:

import { createHash } from 'node:crypto'

const nodeId = (name) => createHash('md5').update(name).digest('hex')

Теперь нода с тем же названием всегда получает тот же id. Повторная заливка не трогает связи, а разница между версиями показывает ровно то, что вы изменили.

#Как держать один сценарий на нескольких аккаунтах

Здесь подход окупается.

Всё, что отличает клиентов, выносят в профили: учётные данные, путь вебхука, название сценария, идентификатор воронки. Логика остаётся общей.

const ACCOUNTS = {
  first:  { creds: 'crm-first',  hook: '…', pipeline: 'PIPELINE_A' },
  second: { creds: 'crm-second', hook: '…', pipeline: 'PIPELINE_B' },
}

Запуск с ключом профиля собирает и заливает нужную копию:

node build-flow.js --account=second --push

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

#Как проверять логику тестами

Когда сценарий — это код, его поведение можно прогнать на примерах, не трогая рабочий инстанс.

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

Это не замена проверке на живых данных. Это способ не ловить руками одни и те же ошибки после каждой правки.

#Почему редактор после этого только для чтения

После перехода на генератор в редакторе n8n можно смотреть и запускать вручную. Править — нет.

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

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

#Когда этого делать не стоит

У подхода есть цена: генератор нужно написать, и для одного простого сценария это лишнее.

Он оправдывает себя, когда выполняется хотя бы одно:

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

Для разового «перекинуть форму в таблицу» хватит редактора.

#Выводы

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

#Частые вопросы

#Можно ли совмещать генератор и ручные правки?

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

#Что делать с учётными данными?

Они остаются в n8n. Генератор оперирует только их идентификаторами, поэтому в репозитории не хранится ни одного секрета.

#Есть ли готовые инструменты вместо своего генератора?

Есть встроенные экспорт и импорт JSON и несколько сторонних обёрток над публичным API. Они переносят сценарий как есть. Как только появляется второй аккаунт с той же логикой, нужен слой, который подставляет отличия, — а это и есть генератор.

#Источники

n8n Public API — методы для чтения и обновления сценариев
Из собственного опыта

Как держать n8n-сценарии в коде: генератор вместо кликов в редакторе