Costruire il Tuo Primo Nodo n8n Personalizzato: Una Guida per Sviluppatori

Vuoi superare i limiti dei connettori pronti e collegare qualsiasi servizio alla tua automazione? Un nodo n8n personalizzato ti permette di incapsulare un’API o una logica complessa in un blocco riutilizzabile e facile da mantenere, migliorando velocità e affidabilità dei tuoi flussi. In questa guida “hands‑on” imparerai a creare un package di community nodes n8n in TypeScript, definire il NodeDescription n8n, implementare il metodo execute in un nodo n8n con gestione degli items e JSON n8n, configurare credenziali (API Key/OAuth2), gestire error handling e logging in n8n, fare debug nodi n8n in locale, e completare il packaging npm per nodi n8n fino alla pubblicazione su npm e marketplace n8n. Troverai esempi concreti, snippet copiabili e best practice per performance e manutenzione. Che tu sia un marketer tecnico o uno sviluppatore, al termine avrai un blueprint chiaro per trasformare una serie di chiamate HTTP in un connettore elegante, testabile e pronto per la produzione.

📚 Nuovo a n8n? Parti dalla guida completa: cos’è n8n e come funziona.

[IMG: schermata progetto “n8n-nodes-hello-api” con cartelle nodes/ e credentials/]

Quando e perché creare un nodo n8n personalizzato

Un nodo personalizzato è la scelta giusta quando:

replichi spesso le stesse chiamate HTTP con parametri simili e vuoi ridurre errore umano e tempo di configurazione
necessiti di UI parametriche (options, collection) per nascondere la complessità dell’API
devi implementare autenticazioni particolari (API Key custom, OAuth2 per integrazioni n8n) e riutilizzarle
vuoi distribuire una capability al team (community nodes n8n) senza esporre segreti o logiche interne

Vantaggi chiave

astrazione e riuso: una volta definito, il nodo “codifica” le best practice per quell’integrazione
affidabilità: centralizzi error handling e logging in n8n con messaggi comprensibili
velocità: on‑boarding più rapido per chi costruisce workflow, con meno “colla” a mano

Limiti e come mitigarli

tempo iniziale: serve scaffolding e packaging npm per nodi n8n; mitighi con template e script
evoluzione API: il nodo va versionato; pianifica minor/patch e test di regressione
funzionalità “edge”: se hai logiche non standard, valuta un approccio ibrido (nodo + sub‑workflow)

Insight: spesso il ROI si vede già al secondo progetto che riusa lo stesso nodo—meno bug, meno training, consistenza negli ambienti.

[IMG: diagramma: HTTP ad‑hoc vs Nodo riutilizzabile → minori errori, time‑to‑value più veloce]

Struttura di progetto e NodeDescription n8n

Crea un package “community” riutilizzabile:

nome: n8n-nodes-hello-api
cartelle:
nodes/HelloApi/HelloApi.node.ts (definizione del nodo)
credentials/HelloApiApi.credentials.ts (credenziale API Key o OAuth2)
index.ts (export di nodi e credenziali)
package.json con metadati e sezione n8n (dichiarazione di nodes e credentials)

Esempio package.json (estratto essenziale):

{
  "name": "n8n-nodes-hello-api",
  "version": "1.0.0",
  "description": "Community node for Hello API",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "lint": "eslint .",
    "prepublishOnly": "npm run build"
  },
  "n8n": {
    "nodes": [
      {
        "type": "node",
        "name": "dist/nodes/HelloApi/HelloApi.node.js"
      }
    ],
    "credentials": [
      {
        "type": "credentials",
        "name": "dist/credentials/HelloApiApi.credentials.js"
      }
    ]
  }
}

NodeDescription n8n (proprietà principali):

displayName, name, version, description
inputs/outputs
credentials (quali tipi accetta il nodo)
properties (UI dei parametri: options/string/number/fixedCollection)
displayOptions per mostrare/nascondere campi in base a resource/operation

Esempio properties (estratto):

