Verifica batch degli standard con Connect

Verifica batch degli standard tramite Connect

In sintesi

Questa ricetta illustra come verificare più file PDF rispetto a uno o più criteri indicati per nome in un’unica chiamata. Usa lo strumento batch di conformità tramite i trasporti Connect. Lo strumento è di livello Enterprise: un controllo class_exists() lo rileva e viene registrato solo quando nextpdf/premium è installato insieme al server. Ogni documento viene verificato rispetto a ciascun criterio della richiesta e la risposta è un report consolidato per documento e per criterio.

Come per il controllo su singolo documento, un «pass» per criterio indica l’esito della verifica eseguita dallo strumento rispetto alle regole che implementa e non è una certificazione di conformità indipendente. È un validatore a determinare la conformità.

Installazione

composer require nextpdf/server

Verificare la presenza dello strumento batch Enterprise con una chiamata tools/list. Vedere /connect/tool-catalog/.

Panoramica concettuale

Uno standard definisce i requisiti per ciascun documento e un controllore valuta ogni documento rispetto a tali requisiti (PDF/A-4 §6.2.3). La conformità è determinata in base ai requisiti, non asserita dal produttore (PDF/A-4 §6.7.3). Per i criteri relativi alle firme, i livelli baseline PAdES sono distinti e i livelli B-LT/B-LTA (materiale di validazione, marca temporale di archiviazione) sono una funzionalità riservata a Enterprise (ETSI EN 319 142-2 §5.5). Il risultato batch applica all’intero insieme di documenti la stessa semantica ristretta «nessuna regola implementata non superata».

Superficie API

Verificare i nomi degli strumenti nel registro in esecuzione con tools/list. Il catalogo di riferimento è /connect/tool-catalog/. Questa ricetta non ripete il conteggio degli strumenti.

Esempio di codice — Avvio rapido

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "batch_compliance_check",
    "arguments": {
      "sources": ["/data/q1.pdf", "/data/q2.pdf"],
      "policies": ["pdfa-4"]
    }
  }
}

Esempio di codice — Produzione

curl -sS -X POST https://connect.example.com/v1/tools/batch_compliance_check \
  -H 'Authorization: Bearer '"$NEXTPDF_CONNECT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"sources":["/data/q1.pdf","/data/q2.pdf"],"policies":["pdfa-4"]}' \
  -o /tmp/batch.json -w '%{http_code}' > /tmp/batch-status || {
    echo "transport failure invoking batch_compliance_check" >&2; exit 1; }

La risposta contiene un id di batch, i conteggi aggregati pass/fail e un array checks per documento con i risultati per criterio e le motivazioni degli esiti negativi. Filtrare gli esiti negativi, correggerli e reinviare solo i documenti interessati.

Casi limite e insidie

sources o policies vuoti sono un errore di parametri non validi.
Un file mancante viene riportato come errore nel singolo risultato anziché far fallire l’intero batch. Verificare in ciascun risultato la presenza di un campo di errore.
Il superamento del limite di dimensione del batch è un errore esplicito. Suddividere il lavoro in batch più piccoli.
Un id di criterio sconosciuto è un errore per standard sconosciuto che indica gli identificatori riconosciuti. I criteri di firma che fanno riferimento a B-LT/B-LTA hanno significato solo in un’installazione Enterprise in grado di produrre tale materiale.
Strumento assente. Senza nextpdf/premium lo strumento batch Enterprise non viene registrato; la chiamata fallisce con un errore di strumento sconosciuto.

Prestazioni

Il budget indicato nel front-matter è un limite di documentazione. Lo strumento elabora i documenti lato server e la memoria di lavoro per documento non è trascurabile. Dimensionare il batch in base alla memoria dell’host anziché aumentare un timeout globale.

Note di sicurezza

Non registrare i percorsi sorgente o il report completo a un livello di log distribuito all’esterno. Registrare solo l’id di batch e i conteggi aggregati pass/fail. Un «pass» per criterio descrive l’insieme di regole implementate, non una garanzia di sicurezza né legale.

Conformità

Dichiarazione	Clausola	reference_id
Lo standard definisce i requisiti; un controllore valuta ciascun documento	PDF/A-4 §6.2.3
Conformità determinata in base ai requisiti, non asserita dal produttore	PDF/A-4 §6.7.3
B-LT/B-LTA aggiungono materiale di validazione; livelli distinti e riservati a Enterprise	ETSI EN 319 142-2 §5.5

Il supporto alla verifica batch degli standard non è una certificazione di conformità. È un validatore indipendente a determinare la conformità per ciascun documento.

Contesto commerciale

Lo strumento batch di conformità è di livello Enterprise e viene registrato solo quando nextpdf/premium è installato insieme al server.

Specifiche di Connect

Disponibilità dei trasporti (MCP / REST / gRPC)

Lo strumento si richiama allo stesso modo tramite MCP tools/call, l’endpoint REST dello strumento e il servizio gRPC attraverso l’esecutore di strumenti condiviso.

Livello di rischio HITL

La verifica batch è di sola lettura e per impostazione predefinita non è approval_required. Una sovrascrittura da parte dell’operatore può solo innalzarne il livello di rischio. Per i dettagli vedere /connect/hitl-risk-tiers/.

Envelope JSON del gate di conferma

Lo strumento non attiva il gate a meno che una sovrascrittura da parte dell’operatore non lo innalzi a approval_required. Il contratto dell’envelope e del token monouso è disponibile in /connect/hitl-risk-tiers/.

Vedere anche

/cookbook/connect/compliance-check/ — verifica degli standard su un singolo documento.
/cookbook/connect/ai-ready-certification/ — la verifica più ampia di idoneità all’IA.
/connect/tool-catalog/ — calcolo dell’insieme di strumenti per livello.
/connect/hitl-risk-tiers/ — il modello di rischio e il gate.