Flujos de trabajo con n8n

El paquete oficial de comunidad es n8n-nodes-factuarea, versión 0.1.2 en la referencia de septiembre de 2026. Requiere Node.js 22+. Incluye una credencial de Factuarea y un trigger de eventos; utiliza el nodo HTTP Request de n8n para las demás operaciones REST.

Instala y suscríbete

Instala el paquete desde Community Nodes de tu instancia de n8n. Crea una credencial de Factuarea con una API key que incluya events:read, webhooks:read, webhooks:write y webhooks:delete. Añade Factuarea Trigger, selecciona la credencial y elige los tipos de evento del catálogo. Al activar el workflow se crea su endpoint de webhook; al desactivarlo se elimina el endpoint que pertenece a ese trigger.

Expón el webhook de n8n mediante HTTPS público. Se rechazan direcciones privadas y destinos solo locales; una excepción de salida para una tienda no habilita webhooks privados. Las credenciales de test registran eventos, pero no entregan webhooks públicos; utiliza un caso controlado en live para verificar la entrega completa.

Usa el snapshot del evento

Para un workflow de factura pagada, suscríbete a invoice.paid y mapea el recurso desde data.object. El id del evento identifica la notificación; data.object.id identifica la factura. En eventos de tienda, data.order.external_id identifica el pedido del proveedor. Guarda el ID del evento en tu sistema antes de aplicar un efecto que no deba repetirse.

{{ $json.id }}
{{ $json.type }}
{{ $json.data.object.id }}
{{ $json.data.object.total }}

Firmas y recuperación

El trigger comprueba el HMAC sobre el cuerpo original de la petición y valida la fecha de la firma. La tolerancia predeterminada es de 300 segundos, configurable entre 30 y 3600. La deduplicación del nodo activo conserva en memoria los últimos 1000 ID de evento; no sustituye una deduplicación persistente entre reinicios.

Tras rotar el secreto del endpoint, desactiva y reactiva el trigger para que reciba el nuevo secreto; la doble firma solo cubre las 24 horas de gracia. Si la activación agota el tiempo de espera, consulta el listado de endpoints antes de reintentar, porque la creación puede haber terminado. Los fallos permanentes repetidos pueden degradar o suspender un endpoint; corrige la causa y recupéralo expresamente. Consulta la entrega de webhooks y las limitaciones del paquete.

Escucha una cuenta entera

El mismo trigger tiene dos modos. Listen On vale Company de forma predeterminada, que es todo lo descrito arriba: una empresa, y un workflow guardado antes de que existiera la opción se comporta así. Con Account, el trigger registra un webhook de cuenta al activar el workflow y lo elimina al desactivarlo, de modo que el workflow recibe los eventos de toda la cuenta: los de sus propios NIF y los de las cuentas gestionadas. El paquete sigue declarando un solo nodo y una sola credencial; el modo de cuenta es un modo del mismo nodo, no un segundo nodo. El modo se lee al activar, así que tras cambiarlo hay que volver a activar el workflow.

La credencial necesita los mismos cuatro scopes que en el modo de empresa (events:read, webhooks:read, webhooks:write y webhooks:delete).

Indica la cuenta

Escribe el UUID de la cuenta en Account ID del nodo o en Default Account ID de la credencial; si ambos están rellenos, manda el del nodo. El trigger nunca deduce la cuenta a partir de la API key. Con los dos vacíos se niega a activarse y nombra los dos campos. El UUID de la cuenta activa aparece en el ejemplo cURL de Ajustes → Desarrolladores.

Eventos y filtros

• Events ofrece el catálogo público de eventos más la lista fija de quince eventos account.* que lleva el paquete, porque ninguna ruta de catálogo los sirve. Un evento account.* nuevo llega al selector solo con una versión más reciente del paquete. El modo de empresa no ofrece ninguno.
• Account Relationship admite own, managed o all (por defecto all). Se envía al crear el endpoint y queda fijo para él. Cada evento entregado indica si es own o managed, nunca all.
• Company ID Filter es opcional y admite el UUID de un NIF de la cuenta. Cuando está relleno, una entrega firmada cuyo company_id es otro se responde con 200 y se descarta sin iniciar el workflow, de modo que Factuarea no la reintenta. Un evento de la propia cuenta, como account.member_added, no tiene company_id y siempre inicia el workflow. El filtro se aplica después de comprobar la firma y antes de la deduplicación, y solo filtra lo que emite el trigger: el endpoint sigue recibiendo todos los eventos de la cuenta.

El elemento emitido añade account, account_relationship y company_id al evento:

{{ $json.type }}
{{ $json.account.id }}
{{ $json.account_relationship }}
{{ $json.company_id }}

Firma de las entregas de cuenta

Una entrega de cuenta se verifica exactamente igual que una de empresa: el mismo HMAC sobre el cuerpo original, la misma tolerancia, la misma aceptación de dos firmas durante una rotación y la misma deduplicación por ID de evento. Su sobre añade account ({ "id": … }), account_relationship (own o managed) y company_id, que es null en un evento de la propia cuenta. La entrega incluye además la cabecera Factuarea-Account-Relationship, con el mismo valor own o managed. El mismo evento de un NIF entregado a un endpoint de empresa y a uno de cuenta lleva el mismo id en ambos. Consulta el sobre y sus cabeceras.

Requisitos y rechazos

OAuth queda fuera: la credencial es una API key, y una conexión OAuth no es una credencial de cuenta. Un endpoint de cuenta de test solo se puede crear desde el panel de Factuarea.

Versión del paquete

El modo de cuenta forma parte de la versión objetivo 0.2.0 del paquete, que su registro de cambios lista como no publicada junto con el eje de empresa. La versión 0.1.2 indicada arriba no lo incluye, y esta guía no afirma que 0.2.0 esté publicada.