Local-first support tool for checking Italian public project codes (CUP) before administrative reporting, with static OpenCUP lookup and a Python library.
Web app · Python package · Documentazione
Nella rendicontazione di progetti pubblici, fondi PNRR e programmi finanziati, un CUP scritto male può bloccare controlli, rallentare pratiche e generare correzioni costose. Verificare manualmente centinaia o migliaia di codici prima di una trasmissione ufficiale e un'attività ripetitiva, lenta e soggetta a errore.
cup-check nasce per ridurre questo attrito operativo: aiuta funzionari, consulenti e team tecnici a controllare in batch liste di CUP prima di rendicontazioni, caricamenti o verifiche amministrative, intercettando rapidamente errori formali e assenze dal perimetro OpenCUP disponibile.
Il progetto mantiene una postura cautelativa: distingue il formato valido dalla verifica di esistenza, usa un dataset OpenCUP statico e versionato quando disponibile, e non presenta mai il risultato come certificazione autoritativa.
cup-check include una web app statica per controllare liste di CUP direttamente nel browser e una libreria Python importabile per usare lo stesso validatore in script, pipeline e applicazioni. La verifica controlla il formato (regole R0-R5) e, quando il dataset OpenCUP statico è disponibile, la presenza del CUP nel mirror pubblicato. Se il dataset non è disponibile, un CUP formalmente valido resta FORMATO_VALIDO_DA_VERIFICARE. Da 0.4.0 la web app include anche un tool per estrarre CUP da fatture PDF, con testo nativo e OCR locale in italiano come fallback per documenti scansionati. Da 0.5.0 include il tool di estrazione da fatture XML FatturaPA, l'import multi-file nel verificatore con tracciabilità dell'origine, e la validazione batch di oltre 100.000 righe tramite Web Worker dedicato.
cup-check is an open source, local-first tool for checking Italian CUP codes used in public investment projects before administrative reporting, uploads or downstream validation. It helps public administrations and technical teams review large CUP lists, find format errors and compare codes with a static OpenCUP mirror.
The project is designed for zero operational cost, browser-side processing, auditable rules and cautious outcomes. It is not an authoritative certification service: final existence checks still belong to the official CUP/OpenCUP channels.
Versione corrente: 0.5.0 — web app statica (TypeScript + Svelte 5), package Python cup-check su PyPI, tool di estrazione CUP da PDF e da fatture XML FatturaPA, import multi-file, accessibilità WCAG AA, batch >100k con Web Worker, i18n italiano/inglese.
Il dataset OpenCUP statico è uno snapshot mensile; il numero di CUP indicizzati è riportato nel dataset-manifest.json della release corrente.
Roadmap: 0.5.0 rilasciata · 0.6.0 in sviluppo (coerenza atto: cross-check CUP con dati atto, dataset dettagli chunked) · dettaglio completo.
- Valida CUP da file CSV e XLSX, anche multi-file con tracciabilità dell'origine.
- Valida CUP incollati come testo, uno per riga.
- Verifica la presenza nel dataset OpenCUP statico quando il dataset è disponibile.
- Mostra risultati filtrabili per esito e testo.
- Mostra ed esporta i risultati raggruppati per CUP o riga per riga.
- Funziona offline dopo la prima visita.
- Espone una libreria Python installabile come
cup-check. - Interfaccia in italiano e inglese con selettore lingua persistito.
Disponibile nel menu "Strumenti" della web app, il tool estrae automaticamente i codici CUP da uno o più file PDF:
- Apri il menu Strumenti e scegli Estrai CUP da fatture PDF.
- Carica uno o più PDF tramite la zona di rilascio o il selettore file.
- Il tool legge il testo nativo con pdf.js; se il documento è scansionato usa OCR locale in italiano (Tesseract.js, nessuna rete esterna).
- Controlla la tabella file/CUP, correggi manualmente eventuali letture imperfette.
- Clicca Apri nel verificatore per passare l'elenco estratto al verificatore principale, oppure Esporta CSV per scaricare il file
cup,file_originedirettamente.
Il tool mostra la validazione formale del CUP (regex + checksum). La verifica di esistenza nel dataset OpenCUP avviene solo nel verificatore principale, dopo il passaggio. I file PDF sono elaborati interamente nel browser; nessun dato viene trasmesso a server esterni.
Disponibile nel menu "Strumenti" della web app, il tool estrae CUP da fatture elettroniche in formato FatturaPA (XML):
- Apri il menu Strumenti e scegli Estrai CUP da fatture XML.
- Carica uno o più file XML tramite la zona di rilascio o il selettore file.
- Il tool cerca prima i campi strutturati (
CodiceCUPeAltriDatiGestionali[TipoDato=CUP]) e usa testo libero (Causale,Descrizione) come fallback. - Correggi manualmente eventuali CUP letti in modo imperfetto dal testo libero.
- Clicca Apri nel verificatore per passare l'elenco al verificatore principale, oppure Esporta CSV per scaricare un file con i dati della fattura (data, numero, importo, causale, fornitore, CIG) oltre ai CUP estratti. File privi di CUP generano comunque una riga nell'export.
L'estrazione avviene interamente nel browser con DOMParser nativo; nessun dato viene trasmesso a server esterni.
File CSV/XLSX e testi incollati vengono elaborati localmente nel browser. L'app non carica i CUP, i file o i report su un backend applicativo.
La web app recupera il dataset OpenCUP statico come asset pubblico e cacheabile, senza servizi server-side applicativi. I file caricati dagli utenti e i report restano elaborati localmente.
Il progetto è rilasciato con licenza EUPL-1.2 ed è strutturato per essere valutabile in contesti di adozione, integrazione o condivisione nella Pubblica Amministrazione, in coerenza con i principi delle Linee guida AGID su acquisizione e riuso del software.
cup-check non è un servizio ufficiale né una fonte autoritativa: fornisce controlli locali, auditabili e cautelativi a supporto dei processi amministrativi.
cup-check è in fase di sviluppo: può contenere errori, bug o interpretazioni
incomplete delle regole. I risultati sono un supporto operativo, non una
certificazione.
La verifica OpenCUP usa una banca dati generata mensilmente: potrebbe non includere gli ultimi CUP emessi, CUP non ancora pubblicati o record aggiornati dopo l'ultimo snapshot.
Gli esiti possibili sono:
INVALIDO_FORMATO— il CUP non rispetta le regole strutturali.FORMATO_VALIDO_DA_VERIFICARE— il CUP rispetta le regole strutturali, ma il dataset non è disponibile.TROVATO_OPENCUP— CUP presente nel mirror OpenCUP disponibile.NON_TROVATO_OPENCUP_DA_VERIFICARE— CUP non presente nel mirror OpenCUP disponibile; richiede verifica cautelativa e potrebbe comunque esistere.
Per attestare l'esistenza di un progetto resta necessario il Sistema CUP o il portale OpenCUP.
- Guida utente
- Note di accessibilità
- Sviluppo
- Processo di release
- Product
- Architettura
- Specifiche tecniche
- Roadmap
- Fonti dati
- Governance
- Contributori
- Glossario
- ADR
Il progetto accetta contributi coerenti con la roadmap e con i vincoli di governance. Vedi CONTRIBUTING.md per processo, convenzioni e regola fixture-first.
Lo sviluppo segue un processo esplicito di qualità e tracciabilità, supportato anche da strumenti moderni di automazione e assistenza, inclusi assistenti AI: decisioni di prodotto e architettura sono documentate negli ADR, i comportamenti del validatore partono dai fixture normativi e ogni modifica rilevante passa da test e CI.
AGENTS.md rende pubbliche le regole operative per gli agenti di coding che collaborano sul repository, in particolare i vincoli sul validatore formale, sul web package statico e sulla separazione tra controlli locali e verifica remota opzionale.
EUPL-1.2. Vedi LICENSE.