Escolher uma API de geração de PDF parece simples até você começar. Há dezenas de fornecedores, as páginas de marketing parecem iguais e os tradeoffs reais só aparecem depois de milhares de documentos em produção.
Esta checklist serve para avaliação de fornecedores. Ela é neutra e vem de incidentes reais vistos em compras, operação e post-mortems. São oito perguntas; sem respostas claras para todas, você ainda não tem informação suficiente para decidir.
1. Qual é o formato de entrada: HTML, JSON ou uma DSL de templates?
Essa é a pergunta mais importante porque define o que sua equipe vai escrever e depurar de madrugada.
- HTML/CSS (Puppeteer, DocRaptor, Prince): familiar, extremamente flexível, caro em runtime e difícil de tornar determinístico.
- JSON / dados estruturados (gPdf): barato para renderizar, byte-identical, mas exige um mapper do seu modelo de dados para o modelo de documento.
- Template DSL (PDFKit, ReportLab, Apache PDFBox): controle total e responsabilidade total por paginação, layout e fallback de fontes.
Não existe resposta certa universal. Existe a resposta errada para a sua equipe. Pergunte aos engenheiros em qual modelo eles prefeririam depurar um bug de paginação por três horas.
2. Qual é a latência de cold start e ela é previsível?
Alguns renderizadores iniciam em microssegundos, especialmente WASM ou binários nativos. Outros levam segundos, principalmente os baseados em Chromium. A diferença aparece quando há pico de tráfego.
Pergunte:
- “Qual é o p99 da primeira requisição em um worker frio?”
- “Quanto tempo após a última requisição até o worker esfriar novamente?”
- “Vocês publicam dados de cold start na status page?”
Se a resposta não vier com número, assuma que é ruim.
3. Como o custo por render é modelado?
Três modelos costumam surpreender:
- Preço por página: previsível e fácil de orçar, mas caro em escala.
- Assinatura com excedente: barata em muitos volumes, mas exige estimar uso.
- Preço por computação: você paga Lambda, containers, memória do Chromium e cold starts.
Calcule a fatura no volume atual, em 5x e em 50x. A curva de custo importa mais do que o preço destacado.
4. A saída é determinística?
Mesmo input, mesmos bytes. Você precisa disso para diff em CI, retenção fiscal, hash de arquivo e revisão jurídica.
Renderizadores baseados em navegador geralmente não são determinísticos entre versões de Chromium. Renderizadores nativos costumam ser melhores. Pergunte: “Meus bytes mudam quando vocês atualizam o motor?”
5. Como lida com fontes, CJK e RTL?
Problemas de fonte são uma das maiores surpresas em PDF. Tudo funciona no mercado inicial; depois você entra em um mercado com outro script e aparecem caixas □□□□.
Pergunte quais scripts vêm embutidos, se glyph desconhecido usa fallback, se fontes customizadas podem ir na requisição e se há suporte a shaping RTL. A resposta boa menciona NotoSans CJK, fallback global e comportamento claro.
6. Quais perfis de compliance são suportados?
Se você pode emitir notas ou faturas na UE, arquivar em PDF/A, anexar XML ou assinar digitalmente, pergunte por suporte nativo. “Converter depois com outra ferramenta” significa uma pipeline extra sob sua responsabilidade.
Boas respostas parecem flags: { profile: "PDF/A-3b" } ou { einvoice: { format: "factur-x", xml: "..." } }.
7. O render é stateless? Para onde vão meus documentos?
Em renderização stateless, a requisição entra, o PDF sai e nada é armazenado. Você controla persistência. É o modelo preferido para workloads regulados.
Em renderização stateful, o fornecedor guarda o PDF e retorna uma URL assinada. É conveniente, mas cria uma cópia de cada documento em um terceiro.
Pergunte onde é armazenado, por quanto tempo e se há garantia escrita de não armazenamento.
8. O que acontece quando o render falha?
Todo renderizador falha às vezes. O importante é a superfície da falha.
- Erro estruturado 4xx/5xx ou PDF vazio?
- Retry idempotente?
- Render com falha é cobrado?
- Há status page, webhooks e métricas p50/p99 por região?
- O fornecedor roda probes sintéticos?
Abra a status page agora. Se não houver detalhe, essa será a transparência depois da compra.
Como a gPdf responde
| # | Pergunta | Resposta da gPdf |
|---|---|---|
| 1 | Entrada | JSON DocumentRequest |
| 2 | Cold start | 5-20 ms, V8 isolate, sem navegador |
| 3 | Custo | $0/$5/$8/$12 por mês; excedente de $0.00005/página |
| 4 | Determinismo | Bytes idênticos na mesma versão do motor |
| 5 | Fontes | NotoSans CJK + fallback latino embutidos |
| 6 | Compliance | PDF/A-1b/2b/3b/4 + Factur-X / ZUGFeRD |
| 7 | Stateless | Sim, sem armazenamento de documentos |
| 8 | Falhas | Status page pública, erros estruturados e idempotência |
Onde não vencemos: se sua entrada é HTML que não pode ser refatorado, DocRaptor ou Prince podem ser a melhor escolha.
Resumo
Não pergunte “qual é a melhor API de PDF”. Faça essas oito perguntas, pontue as respostas e escolha o fornecedor alinhado ao seu workload real. Para faturas, recibos e documentos estruturados, o Playground permite avaliar gPdf rapidamente.