Кастомные ноды для n8n: разработка под ключ

Зачем нужны кастомные ноды?

Стандартный набор n8n включает HTTP Request, Function, Webhook и другие. Однако при интеграции с современными API часто возникают задачи, которые сложно решить встроенными средствами: сложная пагинация, retry с экспоненциальной задержкой, поддержка нескольких версий API, встроенный OAuth2 с refresh-токенами. Кастомная нода — это TypeScript-пакет, который регистрируется в n8n и работает как нативная. Она даёт полный контроль над логикой и переиспользуется в любом workflow.

Возьмём реальный кейс: интеграция с CRM с rate limit 100 запросов/мин и необходимостью обработки ошибок 429 и 500. В кастомной ноде мы реализовали очередь запросов с задержкой, retry с backoff и собственный мониторинг. Результат — стабильная синхронизация десятков тысяч контактов без ручного вмешательства. Наш опыт — более 20 интеграций для CRM, платёжных систем и пагинированных API. Работаем с актуальными версиями n8n и TypeScript.

«Custom nodes are TypeScript packages that extend n8n’s functionality» — n8n docs

Как мы разрабатываем кастомные ноды?

Разработка начинается с анализа документации API: определяем ресурсы, операции, лимиты. Затем проектируем схему credentials, структуру ноды и параметры. Реализация на TypeScript с учётом всех сценариев, включая обработку ошибок. После — тестирование с моками и интеграционные тесты. Финальный этап — упаковка и поставка через npm registry или архив.

Типовая структура проекта

my-n8n-nodes/ ├── nodes/ │ └── MyService/ │ ├── MyService.node.ts │ ├── MyService.node.json │ └── myservice.svg ├── credentials/ │ └── MyServiceApi.credentials.ts ├── package.json └── tsconfig.json 

Credentials и основная нода

package.json:

{ "name": "n8n-nodes-myservice", "version": "1.0.0", "description": "n8n nodes for MyService API", "main": "index.js", "n8n": { "n8nNodesApiVersion": 1, "credentials": ["dist/credentials/MyServiceApi.credentials.js"], "nodes": ["dist/nodes/MyService/MyService.node.js"] }, "devDependencies": { "n8n-workflow": "*", "typescript": "^5.0.0" } } 

Credentials:

// credentials/MyServiceApi.credentials.ts import { ICredentialType, INodeProperties } from 'n8n-workflow'; export class MyServiceApi implements ICredentialType { name = 'myServiceApi'; displayName = 'MyService API'; documentationUrl = 'https://docs.myservice.com/api'; properties: INodeProperties[] = [ { displayName: 'API Key', name: 'apiKey', type: 'string', typeOptions: { password: true }, default: '', }, { displayName: 'Base URL', name: 'baseUrl', type: 'string', default: 'https://api.myservice.com/v1', }, ]; } 

Основная нода:

// nodes/MyService/MyService.node.ts import { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription, NodeApiError, } from 'n8n-workflow'; export class MyService implements INodeType { description: INodeTypeDescription = { displayName: 'MyService', name: 'myService', icon: 'file:myservice.svg', group: ['transform'], version: 1, description: 'Interact with MyService API', defaults: { name: 'MyService' }, inputs: ['main'], outputs: ['main'], credentials: [ { name: 'myServiceApi', required: true } ], properties: [ { displayName: 'Resource', name: 'resource', type: 'options', options: [ { name: 'Contact', value: 'contact' }, { name: 'Deal', value: 'deal' }, ], default: 'contact', }, { displayName: 'Operation', name: 'operation', type: 'options', displayOptions: { show: { resource: ['contact'] } }, options: [ { name: 'Create', value: 'create', action: 'Create a contact' }, { name: 'Get', value: 'get', action: 'Get a contact' }, { name: 'Update', value: 'update', action: 'Update a contact' }, ], default: 'create', }, { displayName: 'Email', name: 'email', type: 'string', displayOptions: { show: { resource: ['contact'], operation: ['create'] } }, default: '', required: true, }, ], }; async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> { const items = this.getInputData(); const returnData: INodeExecutionData[] = []; const credentials = await this.getCredentials('myServiceApi'); const resource = this.getNodeParameter('resource', 0) as string; const operation = this.getNodeParameter('operation', 0) as string; for (let i = 0; i < items.length; i++) { try { let responseData: unknown; if (resource === 'contact' && operation === 'create') { const email = this.getNodeParameter('email', i) as string; responseData = await this.helpers.request({ method: 'POST', url: `${credentials.baseUrl}/contacts`, headers: { 'Authorization': `Bearer ${credentials.apiKey}`, 'Content-Type': 'application/json', }, body: { email }, json: true, }); } returnData.push({ json: responseData as object }); } catch (error) { if (this.continueOnFail()) { returnData.push({ json: { error: error.message }, pairedItem: i }); continue; } throw new NodeApiError(this.getNode(), error); } } return [returnData]; } } 

Как установить кастомную ноду в n8n?

Установка осуществляется через npm: npm install /path/to/my-n8n-nodes или из публичного registry. При использовании Docker монтируйте директорию с нодами через volume и укажите переменную окружения N8N_CUSTOM_EXTENSIONS. После установки нода появляется в редакторе и готова к использованию.

Кастомная нода против цепочки HTTP + Function: что выбрать?

Типы credentials для кастомных нод

Кастомные ноды позволяют реализовать любые типы авторизации: API Key, OAuth2, Basic Auth, Bearer Token, Session Cookie. Для OAuth2 поддерживается автоматическое обновление refresh-токенов. В credentials можно добавить кастомную проверку и документацию.

Объём работ и сроки

В услугу входит: исходный код ноды (TypeScript) с комментариями, credentials-класс, инструкция по установке (npm/docker), документация по использованию и тестовое покрытие (модульные + интеграционные тесты). Также предоставляем консультацию по интеграции с существующими workflow.

Сроки: простая нода с 2–3 операциями и credentials — 2–4 дня. Сложная нода с polling trigger, пагинацией, binary data — 1–2 недели. Стоимость рассчитывается индивидуально после анализа вашего API. Инвестиция в кастомную ноду окупается за счёт автоматизации. Свяжитесь с нами для оценки — пришлём смету в течение дня. Закажите разработку, и ваша интеграция перестанет требовать ручного вмешательства.

Почему стоит инвестировать в кастомную ноду?

Кастомная нода — это не просто удобство, это снижение operational overhead. Вместо десятков одинаковых workflow вы получаете единую, протестированную интеграцию. Мы гарантируем стабильную работу и предоставляем поддержку. Наши инженеры имеют опыт работы с самыми разными API — от платёжных до CRM. Получите консультацию инженера — напишите нам.

Как происходит тестирование кастомных нод?

Мы проводим модульное и интеграционное тестирование. Внедряем моки для HTTP-запросов, тестируем граничные случаи и обработку ошибок. Это гарантирует стабильную работу в боевых сценариях. Типичное покрытие — около 80% строк кода.

Типичные ошибки при разработке custom nodes

• Неправильная типизация параметров displayOptions
• Отсутствие обработки ошибок для каждого вызова API
• Неправильное использование credentials в execute
• Игнорирование rate limit и пагинации
• Отсутствие тестов

Подробнее о создании custom nodes читайте в официальной документации n8n.