Fluxos de treball amb n8n

El paquet oficial de comunitat és n8n-nodes-factuarea, versió 0.1.2 a la referència de setembre de 2026. Requereix Node.js 22+. Inclou una credencial de Factuarea i un trigger d’esdeveniments; fes servir el node HTTP Request de n8n per a la resta d’operacions REST.

Instal·la i subscriu-te

Instal·la el paquet des de Community Nodes de la teva instància de n8n. Crea una credencial de Factuarea amb una API key que inclogui events:read, webhooks:read, webhooks:write i webhooks:delete. Afegeix Factuarea Trigger, selecciona la credencial i tria els tipus d’esdeveniment del catàleg. En activar el workflow es crea el seu endpoint de webhook; en desactivar-lo s’elimina l’endpoint que pertany a aquest trigger.

Exposa el webhook de n8n mitjançant HTTPS públic. Es rebutgen adreces privades i destinacions només locals; una excepció de sortida per a una botiga no habilita webhooks privats. Les credencials de test registren esdeveniments, però no lliuren webhooks públics; fes servir un cas controlat en live per verificar el lliurament complet.

Fes servir el snapshot de l’esdeveniment

Per a un workflow de factura pagada, subscriu-te a invoice.paid i mapeja el recurs des de data.object. L’id de l’esdeveniment identifica la notificació; data.object.id identifica la factura. En esdeveniments de botiga, data.order.external_id identifica la comanda del proveïdor. Desa l’ID de l’esdeveniment al teu sistema abans d’aplicar un efecte que no s’hagi de repetir.

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

Signatures i recuperació

El trigger comprova l’HMAC sobre el cos original de la petició i valida la data de la signatura. La tolerància predeterminada és de 300 segons, configurable entre 30 i 3600. La deduplicació del node actiu conserva en memòria els darrers 1000 ID d’esdeveniment; no substitueix una deduplicació persistent entre reinicis.

Després de rotar el secret de l’endpoint, desactiva i reactiva el trigger perquè rebi el secret nou; la doble signatura només cobreix les 24 hores de gràcia. Si l’activació esgota el temps d’espera, consulta el llistat d’endpoints abans de reintentar, perquè la creació pot haver acabat. Els errors permanents repetits poden degradar o suspendre un endpoint; corregeix-ne la causa i recupera’l expressament. Consulta el lliurament de webhooks i les limitacions del paquet.

Escolta un compte sencer

El mateix trigger té dos modes. Listen On val Company de manera predeterminada, que és tot el que es descriu a dalt: una empresa, i un workflow desat abans que existís l’opció es comporta així. Amb Account, el trigger registra un webhook de compte en activar el workflow i l’elimina en desactivar-lo, de manera que el workflow rep els esdeveniments de tot el compte: els dels seus propis NIF i els dels comptes gestionats. El paquet continua declarant un sol node i una sola credencial; el mode de compte és un mode del mateix node, no un segon node. El mode es llegeix en activar, així que després de canviar-lo cal tornar a activar el workflow.

La credencial necessita els mateixos quatre scopes que en el mode d’empresa (events:read, webhooks:read, webhooks:write i webhooks:delete).

Indica el compte

Escriu l’UUID del compte a Account ID del node o a Default Account ID de la credencial; si tots dos estan omplerts, mana el del node. El trigger mai no dedueix el compte a partir de l’API key. Amb tots dos buits es nega a activar-se i anomena els dos camps. L’UUID del compte actiu apareix a l’exemple cURL de Configuració → Desenvolupadors.

Esdeveniments i filtres

• Events ofereix el catàleg públic d’esdeveniments més la llista fixa de quinze esdeveniments account.* que porta el paquet, perquè cap ruta de catàleg els serveix. Un esdeveniment account.* nou arriba al selector només amb una versió més recent del paquet. El mode d’empresa no n’ofereix cap.
• Account Relationship admet own, managed o all (per defecte all). S’envia en crear l’endpoint i hi queda fix. Cada esdeveniment lliurat indica si és own o managed, mai all.
• Company ID Filter és opcional i admet l’UUID d’un NIF del compte. Quan és omplert, un lliurament signat el company_id del qual és un altre es respon amb 200 i es descarta sense iniciar el workflow, de manera que Factuarea no el reintenta. Un esdeveniment del propi compte, com account.member_added, no té company_id i sempre inicia el workflow. El filtre s’aplica després de comprovar la signatura i abans de la deduplicació, i només filtra el que emet el trigger: l’endpoint continua rebent tots els esdeveniments del compte.

L’element emès afegeix account, account_relationship i company_id a l’esdeveniment:

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

Signatura dels lliuraments de compte

Un lliurament de compte es verifica exactament igual que un d’empresa: el mateix HMAC sobre el cos original, la mateixa tolerància, la mateixa acceptació de dues signatures durant una rotació i la mateixa deduplicació per ID d’esdeveniment. El seu sobre afegeix account ({ "id": … }), account_relationship (own o managed) i company_id, que és null en un esdeveniment del propi compte. El lliurament inclou també la capçalera Factuarea-Account-Relationship, amb el mateix valor own o managed. El mateix esdeveniment d’un NIF lliurat a un endpoint d’empresa i a un de compte té el mateix id en tots dos. Consulta el sobre i les seves capçaleres.

Requisits i rebuigs

OAuth queda fora: la credencial és una API key, i una connexió OAuth no és una credencial de compte. Un endpoint de compte de test només es pot crear des del tauler de Factuarea.

Versió del paquet

El mode de compte forma part de la versió objectiu 0.2.0 del paquet, que el seu registre de canvis llista com a no publicada juntament amb l’eix d’empresa. La versió 0.1.2 indicada a dalt no l’inclou, i aquesta guia no afirma que 0.2.0 estigui publicada.