Renderizar um documento

O que este endpoint faz

Uma chamada transforma um modelo e seus dados em um arquivo pronto. O documento é produzido enquanto você espera e a resposta inclui um endereço de download; não é preciso consultar o status. Para documentos longos ou tarefas em lote, o endpoint de fila faz o mesmo em segundo plano.

Envie o código do modelo e seus dados e receba o documento. A URL de download da resposta é relativa ao endereço base e usa a mesma chave de API.

curl -X POST https://api.pdfgine.com/api/v1/render \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "templateCode": "invoice",
        "format": "pdf",
        "locale": "pt",
        "purpose": "production",
        "data": {
          "document": { "title": "INV-2026-001" }
        }
      }'

O campo format aceita "pdf" ou "docx". Valores numéricos continuam funcionando para clientes existentes: 1 é PDF, 2 é DOCX. As respostas retornam o formato como número.

O propósito production consome cota. Ao testar um modelo, envie editor-test: essa saída não consome cota e usa a revisão do rascunho não publicado.

O ciclo completo

Esta é a resposta à chamada acima e a chamada que busca o arquivo. O status é 202: a solicitação foi aceita e o documento está pronto.

HTTP/1.1 202 Accepted
X-PDFgine-Pages: 1
X-PDFgine-Quota-Remaining: 4999

{
  "documentId": "doc_a96063f5dcd5400286ce9b3be9b0595b",
  "format": "pdf",
  "templateCode": "invoice",
  "templateVersion": 1,
  "templateVersionSource": "published",
  "downloadUrl": "/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf",
  "pageCount": 1,
  "quotaRemaining": 4999,
  "meteringBasis": "pdf-equivalent"
}

curl https://api.pdfgine.com/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -o invoice.pdf

Os problemas mais comuns

• A renderização responde 202, não 200. Um cliente que trata qualquer código diferente de 200 como falha reporta sucesso como erro.
• purpose decide duas coisas ao mesmo tempo: production usa a versão publicada e consome cota; editor-test usa o rascunho não publicado e não consome nada. Testar com production é a forma mais cara de experimentar um modelo.
• 422 não é uma falha do servidor. O corpo lista em errors todos os campos exigidos pelo modelo; a correção está nos dados enviados, não em uma nova tentativa.
• 402 significa que a cota mensal de páginas acabou. O cabeçalho X-PDFgine-Quota-Remaining avisa antes de você chegar a esse ponto.
• downloadUrl é relativa ao endereço da API. Guardá-la como URL absoluta deixa de funcionar quando o endereço muda; guarde documentId e monte o endereço.