AZUR para n8n

Nodos de n8n para AZUR, la plataforma de facturación electrónica del SRI de Ecuador.

Con ellos puede automatizar, sin programar, lo que hoy hace a mano en el portal: crear facturas desde su tienda en línea, enviarlas al SRI, descargar el RIDE, registrar cobros, sincronizar clientes y productos, mover inventario, importar lo que le facturan sus proveedores… y reaccionar al instante cuando el SRI autoriza o rechaza un comprobante.

El paquete trae dos nodos:

| Nodo | Para qué | |---|---| | AZUR | Todas las operaciones públicas de la API v2 de AZUR, organizadas por recurso. | | AZUR Trigger | Arranca un flujo cuando AZUR avisa: comprobante autorizado, rechazado, anulado o cupo bajo. |

Referencia completa de la API: https://azur.com.ec/api/referencia

Instalación

n8n Cloud o n8n con interfaz de administración

1. Entre a Settings → Community Nodes.
2. Pulse Install a community node.
3. Escriba n8n-nodes-azur, acepte el aviso y pulse Install.

Los nodos aparecen al buscar «AZUR» en el panel de nodos.

n8n instalado por usted (npm / Docker)

cd ~/.n8n/nodes
npm install n8n-nodes-azur
# reinicie n8n

La credencial

1. Entre al portal de AZUR con el usuario dueño de la cuenta.
2. Abra el menú de usuario → Credenciales API y cree una credencial nueva. Ahí elige:
   • permisos: qué podrá hacer (por ejemplo, solo «Consultar comprobantes», o también emitir);
   • IP autorizadas (opcional): desde dónde se puede usar;
   • vencimiento (opcional).
3. Copie la credencial: se muestra una sola vez. Empieza por azur_live_ (producción) o azur_test_ (pruebas).
4. En n8n: Credentials → Add credential → AZUR API, pegue la credencial y guarde. n8n la comprueba al momento contra AZUR.

El ambiente lo fija la credencial, no el flujo. Con una azur_test_ nada de lo que haga sale al SRI de verdad; con una azur_live_ todo es real. La credencial también fija la empresa, el establecimiento y el punto de emisión: para trabajar con otro establecimiento, cree otra credencial.

El campo URL de AZUR se deja en https://azur.com.ec salvo que AZUR le indique otra.

Si una operación no está entre los permisos de la credencial, el nodo falla con un mensaje que dice qué permiso le falta; se añade en el mismo menú del portal.

Qué puede hacer el nodo AZUR

| Recurso | Operaciones | |---|---| | Comprobante (factura, nota de crédito, nota de débito, guía de remisión, retención, compra, liquidación de compra, proforma, nota de venta) | Crear (borrador) · Actualizar borrador · Eliminar · Obtener · Listar por tipo · Listar todos los electrónicos · Enviar al SRI · Consultar estado (también en directo con el SRI) · Anular · Reprocesar · Reenviar por correo · Descargar PDF (RIDE) · Descargar XML · Saldo acreditable de una factura · Líneas acreditables · Retención sugerida de una compra | | Cliente / Proveedor | Buscar · Crear · Obtener · Actualizar · Dar de baja · Reactivar · Listar, crear, actualizar y dar de baja sucursales | | Transportista | Buscar · Crear · Obtener · Actualizar · Dar de baja · Reactivar | | Producto | Buscar (con precio y existencias) · Crear · Obtener · Actualizar · Dar de baja · Reactivar · Existencias · Lotes | | Categoría de producto | Listar · Crear · Actualizar | | Inventario | Existencias · Kardex · Listar, crear y actualizar bodegas · Registrar ingreso, salida, transferencia y ajuste | | Contabilidad | Plan de cuentas · Centros de costo · Crear asiento manual · Listar y obtener asientos | | Cartera | Documentos con saldo · Saldo por persona · Estado de cuenta · Movimientos de un documento · Registrar cobro o pago · Deshacer cobro o pago | | Documento recibido | Listar · Importar del SRI por clave de acceso · Obtener · Descargar XML y PDF · Convertir en compra | | Reporte | ATS del mes (XML) · Ventas agrupadas · Compras agrupadas | | Webhook | Listar · Registrar · Eliminar · Últimos envíos | | Cuenta | Contexto · Plan y cupo · Firma electrónica · Vendedores · Secuenciales · Establecimientos · Puntos de emisión · Resumen de ventas | | Catálogo SRI | Unidades de medida · Códigos ICE · Códigos IRBPNR |

Todo se elige de listas

No hace falta saberse ningún id. El nodo consulta su cuenta en vivo:

• Cliente, proveedor, producto, transportista, compra, factura, documento y documento recibido: selector con buscador (o el id a mano, o una expresión).
• Sucursal del cliente o proveedor elegido, bodega, categoría, vendedor, unidad de medida, ICE, IRBPNR, cuenta contable, centro de costo y webhook: desplegables con los datos reales de su cuenta.
• Tarifa de IVA, tipo de identificación, formas de pago del SRI: listas con los códigos del SRI.

