Pharos: dichiarazioni doganali export sotto controllo

Il problema, in due righe

Per un esportatore italiano, ogni spedizione fuori UE genera una dichiarazione doganale identificata da un MRN (Movement Reference Number). Da quel momento parte un conto alla rovescia: entro 90 giorni l'Agenzia delle Dogane deve confermare l'uscita fisica della merce con il visto uscita. Se questo non accade, scattano implicazioni IVA e contabili che, su volumi importanti, valgono cifre a sei zeri.

Il tracciamento di queste pratiche, in tante aziende, è ancora oggi un foglio Excel condiviso, una serie di telefonate al doganalista e un controllo manuale settimanale. Pharos nasce per cambiarlo.

Il contesto

Un gruppo internazionale del settore alimentare con forte vocazione export ci chiede aiuto su un processo critico: tracciare in modo affidabile lo stato di ogni MRN dalla fattura fino alla chiusura presso le Dogane, attivare i recuperi documentali quando il visto non arriva, e archiviare i PDF di prova all'interno del gestionale esistente — senza imporre nuove abitudini all'operatore.

I vincoli tecnici sono chiari: - il gestionale ERP è il sistema di verità: niente repository paralleli, le pratiche devono restare consultabili lì - l'integrazione con l'Agenzia Dogane avviene via web service SOAP soggetto a quota giornaliera - l'autenticazione deve usare Active Directory aziendale, niente account separati - l'IT è interno: la soluzione deve essere manutenibile da team Java standard, senza framework esotici

La soluzione: Pharos

Pharos è un'applicazione Java 17 che vive a fianco del gestionale, in due modalità contemporanee:

1. Un processo batch che ogni N ore (parametro di configurazione) interroga in automatico l'Agenzia Dogane per le pratiche aperte, scarica il documento di chiusura quando disponibile e aggiorna lo stato della pratica nel gestionale.
2. Una dashboard web dove gli operatori vedono in tempo reale tutte le pratiche, lo stato di ognuna, le scadenze in semaforo (verde / giallo / rosso / scaduto) e possono caricare manualmente l'MRN, gli allegati doganali e i documenti probatori quando il visto tarda.

L'operatore vede una sola schermata. Filtra per stato, cerca per cliente o numero fattura, esporta in Excel, scarica i PDF di prova, carica nuovi documenti. Tutto qui.

Sei stati, un flusso

Una pratica attraversa fino a sei stati, ognuno con un proprio colore e un'azione operativa chiara:

• Da generare — la fattura esiste ma non c'è ancora una pratica MRN: la creiamo noi
• Da caricare — pratica creata, manca il numero MRN
• In attesa — MRN registrato, aspettiamo il visto delle Dogane
• DP in attesa — il visto tarda, l'operatore ha caricato i documenti probatori (CMR, prove di consegna, ecc.) per chiudere la pratica per via alternativa
• DP chiuso — il visto arriva dopo la fase probatoria
• Chiuso — pratica conclusa normalmente

Tutta la logica di transizione è derivata da due campi che esistevano già nel gestionale: niente nuove tabelle di stato, niente macchine a stati replicate. La fonte di verità resta il gestionale.

Tre dettagli tecnici di cui andiamo fieri

1. Audit trail su ogni chiamata al web service

Le Dogane impongono una quota giornaliera di interrogazioni: oltrepassarla significa blocco temporaneo. Pharos scrive un record di log per ogni chiamata al web service — successo, errore, no-op — su una connessione separata in autocommit, in modo che il log non sia mai impattato da rollback applicativi. Il counter giornaliero è una semplice query sull'audit trail, e l'anno corrente è in pagina metriche.

2. Transazione atomica per la chiusura

Quando arriva il visto uscita, Pharos esegue tre operazioni in transazione sul gestionale: scrive i metadati dell'allegato, salva il PDF binario, aggiorna lo stato della pratica. Commit per record, rollback su qualsiasi errore. Un singolo record corrotto non blocca il batch: la pratica successiva parte da capo.

3. Visualizzazione XML come HTML

Le fatture elettroniche italiane sono XML poco leggibili dall'occhio umano. Pharos applica al volo il foglio di stile ufficiale dell'Agenzia delle Entrate (XSLT) per renderle in HTML stampabile: l'utente clicca sulla graffetta e vede la fattura come al portale SDI, senza scaricare nulla.

Architettura, in una pagina

• Java 17 + Maven, fat JAR auto-contenuto
• JDBC plain su Oracle (nessun ORM): siamo ospiti del DB del gestionale, scriviamo SQL leggibile
• SAAJ per il SOAP, costruito a mano (niente WSDL codegen)
• com.sun.net.httpserver per la UI web (zero application server)
• Bootstrap 5.3 via CDN per la dashboard (zero build frontend)
• Jakarta Mail per le notifiche
• JNDI / LDAP per l'autenticazione AD aziendale
• Logback con rotazione giornaliera, endpoint Prometheus per il monitoring

Tre megabyte di codice, una JAR, un file di configurazione, un comando per lanciarlo. Zero container, zero application server. Sta su una VM RHEL 6 come ovunque.

Risultati operativi

Dopo la messa in produzione:

• Zero pratiche dimenticate. Il semaforo costringe la regolarizzazione prima della soglia legale.
• ~95% delle chiusure automatiche. L'operatore interviene solo sui casi che tardano.
• Tracciatura completa. Ogni chiamata, ogni caricamento, ogni utente è loggato. In caso di contestazione fiscale, la documentazione è immediatamente ricostruibile.
• Adozione immediata. Una schermata, sei stati colorati: la formazione si esaurisce in mezz'ora.

Cosa portiamo via

Tre lezioni che applicheremo al prossimo caso simile:

1. Stare dentro il sistema di verità del cliente, non costruirne uno parallelo. La dashboard è solo una vista; la fonte resta il gestionale.
2. Parametrizzare tutto ciò che è soggetto a normativa: soglie, cadenze, liste di documenti obbligatori. Le regole doganali cambiano: il codice no.
3. Audit trail = funzionalità di prodotto, non log di debug. È quello che salva il cliente in sede di verifica.

---

Lavoriamo su processi mission-critical che incrociano normativa, sistemi legacy e operatività quotidiana. Se hai un caso simile, sentiamoci.