export const HelloApiDescription = {
  displayName: 'Hello API',
  name: 'helloApi',
  icon: 'file:helloApi.svg',
  group: ['transform'],
  version: 1,
  description: 'Interact with Hello API',
  defaults: { name: 'Hello API' },
  inputs: ['main'],
  outputs: ['main'],
  credentials: [
    { name: 'helloApiApi', required: true }
  ],
  properties: [
    {
      displayName: 'Resource',
      name: 'resource',
      type: 'options',
      noDataExpression: true,
      options: [
        { name: 'User', value: 'user' },
        { name: 'Account', value: 'account' }
      ],
      default: 'user'
    },
    {
      displayName: 'Operation',
      name: 'operation',
      type: 'options',
      displayOptions: { show: { resource: ['user'] } },
      options: [
        { name: 'List', value: 'list', description: 'List users' },
        { name: 'Get', value: 'get', description: 'Get one user' }
      ],
      default: 'list'
    },
    {
      displayName: 'User ID',
      name: 'userId',
      type: 'string',
      required: true,
      displayOptions: { show: { resource: ['user'], operation: ['get'] } },
      default: ''
    },
    {
      displayName: 'Limit',
      name: 'limit',
      type: 'number',
      typeOptions: { minValue: 1, maxValue: 200 },
      displayOptions: { show: { resource: ['user'], operation: ['list'] } },
      default: 50
    }
  ]
};

[IMG: pannello proprietà in n8n con Resource/Operation/User ID/Limit]

Implementare il metodo execute: items, JSON e mapping

Il cuore del nodo è il metodo execute in un nodo n8n: riceve un array di items, legge i parametri definiti nel NodeDescription e restituisce nuovi items con payload JSON (ed eventualmente binari).

Pattern operativo:

ottieni i parametri con this.getNodeParameter(‘nome’, index)
leggi le credenziali con this.getCredentials(‘helloApiApi’)
costruisci l’HTTP request in base a resource/operation
gestisci paginazione, query e body
mappa la risposta in un array di { json: … }
restituisci items allineati all’input (pairedItem) quando serve riferire l’origine

Esempio execute (semplificato, GET list/get):

async execute() {
  const items = this.getInputData();
  const returnData: INodeExecutionData[] = [];
  const credentials = await this.getCredentials('helloApiApi') as { apiKey: string; baseUrl: string };

  for (let i = 0; i < items.length; i++) {
    const resource = this.getNodeParameter('resource', i) as string;
    const operation = this.getNodeParameter('operation', i) as string;

    let endpoint = '';
    let qs: Record<string, any> = {};
    let method = 'GET';

    if (resource === 'user' && operation === 'list') {
      const limit = this.getNodeParameter('limit', i, 50) as number;
      endpoint = '/users';
      qs.limit = limit;
    }

    if (resource === 'user' && operation === 'get') {
      const userId = this.getNodeParameter('userId', i) as string;
      endpoint = `/users/${encodeURIComponent(userId)}`;
    }

    const options: IHttpRequestOptions = {
      method,
      url: `${credentials.baseUrl}${endpoint}`,
      qs,
      headers: {
        Authorization: `Bearer ${credentials.apiKey}`,
        'Content-Type': 'application/json'
      },
      returnFullResponse: false,
      json: true
    };

    const resp = await this.helpers.httpRequest(options);
    const outItems = Array.isArray(resp) ? resp : [resp];
    for (const row of outItems) {
      returnData.push({ json: row, pairedItem: { item: i } });
    }
  }

  return this.prepareOutputData(returnData);
}

Best practice per gestione degli items e JSON n8n:

mantieni pairedItem quando generi più output per un input, così il debug è più chiaro
se generi record multipli da una singola chiamata, “splitta” correttamente in più items

[IMG: esecuzione con 1 input → N output, pairedItem visibile nel canvas di debug]

Credenziali e OAuth2: sicurezza e UX di configurazione

