Guia do produto e da API
Resposta
O que retorna
Toda renderização bem-sucedida retorna o mesmo objeto. Vale guardar dois campos: documentId identifica o arquivo enquanto for mantido, e pageCount determina o faturamento do mês.
Resposta
{
"documentId": "doc_5bd26de32c324a4bb8cffad2c80edd01",
"jobId": "job_00b96f006b034258b00b650d724d0207",
"fileName": "invoice-doc_5bd26de32c324a4bb8cffad2c80edd01.pdf",
"format": "pdf",
"templateCode": "invoice",
"templateVersion": 5,
"templateVersionSource": "published",
"downloadUrl": "/api/v1/documents/doc_5bd2.../download/pdf",
"previewUrl": null,
"pageCount": 1,
"quotaRemaining": 4999,
"meteringBasis": "pdf-equivalent",
"createdAt": "2026-08-28T13:23:32+00:00"
}Uma renderização permanece privada e seu download exige a chave de API. Use o endpoint de prévia apenas quando precisar intencionalmente de um link temporário para o cliente.
Cabeçalhos da resposta
Toda resposta de renderização repete os números de consumo nos cabeçalhos, permitindo acompanhar a cota sem outra chamada.
X-PDFgine-Pages | Quantidade de páginas deste documento |
|---|---|
X-PDFgine-Job | Identificador da tarefa de renderização |
X-PDFgine-Quota-Remaining | Páginas restantes após a operação |
X-PDFgine-Metering-Basis | Unidade de medição |
Campo a campo
Os mesmos campos são retornados para pdf, docx e html; apenas fileName muda.
| Campo | O que significa |
|---|---|
documentId | O identificador do arquivo produzido. Downloads, status e compartilhamento o utilizam, então este é o valor que vale guardar. |
downloadUrl | Relativa ao endereço da API e acessada com a mesma chave. É um caminho, não um link público. |
templateVersion | Qual versão do modelo produziu este arquivo. Guarde-a para poder explicar uma reimpressão meses depois. |
templateVersionSource | published para uma renderização de produção; draft quando purpose era editor-test. |
pageCount | Quantas páginas foram produzidas; é o que a cota contabiliza. |
quotaRemaining | Páginas restantes no mês atual no momento desta resposta. |
meteringBasis | O que uma página significa para o faturamento. pdf-equivalent conta uma saída docx ou html com a mesma quantidade de páginas que o PDF teria. |
previewUrl | Preenchido apenas quando o documento foi compartilhado; caso contrário, null. |
Os problemas mais comuns
- downloadUrl é um caminho. Colá-lo no navegador sem o endereço da API e a chave retorna 404 ou 401, não o arquivo.
- Guarde documentId, não a resposta inteira. A retenção remove os arquivos após o prazo do seu plano, e uma URL armazenada passará a apontar para nada.
- quotaRemaining é uma fotografia daquele momento, não um contador ao vivo. Duas chamadas simultâneas podem ler o mesmo número.
- pageCount é a unidade de faturamento, não o número de arquivos. Um documento de dez páginas custa dez páginas, seja em pdf ou docx.
- previewUrl ser null não significa que o compartilhamento falhou; significa que esta renderização não foi compartilhada. Compartilhar exige uma chamada separada.