Verifica della validità del numero di partita IVA / IVA UE Pro modulo per PrestaShop

Caratteristiche e vantaggi principali del modulo

🌍 Validazione EU VAT — catena di provider

• VIES REST API (Commissione Europea) — servizio ufficiale UE, gratuito, senza chiavi API, restituisce un numero di consultazione conforme alle normative
• VATcomply — proxy gratuito per VIES, limite di 2 richieste/s/IP, senza autenticazione
• VATLayer (APILayer) — API commerciale ad alta disponibilità, richiede una chiave API, restituisce i dati completi dell’azienda
• viesapi.eu — proxy VIES commerciale polacco con HTTP Basic Auth, tempi di risposta rapidi
• Catena configurabile a 3 slot — scegli Provider 1 (principale), Provider 2 (di riserva), Provider 3 (ultima risorsa)
• Fallback automatico — se il primo provider restituisce un errore o un timeout, il modulo prova automaticamente il successivo
• Timeout e retry per provider — configura limiti di tempo separati per ogni provider
• Cache TTL per provider — diversi periodi di validità della cache per ogni API
• Protezione dai duplicati — JavaScript blocca la selezione dello stesso provider in 2 slot, validazione server-side lato PHP

🇵🇱 Validazione della partita IVA polacca — registro GUS

• Integrazione con GUS BIR1.1 API — registro ufficiale governativo REGON, chiave gratuita da api.stat.gov.pl
• Semplice verifica della cifra di controllo del NIP — algoritmo ponderato secondo la specifica ufficiale del Ministero delle Finanze
• Rifiuto di pattern non validi — tutti zeri, tutti uno, cifre identiche — bloccati automaticamente
• Validazione checksum = 10 — secondo la specifica ufficiale del NIP, il valore 10 non è valido
• Recupero dei dati aziendali — nome, indirizzo, CAP, località dal registro REGON
• Timeout e retry configurabili — adattamento alle prestazioni dei server GUS

💰 Esenzione IVA automatica (0% reverse charge)

• Applicazione automatica dell’IVA 0% per clienti B2B verificati dei paesi UE
• Paese di origine configurabile — esclusione dello 0% per le transazioni nazionali (conforme alla normativa IVA)
• Elenco dei paesi da verificare tramite VIES — seleziona i paesi specifici soggetti a validazione
• Opzione "consenti se la validazione non riesce" — non bloccare la registrazione in caso di guasto VIES
• Integrazione con il motore fiscale di PrestaShop tramite `TaxManagerInterface`

👥 Gestione automatica dei gruppi clienti

• Assegnazione automatica del gruppo dopo la validazione — ad es. aggiunta automatica al gruppo "B2B" o "Esenti IVA"
• Mantenimento dei gruppi esistenti — il cliente non perde nessuno dei gruppi già assegnati
• Aggiunta idempotente — nessun duplicato anche in caso di validazioni ripetute
• Validazione Group::isLoadedObject — sicurezza in caso di gruppi eliminati

📧 Notifiche e-mail

• E-mail all’admin in caso di nuova validazione B2B — informazione immediata su un nuovo cliente aziendale
• E-mail in caso di fallimento della ri-validazione — avviso di sicurezza quando la partita IVA non è più valida
• Template multilingua (polacco, inglese) — modificabili nell’editor standard di PS
• Indirizzo del mittente configurabile — per impostazione predefinita l’e-mail del negozio dalle impostazioni PS

🔄 Ri-validazione al cambio di stato dell’ordine

• Nuovo controllo automatico della partita IVA quando l’ordine passa allo stato selezionato (es. "Pagamento accettato")
• Tutela della conformità — intercetta le situazioni in cui la partita IVA è scaduta tra l’ordine e la spedizione
• Log di audit completo — ogni ri-validazione viene salvata con il consultation number VIES
• Multishop-aware — utilizza il contesto del negozio dell’ordine, non il selettore admin corrente

📊 Dashboard amministrativa professionale

