Web Services – API per automatizzare la ricerca PEC

I Web Services e le API di TrovaPEC, in modalità RESTful, automatizzano la ricerca delle PEC: il tuo software invia un codice fiscale o una partita IVA e riceve l’indirizzo PEC ufficiale, senza file da preparare né interfacce da usare a mano.

Se non vuoi o non sai come integrarli nelle tue applicazioni, è disponibile un programma facilmente installabile e configurabile che dialoga con il tuo sistema. Per maggiori informazioni contattaci.

In questa pagina: come funziona · prima di iniziare · specifiche tecniche · esempi di codice · consigli per l’integrazione

Come funziona

Il servizio è asincrono e si usa in quattro passaggi:

1. Invii la richiesta (metodo POST) con la tua key e il codice fiscale o la partita IVA da cercare.
2. Ricevi un token, il codice di prenotazione della richiesta.
3. Chiedi l’esito (metodo GET) con il token, ripetendo la richiesta finché il risultato non è pronto.
4. Ottieni il risultato: la PEC trovata oppure il motivo per cui non è stata trovata.

La richiesta viene evasa in 2-3 minuti.

Prima di iniziare

• Attivazione: il servizio viene attivato dopo aver definito la modalità di fatturazione (anticipata o posticipata) e ti viene fornito un codice identificativo cliente, la key, da usare in ogni richiesta. Richiedi informazioni.
• Cosa puoi cercare: un codice fiscale o una partita IVA (11 cifre, oppure 16 caratteri per il codice fiscale delle persone fisiche; il prefisso “IT” è accettato). Il web service non prevede la ricerca per ragione sociale.
• Indirizzo del servizio: https://trovapec.it/index_ws.php, sempre in HTTPS.
• Formato delle risposte: testo semplice, con i campi separati dal carattere |.

Specifiche tecniche

Tutte le operazioni usano lo stesso indirizzo, https://trovapec.it/index_ws.php: cambiano il metodo HTTP e i parametri. Per provarle a mano abbiamo predisposto due semplici form, che puoi anche scaricare, personalizzare e integrare nei tuoi sistemi:

• index_post.html: per inviare la richiesta;
• index_get.html: per ottenere l’esito della ricerca.

1. Invio richiesta PEC (POST)

2. Richiesta esito PEC (GET)

Esempi di risposta:

OK|esempio@pec.it|pec trovata|ESEMPIO SRL|TORINO|TO
OK||pec non trovata

3. Cancellazione richiesta PEC (POST)

Annulla una richiesta inviata in precedenza. Puoi cancellare soltanto le richieste fatte con la tua key.

4. Richiesta saldo account (POST)

Esempi di codice

Con curl, sostituendo LA_TUA_KEY con la tua key. I comandi sono su una sola riga e funzionano da bash, Prompt dei comandi e PowerShell (in Windows PowerShell 5 scrivi curl.exe al posto di curl):

# 1. invio della richiesta
curl -X POST https://trovapec.it/index_ws.php -d "key=LA_TUA_KEY" -d "cf=12345678901"
# risposta: OK|CodiceToken

# 2. richiesta dell'esito, con il token ricevuto
curl "https://trovapec.it/index_ws.php?key=LA_TUA_KEY&token=CodiceToken"
# risposta: WAIT|CodiceToken oppure OK|PEC|stato|...

# saldo dell'account
curl -X POST https://trovapec.it/index_ws.php -d "key=LA_TUA_KEY" -d "saldo="

Un ciclo completo in PHP: invio, attesa e lettura dell’esito.

<?php
$url = 'https://trovapec.it/index_ws.php';
$key = 'LA_TUA_KEY';

// 1. invio della richiesta
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => ['key' => $key, 'cf' => '12345678901'],
    CURLOPT_RETURNTRANSFER => true,
]);
$risposta = trim(curl_exec($ch));
curl_close($ch);

$campi = explode('|', $risposta, 2);
if (strtoupper($campi[0]) !== 'OK' || empty($campi[1])) {
    exit('Richiesta non accettata: ' . $risposta);
}
$token = $campi[1];

// 2. richiesta dell'esito, ripetuta finché non è pronto
for ($tentativo = 0; $tentativo < 20; $tentativo++) {
    sleep(30);
    $risposta = trim(file_get_contents(
        $url . '?' . http_build_query(['key' => $key, 'token' => $token])
    ));
    $campi = explode('|', $risposta);

    if (strtoupper($campi[0]) === 'WAIT') {
        continue;                       // non ancora pronto
    }
    if (strtoupper($campi[0]) === 'OK') {
        echo 'PEC: ' . $campi[1] . ' (' . $campi[2] . ')';
    } else {
        echo 'Errore: ' . $risposta;
    }
    break;
}

Consigli per l’integrazione

• Basati sul primo campo della risposta: è sempre OK, WAIT o ERROR. Il testo che segue è descrittivo e può cambiare nel tempo, quindi non usarlo per le logiche del tuo programma.
• Conserva il token finché non hai letto l’esito: è l’unico modo per recuperarlo.
• Non stringere troppo il polling: un controllo ogni 30 secondi circa è sufficiente, dato che la richiesta richiede 2-3 minuti.
• Evita gli invii duplicati: ogni richiesta accettata viene conteggiata ai fini della fatturazione.
• Tieni d’occhio il credito con la richiesta di saldo, se il tuo account è prepagato.
• Proteggi la key: usala solo lato server e non inserirla in pagine o app pubbliche.

Hai bisogno di aiuto con l’integrazione o di attivare il servizio?

Per cercare le PEC di interi elenchi, senza integrazioni, vedi la ricerca PEC massiva; per capire cosa viene restituito, leggi le domande frequenti.