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:

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

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