Listar modelos

O que é um modelo

Um modelo é um design de documento armazenado com um código escolhido por você. Ele tem duas versões ao mesmo tempo: um rascunho que você continua editando e uma versão publicada usada na produção. Salvar não publica, então uma alteração inacabada não chega aos clientes.

Retorna os modelos do espaço de trabalho com os números das versões publicadas. O código do modelo é usado na renderização.

curl https://api.pdfgine.com/api/v1/templates \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

[
  {
    "templateId": "tpl_eca4c9985ad74913902f0469469936a1",
    "code": "invoice",
    "name": "Fatura corporativa",
    "version": 5,
    "publishedVersion": 1,
    "publishedAt": "2026-08-23T08:23:21+00:00"
  }
]

Formato do número de página

O conteúdo de um elemento de número de página é um formato: {{ page }} vira a página atual e {{ pages }} o total. Escreva “{{ page }} / {{ pages }}” e o documento imprime “3 / 12”, com contadores no PDF e campos PAGE/NUMPAGES no Word, atualizados automaticamente ao adicionar páginas. Sem marcadores no conteúdo, ele é ignorado e só o número da página é impresso.

Salvar uma versão

Um salvamento inclui a versão que você acredita estar editando. Se outra pessoa salvou nesse intervalo, a resposta é 409 e informa a versão atual, evitando sobrescritas silenciosas.

curl -X POST https://api.pdfgine.com/api/v1/templates \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "code": "invoice",
        "name": "Fatura corporativa",
        "saveMode": "manual",
        "expectedVersion": 5,
        "changeReason": "Logotipo movido para a margem direita.",
        "definition": {
          "page": { "size": "A4", "orientation": "portrait" },
          "elements": [
            { "type": "text", "text": "Fatura corporativa", "fontSize": 24 }
          ]
        }
      }'

HTTP/1.1 409 Conflict

{
  "type": "https://pdfgine.dev/problems/template-conflict",
  "templateCode": "invoice",
  "currentVersion": 6,
  "currentDraftRevision": 0
}

expectedVersion é opcional, mas recomendado: sem ele, a última gravação vence e a alteração anterior desaparece sem deixar rastros.

Os problemas mais comuns

• 409 não é um erro para repetir às cegas. Leia currentVersion, obtenha a definição mais recente, aplique sua alteração sobre ela e salve novamente.
• Salvar não é publicar. A renderização de produção continua usando a última versão publicada até você publicar o rascunho.
• A listagem retorna no máximo 200 modelos. Se houver mais, a resposta inclui um cabeçalho Link com rel="next"; siga-o em vez de assumir que a primeira página contém toda a biblioteca.
• A leitura exige templates:read e o salvamento exige templates:write. Uma chave somente de leitura recebe 403 ao salvar, não 401.
• O código é como todas as outras chamadas encontram o modelo. Renomear o modelo é livre; alterar seu código significa um novo modelo.