Las líneas de un comprobante se añaden una a una: producto (de su catálogo), cantidad y, si quiere, precio, descuento, tarifa de IVA, bodega, lote y detalle. Los totales los calcula AZUR.

Para casos avanzados, en Crear y Actualizar puede elegir JSON y mandar el cuerpo tal cual lo documenta la referencia de la API.

Borrador primero, SRI después

• Crear guarda el documento como borrador: no sale a ninguna parte.
• Enviar al SRI es una operación aparte y es irreversible, con efecto tributario: un comprobante autorizado solo se corrige anulándolo.
• Anular no anula en el SRI: la solicitud se presenta en SRI en línea, y esta operación confirma que el SRI ya la registró y da de baja el comprobante en AZUR (stock, asiento y cartera).
• Existe la casilla Enviar al SRI al guardar para quien quiera hacerlo en un solo paso; viene apagada.

Reintentos sin duplicados

Todas las escrituras llevan la cabecera Idempotency-Key. Si n8n reintenta un nodo (por un corte de red, por Retry On Fail…), AZUR devuelve el documento que ya creó en lugar de crear otro. Por defecto la clave se genera por ejecución e ítem; puede poner la suya (por ejemplo, el número de pedido de su tienda) en Clave de idempotencia.

Listados

Las operaciones de listado tienen Return All y Limit, como los nodos oficiales. Para sincronizar, use el filtro Modificado desde: devuelve solo lo que cambió desde esa fecha y recorre las páginas con el cursor de AZUR, sin saltarse nada aunque entren documentos nuevos.

Sin fechas ni búsqueda, los listados de comprobantes devuelven solo los últimos 60 días, igual que el portal.

Errores

Cuando AZUR rechaza algo, el nodo muestra su mensaje en español y, debajo, el código estable (cupo_agotado, secuencial_ocupado, documento_no_editable, sin_permiso…) y los motivos concretos de validación. Active Continue On Fail si quiere tratar el error en el propio flujo.

El nodo AZUR Trigger

1. Añada AZUR Trigger y elija los eventos: Comprobante autorizado, Comprobante rechazado, Comprobante anulado, Plan: cupo bajo.
2. Active el flujo. El nodo registra su URL en AZUR y guarda el secreto de firma; al desactivar el flujo, borra el registro.
3. Cada aviso se verifica: AZUR firma el cuerpo con HMAC-SHA256 (cabeceras X-Azur-Firma y X-Azur-Momento) y el nodo rechaza con 401 cualquier aviso con firma falsa o fuera de tiempo.

La salida trae evento, momento, intento y datos (el comprobante: id, clave de acceso…). Un mismo aviso puede llegar dos veces si AZUR reintenta: use el id del documento para no procesarlo dos veces.

Requisitos: AZUR solo avisa a URLs https accesibles desde internet (n8n Cloud ya lo es; si usted aloja n8n, configure WEBHOOK_URL con https) y los webhooks los administra el dueño de la cuenta: la credencial no puede ser de un vendedor.

Ejemplos de flujos

Factura automática desde la tienda en línea WooCommerce Trigger (pedido pagado) → AZUR · Cliente · Buscar (por la cédula del pedido) → IF (¿existe?) → AZUR · Cliente · Crear → AZUR · Comprobante · Crear (factura, líneas con los productos del pedido, clave de idempotencia = número de pedido) → AZUR · Comprobante · Enviar al SRI.

Mandar el RIDE cuando el SRI autoriza AZUR Trigger (comprobante autorizado) → AZUR · Comprobante · Descargar PDF → Gmail · Send (con el PDF adjunto) o WhatsApp.

Aviso de rechazos al contador AZUR Trigger (comprobante rechazado) → Slack / Correo con el motivo que trae datos.errores.

Copia diaria a su hoja de cálculo Schedule Trigger (cada noche) → AZUR · Comprobante · Listar todos (Return All, Modificado desde = ayer) → Google Sheets · Append or Update.

Que no le pille la firma ni el cupo Schedule Trigger (lunes) → AZUR · Cuenta · Firma electrónica + AZUR · Cuenta · Plan y cupo → IF (días restantes < 30, disponibles < 100) → correo.

Compras sin teclear Schedule Trigger → AZUR · Documento recibido · Listar (solo los que faltan por registrar) → AZUR · Documento recibido · Convertir en compra → AZUR · Comprobante · Crear (retención, con la retención sugerida).

Lo que no incluye

La Emisión directa (/{tipo}/emision con el api_key del punto de emisión) no está en este paquete: usa otra autenticación, distinta según el endpoint, y emite al SRI en una sola llamada sin borrador. Todo lo que hace se puede hacer aquí con Crear + Enviar al SRI. Si la necesita, use el nodo HTTP Request siguiendo la referencia de la API.

Desarrollo

npm install
npm run build      # compila a dist/
npm run lint       # reglas oficiales de n8n para nodos de la comunidad
npm run dev        # levanta un n8n local con estos nodos

# prueba real contra una cuenta de PRUEBAS (la credencial solo en variables de entorno)
AZUR_CRED=azur_test_... AZUR_URL=https://central.azur.com.ec npm run probar

Licencia

MIT