Referencia de la API REST de Connect

De un vistazo

NextPDF Connect expone su registro de herramientas a través de HTTP como transporte REST, descrito por un contrato OpenAPI 3.1. Esta página sirve como referencia de esa superficie: URL base, autenticación, grupos de operaciones y modelo de errores. La especificación completa legible por máquina se publica para cargarla en un explorador interactivo, un generador de clientes o un cliente de peticiones sin copiar nada manualmente.

Para el catálogo de herramientas independiente del transporte (las mismas operaciones sobre el Model Context Protocol y gRPC, además de REST), véase la referencia de la API de Connect. Para la canalización de RoadRunner, el despliegue y la configuración de autenticación, véase la guía del transporte REST.

URL base y autenticación

El transporte REST escucha en el host y el puerto configurados para el despliegue. En una ejecución local, eso es http://localhost:8080; en producción, es la dirección situada delante del grupo de workers.

La autenticación usa un token de portador. Enviar la clave de API en el encabezado Authorization en cada petición a una ruta controlada por nivel:

curl --request POST \
  --url http://localhost:8080/api/v1/render \
  --header "Authorization: Bearer $NEXTPDF_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"operations":[{"op":"add_text","text":"Hello from NextPDF Connect"}]}'

Las sondas de liveness y readiness de solo lectura no requieren token.

Operaciones

La disponibilidad se controla por nivel. El núcleo de código abierto incluye las operaciones de documentos, renderizado, sesiones y trabajos. La firma, el llenado de formularios, la redacción, la comparación, la verificación de accesibilidad y la optimización requieren una edición comercial instalada junto al servidor. El endpoint de capacidades devuelve el conjunto de referencia para cada despliegue. Debe consultarse en lugar de asumir una lista fija.

Estado y ciclo de vida

Método	Ruta	Propósito
GET	/healthz	Sonda de liveness. Sin autenticación.
GET	/readyz	Sonda de readiness (dependencias y grupo de workers listos). Sin autenticación.
GET	/api/v1/capabilities	Herramientas y niveles que este despliegue expone realmente. Conviene consultarlo primero.

Renderizado y documentos

Método	Ruta	Propósito
POST	/api/v1/render	Renderiza un documento a partir de una lista ordenada de operaciones y devuelve el PDF.
POST	/api/v1/extract-text	Extrae el contenido de texto de un PDF.
POST	/api/v1/merge	Combina varias entradas PDF en un solo documento.
POST	/api/v1/split	Divide un PDF en varios documentos.

Trabajos asíncronos

Método	Ruta	Propósito
POST	/api/v1/jobs	Envía una operación de larga duración como trabajo.
GET	/api/v1/jobs/{id}	Consulta el estado del trabajo.
GET	/api/v1/jobs/{id}/result	Recupera el resultado del trabajo completado.

Sesiones

Las sesiones mantienen un documento abierto a lo largo de varias llamadas para construirlo de forma incremental y renderizarlo una sola vez al final.

Método	Ruta	Propósito
POST	/api/v1/sessions	Abre una sesión.
GET / DELETE	/api/v1/sessions/{sessionId}	Inspecciona o cierra una sesión.
POST	/api/v1/sessions/{sessionId}/pages	Agrega una página.
POST	/api/v1/sessions/{sessionId}/text	Agrega texto.
POST	/api/v1/sessions/{sessionId}/images	Agrega una imagen.
POST	/api/v1/sessions/{sessionId}/tables	Agrega una tabla.
POST	/api/v1/sessions/{sessionId}/html	Agrega HTML renderizado.
POST	/api/v1/sessions/{sessionId}/font	Establece la fuente activa.
POST	/api/v1/sessions/{sessionId}/render	Renderiza el documento de la sesión.

Operaciones de la edición comercial

Estas rutas solo se registran cuando está instalada la edición comercial correspondiente. Varias están sujetas a aprobación mediante el flujo de confirmación con intervención humana; véanse los niveles de riesgo.

Método	Ruta	Propósito
POST	/api/v1/sign	Aplica una firma digital.
POST	/api/v1/fill-form	Completa un formulario interactivo.
POST	/api/v1/redact	Aplica redacción al contenido.
POST	/api/v1/compare	Compara dos documentos PDF.
POST	/api/v1/check-accessibility	Ejecuta una verificación estructural de accesibilidad.
POST	/api/v1/optimize	Optimiza y reduce el tamaño de un documento.

Modelo de errores

El transporte REST usa códigos de estado HTTP según la semántica definida por RFC 9110: 2xx para éxito, 4xx para una petición que el cliente debe corregir (400 cuerpo mal formado, 401 token ausente o inválido, 403 nivel o aprobación denegados, 404 ruta o trabajo desconocido, 409 conflicto de idempotencia, 422 una petición bien formada que el motor no puede procesar), y 5xx para un fallo del servidor. Una respuesta 401 incluye un desafío WWW-Authenticate.

Los cuerpos de error son documentos application/problem+json según RFC 9457 (Problem Details for HTTP APIs): un type estable, un title breve, el status numérico y un detail legible por humanos. La coincidencia debe hacerse sobre type, no sobre la cadena detail. Véanse también RFC 9110 (HTTP Semantics) y RFC 9457 para las definiciones normativas.

Las peticiones que cambian estado deben enviarse con un encabezado Idempotency-Key para que una petición reintentada se procese una sola vez.

Especificación legible por máquina

El contrato completo se publica como un documento OpenAPI 3.1 estático:

https://nextpdf.dev/docs/openapi/nextpdf-connect.yaml

Debe usarse como la única fuente de verdad para la superficie REST:

1. Abrir el explorador interactivo de la API —una referencia Scalar autoalojada y en el navegador, generada a partir de este contrato— para leer y probar cada operación con sus esquemas de petición y respuesta.
2. Importarlo en un cliente de peticiones como Postman o Insomnia.
3. Generar un cliente tipado para el lenguaje correspondiente con un generador de OpenAPI.

El documento es un contrato estático, con versión fijada al paquete. No se sirve desde un endpoint en vivo, por lo que permanece estable entre despliegues.

Consulta también

• Referencia de la API de Connect — el catálogo completo de herramientas en MCP, REST y gRPC.
• Guía del transporte REST — canalización de RoadRunner, autenticación con token de portador y enrutamiento por nivel.
• Introducción a NextPDF Connect — qué es el servidor y cómo ejecutarlo.