Description

@mikiguillamon/n8n-nodes-holded

Community node de n8n para trabajar con la API v2 de Holded.

Qué incluye

• Autenticación por API key de Holded.
• Activación mediante licencia.
• Operaciones guiadas para recursos habituales:

– Contacts
– Products
– Services
– Documents
– Payments
– Projects
– Tasks
– Leads
– Bookings
– Accounting Accounts

• Operación Custom API Request para cubrir cualquier endpoint de Holded sin esperar a que exista una acción dedicada en el nodo.
• Compatible con el uso como herramienta en agentes de IA de n8n.
• Controles tipo nodos oficiales de n8n:

– Return All y Limit en operaciones Get Many.
– Filtros guiados por recurso.
– Additional Query Parameters para parámetros no modelados.
– Fields para cuerpos simples sin escribir JSON.
– JSON avanzado opcional para casos con estructuras anidadas.

• Creación guiada de documentos comerciales:

– Facturas, presupuestos, pedidos, albaranes, compras y abonos.
– Contacto, fechas, moneda, numeración, método de pago, etiquetas y líneas de documento.

Enfoque

La API de Holded es amplia y cambia con el tiempo. Este paquete combina dos capas:

1. Operaciones guiadas para los flujos más frecuentes.
2. Una petición API personalizada para cubrir el resto de endpoints y casos avanzados.

Con esto el nodo es usable desde el primer momento y, a la vez, no se queda corto cuando Holded añade o ajusta endpoints.

Credenciales

La versión 2 del nodo autentica las peticiones con Authorization: Bearer . Genera una clave en Settings > API de Holded con los permisos necesarios para los recursos que utilices. El test de credenciales consulta un contacto como máximo y requiere permiso de lectura de contactos.

Los nodos guardados como versión 1 conservan la cabecera key y las rutas de la API antigua. El test de credenciales comprueba siempre el acceso a v2.

Además, este nodo requiere una licencia. En la versión actual, cualquier clave de licencia con 10 o más caracteres se considera válida. La validación está preparada para cambiarse más adelante a una comprobación contra un servidor externo.

Instalación en n8n

En una instancia self-hosted de n8n:

1. Ve a Settings > Community Nodes.
2. Selecciona Install.
3. Introduce el paquete @mikiguillamon/n8n-nodes-holded.
4. Acepta el aviso de instalación de código no verificado.
5. Reinicia n8n si tu despliegue lo requiere.

Después, busca el nodo Holded en el editor de workflows.

Desarrollo local

npm install
npm test
npm run lint
npm run build
npm run dev

Notas

• El nodo usa la URL base https://api.holded.com.
• El nodo está marcado como usableAsTool, por lo que puede usarse como herramienta en agentes de IA dentro de n8n.
• Las operaciones de creación y actualización aceptan Fields para payloads simples y Advanced Body JSON para no limitar los campos que expone Holded en cada recurso.
• La creación de documentos comerciales tiene campos guiados para los casos habituales y permite completar o sobrescribir cualquier dato con Advanced Body JSON.
• En la versión 2, Get Many recorre las páginas por cursor y devuelve cada registro como un item de n8n. Return All recupera todos los resultados; Limit se aplica al total, aunque requiera varias páginas. Pagination Options permite indicar el cursor inicial y un tamaño de página de hasta 100 registros.
• Para endpoints no modelados explícitamente, usa Custom API Request.

Pasar de v1 a v2

Los nodos nuevos usan la versión 2. Los workflows existentes conservan su versión 1 para evitar cambios automáticos en sus rutas, payloads y resultados. Para migrar un workflow, actualiza la versión del nodo desde el editor de n8n o añade un nodo Holded nuevo y revisa sus campos y las expresiones que consumen su salida.

• Las rutas comerciales son colecciones independientes: /api/v2/invoices, /api/v2/estimates, /api/v2/purchases, etc.
• Los cuerpos y filtros usan los nombres de v2, como contactid, duedate y start_date. Los campos guiados hacen la conversión; Fields y Advanced Body/Query JSON deben usar directamente los nombres y tipos de v2.
• Los documentos necesitan un contacto existente mediante Contact ID y al menos una línea; los tickets (Sales Receipt) permiten omitir el contacto. Ya no se crea un contacto a partir de sus datos de facturación.
• Las líneas de documento y los productos usan claves de impuestos, por ejemplo siva21, en lugar de porcentajes. Usa las claves de compra correspondientes en documentos de compra. Consulta las claves disponibles con GET /api/v2/taxes mediante Custom API Request.
• Las fechas guiadas de creación y actualización aceptan ISO, segundos o milisegundos Unix y se envían en formato ISO. Los filtros de fecha y los valores escritos directamente en JSON deben seguir el formato de la API v2. Los importes de productos y pagos se envían como cadenas decimales.
• Approve guarda primero el documento y solicita después su aprobación. Si la aprobación falla, el error incluye el ID guardado para poder continuar sin crear un duplicado.
• Los abonos de compra se listan en /api/v2/purchase-refunds y se crean o consultan en /api/v2/purchases/refund. La documentación actual no ofrece actualización ni borrado para ellos.
• Los campos visibles al actualizar un documento dependen de su tipo, según las operaciones admitidas por v2.
• Custom API Request acepta rutas desde /api/v2/, admite cuerpos en DELETE y conserva la respuesta completa, incluidos items, cursor y has_more. La paginación de las peticiones personalizadas es manual.

Ejemplo de Advanced Body JSON para crear una factura:

{
  "contactid": "IDDEL_CONTACTO",
  "date": "2026-10-15",
  "items": [
    { "name": "Consultoría", "price": 100, "units": 1, "taxes": ["siva21"] }
  ]
}

npm test compila el paquete y ejecuta pruebas locales de peticiones y respuestas simuladas. Estas pruebas no realizan operaciones contra una cuenta real de Holded.