Eseguire un controllo degli standard

In sintesi

Questa ricetta mostra come valutare un file PDF in base al set di regole dello standard indicato (per esempio PDF/A-4, un livello baseline PAdES o un criterio organizzativo) con lo strumento compliance-check tramite i trasporti Connect. Lo strumento è di livello Enterprise. Viene rilevato con una verifica class_exists() e viene registrato solo quando nextpdf/premium è installato insieme al server. In un’installazione solo open source, lo strumento non è disponibile e la chiamata fallisce con un errore di strumento sconosciuto.

Lo strumento riporta un esito pass/fail per ciascuna regola implementata per lo standard richiesto. Il risultato è il controllo prodotto dallo strumento, non una certificazione di conformità indipendente. La conformità viene stabilita da un validatore (per esempio veraPDF per PDF/A). Questa pagina descrive il comportamento dello strumento, non fornisce una garanzia di conformità.

Installazione

composer require nextpdf/server

Verificare con una chiamata tools/list che lo strumento di conformità Enterprise sia presente nel deployment in esecuzione; vedere /connect/tool-catalog/.

Panoramica concettuale

Uno standard come PDF/A-4 stabilisce i requisiti del documento. Un verificatore valuta il documento rispetto a tali requisiti (PDF/A-4 §6.2.3). La conformità viene determinata rispetto ai requisiti dello standard, non dichiarata dal software che produce il documento (PDF/A-4 §6.7.3). Per gli standard relativi alla firma, il controllo verifica se siano avvenute modifiche dopo la firma rispetto all’intervallo di byte firmato (ISO 32000-2 §12.8).

Il “pass” dello strumento significa quindi che “nessuna regola implementata dallo strumento per questo standard è fallita”. Si tratta di un’indicazione più circoscritta rispetto a una certificazione formale di conformità dell’intero documento.

Superficie API

I nomi degli strumenti vengono verificati rispetto al registro in esecuzione tramite tools/list; il catalogo di riferimento è /connect/tool-catalog/. Questa ricetta non indica il numero degli strumenti, perché è una proprietà di runtime del deployment.

Esempio di codice — Avvio rapido

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "compliance_check",
    "arguments": { "document_id": "<id>", "standard": "pdfa-4" }
  }
}

Esempio di codice — Produzione

Trattare un risultato “fail” come un dato operativo su cui intervenire e distinguere un guasto di trasporto da un normale stato HTTP di errore su un trasporto di rete:

curl -sS -X POST https://connect.example.com/v1/tools/compliance_check \
  -H 'Authorization: Bearer '"$NEXTPDF_CONNECT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"source":"/var/lib/nextpdf/in/report.pdf","standard":"pdfa-4"}' \
  -o /tmp/check.json -w '%{http_code}' > /tmp/check-status || {
    echo "transport failure invoking compliance_check" >&2; exit 1; }

[ "$(cat /tmp/check-status)" = "200" ] || {
  echo "compliance_check returned non-200; inspect /tmp/check.json" >&2; }

La risposta elenca ogni regola valutata, il relativo stato pass/fail e la motivazione di ciascun fallimento. Usare i fallimenti emersi per intervenire e correggere. Non interpretare un “pass” come una certificazione.

Casi limite e insidie

• Nome dello standard sconosciuto. Lo strumento restituisce un errore di standard sconosciuto insieme agli identificatori riconosciuti; usare l’identificatore esatto (pdfa-4, un livello baseline PAdES, un id di criterio organizzativo).
• Documento non trovato. Verificare che il document_id sia stato restituito da una chiamata di output precedente, oppure passare un percorso source valido.
• Riferimenti incrociati danneggiati. Un fallimento dell’analisi significa che l’input non è un file PDF valido o è troncato. Rigenerare il file di origine.
• Strumento assente. Senza nextpdf/premium, lo strumento di conformità Enterprise non viene registrato e la chiamata fallisce con un errore di strumento sconosciuto.

Prestazioni

Il budget indicato nel front matter è un limite documentato, non una garanzia di livello di servizio.

Note di sicurezza

Non registrare nei log il percorso di origine o il report completo a un livello di log inviato all’esterno. Registrare nei log il nome dello strumento, l’id della richiesta e l’esito pass/fail complessivo. Un “pass” descrive il set di regole implementato dallo strumento, non costituisce una garanzia di sicurezza o legale.

Conformità

Affermazione	Clausola
Lo standard stabilisce i requisiti; un verificatore li valuta	PDF/A-4 §6.2.3
La conformità è determinata rispetto ai requisiti, non è asserita dal produttore	PDF/A-4 §6.7.3
Le modifiche successive alla firma sono rilevabili rispetto all’intervallo di byte firmato	ISO 32000-2 §12.8

Il supporto a un controllo di conformità a uno standard non equivale a una certificazione di conformità. La conformità viene stabilita da un validatore indipendente.

Contesto commerciale

Lo strumento compliance-check è di livello Enterprise e si registra soltanto quando nextpdf/premium è installato insieme al server.

Specificità di Connect

Disponibilità dei trasporti (MCP / REST / gRPC)

Lo strumento viene richiamato nello stesso modo tramite MCP tools/call, l’endpoint REST dello strumento e il servizio gRPC, attraverso l’executor di strumenti condiviso.

Livello di rischio HITL

Il controllo è di sola lettura e per impostazione predefinita non è approval_required. Un override da parte dell’operatore può innalzarne il livello di rischio. L’override può solo innalzare, mai abbassare. Vedere /connect/hitl-risk-tiers/.

Envelope JSON del gate di conferma

Lo strumento non attiva il gate, a meno che un override da parte dell’operatore non lo innalzi a approval_required. L’envelope di challenge e il contratto del token monouso sono documentati in /connect/hitl-risk-tiers/.

Vedere anche

• /cookbook/connect/batch-compliance/ — eseguire il controllo su molti documenti.
• /cookbook/connect/ai-ready-certification/ — il controllo più ampio di idoneità all’IA.
• /connect/tool-catalog/ — calcolo del set di strumenti per livello.
• /connect/hitl-risk-tiers/ — il modello di rischio e il gate.