Lister les modèles

Qu’est-ce qu’un modèle

Un modèle est une mise en page de document enregistrée sous un code de votre choix. Il possède deux états simultanés : un brouillon que vous continuez à modifier et une version publiée utilisée en production. Enregistrer ne publie pas ; une modification inachevée ne peut donc pas atteindre vos clients.

Renvoie les modèles de votre espace de travail avec leurs numéros de version publiée. Le code du modèle est utilisé lors du rendu.

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

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

Format du numéro de page

Le contenu d’un numéro de page est un format : {{ page }} devient la page actuelle et {{ pages }} le nombre total. Écrivez « {{ page }} / {{ pages }} » pour imprimer « 3 / 12 », avec compteurs dans le PDF et champs PAGE/NUMPAGES dans Word, mis à jour automatiquement lors de l’ajout de pages. Sans marqueur, le contenu est ignoré et seul le numéro est imprimé.

Enregistrer une version

Un enregistrement contient la version que vous pensez modifier. Si quelqu’un d’autre a enregistré entre-temps, la réponse est 409 et indique la version actuelle ; rien n’est écrasé silencieusement.

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": "Facture d’entreprise",
        "saveMode": "manual",
        "expectedVersion": 5,
        "changeReason": "Logo déplacé vers la marge droite.",
        "definition": {
          "page": { "size": "A4", "orientation": "portrait" },
          "elements": [
            { "type": "text", "text": "Facture d’entreprise", "fontSize": 24 }
          ]
        }
      }'

HTTP/1.1 409 Conflict

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

expectedVersion est facultatif, mais recommandé : sans lui, la dernière écriture l’emporte et la modification précédente disparaît sans laisser de trace.

Les problèmes les plus courants

• 409 n’est pas une erreur à réessayer aveuglément. Lisez currentVersion, récupérez la définition récente, appliquez-y votre modification, puis enregistrez à nouveau.
• Enregistrer ne signifie pas publier. Le rendu de production utilise la dernière version publiée jusqu’à la publication du brouillon.
• La liste renvoie au plus 200 modèles. S’il en existe davantage, la réponse contient un en-tête Link avec rel="next" ; suivez-le plutôt que de supposer que la première page contient toute la bibliothèque.
• La lecture nécessite templates:read et l’enregistrement templates:write. Une clé en lecture seule reçoit 403 à l’enregistrement, pas 401.
• Le code permet à tous les autres appels de trouver le modèle. Vous pouvez renommer le modèle librement ; changer son code implique un nouveau modèle.