API PEC con Python e Node.js: guida all’integrazione

Un’API PEC in Python o Node.js serve a trasformare un elenco di Partite IVA o Codici Fiscali in indirizzi di Posta Elettronica Certificata ufficiali, senza ricerche manuali una per una. Il punto tecnico da capire subito è che la fonte di riferimento, l’indice nazionale INI-PEC, lavora in modalità massiva con un flusso asincrono a lotti, non con una semplice chiamata che risponde all’istante. Chi gestisce centinaia o migliaia di anagrafiche ottiene il risultato più rapido e più solido collegando il proprio codice a un servizio che interroga già le fonti istituzionali e restituisce dati normalizzati, come i Web Services di TrovaPEC per la ricerca PEC. Di seguito si vedono i dati che un’API PEC può restituire, come è strutturato il canale ufficiale e come scrivere l’integrazione passo per passo, prima in Python e poi in Node.js.

TrovaPEC
trovapec.it
Trova le PEC dai tuoi elenchi
TrovaPEC cerca indirizzi PEC ufficiali da liste di Partite IVA o Codici Fiscali, con dati aggiornati tramite l’INI-PEC.

Visita

In breve

  • Un’API di ricerca PEC interroga l’INI-PEC, l’indice ufficiale degli indirizzi PEC di imprese e professionisti, e restituisce PEC, denominazione, codice fiscale e data di aggiornamento.
  • Il canale massivo ufficiale è asincrono: si invia un lotto di codici, si riceve un identificativo di richiesta e si scarica il risultato in un secondo momento.
  • In Python e in Node.js il flusso è lo stesso: validare l’elenco, inviare il lotto, attendere l’elaborazione, scaricare e riconciliare i risultati.
  • Un’API per cercare una PEC è diversa da un’API per attivare o gestire una casella PEC: la prima legge un indice pubblico, la seconda amministra una casella.
  • Per elenchi ampi, un servizio via API che attinge all’INI-PEC elimina il lavoro manuale e riduce gli scarti già in fase di preparazione.

Indice

Cosa restituisce un’API di ricerca PEC

L’INI-PEC è l’Indice nazionale degli indirizzi PEC di imprese e professionisti, realizzato e gestito dal Ministero con il supporto di InfoCamere. Ogni API seria per la ricerca di indirizzi PEC in Italia parte da qui, perché i dati arrivano dal Registro Imprese e dagli Ordini e Collegi professionali.

Secondo l’allegato tecnico del Web Service Fornitura PEC Massiva, i campi restituiti sono questi:

SoggettoDati restituiti
ImpresaCodice fiscale, denominazione, provincia della sede legale, data di aggiornamento dal Registro Imprese, indirizzo PEC
ProfessionistaNome e cognome, codice fiscale, ordine o collegio, provincia di iscrizione, numero e data di iscrizione, data di aggiornamento, indirizzo PEC

Due dettagli contano molto quando si scrive il codice che legge la risposta:

  • Un codice può produrre due risultati. Se il codice fiscale di una persona fisica è presente sia come impresa individuale sia come professionista, il servizio restituisce entrambe le posizioni. Il parser deve quindi accettare più righe per lo stesso codice in input.
  • La data di aggiornamento ha un significato preciso. Indica quando il Registro Imprese o l’Ordine ha comunicato l’informazione all’INI-PEC. È il campo da salvare nel proprio database per sapere quanto è recente il dato.

Per le imprese, le chiavi di ricerca ammesse sono il codice fiscale oppure, in alternativa, provincia più ragione sociale. In un’integrazione automatica la chiave affidabile resta il codice fiscale o la Partita IVA: la ragione sociale cambia, si scrive in modi diversi e genera ambiguità.

Ricerca PEC e gestione casella: due API diverse

Cercando “API PEC” si trovano due famiglie di servizi che hanno poco in comune.

  • API di ricerca e verifica. Leggono un indice pubblico e rispondono alla domanda “qual è la PEC ufficiale di questa impresa o di questo professionista?”. Servono a chi deve inviare comunicazioni certificate, aggiornare un’anagrafica fornitori o clienti, preparare un invio massivo.
  • API di gestione della casella. Sono offerte dai gestori di posta certificata a chi possiede una casella: attivazione, rinnovo, spazio, elenco delle proprie caselle. Non dicono nulla sugli indirizzi di terzi.

