agenzia-entrate

n8n community node per le API Open Access dell'Agenzia delle Entrate: verifica Codice Fiscale e Partita IVA

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 1.0.0
Author: marcostoduto

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 IT dalla 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-After e 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 fonte nell'output (api o validazione_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

  1. Credentials → New → Agenzia Entrate Open Access API
  2. Inserisci Client ID e Client Secret rilasciati in fase di adesione.
  3. 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 con version in package.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

Discussion