Visão geral do NextPDF Gotenberg

Em resumo

O NextPDF Gotenberg é uma pequena ponte entre o NextPDF e um serviço Gotenberg externo. Use-a quando o NextPDF não conseguir renderizar nativamente um documento do Office. A ponte envia o documento para uma instância Gotenberg por meio do Hypertext Transfer Protocol (HTTP), recebe a saída em Portable Document Format (PDF) e entrega o PDF à aplicação. A partir daí, o NextPDF cuida do restante do pós-processamento.

O pacote é pequeno e explícito. Ele não incorpora um renderizador, não inicia o LibreOffice e não executa um navegador. Cada conversão usa uma única requisição HTTP multipart para um endpoint Gotenberg. Você opera esse endpoint e aponta a ponte para ele na configuração.

Use esta ponte quando você tiver arquivos de origem .docx, .xlsx, .pptx, .odt, .ods ou .odp e precisar gerar saída em PDF em um pipeline NextPDF. Depois que o PDF é gerado, o NextPDF ou o nextpdf/premium cuida da assinatura, conversão para PDF/A, aplicação de marca d’água e mesclagem.

Do que a ponte depende

A ponte tem uma dependência de runtime que não é um pacote PHP: um serviço Gotenberg em execução acessível por meio do Hypertext Transfer Protocol Secure (HTTPS).

A ponte não instala, gerencia nem supervisiona o Gotenberg. Você mesmo implanta o Gotenberg; o projeto upstream publica uma imagem de contêiner. Você é responsável pela disponibilidade, capacidade e exposição de rede do serviço.
A ponte se comunica com a rota de conversão do LibreOffice do Gotenberg. A URL da requisição é montada como <apiUrl>/forms/libreoffice/convert, onde <apiUrl> é a URL base que você configura. Essa rota define o conjunto de formatos suportados pela ponte.
A verificação de integridade envia uma requisição HTTP HEAD para <apiUrl>/health e trata qualquer status abaixo de 500 como disponível.

Como a conversão é executada em um serviço que você opera, o comportamento depende da versão do Gotenberg em execução. A ponte envia uma requisição multipart fixa e assume apenas dois caminhos do Gotenberg: o caminho da rota (/forms/libreoffice/convert) e o caminho de integridade (/health). Consulte /integrations/gotenberg/install/ para a linha de base de implantação e /integrations/gotenberg/security-and-operations/ para o reforço de segurança do serviço.

Formatos de documento suportados

A ponte converte apenas os formatos enumerados no tipo OfficeFormat. Ela detecta cada formato a partir da extensão do arquivo. A correspondência não diferencia maiúsculas de minúsculas, e um ponto inicial é permitido. Em seguida, a ponte envia cada arquivo para o Gotenberg com um tipo Multipurpose Internet Mail Extensions (MIME) fixo:

Formato	Extensão	Tipo MIME enviado ao Gotenberg
Word (OOXML)	`docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
Excel (OOXML)	`xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
PowerPoint (OOXML)	`pptx`	`application/vnd.openxmlformats-officedocument.presentationml.presentation`
OpenDocument Text	`odt`	`application/vnd.oasis.opendocument.text`
OpenDocument Spreadsheet	`ods`	`application/vnd.oasis.opendocument.spreadsheet`
OpenDocument Presentation	`odp`	`application/vnd.oasis.opendocument.presentation`

Esta lista está completa. Uma extensão fora deste conjunto gera um ValueError antes que qualquer requisição de rede seja feita, de modo que a ponte nunca tenta uma conversão que não consegue descrever. A ponte não afirma suportar “qualquer arquivo do Office” nem “todos os formatos de documento”. Ela suporta os seis formatos acima porque o código reconhece apenas esses seis e a suíte de testes exercita apenas esses seis.

Formatos binários legados (.doc, .xls, .ppt), rich text (.rtf), texto simples, valores separados por vírgula (CSV) e formatos de imagem não fazem parte do conjunto reconhecido pela ponte. A própria rota do LibreOffice do Gotenberg pode aceitar uma gama mais ampla de entradas. A ponte se limita deliberadamente ao conjunto enumerado para manter consistentes e verificáveis a detecção de formato, o tipo MIME e os metadados do resultado.

