NextPDF Connect — transporte REST

De un vistazo

El transporte REST ejecuta bin/nextpdf-server en un pool de workers HTTP de RoadRunner. Se define mediante un documento OpenAPI 3.1, autentica cada solicitud que no corresponda a estado de salud con una clave de API de tipo bearer y controla las rutas de Pro y Enterprise según el nivel instalado.

Instalación

composer require nextpdf/server
./vendor/bin/rr get-binary

Descripción conceptual

Cada solicitud pasa por una canalización de middleware PSR-15 antes de llegar a un handler: asignación de un identificador de solicitud, límites de tamaño del cuerpo y de carga útil por nivel, CORS, autenticación, autorización de capacidades, limitación de tasa por IP y por cliente, idempotencia y tiempo de espera. Un middleware PSR-15 que no puede producir por sí mismo la respuesta delega en el handler de solicitud proporcionado (PSR-15 §2.2 MiddlewareInterface::process, cláusula psr_15_handlers#2.2.p14); los objetos de solicitud PSR-7 que atraviesan la canalización son inmutables: una llamada que cambia el estado devuelve una nueva instancia en lugar de mutar la existente (PSR-7 §3.2.1).

La tabla de rutas se construye durante el arranque y depende del tiempo de ejecución: las rutas del núcleo siempre se registran; las rutas de operaciones Pro se registran solo cuando Pro o Enterprise está instalado; las rutas de Enterprise se registran solo cuando Enterprise está instalado. Las rutas de sesión se registran solo cuando las sesiones están habilitadas.

Superficie de la API

Rutas siempre registradas

Método	Ruta	Autenticación
GET	/healthz	ninguna (liveness)
GET	/readyz	ninguna (readiness)
POST	/api/v1/render	bearer
GET	/api/v1/capabilities	bearer
POST	/api/v1/jobs	bearer
GET	/api/v1/jobs/{id}	bearer
GET	/api/v1/jobs/{id}/result	bearer
DELETE	/api/v1/jobs/{id}	bearer
POST	/api/v1/extract-text · /merge · /split	bearer

Las sondas de estado de salud son endpoints seguros y de solo lectura: no provocan ningún cambio de estado, propiedad que RFC 9110 define como método seguro (RFC 9110 §9.2.1).

Rutas controladas por nivel (dependientes del tiempo de ejecución)

Se registran solo cuando el paquete correspondiente está instalado:

• Pro o Enterprise instalado: /api/v1/sign, /fill-form, /redact, /compare, /check-accessibility, /optimize.
• Enterprise instalado: /api/v1/compliance-check, /forensic-analyze, /ai-certify.

Una solicitud a una ruta cuyo nivel no está instalado no se enruta. Una solicitud autenticada con una clave cuyo nivel está por debajo del nivel de la ruta se rechaza con 403. Cuando se expone la firma, NextPDF Connect con Pro ofrece únicamente la firma PAdES baseline-B (B-B); los perfiles de validación a largo plazo no forman parte de la superficie de este transporte.

Contrato OpenAPI

La superficie REST se distribuye como un documento OpenAPI 3.1 estático en openapi/nextpdf-connect.yaml dentro del paquete. Su esquema de seguridad consiste en una clave de API de tipo bearer en el encabezado Authorization (Bearer npk_live_{kid}_{secret}). Las respuestas de error son documentos de detalles de problema RFC 7807 con una URL type por condición.

Renderizado de OpenAPI — Scalar

Según el §12 del plan de la plataforma de documentación, el sitio de documentación agregado renderiza este documento OpenAPI con Scalar (@scalar/api-reference). Se incrusta como un componente <ScalarApiReference src=…> en la página de integración REST. La fuente de verdad es el openapi/nextpdf-connect.yaml del paquete. El proceso de construcción del sitio lo extrae y lo renderiza, en lugar de mantener a mano una referencia paralela de endpoints. El servidor no incluye ningún endpoint de servicio OpenAPI en tiempo de ejecución; el documento es un artefacto generado durante la construcción.

Ejemplo de código — Inicio rápido

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.yaml

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{"operations":[{"type":"add_text","text":"Hello"}]}' \
  --output hello.pdf

Ejemplo de código — Producción

Ejecutar el perfil combinado para que los transportes REST y gRPC compartan un único supervisor:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
export NEXTPDF_WORKER_COUNT=8
./vendor/bin/rr serve -c .rr.full.yaml

Casos límite y trampas

• Una ruta controlada por nivel devuelve 404 cuando el paquete está ausente. La ruta no está registrada, por lo que el router no la encuentra. Es el comportamiento esperado; no es un fallo de autenticación.

• 401 frente a 403. 401 indica que no hay una clave válida (y la respuesta incluye un encabezado WWW-Authenticate: Bearer, según RFC 9110 §11.6.1). 403 indica una clave válida cuyo nivel no está habilitado para la operación.

• Las sesiones están desactivadas de forma predeterminada. Las rutas /api/v1/sessions/... existen solo cuando NEXTPDF_SESSIONS_ENABLED=true y hay herramientas disponibles.

• Las operaciones de alto riesgo siguen estando controladas. Una llamada REST que ejecuta una herramienta ApprovalRequired pasa por el mismo control con intervención humana que MCP. Consultar /connect/hitl-risk-tiers/.

Rendimiento

Cada worker de RoadRunner atiende una solicitud a la vez. Los renderizados síncronos largos ocupan un worker; usar las rutas de trabajos asíncronos para el trabajo lento, de modo que los workers queden libres. Dimensionar el pool según la latencia observada; consultar /connect/production-usage/.

Notas de seguridad

Terminar TLS delante del listener REST; este se enlaza mediante HTTP en texto plano por diseño y espera un terminador en la capa superior. Autenticarse con una clave npk_live_ con suficiente aleatoriedad, guardar las claves fuera del control de versiones y preferir el almacén de claves en archivo con recarga en caliente. Consultar /connect/security-and-operations/.

Conformidad

Afirmación	Fuente	reference_id
401 DEBE llevar un encabezado WWW-Authenticate de desafío	RFC 9110 §11.6.1
Los métodos seguros son de solo lectura	RFC 9110 §9.2.1
Las solicitudes PSR-7 son inmutables	PSR-7 §3.2.1
El middleware que no puede producir la respuesta delega en el handler de solicitud proporcionado	PSR-15 §2.2 MiddlewareInterface::process (psr_15_handlers#2.2.p14)

Contexto comercial

Las rutas de firma, redacción, comparación, accesibilidad, optimización y conformidad aparecen solo cuando nextpdf/premium está instalado. El modelo de autenticación no cambia; el nivel de la clave determina el acceso.

Consulta también

• /connect/quickstart/ — la solicitud de renderizado ejecutable
• /connect/security-and-operations/ — autenticación y postura de TLS
• /connect/production-usage/ — trabajos, idempotencia, limitación de tasa
• /transports/mcp/ · /transports/grpc/ — los otros transportes
• /connect/tool-catalog/ — cómo se asigna el conjunto de rutas al catálogo de herramientas