Guida all'integrazione · Italia · Ultimo aggiornamento: luglio 2026

Verifica della partita IVA via API — numero di consultazione VIES in automatico

Se il tuo gestionale, il tuo e-commerce o il tuo software di fatturazione emette fatture B2B intracomunitarie non imponibili, devi verificare la partita IVA dell'acquirente — e conservare la prova di quella verifica. È proprio qui che la maggior parte delle integrazioni lascia un buco.

A fronte di un'interrogazione qualificata, il servizio VIES restituisce un numero di consultazione — una prova ufficiale con marca temporale che l'Agenzia delle Entrate accetta come giustificativo della non imponibilità nelle cessioni intracomunitarie (art. 41 DL 331/1993, art. 138 Direttiva 2006/112/CE). Senza quel numero, in una verifica fiscale hai solo uno screenshot — non un documento riconosciuto.

Che cos'è il numero di consultazione VIES?

Il VIES (VAT Information Exchange System) è il sistema ufficiale UE per la validazione delle partite IVA. Quando interroghi una partita IVA indicando la tua (il "richiedente"), VIES genera un numero di consultazione nel formato WAPIAAAAW1234567.

Questo numero documenta:

Quale partita IVA è stata verificata
Da chi (la tua partita IVA come richiedente)
Il momento esatto della verifica
Che l'esito era "valido" al momento del controllo

L'iscrizione al VIES è condizione necessaria per operare in regime di non imponibilità intracomunitaria; il numero di consultazione è la prova documentale di aver effettuato la verifica.

Il problema: la maggior parte delle API non restituisce il numero di consultazione

Le comuni API di verifica IVA — incluse molte integrazioni nei gestionali più diffusi — interrogano VIES ma restituiscono solo true o false. Il numero di consultazione va perso.

Risultato: sai che una partita IVA era valida, ma non puoi provarlo. In una verifica non basta.

Vatnode: verifica la partita IVA e ottieni il numero di consultazione in una sola chiamata

Vatnode restituisce a ogni richiesta il numero di consultazione completo — pronto per essere salvato nel tuo database o gestionale:

cURL

curl -X POST https://vatnode.com/v1/validate \
  -H "x-api-key: vnd-la-tua-chiave" \
  -H "Content-Type: application/json" \
  -d '{"vat_number":"IT00743110157","requester_vat":"IT12345678901"}'

Risposta · JSON

{
  "valid": true,
  "vatNumber": "IT00743110157",
  "countryCode": "IT",
  "consultationNumber": "WAPIAAAAW1234567",  ← la prova
  "name": "...",
  "address": "...",
  "requestDate": "2026-07-06+02:00",
  "timestamp": "2026-07-06T10:14:02.000Z"
}

Salva consultationNumber e timestamp direttamente nel record della fattura: è la tua prova a norma.

VIES spesso non è raggiungibile — cosa succede?

VIES ha frequenti interruzioni per singolo Paese. Quando il database dello Stato membro è offline, Vatnode restituisce un errore chiaro e ripetibile invece di un fuorviante valid:false, così non rifiuti per errore un cliente reale:

JSON

{ "error": "vies_unavailable", "retryable": true }

Implementa un breve retry con backoff. Lo stato in tempo reale di tutti i 27 Paesi è sulla pagina di stato VIES.

Caso d'uso: software di fatturazione

JavaScript (Node.js)

// Alla creazione di una fattura B2B verso un cliente UE
async function validaESalva(partitaIva, richiedente, fatturaId) {
  const res = await fetch('https://vatnode.com/v1/validate', {
    method: 'POST',
    headers: { 'x-api-key': 'vnd-la-tua-chiave', 'Content-Type': 'application/json' },
    body: JSON.stringify({ vat_number: partitaIva, requester_vat: richiedente })
  });
  const data = await res.json();
  if (data.error) throw new Error(data.error);      // es. vies_unavailable → retry
  if (!data.valid) throw new Error('Partita IVA non valida');

  await db.fatture.update(fatturaId, {
    numero_consultazione: data.consultationNumber,
    verificata_il: data.timestamp
  });
}

Copertura

Vatnode copre tutti i 27 Stati membri UE tramite VIES, con cattura del numero di consultazione ed enrichment (ragione sociale + indirizzo, ove forniti da VIES). In più valida i Paesi non-VIES tramite i loro registri nazionali ufficiali — Norvegia già attiva, Svizzera in arrivo. La lista completa è nella documentazione API.

Prova gratis

100 verifiche al mese gratis — nessuna carta richiesta. Prezzo da fondatore bloccato per i partner iniziali.

Niente spam. Prezzi per i primi utenti garantiti.