Los n8n custom nodes son la forma más poderosa de extender las capacidades de n8n cuando los más de 400 nodos nativos no cubren lo que necesitás. Si trabajás con una API interna, un servicio regional de LATAM o cualquier herramienta que n8n no soporte todavía, podés crear tu propio nodo personalizado desde cero.
Los n8n custom nodes se desarrollan con TypeScript, se empaquetan como módulos npm y se instalan en tu instancia como cualquier otra extensión. En esta guía completa vas a aprender cómo funciona la arquitectura de nodos, cómo crear tu primer custom node paso a paso, cómo manejar credenciales y cómo instalarlo en tu instancia self-hosted. Si sos desarrollador y trabajás con n8n, crear custom nodes es el paso natural para integrar herramientas específicas de tu stack.
¿Qué son los n8n custom nodes y cuándo crearlos?
Un custom node en n8n es básicamente un paquete npm que extiende la funcionalidad de la plataforma agregando una integración que no existe de forma nativa. Antes de embarcarte en crear uno, evaluá si es realmente necesario:
Usá el nodo HTTP Request primero
Para la mayoría de las APIs REST, el nodo HTTP Request de n8n es más que suficiente. No necesitás un custom node si la API es estándar y no la vas a reutilizar decenas de veces en distintos workflows.
Creá un n8n custom node cuando
- Necesitás integrar una API compleja con autenticación especial (OAuth2 con flujos custom, firmas HMAC, etc.).
- Querés que otros usuarios de tu organización puedan usar la integración sin conocer los detalles de la API.
- Querés distribuir el nodo en npm para que la comunidad lo aproveche.
- La API requiere manejo de binarios (archivos), streams o WebSockets que el nodo HTTP Request no maneja bien.
- Querés un nodo con una UI rica: campos dinámicos, validación en tiempo real y opciones condicionales.
- Necesitás integrar servicios regionales de LATAM (pasarelas de pago locales, servicios de facturación electrónica, APIs gubernamentales) que la comunidad de n8n aún no ha implementado.
Tipos de n8n custom nodes que podés crear
Antes de escribir código, es importante que entiendas que existen diferentes tipos de nodos en n8n, y tu custom node puede ser cualquiera de ellos:
Regular Node (Nodo de acción)
Es el tipo más común. Recibe datos de entrada, ejecuta una operación (llamada a API, transformación de datos, etc.) y pasa los resultados al siguiente nodo del workflow. La mayoría de los n8n custom nodes que vas a crear caen en esta categoría.
Trigger Node (Nodo disparador)
Inicia un workflow cuando ocurre un evento externo. Puede funcionar por polling (consultando periódicamente una API) o por webhook (recibiendo una notificación HTTP). Si tu servicio envía webhooks, este es el tipo que necesitás.
Credential Node (Nodo de credenciales)
Técnicamente no es un «nodo» sino un archivo complementario que define cómo se autentican las credenciales. Casi siempre vas a crear uno junto con tu custom node para manejar API keys, tokens OAuth2 u otros métodos de autenticación.
Estructura de un n8n custom node
Un custom node de n8n es un paquete npm con una estructura específica que la plataforma reconoce automáticamente. Estos son los archivos clave:
- package.json: el manifiesto del paquete con la propiedad especial
n8nque le dice a la plataforma dónde encontrar los nodos y credenciales. - Archivo del nodo (MiNodo.node.ts): contiene la lógica principal — nombre, descripción, icono, propiedades (campos de configuración) y el método
execute()que se ejecuta cuando el nodo corre. - Archivo de credenciales (MiNodoApi.credentials.ts): define cómo se autentican las credenciales del nodo (API Key, OAuth2, Basic Auth, etc.).
- Icono (opcional): imagen SVG o PNG que aparece en el panel de n8n junto al nombre del nodo.
La estructura del package.json debe incluir la sección especial de n8n para que la plataforma detecte tu custom node:
{
"name": "n8n-nodes-mi-servicio",
"version": "0.1.0",
"n8n": {
"nodes": [
"dist/nodes/MiNodo/MiNodo.node.js"
],
"credentials": [
"dist/credentials/MiNodoApi.credentials.js"
]
}
}La convención de nombres para paquetes de n8n custom nodes es n8n-nodes-nombre-del-servicio. Seguir esta convención hace que tu nodo sea más fácil de encontrar en npm.
Paso 1: Configurar el entorno para desarrollar n8n custom nodes
Para crear tu primer custom node necesitás Node.js 18+ y el generador oficial de n8n. Empezá instalando las herramientas necesarias:
# Instalá n8n globalmente (si aún no lo tenés)
npm install -g n8n
# Usá el generador oficial para crear la estructura del proyecto
npx @n8n/create-nodes-moduleEl generador te hace preguntas para scaffoldear la estructura del proyecto:
- Nombre del nodo (por ejemplo: «MercadoPago», «FacturaElectronica»).
- Tipo de nodo (Regular Node o Trigger Node).
- Método de autenticación (API Key, OAuth2 o ninguna).
Esto genera una carpeta con toda la estructura necesaria. Instalá las dependencias y compilá:
cd n8n-nodes-mi-servicio
npm install
# Compilar TypeScript
npm run build
# Para desarrollo con recarga automática
npm run devEl proyecto viene preconfigurado con TypeScript, ESLint y el watcher de n8n para que puedas desarrollar con recarga en tiempo real. Cada vez que guardás un cambio, el nodo se recompila automáticamente.
Paso 2: Crear la estructura del archivo del n8n custom node
El archivo principal del nodo es donde definís toda su funcionalidad. Un nodo mínimo pero funcional tiene esta estructura en TypeScript:
import {
IExecuteFunctions,
INodeExecutionData,
INodeType,
INodeTypeDescription,
} from 'n8n-workflow';
export class MiNodo implements INodeType {
description: INodeTypeDescription = {
displayName: 'Mi Nodo Custom',
name: 'miNodo',
icon: 'file:mi-nodo.svg',
group: ['transform'],
version: 1,
description: 'Descripción de lo que hace tu nodo custom',
defaults: {
name: 'Mi Nodo Custom',
},
inputs: ['main'],
outputs: ['main'],
credentials: [
{
name: 'miNodoApi',
required: true,
},
],
properties: [
{
displayName: 'Operación',
name: 'operation',
type: 'options',
options: [
{ name: 'Crear', value: 'create' },
{ name: 'Obtener', value: 'get' },
{ name: 'Listar', value: 'list' },
],
default: 'get',
description: 'Operación a ejecutar',
},
{
displayName: 'ID del Recurso',
name: 'resourceId',
type: 'string',
default: '',
displayOptions: {
show: {
operation: ['get'],
},
},
description: 'ID del recurso a obtener',
},
],
};
async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
const items = this.getInputData();
const returnData: INodeExecutionData[] = [];
const operation = this.getNodeParameter('operation', 0) as string;
const credentials = await this.getCredentials('miNodoApi');
for (let i = 0; i < items.length; i++) {
try {
if (operation === 'get') {
const resourceId = this.getNodeParameter('resourceId', i) as string;
const response = await this.helpers.request({
method: 'GET',
url: `https://api.mi-servicio.com/recursos/${resourceId}`,
headers: {
Authorization: `Bearer ${credentials.apiKey}`,
},
json: true,
});
returnData.push({ json: response });
}
} catch (error) {
if (this.continueOnFail()) {
returnData.push({ json: { error: error.message } });
continue;
}
throw error;
}
}
return [returnData];
}
}Fijate en algunos detalles importantes de este ejemplo de n8n custom nodes:
- La propiedad
descriptiondefine cómo se ve el nodo en el panel de n8n: nombre, icono, campos de configuración. - El campo
displayOptionspermite mostrar u ocultar propiedades según la operación seleccionada — esto hace que la UI sea más limpia. - El método
execute()contiene la lógica que se ejecuta cuando el nodo corre en un workflow. Iterá sobre cada item de entrada para procesar datos en lote. - El bloque
try/catchconcontinueOnFail()permite que el workflow continúe aunque un item falle — una práctica recomendada en producción.
Paso 3: Manejar credenciales en tu n8n custom node
El archivo de credenciales define cómo los usuarios configuran la autenticación. Acá tenés un ejemplo para autenticación con API Key:
import {
ICredentialType,
INodeProperties,
} from 'n8n-workflow';
export class MiNodoApi implements ICredentialType {
name = 'miNodoApi';
displayName = 'Mi Nodo API';
documentationUrl = 'https://docs.mi-servicio.com/api';
properties: INodeProperties[] = [
{
displayName: 'API Key',
name: 'apiKey',
type: 'string',
typeOptions: {
password: true,
},
default: '',
description: 'Tu API Key de Mi Servicio',
},
{
displayName: 'Entorno',
name: 'environment',
type: 'options',
options: [
{ name: 'Producción', value: 'production' },
{ name: 'Sandbox', value: 'sandbox' },
],
default: 'sandbox',
description: 'Entorno de la API',
},
];
}Este patrón de incluir un selector de entorno (producción/sandbox) es especialmente útil cuando creás n8n custom nodes para pasarelas de pago o APIs de LATAM que suelen tener ambientes de prueba separados.
Instalar y probar tu n8n custom node
Tenés tres opciones para instalar tu custom node dependiendo de tu setup:
Opción 1: Link de desarrollo local (para pruebas)
Ideal mientras estás desarrollando. En la carpeta del nodo, compilá y hacé npm link. Luego en la carpeta de n8n, ejecutá npm link nombre-de-tu-paquete. Reiniciá n8n y tu nodo aparecerá en el panel.
# En la carpeta del custom node
npm run build
npm link
# En la carpeta de instalación de n8n
npm link n8n-nodes-mi-servicio
# Reiniciar n8n
n8n startOpción 2: Variable de entorno (self-hosted)
Si tenés n8n self-hosted, podés especificar la ruta al nodo con la variable de entorno:
N8N_CUSTOM_EXTENSIONS='/ruta/a/n8n-nodes-mi-servicio'n8n cargará automáticamente todos los custom nodes que encuentre en esa carpeta al iniciar.
Opción 3: Publicar en npm (para distribución)
Si querés que otros usuarios instalen tu nodo, publicalo en npm con npm publish. Después, cualquier persona puede instalarlo desde la UI de n8n: Settings → Community Nodes → Install. Esta opción funciona tanto en n8n Cloud como en instancias self-hosted.
Después de instalar con cualquier método, reiniciá n8n. Tu custom node aparece en el panel bajo la categoría que definiste en group.
Errores comunes al crear n8n custom nodes
Después de ayudar a varios desarrolladores en LATAM a crear sus propios nodos, estos son los errores que veo con más frecuencia:
- El nodo no aparece en el panel: el 90% de las veces es porque la ruta en
package.jsonapunta a los archivos.tsen lugar de los.jscompilados endist/. Verificá que las rutas en la secciónn8n.nodesapunten a los archivos JavaScript. - Error de tipos en TypeScript: asegurate de usar las interfaces correctas de
n8n-workflow. El tipo de retorno deexecute()debe serPromise<INodeExecutionData[][]>— fijate en el doble array. - Credenciales no se cargan: el nombre en
credentials.namedel archivo del nodo debe coincidir exactamente con elnamedel archivo de credenciales. - El nodo falla silenciosamente: siempre implementá el patrón
try/catchconcontinueOnFail()y logueá errores conthis.loggerpara facilitar el debugging. - Problemas con Docker: si corrés n8n en Docker, asegurate de montar el volumen donde están tus custom nodes y que la variable
N8N_CUSTOM_EXTENSIONSapunte a la ruta dentro del contenedor.
Mejores prácticas para n8n custom nodes en producción
Si vas a usar tu custom node en un entorno de producción o a distribuirlo a la comunidad, seguí estas recomendaciones:
- Versioná tu nodo: usá la propiedad
versionen el description. Si hacés cambios breaking, incrementá la versión para que n8n pueda manejar la migración. - Manejá la paginación: si tu API devuelve resultados paginados, implementá la lógica de paginación dentro del nodo para que el usuario no tenga que hacerlo manualmente.
- Validá los inputs: no confíes en que el usuario va a ingresar datos válidos. Validá tipos, rangos y formatos antes de hacer la llamada a la API.
- Documentá las propiedades: usá el campo
descriptionen cada propiedad para que aparezca como tooltip en la UI de n8n. - Incluí un README completo: si publicás en npm, el README es lo primero que van a ver los usuarios. Incluí ejemplos de uso, screenshots y requisitos de configuración.
- Escribí tests: usá Jest para testear la lógica de tu nodo. n8n provee helpers para simular el contexto de ejecución en los tests unitarios.
Preguntas frecuentes sobre n8n custom nodes
¿Necesito saber TypeScript para crear n8n custom nodes?
TypeScript es el lenguaje recomendado y toda la documentación oficial de n8n lo usa. Sin embargo, como TypeScript es un superset de JavaScript, podés escribir JavaScript válido en archivos .ts y va a compilar sin problemas. Lo que sí necesitás respetar son las interfaces y tipos que n8n espera — pero el generador de proyectos ya te da la estructura base.
¿Los n8n custom nodes funcionan en n8n Cloud?
Sí, pero solo si los publicás en npm. n8n Cloud permite instalar community nodes desde la interfaz gráfica en Settings → Community Nodes. No podés usar el método de variable de entorno ni npm link en n8n Cloud.
¿Cuánto tiempo lleva crear un custom node básico?
Con el generador de n8n y experiencia básica en JavaScript/TypeScript, un nodo simple con una o dos operaciones te puede llevar entre 2 y 4 horas. Un nodo complejo con múltiples operaciones, autenticación OAuth2 y manejo de archivos binarios puede tomar un par de días.
¿Puedo crear n8n custom nodes para servicios de LATAM?
¡Absolutamente! De hecho, es uno de los mejores casos de uso. Servicios como MercadoPago, Rappi, AFIP, SAT México, o bancos locales no siempre tienen nodos oficiales en n8n. Crear un custom node para estos servicios no solo te ayuda a vos, sino que puede beneficiar a toda la comunidad latina de n8n si lo publicás en npm.
¿Cómo actualizo un custom node que ya está instalado?
Si lo instalaste desde npm, podés actualizarlo desde la UI de n8n en Settings → Community Nodes. Si usás el método de variable de entorno, simplemente reemplazá los archivos compilados y reiniciá n8n. Siempre incrementá la versión en package.json antes de publicar una actualización.
