Package Information
Available Nodes
Documentation generating…
Documentation
@mstoduto/n8n-nodes-agenzia-entrate
Community node per n8n che integra le API Open Access dell'Agenzia delle Entrate:
| Risorsa | Operazione | Endpoint |
|---|---|---|
| Codice Fiscale | Verifica | POST /codice-fiscale-liberoaccesso/verifica |
| Codice Fiscale | Stato Servizio | GET /codice-fiscale-liberoaccesso/status |
| Partita IVA | Verifica | POST /partita-iva-liberoaccesso/verifica |
| Partita IVA | Stato Servizio | GET /partita-iva-liberoaccesso/status |
Funzionalità
- Credenziali dedicate (
X-Client-Id/X-Client-Secret) con Base URL configurabile. - Normalizzazione input (attiva di default): rimuove spazi, punti e trattini, mette in maiuscolo e toglie il prefisso
ITdalla P.IVA. - Pre-validazione locale (opzionale): controlla formato e carattere di controllo di CF (16 caratteri, omocodia inclusa) e P.IVA/CF numerico (11 cifre). Se l'input è palesemente errato, restituisce l'esito senza chiamare l'API, così non consuma quota.
- Gestione rate limit (429): rispetta l'header
Retry-Aftere riprova (default 3 tentativi, attesa massima 65 s). Sulla quota giornaliera (X-RateLimit-Type: day) non riprova. - Errori leggibili per 401, 403, 429 e 503; con Continue On Fail l'errore finisce nell'output invece di fermare il workflow.
- Campo
fontenell'output (apiovalidazione_locale) e opzione per includere l'item originale. usableAsTool: il nodo è utilizzabile come tool da un AI Agent.
Output di esempio
// Partita IVA
{ "valida": true, "partitaIva": "12345678901", "denominazione": "Rossi S.r.l.",
"dataInizioAttivita": "2018-01-01", "dataCessazioneAttivita": null,
"isGruppoIva": false, "fonte": "api" }
// Codice Fiscale
{ "valido": true, "messaggio": "Codice fiscale valido",
"codiceFiscale": "TLEMRA83A01H501T", "fonte": "api" }
Installazione
Da file (self-hosted)
cd n8n-nodes-agenzia-entrate
npm install
npm run build
npm pack # crea mstoduto-n8n-nodes-agenzia-entrate-1.0.0.tgz
# nella cartella custom di n8n
mkdir -p ~/.n8n/custom && cd ~/.n8n/custom
npm init -y && npm install /percorso/mstoduto-n8n-nodes-agenzia-entrate-1.0.0.tgz
# riavvia n8n
La cartella dist/ è già compilata nell'archivio, quindi in alternativa basta copiare l'intero pacchetto in ~/.n8n/custom/node_modules/n8n-nodes-agenzia-entrate e riavviare n8n.
Docker
services:
n8n:
image: n8nio/n8n
volumes:
- ./n8n-nodes-agenzia-entrate:/home/node/.n8n/custom/node_modules/n8n-nodes-agenzia-entrate
Da npm
Settings → Community Nodes → Install → @mstoduto/n8n-nodes-agenzia-entrate.
Configurazione credenziali
- Credentials → New → Agenzia Entrate Open Access API
- Inserisci Client ID e Client Secret rilasciati in fase di adesione.
- Il pulsante Test esegue una verifica P.IVA fittizia: un 401/403 indica credenziali errate. Il test consuma una richiesta della quota.
Workflow di esempio
examples/verifica-anagrafica.json legge un elenco di record, verifica la P.IVA e il CF di ognuno e separa i record validi da quelli non validi. Si importa con Import from File.
Sviluppo
npm install
npm run dev # tsc --watch
npm test # compila offline + test con API simulata (test/mock-test.js)
dev-types/ contiene uno stub minimale di n8n-workflow usato solo per compilare offline (tsc -p tsconfig.offline.json). Con npm install vengono usati i tipi reali.
Pubblicazione su npm
Il workflow .github/workflows/publish.yml pubblica il pacchetto con provenance:
- in automatico quando fai il push di un tag
vX.Y.Z, che deve coincidere conversioninpackage.json; - a mano da Actions → Publish to npm → Run workflow.
Serve il secret NPM_TOKEN (Settings → Secrets and variables → Actions). Prima di pubblicare, il workflow esegue test/mock-test.js sulla dist/ già compilata, quindi ricompila e fai commit di dist/ prima di creare il tag:
npm version patch --no-git-tag-version
npm run build # oppure npm run build:offline
git commit -am "v$(node -p "require('./package.json').version")"
git tag "v$(node -p "require('./package.json').version")" && git push --follow-tags
Licenza
MIT