Referência da API REST do Connect

Visão geral

O NextPDF Connect expõe seu registro de ferramentas via HTTP como um transporte REST, descrito por um contrato OpenAPI 3.1. Esta página serve como referência para essa interface: a URL base, como autenticar, os grupos de operações e o modelo de erros. A especificação completa, legível por máquina, é publicada para que você possa carregá-la em um explorador interativo, em um gerador de clientes ou em um cliente de requisições sem copiar nada manualmente.

Para ver o catálogo de ferramentas independente de transporte (as mesmas operações via Model Context Protocol e gRPC, além de REST), consulte a referência da API do Connect. Para detalhes sobre o pipeline do RoadRunner, a implantação e a configuração de autenticação, consulte o guia do transporte REST.

URL base e autenticação

O transporte REST escuta no host e na porta configurados para a implantação. Em uma execução local, esse endereço é http://localhost:8080; em produção, é o endereço na frente do pool de workers.

A autenticação usa um bearer token. Envie a chave de API no cabeçalho Authorization em toda requisição para uma rota restrita por tier:

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"}]}'

As sondagens de liveness e readiness, que são somente leitura, não exigem token.

Operações

A disponibilidade é restrita por tier. O núcleo open-source inclui as operações de documento, renderização, sessão e job. Assinatura, preenchimento de formulários, redação, comparação, verificação de acessibilidade e otimização exigem uma edição comercial instalada no servidor. O conjunto definitivo de uma determinada implantação é retornado pelo endpoint de capacidades. Consulte-o em vez de presumir uma lista fixa.

Saúde e ciclo de vida

Método	Caminho	Finalidade
GET	/healthz	Sondagem de liveness. Sem autenticação.
GET	/readyz	Sondagem de readiness (dependências e pool de workers prontos). Sem autenticação.
GET	/api/v1/capabilities	As ferramentas e os tiers que esta implantação realmente expõe. Consulte este primeiro.

Renderização e documentos

Método	Caminho	Finalidade
POST	/api/v1/render	Renderiza um documento a partir de uma lista ordenada de operações e retorna o PDF.
POST	/api/v1/extract-text	Extrai o conteúdo de texto de um PDF.
POST	/api/v1/merge	Mescla várias entradas PDF em um único documento.
POST	/api/v1/split	Divide um PDF em vários documentos.

Jobs assíncronos

Método	Caminho	Finalidade
POST	/api/v1/jobs	Envia uma operação de longa duração como um job.
GET	/api/v1/jobs/{id}	Consulta o status do job.
GET	/api/v1/jobs/{id}/result	Recupera o resultado do job concluído.

Sessões

As sessões mantêm um documento aberto ao longo de várias chamadas, para que você possa construí-lo de forma incremental e renderizá-lo uma única vez no final.

Método	Caminho	Finalidade
POST	/api/v1/sessions	Abre uma sessão.
GET / DELETE	/api/v1/sessions/{sessionId}	Inspeciona ou encerra uma sessão.
POST	/api/v1/sessions/{sessionId}/pages	Adiciona uma página.
POST	/api/v1/sessions/{sessionId}/text	Adiciona texto.
POST	/api/v1/sessions/{sessionId}/images	Adiciona uma imagem.
POST	/api/v1/sessions/{sessionId}/tables	Adiciona uma tabela.
POST	/api/v1/sessions/{sessionId}/html	Adiciona HTML renderizado.
POST	/api/v1/sessions/{sessionId}/font	Define a fonte ativa.
POST	/api/v1/sessions/{sessionId}/render	Renderiza o documento da sessão.

Operações da edição comercial

Essas rotas só são registradas quando a edição comercial correspondente está instalada. Várias delas dependem de aprovação pelo fluxo de confirmação human-in-the-loop; consulte níveis de risco.

Método	Caminho	Finalidade
POST	/api/v1/sign	Aplica uma assinatura digital.
POST	/api/v1/fill-form	Preenche um formulário interativo.
POST	/api/v1/redact	Redige conteúdo.
POST	/api/v1/compare	Compara dois documentos PDF.
POST	/api/v1/check-accessibility	Executa uma verificação estrutural de acessibilidade.
POST	/api/v1/optimize	Otimiza e reduz um documento.

Modelo de erros

O transporte REST usa códigos de status HTTP com a semântica definida pelo RFC 9110: 2xx para sucesso, 4xx para uma requisição que o chamador precisa corrigir (400 corpo malformado, 401 token ausente ou inválido, 403 tier ou aprovação negados, 404 rota ou job desconhecido, 409 conflito de idempotência, 422 uma requisição bem formada que o motor não consegue processar) e 5xx para uma falha do lado do servidor. Uma resposta 401 inclui um desafio WWW-Authenticate.

Os corpos de erro são documentos application/problem+json conforme o RFC 9457 (Problem Details for HTTP APIs): um type estável, um title curto, o status numérico e um detail legível por humanos. Faça a correspondência pelo type, não pela string detail. Consulte também o RFC 9110 (HTTP Semantics) e o RFC 9457 para obter as definições normativas.

Envie requisições que alteram estado com um cabeçalho Idempotency-Key, para que uma requisição repetida seja processada apenas uma vez.

Especificação legível por máquina

O contrato completo é publicado como um documento OpenAPI 3.1 estático:

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

Use-o como a única fonte de verdade para a interface REST:

1. Abra o explorador interativo da API — uma referência Scalar no navegador, auto-hospedada e gerada a partir deste contrato — para ler e testar cada operação com seus esquemas de requisição e resposta.
2. Importe-o para um cliente de requisições como o Postman ou o Insomnia.
3. Gere um cliente tipado para a sua linguagem com um gerador OpenAPI.

O documento é um contrato estático, com versão fixada ao pacote. Ele não é servido por um endpoint ativo; portanto, permanece estável entre implantações.

Consulte também

• Referência da API do Connect — o catálogo completo de ferramentas em MCP, REST e gRPC.
• Guia do transporte REST — pipeline do RoadRunner, autenticação por bearer e roteamento por tier.
• Visão geral do NextPDF Connect — o que é o servidor e como executá-lo.