Pipeline documentali: da DOCX a PDF/A-3 ad archivio firmato in una singola chiamata API
Una pipeline documentale che converte i documenti di input in output archivistico conforme sembra un problema risolto. In pratica, produce errori silenziosi in ogni fase: font che appaiono corretti sullo schermo ma falliscono la validazione PDF/A, livelli di testo che vengono distrutti durante la conversione, metadati presenti ma tecnicamente errati e timestamp applicati a documenti non ancora nella loro forma finale.
Questo articolo illustra la catena di conversione completa, cosa va storto in ogni fase e come appare una pipeline affidabile.
La catena completa
Source document (DOCX / HTML / existing PDF)
↓ conversion
PDF (rendered with correct fonts and layout)
↓ PDF/A-3 conformance
PDF/A-3 (embedded fonts, color profiles, XMP metadata, no external references)
↓ structured attachment (for hybrid invoices)
PDF/A-3 with embedded XML (Factur-X, ZUGFeRD, XRechnung attachment)
↓ digital signature
Signed PDF/A-3 (PAdES signature, LTV information embedded)
↓ RFC 3161 timestamp
Timestamped PDF/A-3 (RFC 3161 token from qualified EU TSA)
↓ archive + audit trail
Final archive (WORM storage + hash-chained audit trail + evidence pack)Ogni freccia è una fase che può introdurre non-conformità. Ogni fase dovrebbe includere la validazione prima di eseguire quella successiva.
Fase 1: dalla sorgente a PDF
Il percorso di conversione più comune è da DOCX a PDF. Il rischio qui è la sostituzione dei font: se un font utilizzato nel DOCX non è disponibile sul server di conversione, il renderer sostituisce un font diverso. L’output sembra simile sullo schermo ma contiene un font diverso da quello specificato. Quando in seguito viene eseguita la validazione PDF/A, potrebbe rilevare il font sbagliato o fallire perché il font incorporato non corrisponde al font referenziato nel documento.
La mitigazione: assicurarsi che l’ambiente di conversione abbia installati tutti i font richiesti, oppure usare un approccio di conversione che incorpora i font al momento della conversione. LibreOffice headless e Gotenberg (un wrapper Docker-based di LibreOffice) sono opzioni open source affidabili per la conversione da DOCX a PDF. Gotenberg in particolare fornisce un ambiente isolato e prevedibile.
Non convertire DOCX in PDF stampando su un driver PDF. I driver di stampa spesso rasterizzano il testo, distruggendo il livello di testo e producendo un documento visivamente identico ma non più leggibile da macchine o ricercabile. Un PDF rasterizzato non può essere trasformato in un PDF/A-3 valido senza ri-OCR, il che introduce ulteriori errori.
Per HTML in PDF, il rendering con browser headless (utilizzando i motori di rendering dei browser) è generalmente più affidabile per la fedeltà del layout rispetto a wkhtmltopdf. I moderni motori browser gestiscono correttamente il CSS. Verificare che il sorgente HTML abbia tutti i font incorporati o specificati come font web-safe.
Fase 2: da PDF a PDF/A-3
La conformità PDF/A-3 non si ottiene automaticamente producendo un PDF da una libreria compatibile PDF/A-3. Diverse cose possono rompersi:
Metadati XMP mancanti o errati: PDF/A richiede un blocco XMP auto-descrittivo che identifichi il livello di conformità. I campi richiesti:
<rdf:Description rdf:about="" xmlns:pdfaid="http://www.aiim.org/pdfa/ns/id/">
<pdfaid:part>3</pdfaid:part>
<pdfaid:conformance>B</pdfaid:conformance>
</rdf:Description>Senza questo blocco, un documento non è tecnicamente PDF/A-3 indipendentemente dalla sua struttura. Molti convertitori producono output simile a PDF/A ma omettono o configurano erroneamente il blocco XMP.
Font non incorporati: anche se la conversione ha incorporato i font, alcuni convertitori lasciano i font Type1 o TrueType parzialmente incorporati (solo metriche, non i dati completi dei glifi). PDF/A richiede l’incorporazione completa.
Spazi colore non supportati: le immagini nel documento devono usare spazi colore con profili ICC incorporati. Un’immagine RGB senza profilo ICC non supera la validazione PDF/A. Convertire le immagini in sRGB con un profilo incorporato prima di includerle nel documento.
Trasparenza: PDF/A-1 proibisce la trasparenza. PDF/A-2 e PDF/A-3 la consentono ma richiedono una gestione specifica. Molti documenti sorgente utilizzano ombre morbide o overlay traslucidi che devono essere appiattiti prima dell’output PDF/A-1.
Cifratura: PDF/A proibisce la cifratura. Un PDF con una password utente o proprietario non è conforme a PDF/A indipendentemente dalle altre proprietà.
Eseguire VeraPDF dopo questa fase per confermare la conformità prima di procedere. VeraPDF è il validatore di riferimento, utilizzato dagli archivi nazionali e dai regolatori in tutta Europa. È open source e può essere eseguito in una pipeline headless.
Fase 3: incorporazione di XML strutturato (documenti ibridi)
Per le fatture (Factur-X, ZUGFeRD, XRechnung), il PDF/A-3 deve contenere il XML della fattura come allegato con metadati specifici.
La relazione dell’allegato deve essere Alternative per Factur-X, non Data o Unspecified. Questo è definito nella specifica Factur-X ed è uno degli errori di conformità più comuni nei generatori di fatture PDF/A-3.
Lo schema di estensione XMP richiesto per l’allegato Factur-X:
<fx:ConformanceLevel>EN 16931</fx:ConformanceLevel>
<fx:DocumentFileName>factur-x.xml</fx:DocumentFileName>
<fx:DocumentType>INVOICE</fx:DocumentType>
<fx:Version>1.0</fx:Version>Il nome del file deve essere esattamente factur-x.xml per Factur-X, e i metadati XMP devono fare riferimento a questo nome file. I validatori che verificano la conformità Factur-X (non solo PDF/A-3) rifiuteranno i documenti in cui il nome file o il riferimento XMP è errato.
Fase 4: firma digitale
Applicare una firma PAdES (PDF Advanced Electronic Signatures), non una firma PDF di base. PAdES è definito in ETSI EN 319 132 e supporta l’incorporazione LTV.
Al momento della firma, incorporare la catena di certificati completa e la risposta OCSP o lo snapshot CRL che prova che il certificato di firma era valido al momento della firma. Queste sono le informazioni LTV discusse in validazione PDF a lungo termine. Senza di esse, la firma potrebbe diventare non verificabile quando il certificato di firma scade.
Non applicare il timestamp prima della firma. L’ordine corretto è: firmare prima, poi applicare il timestamp alla firma. L’applicazione del timestamp al documento prima della firma cambia l’hash del documento, il che invalida la firma.
Fase 5: timestamp RFC 3161
Richiedere il timestamp immediatamente dopo la firma, mentre il certificato di firma è ancora verificabile online. Il timestamp viene applicato all’hash del documento firmato e copre sia il contenuto del documento che la firma.
Memorizzare il token di timestamp all’interno del PDF (nel dizionario DSS del documento) e anche nel Legal Evidence Pack come file autonomo per la verifica indipendente.
Fase 6: archivio e traccia di audit
Scrivere il documento finale nello storage WORM con il periodo di conservazione bloccato. Aggiungere l’evento di archiviazione alla traccia di audit con catena di hash.
La voce della traccia di audit per la fase di archiviazione dovrebbe includere: l’hash del documento, la posizione di storage, il periodo di conservazione, il timestamp dell’evento di archiviazione e l’hash della voce di audit precedente. Questo produce un record a prova di manomissione che il documento è stato archiviato in questa esatta forma in questo esatto momento.
Validazione in ogni fase
La modalità di errore da evitare è la non-conformità silenziosa: un documento che attraversa tutte e sei le fasi e produce un file che sembra corretto ma non supera la validazione quando presentato a un revisore.
Validare alle fasi 2, 3 e 5:
- Dopo la conversione in PDF/A-3: VeraPDF per la conformità PDF/A-3
- Dopo l’incorporazione XML (se applicabile): validatore del profilo Factur-X o ZUGFeRD
- Dopo il timestamp: verificatore PAdES (DSS o equivalente) per la validità di firma e timestamp
Se la validazione fallisce in qualsiasi fase, arrestare la pipeline e restituire un errore strutturato. Non procedere all’archiviazione con un documento non conforme.
SealDoc come pipeline documentale
L’API SealDoc implementa la catena completa descritta sopra come un singolo endpoint. Si invia il documento sorgente (DOCX, HTML o PDF esistente) insieme ai metadati strutturati (dati della fattura, informazioni sulle parti, categoria di conservazione). L’API esegue la conversione, la validazione PDF/A-3, l’incorporazione XML, la firma, il timestamp e l’archiviazione, restituendo il pacchetto di prove in caso di successo o un errore di validazione strutturato in caso di errore.
Ogni fase nella pipeline è implementata per fallire velocemente: se VeraPDF restituisce un errore di conformità, la pipeline si ferma e restituisce la clausola specifica che è stata violata piuttosto che procedere alla fase successiva con un documento non conforme. Il pacchetto di prove viene generato solo quando tutte le fasi di validazione sono state superate.
Per le organizzazioni che devono integrare l’archiviazione documentale nei flussi di lavoro esistenti, l’API accetta webhook che notificano al completamento o all’errore, e il pacchetto di prove è recuperabile come ZIP contenente tutti i componenti in formati aperti e verificabili indipendentemente.