La configurazione credenziali API in n8n rende il tuo nodo facile da usare e sicuro.

Esempio credenziale API Key (credentials/HelloApiApi.credentials.ts):

export class HelloApiApi implements ICredentialType {
  name = 'helloApiApi';
  displayName = 'Hello API';
  documentationUrl = 'https://docs.helloapi.com';
  properties: INodeProperties[] = [
    {
      displayName: 'Base URL',
      name: 'baseUrl',
      type: 'string',
      default: 'https://api.helloapi.com/v1'
    },
    {
      displayName: 'API Key',
      name: 'apiKey',
      type: 'string',
      typeOptions: { password: true },
      default: ''
    }
  ];
}

Per OAuth2 per integrazioni n8n, definisci il flusso (Auth URL, Token URL, scopes) nella credenziale e in execute usa this.helpers.httpRequest con requestWithAuthentication quando disponibile, evitando di gestire manualmente i token.

Suggerimenti UX:

aggiungi loadOptions se l’API permette di caricare liste (es. “Select Account”): usa un metodo loadOptionsMethod che chiama l’API e costruisce le options
imposta displayOptions per mostrare solo campi pertinenti

[IMG: schermata “Credentials” con Base URL e API Key, pulsante Test]

Error handling e logging: rendi il nodo “debuggable”

Un buon nodo spiega gli errori e registra il contesto minimo:

intercetta HTTP 4xx/5xx e lancia nuove Error con messaggi chiari (endpoint, status, hint)
aggiungi opzioni “Continue On Fail” a livello di node execution (rispetta l’impostazione globale di n8n)
logga dimensione risposta/tempo (se possibile) per diagnosi performance

Pattern semplice:

try {
  const resp = await this.helpers.httpRequest(options);
  // ...
} catch (error) {
  if (this.continueOnFail()) {
    return this.prepareOutputData([{ json: { error: error.message }, pairedItem: { item: i } }]);
  }
  throw new NodeOperationError(this.getNode(), error as Error, { itemIndex: i });
}

Consigli:

non serializzare intere risposte in errori (privacy/costi): estrai solo ciò che serve
documenta messaggi tipici (401 invalid key, 404 not found, 429 rate limit)

[IMG: pannello di esecuzione che mostra un errore 429 con suggerimento “retry after”]

Debug in locale e test rapidi

Per debug nodi n8n in locale:

build locale con npm run build
installa il package nel tuo ambiente n8n (npm i oppure npm link)
riavvia n8n e verifica che il nodo compaia nella palette
crea un workflow minimo (Manual Trigger → tuo nodo) e ispeziona gli items in output

Checklist test:

parametri obbligatori/optional funzionano
credenziali mancanti generano errori chiari
list vs get restituiscono array vs singolo coerenti
pairedItem presente quando espandi output

[IMG: workflow di test con Manual Trigger → Hello API (list) → Debug]

Packaging npm e pubblicazione su marketplace

Packaging npm per nodi n8n:

compila in dist/ con tsc
assicurati che package.json punti a dist/index.js e che la sezione n8n referenzi i file compilati
aggiungi README con istruzioni, esempi, note di sicurezza
versione semantica: patch per fix, minor per nuove opzioni compatibili, major per breaking changes

pubblicazione su npm e marketplace n8n:

pubblica su npm con nome univoco (prefisso n8n-nodes-)
proponi il tuo package come community node n8n con descrizione chiara, icon, categorie
rispondi ai feedback e mantieni changelog; aggiungi test di regressione per gli endpoint critici

[IMG: estratto README su npm con badge versioni e snippet di esempio]

Best practice di progettazione e manutenzione

UI chiara: usa options e fixedCollection per raggruppare parametri correlati
compatibilità: versiona il nodo; evita breaking senza major
performance: batch e paginazione, limita payload e parsing non necessari
sicurezza: non loggare segreti; usa campi password; supporta proxy e rate limit hint
documentazione: esempi minimi e casi reali; errori comuni e come risolverli

