Escolher uma API de geração de PDF parece fácil até você começar. Há cerca de 40 fornecedores, as páginas de marketing soam parecidas, e você só aprende os trade-offs reais depois de alguns milhares de documentos em produção.

Esta é uma checklist para levar a uma avaliação de fornecedores — neutra em relação a vendor, baseada nos incidentes reais que equipes encontram durante compras e post-mortems. São oito perguntas; se você não consegue uma resposta clara para todas, ainda não tem informação suficiente para escolher.

1. Qual é o formato de entrada: HTML, JSON ou uma DSL de templates?

É a pergunta mais importante. A resposta define o que sua equipe vai escrever — e o que ela vai depurar às 2 da manhã.

HTML/CSS (Puppeteer, DocRaptor, Prince): familiar, infinitamente flexível, caro em runtime, difícil de tornar determinístico.
JSON / dados estruturados (gPdf): barato para renderizar, byte a byte idêntico, exige escrever um pequeno mapper do seu modelo de dados para o modelo de documento.
Template DSL (PDFKit, ReportLab, Apache PDFBox): controle total, responsabilidade total — você escreverá paginação, layout e fallback de fontes por conta própria.

Não existe resposta errada. Existe uma resposta errada para a sua equipe. Pergunte aos seus engenheiros em qual modelo eles prefeririam depurar um bug de paginação de três horas.

2. Qual é a latência de cold start — e ela é previsível?

Alguns renderizadores iniciam em microssegundos (qualquer coisa em WASM ou binário nativo). Outros iniciam em segundos (baseados em Chromium). A diferença fica invisível até você ter um pico de tráfego.

O que perguntar ao fornecedor:

“Qual é a latência p99 da primeira requisição para um worker frio?”
“Quanto tempo depois da minha última requisição um worker volta a ficar frio?”
“Vocês publicam uma página de status com dados de cold start?”

Se eles não conseguem responder à primeira pergunta com um número, assuma que é ruim.

3. Como o custo por renderização é modelado?

Três modelos, na ordem em que mais costumam machucar:

Preço por página (Anvil a US $0,10/PDF, DocRaptor a US$ 89/100 mil): previsível, fácil de orçar, caro em escala.
Planos de assinatura com excedente (gPdf a US $5-12/mês + US$ 0,00005/página excedente): barato em qualquer volume, mais difícil de projetar para uso que você nunca testou.
Preço baseado em computação (Puppeteer auto-hospedado em Lambda): você paga a conta de computação diretamente, incluindo cold starts e memória do Chromium.

Calcule a sua conta REAL em três níveis de tráfego (atual, 5×, 50×) antes de assinar. O formato da curva de custo importa mais que o número de destaque.

4. A saída é determinística?

Determinismo — mesma entrada → mesmos bytes — parece acadêmico até você precisar dele.

Você precisa disso quando:

Compara PDFs em CI para detectar mudanças não intencionais de template.
Retém documentos por lei fiscal ou de e-invoice (o PDF armazenado e o PDF renderizado novamente precisam bater).
Gera hash do PDF para integridade de arquivo.
Versiona a saída renderizada para revisão jurídica.

Renderizadores baseados em navegador (Puppeteer, qualquer coisa em Chromium) NÃO são determinísticos entre versões de patch. Renderizadores binários nativos (Prince, gPdf) geralmente são. Pergunte explicitamente: “Meus bytes de saída vão mudar se vocês publicarem uma atualização do renderizador?”

5. Como o renderizador lida com fontes, especialmente CJK e RTL?

Esta é a pergunta que já custou mais carreiras do que qualquer outra no mundo PDF.

O modo de falha é consistente: você lança no seu mercado inicial, as fontes estão corretas. Seis meses depois, expande para um mercado que usa uma escrita para a qual o renderizador não tem glifos. O PDF começa a emitir caixas □□□□. O cliente escala. Sua equipe passa dois sprints adicionando fontes a um Dockerfile.

Perguntas para fazer:

“Quais escritas vêm embutidas sem configuração extra? (latim, CJK, cirílico, devanagari, árabe, hebraico?)”
“O que acontece quando um glifo desconhecido aparece — fallback ou tofu?”
“Posso adicionar fontes customizadas no momento da requisição, ou preciso implantá-las antes?”
“Vocês suportam shaping de texto RTL?”

Uma boa resposta: “Embutimos NotoSans CJK e um conjunto de fallback Noto; glifos desconhecidos caem para Noto Symbols.” Uma resposta ruim: “Sim, suportamos fontes.”

6. Quais perfis de conformidade são suportados?

Se o seu negócio talvez venha a:

