Execute uma verificação de padrões com o Connect

Visão geral

Use esta receita para avaliar um PDF em relação ao conjunto de regras de um padrão nomeado por meio dos transportes do Connect. Os exemplos incluem PDF/A-4, um nível baseline de PDF Advanced Electronic Signatures (PAdES) ou uma política organizacional. A ferramenta compliance-check é da camada Enterprise. O servidor a descobre por meio de uma sondagem class_exists() e a registra somente quando nextpdf/premium está instalado junto com o servidor. Em uma instalação apenas open-source, a ferramenta não está presente e a chamada falha com um erro de ferramenta desconhecida.

A ferramenta informa um resultado pass/fail por regra, para cada regra que implementa para o padrão solicitado. Esse resultado é a verificação feita pela própria ferramenta, não uma certificação de conformidade independente. Um validador, como o veraPDF para PDF/A, faz a determinação de conformidade. Esta página descreve o comportamento da ferramenta, não oferece garantia de conformidade.

Instalação

composer require nextpdf/server

Confirme se a ferramenta de conformidade Enterprise está presente na implantação em execução com uma chamada tools/list. Veja /connect/tool-catalog/.

Visão conceitual

Um padrão como PDF/A-4 declara requisitos para o documento. Um verificador avalia o documento em relação a esses requisitos (PDF/A-4 §6.2.3). A conformidade é determinada em relação aos requisitos do padrão, não declarada pelo software que produziu o documento (PDF/A-4 §6.7.3). Para padrões relacionados a assinaturas, a verificação inspeciona se houve modificação após a assinatura em relação ao byte range assinado (ISO 32000-2 §12.8).

O “pass” da ferramenta significa “nenhuma regra que a ferramenta implementa para este padrão falhou”. Esse resultado é mais limitado do que uma certificação formal de conformidade do documento inteiro.

Superfície da API

Verifique os nomes das ferramentas no registro em execução com tools/list. O catálogo oficial é /connect/tool-catalog/. Esta receita não reitera uma contagem de ferramentas, que é uma propriedade de runtime da implantação.

Exemplo de código — Início rápido

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

Exemplo de código — Produção

Trate um resultado “fail” como dados sobre os quais você pode agir. Distinga uma falha de transporte de um status Hypertext Transfer Protocol (HTTP) normal que indica não sucesso em um transporte em rede:

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

A resposta lista cada regra avaliada, seu status pass/fail e um motivo para cada falha. Use as falhas para orientar a correção. Não trate um “pass” como certificação.

Casos extremos e armadilhas

Nome de padrão desconhecido. A ferramenta retorna um erro de padrão desconhecido junto com os identificadores reconhecidos. Use o identificador exato (pdfa-4, um nível baseline de PAdES, um id de política organizacional).
Documento não encontrado. Verifique se o document_id veio de uma chamada de saída anterior ou passe um caminho source válido.
Cross-reference corrompida. Uma falha de parsing significa que a entrada não é um PDF válido ou está truncada. Gere o source outra vez.
Ferramenta ausente. Sem nextpdf/premium, a ferramenta de conformidade Enterprise não é registrada e a chamada falha com um erro de ferramenta desconhecida.

Desempenho

O orçamento do front-matter é um limite de documentação, não uma garantia de nível de serviço.

Notas de segurança

Não registre em log o caminho de origem nem o relatório completo em um nível de log enviado externamente. Registre em log o nome da ferramenta, o id da requisição e o resultado pass/fail geral. Um “pass” descreve o conjunto de regras que a ferramenta implementa, não uma garantia jurídica ou de segurança.

Conformidade

Afirmação	Cláusula	reference_id
O padrão declara requisitos; um verificador os avalia	PDF/A-4 §6.2.3
A conformidade é determinada em relação aos requisitos, não declarada pelo produtor	PDF/A-4 §6.7.3
A modificação após a assinatura é detectável em relação ao byte range assinado	ISO 32000-2 §12.8

O suporte a uma verificação de padrões não é uma certificação de conformidade. Um validador independente faz a determinação de conformidade.

Contexto comercial

A ferramenta compliance-check é da camada Enterprise. Ela se registra somente quando nextpdf/premium está instalado junto com o servidor.

Especificidades do Connect

Disponibilidade de transporte (MCP / REST / gRPC)

Invoque a ferramenta da mesma forma pelo Model Context Protocol (MCP) tools/call, pelo endpoint de ferramenta Representational State Transfer (REST) e pelo serviço gRPC, por meio do executor de ferramentas compartilhado.

Camada de risco HITL

A verificação é somente leitura e não é approval_required por padrão. Uma substituição do operador pode elevar seu nível de risco. A substituição só pode elevar o nível, nunca reduzi-lo. Veja /connect/hitl-risk-tiers/.

Envelope JSON do gate de confirmação

A ferramenta não aciona o gate a menos que uma substituição do operador a eleve para approval_required. O envelope de desafio e o contrato de token de uso único estão documentados em /connect/hitl-risk-tiers/.

Veja também

/cookbook/connect/batch-compliance/ — execute a verificação em muitos documentos.
/cookbook/connect/ai-ready-certification/ — execute a verificação de prontidão para IA mais ampla.
/connect/tool-catalog/ — revise o cálculo do conjunto de ferramentas por camada.
/connect/hitl-risk-tiers/ — revise o modelo de risco e o gate.