Chi ha un elenco di Partite IVA e deve raggiungere quei soggetti via PEC ha bisogno della prima famiglia. Dopo la ricerca, il passo naturale è l’invio, che può essere gestito anche in blocco con l’invio PEC massivo, con rendicontazione dei ritorni.

Come funziona il canale ufficiale INI-PEC

L’INI-PEC consente ricerche puntuali da portale oppure ricerche massive tramite servizi di cooperazione applicativa, cioè scambi automatici tra sistemi informatici. La documentazione tecnica del servizio massivo descrive un’architettura che ogni sviluppatore dovrebbe conoscere, perché spiega i tempi e i vincoli di qualunque API PEC costruita sopra l’indice.

Le caratteristiche principali, tratte dall’allegato tecnico del web service:

  1. Protocollo SOAP con WSDL. Il servizio è descritto da file WSDL per l’ambiente di produzione e per quello di collaudo.
  2. Autenticazione Basic su HTTPS. Utente e password viaggiano nell’header; gli accessi sono registrati e sono previsti controlli sull’abilitazione e sul numero massimo di richieste.
  3. Input compresso. Si invia un file ZIP che contiene un .txt o un .csv di codici fiscali o Partite IVA.
  4. Due fasi. L’operazione richiestaFornituraPec restituisce la coppia idRichiesta e tipoRichiesta; il risultato si scarica in differita con scaricoFornitura, quando il lotto è stato elaborato.
  5. Finestra di download limitata. L’output resta disponibile per un massimo di 7 giorni solari, e i dati in input vengono cancellati dopo l’elaborazione.
  6. Instradamento per lunghezza del codice. Un codice di 11 caratteri viene cercato solo tra le imprese; uno di 16 caratteri sia tra le imprese sia tra i professionisti. I codici non trovati finiscono in una lista di scarti che compone il report CSV finale.
  7. Codici di errore dedicati. Le famiglie EF1–EF5, EB1–EB9 ed EC1 segnalano problemi su file, lotto e controlli.

L’accesso è contrattuale e ha un costo: un documento dell’Agenzia delle Dogane e dei Monopoli descrive una tariffa con canone annuale per fascia di interrogazioni più un costo per ogni informazione ricevuta. Per un’azienda o uno studio, gestire in proprio convenzione, credenziali, ambienti di collaudo e codici d’errore è un progetto a sé. Un servizio come TrovaPEC, che si aggiorna tramite l’INI-PEC, porta lo stesso dato nel proprio gestionale con un’integrazione più leggera.

Integrare un’API PEC in Python: i passaggi

Il flusso che segue vale per qualunque API di ricerca PEC massiva, perché ricalca la natura a lotti dell’indice. Gli endpoint e i nomi dei campi negli esempi sono segnaposto: quelli reali sono riportati nella documentazione del servizio che si collega.

1. Pulire e validare l’elenco

La maggior parte degli scarti nasce prima della chiamata: spazi, prefisso “IT”, duplicati, Partite IVA con una cifra sbagliata. Validare la cifra di controllo evita di pagare o attendere per codici che non possono esistere.

def piva_valida(piva: str) -> bool:
    if len(piva) != 11 or not piva.isdigit():
        return False
    somma = 0
    for i, c in enumerate(piva):
        n = int(c)
        if i % 2 == 1:
            n *= 2
            if n > 9:
                n -= 9
        somma += n
    return somma % 10 == 0

def prepara(codici):
    puliti = set()
    scarti = []
    for c in codici:
        c = c.strip().upper().replace(" ", "")
        if c.startswith("IT") and len(c) == 13:
            c = c[2:]
        if (len(c) == 11 and piva_valida(c)) or len(c) == 16:
            puliti.add(c)
        else:
            scarti.append(c)
    return sorted(puliti), scarti

Dove si sbaglia: si scartano in silenzio i codici non validi. Conviene invece conservarli in una lista separata, da correggere con una verifica Partita IVA massiva o con la normalizzazione delle anagrafiche.

