Gerar um PDF

POST /v1/render produz um PDF a partir de um template e de dados. Uma geração bem-sucedida custa um crédito; uma geração que falha não custa nada.

Há duas formas de dizer o que gerar, e cada uma tem o seu guia:

• Com um template salvo: você guarda o template na conta e envia o id junto com os dados.
• Com HTML direto: você envia o HTML e os dados na mesma requisição, e nada é guardado.

Esta página é a referência da requisição e da resposta, que são iguais nas duas.

Requisição

{
  "template_id": "0194f2c0-…",
  "data": { "customer": "Ana Souza", "total": "1234.50" },
  "locale": "pt-BR",
  "title": "Fatura 2025-0042",
  "output": "pdf",
  "strict": false
}

Campo	Tipo	Significado
template_id	string	Um template salvo na sua conta. Envie este ou html.
html	string	HTML inline, tratado como template. Envie este ou template_id.
data	objeto	Valores do template. Padrão: {}.
locale	string	Uma tag BCP 47, como pt-BR. Padrão: o idioma do template e, depois, o da sua conta.
title	string	O título do documento gravado no PDF.
output	"pdf" ou "url"	pdf (padrão) devolve o arquivo. url devolve um JSON com um link assinado.
strict	booleano	Recusa o documento se ele usar algo que o serviço não suporta totalmente.

Enviar template_id e html juntos, ou nenhum dos dois, é um 400.

Resposta: o PDF

Com output: "pdf" o corpo é o PDF (Content-Type: application/pdf) e estes cabeçalhos o descrevem:

Cabeçalho	Valor
X-Render-Id	Id desta geração.
X-Pages	Número de páginas.
X-Credits-Remaining	Seu saldo depois desta geração.
X-Diagnostics	Quantidade de itens que o serviço não suportou totalmente; veja Validar.

Resposta: um link

Com output: "url" o PDF é guardado por um tempo e você recebe um JSON:

{
  "id": "0194f2c1-…",
  "url": "https://api.example.com/v1/files/0194f2c1-…?exp=1760000000&sig=…",
  "expires_at": 1760000000,
  "pages": 1,
  "bytes": 27003,
  "credits_remaining": 999,
  "diagnostics": []
}

O link funciona sem chave de API até expires_at, e depois deixa de funcionar. Por quanto tempo os arquivos ficam guardados depende do seu plano; veja Planos e créditos. Compartilhe o link com o seu cliente, ou baixe o arquivo uma vez e guarde você mesmo.

Modo estrito

Por padrão, um recurso não suportado é ignorado e reportado. Com strict: true a requisição falha com 422 strict_mode_rejected e lista todos os diagnósticos, sem usar crédito. Use nos testes para garantir que um template continue limpo.

Limites

Uma geração é recusada quando a entrada, o HTML expandido, a quantidade de páginas ou o tempo passam dos limites do seu plano, e quando o serviço está no limite de capacidade. Veja Erros e limites.