Como uma conversão flui

Uma conversão segue uma única passagem linear. A ponte valida cada etapa antes que qualquer byte saia do processo:

A configuração é verificada. Uma URL de Application Programming Interface (API) vazia falha imediatamente com uma exceção de conversão.
A URL da API é validada. O HTTPS é obrigatório, e o host é resolvido e filtrado para impedir que aponte para um endereço privado ou reservado. O conjunto de endereços resolvidos é capturado para fixação posterior.
A entrada é lida (em conversões de arquivo, o caminho é canonizado primeiro para bloquear traversal) e sua extensão é mapeada para um OfficeFormat.
A ponte verifica o comprimento em bytes em relação ao máximo configurado e filtra o nome do arquivo em busca de sequências de traversal, barras, null bytes e caracteres de controle.
O conjunto de endereços é verificado novamente imediatamente antes da requisição para fechar a lacuna entre a validação e a conexão.
A ponte monta um corpo multipart/form-data e o envia via POST para a rota do LibreOffice, com um bearer token se houver um configurado.
A ponte analisa a resposta. O status deve ser 200, o Content-Type deve conter application/pdf, e o corpo deve começar com a assinatura %PDF. Somente então um resultado é retornado.

Qualquer falha nas etapas 1–7 gera uma exceção tipada. A ponte não retorna um resultado parcial nem não verificado. As exceções exatas e seus gatilhos estão catalogados em /integrations/gotenberg/troubleshooting/.

O que você recebe de volta

Uma conversão bem-sucedida retorna um objeto de resultado. O objeto inclui os bytes brutos do PDF, o formato de origem convertido e uma medição opcional do tempo de renderização. Ele também expõe uma verificação de validade (um corpo não vazio que começa com %PDF) e um acessor de tamanho em bytes. Os bytes são um stream (fluxo de dados) PDF normal, então você pode gravá-los em disco, transmiti-los para um cliente ou passá-los para um documento NextPDF para processamento adicional.

Onde a ponte para

A ponte converte e valida. Ela não:

Assina, criptografa, lineariza nem converte a saída para PDF/A. O NextPDF core ou o nextpdf/premium cuida dessas tarefas de pós-processamento.
Repete requisições com falha, enfileira trabalho nem armazena resultados em cache. Essas são tarefas no nível da aplicação. /integrations/gotenberg/production-usage/ mostra como adicioná-las em torno da ponte.
Gerencia o ciclo de vida do serviço Gotenberg. A implantação e as operações são abordadas em /integrations/gotenberg/security-and-operations/.

Edições e pós-processamento

O core open source software (OSS) pode gravar o PDF convertido como está. Se você precisar assinar o documento convertido, produzir um perfil de arquivamento PDF/A ou aplicar uma marca d’água, o pacote nextpdf/premium adiciona esses recursos. A própria ponte é neutra em relação à edição: ela produz um PDF. O que você faz com esse PDF determina se você precisa de uma edição comercial.

A linha de base PDF Advanced Electronic Signatures (PAdES) disponível na edição Pro é apenas B-B. Os perfis de long-term validation (LTV) (B-T, B-LT, B-LTA) não fazem parte da edição Pro e não são fornecidos por esta ponte. Não deduza capacidade de timestamp ou LTV pela presença deste pacote.

Veja também

/integrations/gotenberg/install/ — instale o pacote e implante uma linha de base do Gotenberg.
/integrations/gotenberg/configuration/ — todas as opções de configuração, com tipo, padrão e efeito.
/integrations/gotenberg/quickstart/ — execute a primeira conversão.
/integrations/gotenberg/production-usage/ — integre a ponte a uma aplicação real.
/integrations/gotenberg/troubleshooting/ — o catálogo de exceções e o que cada exceção significa.
/integrations/gotenberg/security-and-operations/ — o modelo de segurança e como operar o serviço dependente com segurança.
/integrations/gotenberg/boot-and-discovery/ — como os frameworks hospedeiros descobrem e integram a ponte.
/integrations/gotenberg/integration/ — conduza a renderização do NextPDF por meio do serviço.