Documentpijplijnen: van DOCX naar PDF/A-3 naar ondertekend archief in een API-aanroep

Een documentpijplijn die invoerdocumenten omzet naar conforme archiefuitvoer klinkt als een opgelost probleem. In de praktijk produceert hij stille fouten bij elke stap: lettertypen die er op het scherm correct uitzien maar PDF/A-validatie mislukken, tekstlagen die tijdens conversie worden vernietigd, metadata die aanwezig maar technisch onjuist is en tijdstempels aangebracht op documenten die nog niet in hun definitieve vorm zijn.

Dit artikel doorloopt de volledige conversieketen, wat bij elke fase misgaat en hoe een betrouwbare pijplijn eruitziet.

De volledige keten

Brondocument (DOCX / HTML / bestaande PDF)
    ↓  conversie
PDF (weergegeven met correcte lettertypen en indeling)
    ↓  PDF/A-3-conformiteit
PDF/A-3 (ingebedde lettertypen, kleurprofielen, XMP-metadata, geen externe verwijzingen)
    ↓  gestructureerde bijlage (voor hybride facturen)
PDF/A-3 met ingebedde XML (Factur-X, ZUGFeRD, XRechnung-bijlage)
    ↓  digitale handtekening
Ondertekende PDF/A-3 (PAdES-handtekening, LTV-informatie ingebed)
    ↓  RFC 3161-tijdstempel
PDF/A-3 met tijdstempel (RFC 3161-token van gekwalificeerde EU-TSA)
    ↓  archief + auditspoor
Definitief archief (WORM-opslag + hashgekoppeld auditspoor + evidence pack)

Elke pijl is een stap die non-conformiteit kan introduceren. Elke stap dient validatie te bevatten voordat de volgende stap start.

Stap 1: bron naar PDF

De meest voorkomende conversieroute is DOCX naar PDF. Het risico hier is lettertypevervanging: als een lettertype dat in de DOCX wordt gebruikt, niet beschikbaar is op de conversieserver, vervangt de renderer het door een ander lettertype. De uitvoer ziet er op het scherm vergelijkbaar uit maar bevat een ander lettertype dan opgegeven. Wanneer later PDF/A-validatie wordt uitgevoerd, kan het het verkeerde lettertype detecteren of mislukken omdat het ingebedde lettertype niet overeenkomt met het in het document vermelde.

De maatregel: zorg dat de conversieomgeving alle vereiste lettertypen heeft geinstalleerd, of gebruik een conversiemethode die lettertypen inbedt tijdens conversie. LibreOffice headless en Gotenberg (een op Docker gebaseerde LibreOffice-wrapper) zijn betrouwbare open-sourceopties voor DOCX-naar-PDF-conversie. Gotenberg biedt in het bijzonder een voorspelbare geïsoleerde omgeving.

Converteer DOCX niet naar PDF via afdrukken naar een pdf-stuurprogramma. Afdrukstuurprogramma’s rasteren tekst vaak, wat de tekstlaag vernietigt en een document produceert dat visueel identiek maar niet meer machine-leesbaar of doorzoekbaar is. Een gerasterde PDF kan niet worden omgezet in een geldige PDF/A-3 zonder opnieuw OCR, wat extra fouten introduceert.

Voor HTML naar PDF is weergave via een headless browser (met browserrendererengines) over het algemeen betrouwbaarder voor indelingstrouw dan wkhtmltopdf. Moderne browserengines verwerken CSS correct. Controleer of de HTML-bron alle lettertypen ingebed heeft of veilige weblettertypen gebruikt.

Stap 2: PDF naar PDF/A-3

PDF/A-3-conformiteit wordt niet automatisch bereikt door een PDF te genereren uit een PDF/A-3-bewuste bibliotheek. Verschillende dingen kunnen misgaan:

Ontbrekende of onjuiste XMP-metadata: PDF/A vereist een zelfdescriptief XMP-blok dat het conformiteitsniveau identificeert. De vereiste velden:

<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>

Zonder dit blok is een document technisch geen PDF/A-3, ongeacht zijn structuur. Veel converters produceren PDF/A-achtige uitvoer maar laten het XMP-blok weg of configureren het onjuist.

Niet-ingebedde lettertypen: zelfs als de conversie lettertypen heeft ingebed, laten sommige converters Type1- of TrueType-lettertypen gedeeltelijk ingebed (alleen metrische gegevens, niet de volledige glyfgegevens). PDF/A vereist volledige inbedding.

Niet-ondersteunde kleurruimten: afbeeldingen in het document moeten kleurruimten gebruiken met ingebedde ICC-profielen. Een RGB-afbeelding zonder ICC-profiel mislukt PDF/A-validatie. Converteer afbeeldingen naar sRGB met een ingebed profiel voordat ze in het document worden opgenomen.

Transparantie: PDF/A-1 verbiedt transparantie. PDF/A-2 en PDF/A-3 staan het toe maar vereisen specifieke afhandeling. Veel brondocumenten gebruiken zachte schaduwen of doorzichtige overlays die moeten worden afgevlakt voor PDF/A-1-uitvoer.

Versleuteling: PDF/A verbiedt versleuteling. Een PDF met een gebruikers- of eigenaarswachtwoord is niet PDF/A-conform ongeacht andere eigenschappen.