2. Autenticarsi e inviare il lotto

import time
import requests

BASE_URL = "https://api.servizio-pec.example"  # segnaposto
sessione = requests.Session()
sessione.headers["Authorization"] = "Bearer LA_TUA_CHIAVE"

validi, scarti = prepara(elenco_da_csv)
r = sessione.post(f"{BASE_URL}/richieste", json={"codici": validi}, timeout=30)
r.raise_for_status()
id_richiesta = r.json()["id"]

La chiave va letta da una variabile d’ambiente o da un gestore di segreti, mai scritta nel codice versionato.

3. Attendere l’elaborazione

while True:
    stato = sessione.get(f"{BASE_URL}/richieste/{id_richiesta}", timeout=30).json()
    if stato["stato"] in ("completata", "errore"):
        break
    time.sleep(30)

Dove si sbaglia: un polling troppo frequente consuma il limite di richieste. Un intervallo crescente e un numero massimo di tentativi rendono lo script prevedibile.

4. Scaricare e riconciliare

Il risultato va unito all’elenco di partenza per codice fiscale, ricordando che un codice può restituire due righe (impresa e professionista). Si salvano PEC, data di aggiornamento e un esito per ogni riga: trovato, non trovato, scartato in validazione.

Fasi e risultati del flusso API PEC massivo

Se il servizio è SOAP

Quando l’API espone un WSDL, in Python si usa di solito Zeep, un client SOAP che legge il WSDL e genera le operazioni disponibili; il comando python -mzeep seguito dall’indirizzo del WSDL mostra metodi e tipi prima di scrivere codice. L’autenticazione Basic si imposta sulla sessione requests passata al trasporto del client.

Lo stesso flusso in Node.js

In Node.js cambiano la sintassi e la gestione dell’attesa, non la logica. Con Node 18 o successivo fetch è disponibile senza librerie aggiuntive.

const BASE_URL = "https://api.servizio-pec.example"; // segnaposto
const headers = {
  "Authorization": `Bearer ${process.env.PEC_API_KEY}`,
  "Content-Type": "application/json"
};
const attendi = (ms) => new Promise((r) => setTimeout(r, ms));

async function cercaPec(codici) {
  const invio = await fetch(`${BASE_URL}/richieste`, {
    method: "POST", headers, body: JSON.stringify({ codici })
  });
  if (!invio.ok) throw new Error(`Invio fallito: ${invio.status}`);
  const { id } = await invio.json();

  for (let tentativo = 0; tentativo < 40; tentativo++) {
    const res = await fetch(`${BASE_URL}/richieste/${id}`, { headers });
    const stato = await res.json();
    if (stato.stato === "completata") return stato.risultati;
    if (stato.stato === "errore") throw new Error(stato.messaggio);
    await attendi(30000);
  }
  throw new Error("Tempo di attesa superato");
}

Le differenze pratiche rispetto a Python:

  • Concorrenza. Node gestisce bene molte richieste in parallelo, ed è proprio questo il rischio: lanciare centinaia di chiamate insieme supera i limiti del servizio. Meglio un lotto unico o una coda con concorrenza limitata.
  • Validazione. La funzione di controllo della Partita IVA si riscrive identica in JavaScript; per il codice fiscale esistono librerie dedicate su npm.
  • SOAP. Se il servizio espone un WSDL, serve un client SOAP per Node; il flusso in due fasi resta invariato.
  • Processi lunghi. In un’applicazione web l’attesa del lotto non deve bloccare la richiesta dell’utente: si salva l’identificativo e si completa il lavoro in un processo separato.

Dati aggiornati e affidabili: cosa controllare