• Dashboard con 5 sezioni — catena di provider, statistiche di validazione, ultime validazioni, telemetria provider, guida rapida introduttiva
• Visualizzazione della catena — 3 slot con icone, nomi, stato (attivo/disattivato/nessuna chiave)
• 7 schede KPI — totale, validi, non validi, ultimi 7 giorni, VIES, GUS, voci cache
• Tabella delle ultime 10 validazioni — numero IVA, fonte, risultato, azienda, cliente, data
• Telemetria provider — success rate per provider, numero di controlli, ultima chiamata
• Schede provider con badge FREE/PAID — informazione chiara sui costi
• Colorazione automatica — verde (OK), arancione (warn), rosso (error)

🏪 Supporto multistore completo

• Isolamento della cache per negozio — colonna `id_shop` nella tabella cache, chiave UNIQUE composita
• Isolamento dei log per negozio — audit per entità legale
• Configurazione per negozio — provider, chiavi API, gruppi clienti diversi per ogni negozio
• Ri-validazione shop-aware — l’hook usa il contesto dell’ordine, non quello dell’admin
• Impostazione automatica dei valori predefiniti per tutti i negozi durante l’installazione

⚡ Prestazioni e ottimizzazione

• Cache a due livelli — statica (in-memory) + persistente (database)
• Negative cache — nessuna nuova query DB per numeri non validati
• TTL enforcement in lettura — le voci vecchie vengono ignorate automaticamente
• Lazy render della dashboard — le statistiche vengono calcolate solo nella scheda Dashboard
• Singola query SQL aggregata — 6 COUNT(*) → 1 SUM(CASE WHEN)
• Read replica per tutte le letture (`_PS_USE_SQL_SLAVE_`)
• Indici dedicati — idx_date, idx_source, idx_shop
• Retention dei log tramite CRON — pulizia automatica dopo il periodo configurabile (default 365 giorni)

🔒 Sicurezza

• CSRF tokens in tutti i punti di ingresso (front, admin, CRON)
• Timing-safe comparison (`hash_equals`) per la validazione dei token
• Sanitizzazione SQL completa — `pSQL()`, `(int)`, `bqSQL()` ovunque
• Escaping Smarty — `htmlall:UTF-8` per tutte le variabili nei template
• SSL verification — `CURLOPT_SSL_VERIFYPEER=true` in tutte le chiamate ai provider
• Whitelist dei provider — impossibile salvare un provider non valido nella catena
• _PS_VERSION_ guard in ogni file PHP
• Annotazione AdminSecurity nel controller admin Symfony

🛠️ Compatibilità e dipendenze

• PrestaShop 1.7.0 – 9.x — piena compatibilità, guard versionati
• PHP 7.0 – 8.5 — nessuna sintassi moderna senza guard
• MySQL 5.6+ / MariaDB 10.x+ — charset utf8mb4
• Zero Composer / vendor — autoloader PSR-4 proprietario (15 righe di codice)
• Dual translation system — trans() + fallback l() funziona su tutte le versioni PS
• Traduzioni polacche complete — oltre 200 voci in pl.php e nei file XLF
• Dual theme support — temi admin legacy (Smarty) e moderni (Symfony)

👨‍💼 Pannello amministrativo — 10 schede

• Dashboard — dashboard con 5 sezioni, scheda predefinita
• Impostazioni — opzioni generali di validazione, controllo ISO, auto-group, cache TTL, ri-validazione
• Impostazioni EU VAT — attivazione VIES, elenco paesi, aliquota 0%, allow on fail, paese di origine
• Catena di provider — 3 select con JavaScript che blocca i duplicati
• VIES REST — timeout, cache TTL, retry (senza chiavi)
• VATcomply — timeout, cache TTL, retry (senza chiavi)
• VATLayer — API key, timeout, cache TTL, retry
• viesapi.eu — identifier, access key, timeout, cache TTL, retry
• Configurazione GUS — attivazione, paese, chiave utente, allow on fail, timeout, cache TTL, retry
• Strumenti — URL CRON per la pulizia di cache e log

🎯 Per chi è questo modulo?

• Negozi PrestaShop che vendono ad aziende (B2B) nell’Unione Europea
• Venditori che emettono fatture con inversione contabile (reverse charge)
• Negozi che operano sul mercato polacco e richiedono la verifica del NIP nel GUS
• Piattaforme multistore con diverse entità giuridiche per negozio
• Venditori che necessitano di un audit della validazione IVA conforme alle normative fiscali
• Negozi con alto volume di transazioni B2B che richiedono cache e alta disponibilità