n8n-nodes-invoka

Nodos de comunidad de n8n para Invoka, la API de facturación electrónica del SRI de Ecuador para programadores.

• Invoka: emite facturas, notas de crédito y débito, guías de remisión, liquidaciones de compra y retenciones 2.0 (la 1.0 queda como obsoleta). También consulta su estado, descarga el XML y el PDF, reprocesa, consulta RUC y cédulas, revisa los créditos y administra empresas y el webhook.
• Invoka Trigger: arranca un flujo cuando Invoka avisa de que un comprobante quedó autorizado o con error. Verifica la firma HMAC de cada aviso.

Documentación de la API: https://invoka.com.ec/docs

Instalación

En n8n: Settings → Community Nodes → Install y escriba n8n-nodes-invoka.

Si n8n corre por su cuenta (self-hosted):

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

Credencial

La prueba de la credencial consulta el saldo (GET /api/creditos/saldo). No usa /api/ping porque ese endpoint no valida la clave.

Hay una sola API key por cuenta, y con ella se emite para todas las empresas (RUC) que la cuenta tenga registradas.

Ambiente: Pruebas o Producción

El ambiente se elige en cada comprobante. No va en la credencial.

• Pruebas (valor por defecto): es gratis e ilimitado. El SRI procesa el comprobante en su ambiente de pruebas y no tiene validez tributaria.
• Producción: consume 1 crédito por cada comprobante autorizado y es real ante el SRI. Cuando se elige, el nodo muestra un aviso ⚠.

El nodo siempre manda el ambiente que diga ese campo, aunque se use el modo JSON y el JSON traiga otro.

Operaciones

Cómo se emite

Cada emisión acepta dos modos:

• Llenar campos: un formulario guiado con el emisor, el comprador o proveedor, los ítems (IVA en lista desplegable), las formas de pago y la información adicional.
• JSON completo: el cuerpo tal como lo documenta la API. Sirve para lo que el formulario no cubre, como los reembolsos de una factura o los «gastos» de una retención 2.0.

Para no repetir trabajo, el nodo resuelve varias cosas por su cuenta:

• Razón social del emisor: obligatoria en la factura (también en modo JSON: emisor.razon_social). En el formulario, si solo se llena el nombre comercial, se usa como razón social; si faltan ambos, el nodo avisa antes de llamar a la API.
• Fecha de emisión: si se deja vacía, pone la fecha de hoy en Ecuador (America/Guayaquil). El SRI no acepta otra fecha.
• Formatos: el secuencial, el establecimiento y el punto de emisión se rellenan con ceros. Los números de documento se aceptan con o sin guiones (001-001-000000123). Las fechas se aceptan como AAAA-MM-DD o AAAA/MM/DD.
• Respuesta: Invoka registra el comprobante y lo procesa en segundo plano, así que la respuesta trae la clave de acceso y el estado «En procesamiento». Con Opciones → Esperar la autorización, el nodo consulta cada pocos segundos hasta que el SRI autorice o rechace, y devuelve el estado final con los enlaces al XML y al PDF. Si además se activa Fallar si no se autoriza, el flujo se detiene cuando el SRI rechaza el comprobante.
• Notas a consumidor final: el SRI no autoriza notas de crédito ni de débito a CONSUMIDOR FINAL. Invoka las acepta igual y luego el SRI las devuelve, con el secuencial ya gastado. El nodo las frena antes de enviarlas.
• Errores: Invoka contesta algunos errores de validación con HTTP 200 y creado: false. El nodo los convierte en errores de n8n con el mensaje de Invoka y una pista de qué hacer (por ejemplo, para «Empresa No existe», «Clave de Acceso ya existe» o una fecha que no es la de hoy).

Invoka no genera el secuencial. Lleve usted la numeración de cada establecimiento y punto de emisión, por ejemplo con un contador en una base de datos o en una hoja de cálculo.

Selector dinámico

En Consultar, Esperar, XML, PDF y Reprocesar, el comprobante se puede escribir (clave de acceso de 49 dígitos) o elegir de una lista reciente. Esa lista sale del historial de créditos (comprobantes de producción) y de las últimas 10 entregas del webhook. La API de Invoka no tiene un listado de comprobantes ni de empresas, así que el RUC del emisor se escribe o se toma de un nodo anterior.

Invoka Trigger

⚠ Invoka tiene un solo webhook por cuenta.

Al activar el flujo, el Trigger:

1. Lee el webhook que la cuenta tenga configurado y lo recuerda.
2. Pone la URL de n8n en su lugar. No cambia el secreto: usa el que ya tenía la cuenta, o el que Invoka genere si no había ninguno.

Al desactivar el flujo, por defecto restaura el webhook anterior: la misma URL y el mismo estado activo o inactivo. Si no había ninguno, lo elimina. Si mientras tanto alguien cambió el webhook, no lo toca. En Opciones → Al desactivar puede elegir, en cambio, eliminarlo o dejarlo como está.

Cada aviso se verifica con su firma. Cuando llega la firma V2, se usa esa; si no, la original:

X-Invoka-Signature-V2: t=MOMENTO,v1=HMAC_SHA256(MOMENTO + "." + cuerpo_crudo, secreto)
X-Invoka-Signature:    sha256=HMAC_SHA256(cuerpo_crudo, secreto)

Si la firma no coincide, el aviso se rechaza con 401. Con la V2 también se rechazan los avisos cuya marca de tiempo esté a más de 300 segundos del reloj de n8n, para evitar reenvíos (se ajusta en Opciones → Tolerancia de tiempo).

Invoka entrega el secreto completo solo al guardar el webhook; al consultarlo lo muestra enmascarado. Por eso el Trigger guarda el secreto que recibe al activarse. Si alguien cambia el secreto después, escríbalo en Opciones → Secreto, o desactive y vuelva a activar el flujo. Hay filtros por evento (comprobante.autorizado, comprobante.error, webhook.prueba), por ambiente y por RUC emisor. Los avisos que no pasan el filtro se responden con 200 para que Invoka no los reintente.

La salida trae el campo entrega (cabecera X-Invoka-Delivery), que es el mismo en todos los reintentos de un aviso: úselo para no procesar dos veces el mismo aviso.

Invoka necesita una URL pública para avisar; localhost no sirve. Si el aviso no recibe un 2xx, Invoka lo reintenta hasta 5 veces (a los 1, 5, 15, 60 y 180 minutos).

Desarrollo

npm install
npm run build
CI=1 npx eslint nodes credentials      # el «n8n-node lint» interactivo se queda esperando
INVOKA_KEY=API_xxx INVOKA_RUC=... INVOKA_ESTAB=001 INVOKA_PTO=001 INVOKA_CLAVE=<clave> npm run probar

scripts/probar.mjs carga dist/ y prueba contra Invoka de verdad. Las emisiones (INVOKA_EMITIR=1, siempre en ambiente de pruebas), las consultas SRI (INVOKA_SRI=1) y el ciclo real del webhook (PROBAR_WEBHOOK=1) solo corren si se piden con su bandera.

Licencia

MIT