Configuración de credenciales con API key para custom nodes en n8n

Crear un custom node en n8n para verificar correos es más sencillo de lo que parece. Aquí verás cómo configurar las credenciales con una API key, ajustar el JSON de la interfaz y compilar con pnpm para probarlo en local. Se enfatiza el uso de expresiones, nombres que coincidan y pequeñas correcciones de tipado que evitan errores.

¿Cómo configurar credentials con API key en n8n?

Configura primero el fichero de credenciales. Copia el bloque de Setup Credentials y pégalo en tu IDE. Después ajusta cada campo con cuidado.

• Asegura que el nombre coincide con el del archivo del nodo, por ejemplo en email.node.ts. Debe ser idéntico para que funcione.
• Usa el campo display name. Si tu editor sugiere autocompletado, aprovéchalo.
• Recuerda que no es un objeto JSON sino una variable. Si tu linter marca en rojo, probablemente espera punto y coma.
• Añade la propiedad faltante en la documentación, type options, con el valor password true. Así la API key no se mostrará en texto plano.
• En la sección de authenticate coloca exactamente el parámetro que tu API espera. En el ejemplo se usa API_key. Verifica y copia el nombre desde la plataforma de verificación de emails para evitar errores.
• Observa el parámetro qs. Significa query string y define que la API key viaja en la URL. También podría ir en header o en body si así lo exige el servicio.
• Usa una expresión para leer la credencial. En n8n las expresiones comienzan con signo igual, por eso se usa '={{$credentials.apiKey}}'.
• Si renombras el parámetro a api_key, recuerda cambiarlo también en la expresión correspondiente para mantener la coincidencia.
• Si el linter marca error de tipado, añade el tipo adecuado en authenticate. En el ejemplo se corrige con generic.
• Agrega un ícono. Tras display name añade icon con el valor file:email.svg e importa el ícono. El archivo debe estar en la misma carpeta.

¿Qué editar en el JSON del nodo para la interfaz gráfica?

Copia el bloque de la sección add node metadata y pégalo en tu editor. Cambia el nombre del nodo a Verificar email. El resto queda igual.

• Crea una carpeta llamada Verificar email y mueve dentro el nodo, el JSON y el ícono.
• Edita package.json. Coloca el nombre de tu custom node, por ejemplo Verificar email. El enlace de GitHub puede quedar temporal si estás en desarrollo.
• Actualiza los paths de credenciales y del nodo. Elimina referencias anteriores y cuida no dejar comas finales.

¿Cómo compilar, enlazar y probar el custom node?

Realiza la instalación y las pruebas locales para validar el flujo completo.

• Instala dependencias con pnpm. Si es necesario, instala rimraf con pnpm install rimraf para limpiar directorios innecesarios.
• Ejecuta pnpm install y después pnpm run build.
• Para pruebas locales ve a la guía test your node y a run your node locally. Si es la primera vez, crea la carpeta .n8n y la subcarpeta custom y ejecuta los tres comandos indicados en troubleshooting.
• Enlaza el paquete de forma local. Usa pnpm link y el path absoluto de tu proyecto. Copia el path desde tu IDE con copy path reference.
• Arranca n8n. Si aparece el error verificar email API is not a constructor, revisa que el nombre del constructor coincida con el nombre del fichero y que el nombre de la credencial coincida con el del nodo, incluyendo mayúsculas y minúsculas. Vuelve a ejecutar el build y arranca de nuevo.
• Abre la URL de n8n y crea un workflow con trigger manual. Busca el nodo Verificar email.
• Crea la credencial desde el desplegable Create new credential con tipo API key. Copia la clave desde la plataforma de verificación y guárdala.
• Prueba con un correo de ejemplo, como test@domain.com. El sistema informa que se rechazó, por tanto es inválido.
• Prueba con play@gmail.com. Se acepta el email y confirma que el servicio y el nodo funcionan.

Palabras clave y habilidades aplicadas

• Configuración de credentials con API key y opciones de seguridad con password true.
• Uso de authenticate, parámetro API_key y transporte mediante query string con qs, o alternativas como header o body.
• Empleo de expresiones en n8n con prefijo igual para leer credentials.apiKey.
• Correcciones de tipado forzadas por el linter y ajuste a generic en authenticate.
• Integración de íconos con file:email.svg y gestión de archivos.
• Estructuración del proyecto con carpeta Verificar email y actualización de package.json.
• Construcción con pnpm install y pnpm run build, limpieza con rimraf, y enlace local con pnpm link usando path absoluto.
• Pruebas en n8n con workflow de trigger manual, creación de credenciales con Create new credential y ejecución con Execute step.

¿Probaste otra API gratuita con este flujo? Comparte tu experiencia y cuéntame qué retoques hiciste en credentials y en el JSON del nodo.