Emitir faturas na UE (Factur-X / ZUGFeRD / EN 16931, obrigatório em DE/FR/IT/PL até 2026)
Arquivar documentos sob regras de retenção SOX, HIPAA ou GDPR (PDF/A)
Enviar prontuários médicos (PDF/A-3 com XML anexado)
Incorporar assinaturas digitais (PAdES)

…pergunte quais perfis de conformidade o renderizador suporta nativamente. A resposta ruim: “você pode rodar outra ferramenta para converter depois”. Isso é uma pipeline de várias etapas que agora você mantém.

As boas respostas geralmente parecem uma única flag — por exemplo, o gPdf aceita settings.profile: "pdfa-3b" mais um bloco settings.e_invoice com standard: "factur_x" e um XML CII embutido. Integrado é drasticamente menos operação do que acoplado depois.

7. A renderização é stateless? Para onde meus documentos vão depois de renderizados?

Duas perguntas, relacionadas.

Renderização stateless significa que a requisição entra, o PDF é emitido e nada é armazenado. Você cuida da persistência (S3, seu banco, o que for). É o que você quer para cargas com muita conformidade — o renderizador nunca se torna custodiante dos seus dados.

Renderização stateful significa que o fornecedor armazena o PDF (muitas vezes em sua CDN) e entrega uma URL assinada. Conveniente para fluxos casuais (por exemplo, “enviar um link ao cliente”), problemático para fluxos regulados (agora há um terceiro com uma cópia de cada documento que você já renderizou).

Pergunte:

“A renderização é stateless por padrão?”
“Onde, geograficamente, o documento é armazenado se vocês o armazenam?”
“Por quanto tempo ele é retido?”
“Posso obter uma garantia escrita de renderização stateless para revisão de conformidade?”

Se a resposta for vaga, sua equipe jurídica ou de privacidade transformará isso em problema nove meses depois.

8. O que acontece quando o renderizador falha — e como eu fico sabendo?

Todo renderizador falha às vezes. As perguntas são:

Como a falha aparece? Um 500 com stack trace? Um 4xx com erro estruturado? Um PDF vazio?
Qual é a política de retry? É idempotente? Você é cobrado por renderizações com falha?
Que instrumentação o fornecedor oferece? Página de status? Webhooks de incidente? Dashboards p50/p99 por região?
Existe um probe sintético — o fornecedor monitora o próprio endpoint público, ou depende de você abrir o chamado?

Um teste rápido: visite a página de status do fornecedor agora. Se ela não existe, não é em tempo real ou mostra “all systems operational” sem detalhe, esse é o nível de transparência de confiabilidade que você receberá depois da compra.

(Para referência: o gPdf publica /status com dados de probes sintéticos + Cloudflare Analytics dos últimos 7 dias.)

Como o gPdf responde às oito perguntas

Como este é o nosso blog e você pode suspeitar que inclinamos as perguntas, aqui está nosso scorecard honesto:

#	Pergunta	Resposta do gPdf
1	Formato de entrada	JSON `DocumentRequest` (dados estruturados)
2	Cold start	5-20 ms (isolate V8, sem navegador)
3	Modelo de custo	US $0/5/8/12 por mês; US$ 0,00005/página excedente
4	Determinismo	Byte a byte idêntico, garantido na mesma versão do motor
5	Fontes	NotoSans CJK + fallback latino embutidos
6	Conformidade	PDF/A-1b/2b/3b/4 + anexo Factur-X / ZUGFeRD embutido
7	Stateless	Sim, contratualmente — sem armazenamento de documentos em nenhum lugar
8	Falha e visibilidade	Página de status pública com tendência de 7 dias; 4xx/5xx estruturados; idempotente

Onde perdemos: Q1, se sua entrada é HTML de verdade e você não consegue refatorar (por exemplo, relatórios gerados por usuários, templates legados). Nesse caso, DocRaptor ou Prince são a resposta certa.

TL;DR

Não pergunte “qual é a melhor API de PDF”. Faça as oito perguntas, pontue as respostas e escolha o fornecedor que combina com sua carga real. A equipe que perdeu uma compra para um rival ligeiramente mais barato porque foi pega de surpresa pela pergunta #5 nove meses depois diria a mesma coisa.

Se sua carga se alinha com a forma como o gPdf foi construído, o Playground leva 30 segundos para avaliar. Se não se alinha, apontaremos você com tranquilidade para a ferramenta certa — normalmente DocRaptor para problemas com formato de HTML, Prince para auto-hospedagem ou Puppeteer se sua entrada forem páginas web realmente arbitrárias.