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-сценарії в коді: генератор замість кліків у редакторі