Ejecutar una comprobación de estándares en Connect

De un vistazo

Esta receta evalúa un PDF frente al conjunto de reglas de un estándar indicado (por ejemplo PDF/A-4, un nivel de base PAdES o una política de la organización) mediante la herramienta compliance-check a través de los transportes de Connect. La herramienta es de nivel Enterprise. Se descubre mediante un sondeo class_exists() y solo se registra cuando nextpdf/premium está instalado junto con el servidor. En una instalación exclusivamente de código abierto, la herramienta no está presente y la llamada falla con un error de herramienta desconocida.

La herramienta devuelve un resultado pass/fail por regla según las reglas que implementa para el estándar solicitado. Ese resultado es la comprobación propia de la herramienta, no una certificación de conformidad independiente. Un validador (por ejemplo veraPDF para PDF/A) es quien determina la conformidad. Esta página describe el comportamiento de la herramienta, no una garantía de conformidad.

Instalación

composer require nextpdf/server

Confirmar que la herramienta de conformidad Enterprise está presente en el despliegue en ejecución mediante una llamada tools/list; consultar /connect/tool-catalog/.

Visión conceptual

Un estándar como PDF/A-4 establece requisitos para el documento. Un verificador evalúa el documento frente a esos requisitos establecidos (PDF/A-4 §6.2.3). La conformidad se determina frente a los requisitos del estándar; no la declara el software productor (PDF/A-4 §6.7.3). En los estándares relacionados con firmas, la comprobación inspecciona si se produjo alguna modificación tras la firma respecto del rango de bytes firmado (ISO 32000-2 §12.8).

Por lo tanto, el «pass» de la herramienta significa «ninguna de las reglas que la herramienta implementa para este estándar ha fallado». Ese alcance es más limitado que una certificación formal de conformidad de todo el documento.

Superficie de la API

Los nombres de las herramientas se verifican frente al registro en ejecución mediante tools/list; el catálogo de referencia es /connect/tool-catalog/. Esta receta no fija un recuento de herramientas, ya que se trata de una propiedad de tiempo de ejecución del despliegue.

Ejemplo de código — Inicio rápido

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

Ejemplo de código — Producción

Tratar un resultado «fail» como datos sobre los que actuar, y distinguir un fallo de transporte de una respuesta HTTP normal pero no exitosa en un transporte de red:

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 respuesta enumera cada regla evaluada, su estado pass/fail y el motivo de cada fallo. Usar los fallos para la remediación. No interpretar un «pass» como una certificación.

Casos límite y advertencias

Nombre de estándar desconocido. La herramienta devuelve un error de estándar desconocido con los identificadores reconocidos; usar el identificador exacto (pdfa-4, un nivel de base PAdES, un id de política de la organización).
Documento no encontrado. Verificar que el document_id proviene de una llamada de salida anterior, o pasar una ruta source válida.
Referencia cruzada dañada. Un fallo de análisis significa que la entrada no es un PDF válido o está truncada. Regenere el origen.
Herramienta ausente. Sin nextpdf/premium, la herramienta de conformidad Enterprise no se registra y la llamada falla con un error de herramienta desconocida.

Rendimiento

El presupuesto del front-matter es un límite documentado, no una garantía de nivel de servicio.

Notas de seguridad

No registrar la ruta de origen ni el informe completo en un nivel de registro que se envíe externamente. Registrar el nombre de la herramienta, el id de la solicitud y el resultado global pass/fail. Un «pass» describe el conjunto de reglas que la herramienta implementa, no una garantía de seguridad ni legal.

Conformidad

Afirmación	Cláusula	reference_id
El estándar establece requisitos; un verificador los evalúa	PDF/A-4 §6.2.3
La conformidad se determina frente a los requisitos, no la afirma el productor	PDF/A-4 §6.7.3
La modificación tras la firma es detectable frente al rango de bytes firmado	ISO 32000-2 §12.8

Superar una comprobación de estándares no equivale a una certificación de conformidad. Un validador independiente determina la conformidad.

Contexto comercial

La herramienta compliance-check es de nivel Enterprise y solo se registra cuando nextpdf/premium está instalado junto con el servidor.

Particularidades de Connect

Disponibilidad por transporte (MCP / REST / gRPC)

La herramienta se invoca de la misma forma mediante MCP tools/call, el endpoint de herramienta REST y el servicio gRPC, a través del ejecutor de herramientas compartido.

Nivel de riesgo HITL

La comprobación es de solo lectura y, de forma predeterminada, no es approval_required. Una anulación por parte de un operador puede elevar su nivel de riesgo. La anulación solo puede elevarlo, nunca rebajarlo. Consultar /connect/hitl-risk-tiers/.

Sobre el JSON de la puerta de confirmación

La herramienta no activa la puerta salvo que una anulación por parte de un operador la eleve a approval_required. El sobre de desafío y el contrato de token de un solo uso están documentados en /connect/hitl-risk-tiers/.

Véase también

/cookbook/connect/batch-compliance/ — ejecutar la comprobación en muchos documentos.
/cookbook/connect/ai-ready-certification/ — la comprobación más amplia de preparación para IA.
/connect/tool-catalog/ — recuento del conjunto de herramientas por nivel.
/connect/hitl-risk-tiers/ — el modelo de riesgo y la puerta.