Una PEC corretta oggi può cambiare domani, quindi l’integrazione va pensata come un processo ricorrente e non come un’estrazione una tantum.

  • Fonte. I dati devono provenire dall’INI-PEC, alimentato dal Registro Imprese e dagli Ordini professionali.
  • Data di aggiornamento. Va salvata per ogni riga e usata per decidere quando ripetere la ricerca.
  • Esiti espliciti. Ogni codice deve avere un esito tracciato, così da poter documentare l’origine dell’indirizzo usato per una comunicazione con valore legale.
  • Destinazione dei dati. Le PEC trovate servono davvero quando arrivano nel gestionale o nel CRM dove lavorano i team. Le funzioni essenziali di un CRM per PMI includono proprio integrazioni e qualità del dato, i punti dove un flusso PEC automatico si innesta.

Per i casi specifici, come le anagrafiche fornitori, è utile anche la guida su come estrarre un elenco PEC fornitori verificato.

Ricerca PEC via API con TrovaPEC

TrovaPEC offre la ricerca massiva di indirizzi PEC ufficiali di aziende, professionisti ed enti pubblici a partire da elenchi di Partite IVA o Codici Fiscali, con informazioni aggiornate tramite l’Indice Nazionale degli Indirizzi PEC. Per chi sviluppa in Python o Node.js, i Web Services per la ricerca PEC permettono di portare questa ricerca dentro i processi aziendali, senza limiti di volume.

TrovaPEC

Accanto alla ricerca sono disponibili la verifica massiva delle Partite IVA, anche su VIES, la normalizzazione e correzione delle anagrafiche, l’invio massivo di PEC e la rendicontazione dei ritorni. Per una singola verifica è disponibile anche la ricerca PEC gratuita; per un primo elenco senza integrazione si può partire dalla guida per trovare PEC da un elenco.

Il nostro punto di vista

Chi cerca “API PEC” di solito ha già un problema concreto: un file con migliaia di Partite IVA, una scadenza e la necessità di inviare comunicazioni con valore legale agli indirizzi giusti.

Il codice per chiamare un’API è la parte più semplice. Il valore sta in ciò che c’è dietro: dati che arrivano dalle fonti istituzionali, codici puliti prima dell’invio, esiti tracciati riga per riga. Per questo abbiamo costruito TrovaPEC attorno all’automazione completa di ricerca, verifica e gestione degli indirizzi PEC, con informazioni aggiornate tramite l’INI-PEC.

Integrare la ricerca nei propri sistemi tramite web services significa togliere dal lavoro quotidiano le ricerche manuali e trattare le PEC come un dato aziendale vivo, da aggiornare e usare senza attriti.

Alessandro

Domande frequenti

Esiste una libreria Python ufficiale per l’INI-PEC?

Il canale massivo ufficiale è un web service SOAP descritto da WSDL, non una libreria. In Python lo si interroga con un client SOAP generico come Zeep, mentre i servizi REST si chiamano con requests. In entrambi i casi il flusso resta a due fasi: invio del lotto e scarico del risultato.

Perché la risposta non arriva subito?

Perché la ricerca massiva è elaborata a lotti: il sistema restituisce un identificativo di richiesta e rende disponibile il risultato quando l’elaborazione è conclusa. Nel canale ufficiale l’output resta scaricabile per un massimo di 7 giorni solari. Il codice deve quindi salvare l’identificativo e controllare lo stato a intervalli.

Posso cercare una PEC partendo dalla ragione sociale?

Per le imprese l’INI-PEC ammette anche la combinazione di provincia e ragione sociale, ma in un’integrazione automatica la chiave affidabile è il codice fiscale o la Partita IVA. Se si dispone solo dei nomi, conviene prima risalire alle Partite IVA e poi lanciare la ricerca PEC.

Perché alcuni codici risultano non trovati?

Le cause più comuni sono codici formalmente errati, duplicati con formati diversi o soggetti senza una PEC registrata nell’indice. Una validazione preventiva e una verifica massiva delle Partite IVA riducono gli scarti prima dell’invio del lotto.

Fonti

INI-PEC: come funziona
Allegato tecnico Web Service Fornitura PEC Massiva
Comune di Parma: documento sul servizio INI-PEC
Docs Italia: scheda INI-PEC tra le basi di dati di interesse nazionale
Agenzia delle Dogane e dei Monopoli: servizi di accesso ai dati INI-PEC
Zeep: client SOAP per Python
CRM per PMI: funzioni essenziali

Raccomandati

Lascia un commento