# n8n-nodes-aliaddo Paquete de nodos comunitarios de n8n para integrarse con [Aliaddo](https://app.aliaddo.com), el ERP/CRM colombiano en la nube para facturación electrónica, ventas, contactos, inventario y contabilidad, y con su Hub de autenticación de usuario. Incluye dos nodos: - **Aliaddo ERP** — 20 recursos sobre la [API de Aliaddo](https://aliaddo.readme.io/). - **Aliaddo HUB** — autenticación y consulta de suscripciones contra el Hub de Aliaddo. ## Requisitos - **n8n** versión `>=1.30.0` - **Node.js** versión `>=18.0.0` - Una cuenta activa en [Aliaddo](https://app.aliaddo.com) ## Instalación ### En n8n Cloud o Self-hosted 1. Ve a **Settings → Community Nodes** 2. Haz clic en **Install** 3. Ingresa `n8n-nodes-aliaddo` y confirma ### Manual (Self-hosted) ```bash npm install n8n-nodes-aliaddo ``` ## Configuración de Credenciales ### Aliaddo ERP Auth 1. En Aliaddo, ve a **Mis datos → Integración → API Key** 2. En n8n, crea una credencial de tipo **Aliaddo ERP Auth** y elige uno de los dos modos: - **Access Token (Classic):** pega el token clásico generado en Aliaddo. Disponible para todo público. Si lo defines, API Key/Secret Key se ignoran. - **API Key + Secret Key:** el nodo firma cada petición automáticamente con HMAC-SHA256 (`X-Api-Key`/`X-Nonce`/`X-Timestamp`/`X-Signature`). **Uso restringido al equipo de desarrollo de Aliaddo** (no disponible para el público general). En este modo, el campo **Bearer Token (Dinámico)** del nodo (visible siempre) permite enviar un Bearer generado fuera de n8n (por ejemplo, con el nodo **Aliaddo HUB**); déjalo vacío si no aplica. > **Límite de tasa:** La API de Aliaddo permite entre 50 y 150 solicitudes por minuto. El nodo muestra un mensaje claro si se supera el límite. ### Aliaddo HUB Auth 1. Solicita tu **API Key** y **Secret Key** del Hub de Aliaddo al equipo de Aliaddo. 2. En n8n, crea una credencial de tipo **Aliaddo HUB Auth**, ingresa ambas claves y elige el **Environment** (Production o UAT). 3. Todas las peticiones del nodo **Aliaddo HUB** se firman automáticamente con HMAC-SHA256. ## Uso como Tool de un AI Agent Ambos nodos (`Aliaddo ERP` y `Aliaddo HUB`) se pueden conectar como *tool* de un nodo **AI Agent**. Al ser un paquete comunitario (no viene incluido por defecto en n8n), tu instancia self-hosted necesita la variable de entorno `N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true` (requiere reiniciar n8n) para que aparezcan como opción de tool; sin ella, el nodo se instala y se ve en el editor pero el AI Agent no lo reconoce como herramienta. ## Recursos y Operaciones — Aliaddo ERP | Recurso | Operaciones disponibles | | ------------------------------- | ------------------------------------------------------------------------------------ | | **Cotización** | Crear, Consultar, Consultar por ID | | **Factura de Venta** | Crear, Consultar, Consultar por ID | | **Factura de Compra** | Crear, Consultar, Consultar por ID, Pagar | | **Orden de Venta** | Crear, Consultar, Consultar por ID | | **Asiento Contable** | Crear, Consultar, Consultar por ID | | **Lead** | Crear, Consultar, Eliminar, Consultar Etapas, Consultar Fuentes | | **Negocio** | Crear, Consultar, Eliminar | | **Motor de Búsqueda** | Buscar (productos, contactos, etc.) | | **Actividad** | Crear, Consultar, Eliminar | | **Contacto** | Crear, Consultar, Consultar por ID, Eliminar, Consultar Vendedores | | **Producto** | Crear, Consultar, Consultar por ID, Eliminar, Stock, Categorías, Listas de Precios, Unidades de Medida | | **Impuesto** | Crear, Consultar, Consultar por ID | | **Bodega** | Consultar | | **Sucursal** | Consultar | | **Usuario** | Consultar, Consultar Propietarios | | **Validar Cliente** | Validar (reglas de negocio, sin llamada HTTP) | | **Validar Producto** | Validar (reglas de negocio + verificación real de stock por bodega si aplica) | | **Validar Stock** | Validar stock de un producto en una bodega puntual | | **Consultar IDs de Entidades** | Resuelve en una sola llamada los IDs de sucursal, cliente y N productos | | **Crear Documento** | Crea Factura de venta, Cotización u Orden de venta con un solo endpoint unificado | Los recursos **Motor de Búsqueda**, **Validar Cliente/Producto/Stock**, **Consultar IDs de Entidades** y **Crear Documento** están pensados para exponerse como herramientas de un AI Agent de n8n (vía `$fromAI()`), reduciendo la cantidad de nodos/herramientas que el agente necesita elegir. ## Recursos y Operaciones — Aliaddo HUB | Operación | Descripción | | ------------------------------ | ------------------------------------------------------------------------------------------------------ | | **Obtener Token** | Autentica al usuario (`phone`) y devuelve el listado de compañías/suscripciones disponibles | | **Autorizar Empresa** | Autoriza al usuario en una `companyId` específica y devuelve el token de acceso | | **Consultar Suscripciones** | Consulta las suscripciones/productos activos de un `phone`, agrupadas por compañía | ## Ejemplos de Uso ### Consultar todos los contactos y guardarlos en Google Sheets ``` Trigger (Schedule) → Aliaddo ERP (Contacto: Consultar, Retornar Todos = true) → Google Sheets (Append) ``` ### Crear una factura cuando se cierra un negocio en el CRM ``` Trigger (Webhook) → Aliaddo ERP (Factura de Venta: Crear) → Gmail (Enviar confirmación) ``` ### Sincronizar leads desde un formulario ``` n8n Form → Aliaddo ERP (Lead: Crear) → Slack (Notificar equipo de ventas) ``` ### Agente de IA que crea documentos comerciales por conversación ``` AI Agent → Aliaddo ERP (Consultar IDs de Entidades) → Aliaddo ERP (Validar Stock, si aplica) → Aliaddo ERP (Crear Documento) ``` ### Autenticar un usuario del Hub y listar sus suscripciones ``` Trigger (Webhook) → Aliaddo HUB (Obtener Token) → Aliaddo HUB (Consultar Suscripciones) → Respond to Webhook ``` ## Manejo de Errores ### Aliaddo ERP El nodo incluye mensajes descriptivos en español para los errores más comunes de la API: | Código HTTP | Mensaje | | ----------- | ----------------------------------------------------------- | | `400` | Solicitud inválida (datos inexistentes o incorrectos) | | `401` | Token inválido o expirado | | `402` | Cuenta suspendida o plan no permite la acción | | `403` | Sin permisos para esta acción | | `404` | Recurso no encontrado (también aplica a cuenta suspendida) | | `405` | Método no permitido para este endpoint | | `409` | Conflicto con el estado actual del recurso | | `429` | Límite de solicitudes excedido | | `500` | Error interno del servidor de Aliaddo | | `503` | Servicio no disponible (mantenimiento) | ### Aliaddo HUB El nodo propaga el mensaje de error tal como lo devuelve el Hub (ya viene descriptivo en español), junto con el código de estado HTTP: ```json [ { "error": { "message": "401 - \"{\\\"success\\\":false,\\\"message\\\":\\\"Firma inválida: Nonce duplicado o reusado (Replay Attack detectado).\\\"}\"", "status": 401 } } ] ``` ### En ambos nodos Activa **On Error: Continue (using error output)** en la configuración del nodo para enrutar los ítems fallidos a una salida "Error" separada en vez de detener el workflow. ## Documentación de la API - [Referencia oficial de la API de Aliaddo](https://aliaddo.readme.io/) - [Autenticación por API Key](https://aliaddo.readme.io/reference/autenticacion-por-api-key) ## Licencia [MIT](https://www.npmjs.com/package/mit) ## Contribuciones ¿Encuentras un problema o quieres añadir una operación? Abre un issue o un pull request en el repositorio. --- Desarrollado por el equipo de **Aliaddo** · [soporte@aliaddo.com](mailto:soporte@aliaddo.com)