Voer VeraPDF na deze stap uit om conformiteit te bevestigen voordat je verdergaat. VeraPDF is de referentievalidator, gebruikt door nationale archieven en toezichthouders door heel Europa. Het is open source en kan in een headless pijplijn worden uitgevoerd.

Stap 3: gestructureerde XML inbedden (hybride documenten)

Voor facturen (Factur-X, ZUGFeRD, XRechnung) moet de PDF/A-3 de XML-factuur als bijlage bevatten met specifieke metadata.

De bijlagerelatie moet Alternative zijn voor Factur-X, niet Data of Unspecified. Dit is gedefinieerd in de Factur-X-specificatie en is een van de meest voorkomende conformiteitsfouten in PDF/A-3-factuurgeneratoren.

Het vereiste XMP-uitbreidingsschema voor de Factur-X-bijlage:

<fx:ConformanceLevel>EN 16931</fx:ConformanceLevel>
<fx:DocumentFileName>factur-x.xml</fx:DocumentFileName>
<fx:DocumentType>INVOICE</fx:DocumentType>
<fx:Version>1.0</fx:Version>

De bestandsnaam moet precies factur-x.xml zijn voor Factur-X, en de XMP-metadata moet naar deze bestandsnaam verwijzen. Validators die Factur-X-conformiteit controleren (niet alleen PDF/A-3) wijzen documenten af waarbij de bestandsnaam of de XMP-verwijzing onjuist is.

Stap 4: digitale handtekening

Pas een PAdES (PDF Advanced Electronic Signatures)-handtekening toe, geen standaard pdf-handtekening. PAdES is gedefinieerd in ETSI EN 319 132 en ondersteunt LTV-inbedding.

Bedt bij het ondertekenen de volledige certificaatketen en de OCSP-reactie of CRL-snapshot in die bewijst dat het ondertekeningscertificaat geldig was op het moment van ondertekening. Dit is de LTV-informatie besproken in langetermijn-pdf-validatie. Zonder dit kan de handtekening onverifieerbaar worden wanneer het ondertekeningscertificaat vervalt.

Zet geen tijdstempel voor het ondertekenen. De juiste volgorde is: eerst ondertekenen, dan de handtekening van een tijdstempel voorzien. Het document van een tijdstempel voorzien voor het ondertekenen wijzigt de documenthash, waardoor de handtekening ongeldig wordt.

Stap 5: RFC 3161-tijdstempel

Vraag het tijdstempel direct na het ondertekenen aan, terwijl het ondertekeningscertificaat nog online verifieerbaar is. Het tijdstempel wordt aangebracht op de hash van het ondertekende document en dekt zowel de documentinhoud als de handtekening.

Sla het tijdstempeltoken op in de PDF (in het DSS-woordenboek van het document) en ook in het Legal Evidence Pack als een zelfstandig bestand voor onafhankelijke verificatie.

Stap 6: archief en auditspoor

Schrijf het uiteindelijke document naar WORM-opslag met de bewaartermijn vergrendeld. Voeg de archiveringsgebeurtenis toe aan het hashgekoppelde auditspoor.

De auditspoorvermelding voor de archiveringsstap dient te bevatten: de documenthash, de opslaglocatie, de bewaartermijn, de tijdstempel van de archiveringsgebeurtenis en de hash van de vorige auditvermelding. Dit produceert een manipulatie-evident record dat het document in precies deze vorm op precies dit moment is gearchiveerd.

Validatie bij elke stap

Het te vermijden faalmodus is stille non-conformiteit: een document dat alle zes stappen doorloopt en een bestand produceert dat er correct uitziet maar validatie mislukt wanneer het aan een auditor wordt gepresenteerd.

Valideer bij stappen 2, 3 en 5:

Na PDF/A-3-conversie: VeraPDF voor PDF/A-3-conformiteit
Na XML-inbedding (indien van toepassing): Factur-X- of ZUGFeRD-profielvalidator
Na tijdstempeling: PAdES-verificatieprogram (DSS of equivalent) voor handtekening- en tijdstempelgeldigheid

Als validatie bij een stap mislukt, stop de pijplijn en retourneer een gestructureerde fout. Ga niet door naar archivering met een niet-conform document.

SealDoc als documentpijplijn

De SealDoc-API implementeert de hierboven beschreven volledige keten als een enkel endpoint. Je dient het brondocument (DOCX, HTML of bestaande PDF) in samen met de gestructureerde metadata (factuurgegevens, partijinformatie, bewaarcategorie). De API voert conversie, PDF/A-3-validatie, XML-inbedding, ondertekening, tijdstempeling en archivering uit en retourneert het evidence pack bij succes of een gestructureerde validatiefout bij mislukking.

Elke stap in de pijplijn is geimplementeerd om snel te falen: als VeraPDF een conformiteitsfout retourneert, stopt de pijplijn en retourneert de specifieke clausule die werd geschonden in plaats van door te gaan naar de volgende stap met een niet-conform document. Het evidence pack wordt alleen gegenereerd wanneer alle validatiestappen zijn geslaagd.

Voor organisaties die documentarchivering moeten integreren in bestaande workflows accepteert de API webhooks die melden bij voltooiing of mislukking, en het evidence pack is opvraagbaar als een ZIP met alle onderdelen in open, onafhankelijk verifieerbare formaten.