Gere PDFs a partir de HTML e Markdown com uma API REST

Seu aplicativo gera faturas. Você tem o modelo HTML. Agora você precisa transformá-lo em um PDF para download. A abordagem padrão: instalar o Puppeteer, iniciar uma instância headless do Chromium, ligar page.pdf(). São 300-500 MB de dependências para uma função de impressão.

Piora na produção. O Chromium vaza memória sob carga. As imagens do Docker ultrapassam 1 GB. As partidas a frio levam de 3 a 8 segundos. Você acaba mantendo um pool de processos do navegador para alguma coisa isso deve ser uma única chamada de função.

Existe um caminho mais curto. Envie seu HTML para uma API e receba um PDF de volta.

HTML para PDF em uma solicitação POST

O /v1/pdf/from-html endpoint aceita uma string HTML e retorna um PDF. Nenhum binário de navegador, sem dependências, sem configuração.

curl -X POST https://api.botoi.com/v1/pdf/from-html \\
  -H "Content-Type: application/json" \\
  -d '{
    "html": "<h1>Invoice #1042</h1><p>Amount due: $2,450.00</p>"
  }'

Resposta:

{
  "success": true,
  "data": {
    "url": "https://api.botoi.com/pdfs/f7a2c1e8.pdf",
    "size_bytes": 24576,
    "pages": 1
  }
}

O url campo aponta para o PDF gerado. Faça o download, redirecione seu usuário para ele, ou armazene-o em seu próprio bucket S3. A API lida com renderização, paginação e incorporação de fontes.

Markdown para PDF em uma solicitação POST

Nem todo documento começa como HTML. Relatórios, registros de alterações e documentação geralmente vivem como Markdown. O /v1/pdf/from-markdown endpoint converte Markdown em um PDF estilizado diretamente.

Resposta:

Tabelas, títulos, texto em negrito, blocos de código e listas são renderizados corretamente. A API aplica-se limpa padrões tipográficos para que a saída pareça apresentável sem CSS personalizado.

Exemplo prático: geração de fatura

Uma fatura realista precisa de um cabeçalho da empresa, endereço de cobrança, tabela de itens de linha, cálculo de imposto, e condições de pagamento. Aqui está uma fatura completa enviada como uma chamada de API:

Essa única solicitação produz um PDF de fatura profissional com papel timbrado da Cascade Software, quatro itens de linha totalizando $ 2.257,00, imposto sobre vendas de 8,5% de $ 191,85 e um total geral de $ 2.448,85. O CSS no <style> tag controla fontes, espaçamento, bordas da tabela e o bold total row. Você pode usar qualquer CSS compatível com o navegador, incluindo flexbox, grid e @page regras para margens e tamanho de página.

Exemplo prático: relatório trimestral da Markdown

Reports are a natural fit for Markdown. Gerentes de produto, analistas e equipes de operações já escrevem em Markdown. A conversão para PDF para distribuição ou arquivamento por e-mail é uma chamada de API:

A API renderiza tabelas, títulos, texto em negrito e lista numerada em um PDF limpo. Não etapa HTML intermediária do seu lado. Passe a string Markdown do seu banco de dados, um Git repositório ou uma exportação do Notion.

Exemplo prático: geração de recibos no Express

Aqui está uma rota expressa que gera um recibo em PDF sob demanda quando um usuário solicita um para um pedido anterior:

O buildReceiptHtml função pega dados de pedidos do seu banco de dados e produz uma string HTML estilizada. A rota envia para a API botoi e retorna a URL do PDF para o cliente. Nenhum marionetista. Nenhuma operação do sistema de arquivos. No temp directories.

Mesmo padrão em Hono

Se você estiver executando Cloudflare Workers ou Bun, a versão Hono é quase idêntica:

A principal diferença: Hono acessa variáveis ​​de ambiente por meio de c.env em vez de process.env. Todo o resto permanece igual. Uma chamada de busca, uma resposta JSON, um URL de PDF.

Comparação: API vs Puppeteer vs wkhtmltopdf vs Prince

Quatro abordagens comuns para conversão de HTML para PDF, comparadas no que é importante na produção:

Marionetista oferece controle total do navegador, mas acarreta custos operacionais elevados. Você está executando o Chromium em seu servidor, gerenciando limites de memória e corrigindo a segurança vulnerabilidades no binário do navegador. Funciona bem se você precisar de execução de JavaScript, cookie injeção ou renderização de página autenticada.

wkhtmltopdf é mais leve que o Puppeteer, mas usa o obsoleto QtWebKit motor. O suporte CSS está travado nos níveis de 2015. Flexbox e grade não funcionam. O projeto é arquivado no GitHub sem mantenedores ativos.

Príncipe XML produz saída de impressão da mais alta qualidade com mídia paginada CSS completa suporte. A compensação: uma taxa de licença de US$ 3.800 por servidor. Isso faz sentido para publicação fluxos de trabalho, não para gerar faturas em um aplicativo SaaS.

A abordagem da API ganha quando você precisa de PDFs de modelos que você controla (faturas, recibos, relatórios, contratos) e não precisa renderizar páginas autenticadas arbitrárias. zero configuração, manutenção zero, latência previsível.

Pontos-chave

• Dois endpoints, dois formatos de entrada. /v1/pdf/from-html para HTML completo com CSS. /v1/pdf/from-markdown para conteúdo Markdown.
• Sem dependências do lado do servidor. Sem marionetista, sem Chromium, sem wkhtmltopdf binário. Uma chamada HTTP de qualquer idioma.
• Suporte CSS completo. Estilos embutidos, tags de estilo, flexbox, grade, Google Fonts, e @page consultas de mídia funcionam.
• Nível gratuito disponível. 5 solicitações por minuto sem chave de API. Planos pagos comece em US$ 9/mês para cargas de trabalho de produção.
• Casos de uso comuns. Faturas, recibos, relatórios, contratos, documentação exportações e anexos de e-mail.

Verifique o API documentos para obter a referência completa dos parâmetros, incluindo tamanho da página, margens e cabeçalho/rodapé configuração.