Insight: pensa al nodo come “mini SDK” per la tua API. Ogni minuto speso sulla UX dei parametri e sui messaggi di errore fa risparmiare ore a chi costruisce automazioni.

[IMG: checklist “UX, Security, Performance, Docs, Versioning”]

Esempio end‑to‑end: “Hello API – Users”

Obiettivo: elencare utenti (limit) e recuperare un utente per ID.

Credenziali

Base URL: https://api.helloapi.com/v1
API Key: segreta

Proprietà del nodo

Resource: User
Operation: List / Get
Limit (List), User ID (Get)

execute (riassunto)

se List: GET /users?limit=n → restituisce array users come items
se Get: GET /users/{id} → restituisce 1 item

Test

Manual Trigger → Hello API (List, limit 5)
Aggiungi un Set per visualizzare solo fields richiesti (id, name, email)
Prova errore 404 su Get con ID inesistente; conferma messaggio chiaro

[IMG: canvas con rami List e Get, output tabellare degli utenti]

Quick Takeaways

Un nodo n8n personalizzato incapsula un’integrazione in un blocco riutilizzabile e sicuro.
Definisci un NodeDescription n8n pulito: properties, credentials, displayOptions.
Il metodo execute gestisce items, mapping e chiamate HTTP; usa pairedItem e rispetta Continue On Fail.
Configura credenziali (API Key o OAuth2) per un’esperienza d’uso semplice e sicura.
Fai debug locale con build+link e un workflow minimo; testa errori e edge cases.
Pubblica come community nodes n8n su npm/marketplace con versioning e README chiaro.

Conclusione

Costruire un nodo n8n personalizzato è il modo più efficace per trasformare un’integrazione ricorrente in un acceleratore aziendale: UI amichevole, credenziali sicure, metodo execute robusto e messaggi di errore utili. Con una struttura di progetto chiara, un NodeDescription n8n ben pensato e un packaging npm per nodi n8n, il tuo team potrà arricchire i workflow senza riscrivere ogni volta chiamate HTTP e mapping. Parti da un MVP (Resource/Operation essenziali), aggiungi loadOptions, gestisci paginazione e rate limit, poi investi nella documentazione. Se sei un marketer tecnico, questo approccio ti permette di standardizzare integrazioni “chiave” e scalare la produttività del team, riducendo i tempi di go‑live e gli errori operativi. Pronto a costruire il tuo primo connettore? Scegli un’API che usi spesso, crea il package “n8n-nodes-”, implementa List/Get e pubblica la prima versione: il resto sarà un’evoluzione naturale.

FAQ

Cos’è il NodeDescription n8n e perché è importante?
È la “scheda tecnica” del nodo: definisce nome, versioni, credenziali, properties e UI. Un buon NodeDescription semplifica l’uso e riduce gli errori.
Come funziona il metodo execute in un nodo n8n?
Riceve items in input, legge parametri, chiama l’API (se serve) e restituisce nuovi items con json/binary. Gestisci pairedItem e Continue On Fail per un debug efficace.
Come integro OAuth2 nel mio nodo?
Definisci una credenziale OAuth2 e usa gli helper di richiesta autenticata. Configura Auth/Token URL, scopes e gestisci i refresh token in trasparenza per l’utente.
Qual è il flusso consigliato per debug nodi n8n in locale?
Build del package, installazione locale (npm link o install), riavvio n8n, workflow minimo con Manual Trigger → tuo nodo. Testa sia happy path che errori.
Come pubblico il mio nodo su npm e marketplace n8n?
Prepara dist/, aggiorna package.json (sezione n8n), scrivi README, usa versioning semantico e pubblica su npm. Proponilo poi come community nodes n8n con icon e descrizione.

Hai già in mente quale servizio vorresti integrare come nodo? Raccontamelo nei commenti e condividi questa guida con chi nel tuo team costruisce automazioni: qual è l’API che trasformerebbe subito i tuoi workflow se avessi un connettore dedicato?