Schéma JSON des modèles

Structure d’une définition

Une définition de modèle est un objet en deux parties : page, qui définit la feuille, et elements, la liste ordonnée des éléments qui y sont dessinés.

{
  "page": {
    "size": "A4",
    "orientation": "portrait",
    "margin": { "top": 48, "right": 48, "bottom": 48, "left": 48 }
  },
  "elements": [
    {
      "id": "invoice-title",
      "type": "heading",
      "placementMode": "flow",
      "content": { "text": "Invoice" },
      "layout": { "width": 100, "widthUnit": "percent", "height": 40 },
      "style": { "fontSize": 24, "textStyle": "bold" }
    }
  ]
}

Formats de page : A4 · A3 · Letter. L’orientation est portrait ou landscape et les marges sont exprimées en pixels CSS, à raison de 96 par pouce.

Champs acceptés par chaque élément

Chaque élément contient id, type, placementMode. Le reste dépend du type, et le tableau ci-dessous est généré à partir des mêmes règles que le validateur ; il ne peut donc pas prendre de retard sur le produit.

Un champ absent de la ligne de son type provoque un échec de validation au lieu d’être ignoré. Un champ supprimé silencieusement serait pire : le document serait incomplet alors que la requête semblerait réussie.

placementMode

Détermine comment un élément trouve sa position sur la feuille. Le mode décide aussi si layout.x et layout.y sont pris en compte.

• flow — empilés les uns sous les autres dans la page ; x et y sont ignorés et l’élément s’agrandit avec son contenu
• free — placé en layout.x et layout.y, exactement à l’endroit choisi
• band — répété sur chaque page dans la bande indiquée par l’élément, comme un en-tête ou un pied de page

L’élément dataset

Un dataset imprime une collection qui n’est pas un tableau : une liste de visites, de photographies ou de signatures, dessinée selon la mise en page du modèle plutôt qu’en colonnes.

{
  "id": "maintenance-visits",
  "type": "dataset",
  "placementMode": "flow",
  "binding": "visits",
  "layout": { "width": 100, "widthUnit": "percent", "height": 160 },
  "style": { "fontSize": 11 },
  "dataRules": { "required": true }
}

binding désigne le tableau dans vos données, exactement comme pour un tableau. Le contenu dessiné pour chaque élément provient de la mise en page et du style ; la même collection peut donc être un tableau dans un modèle et un dataset dans un autre.

Un dataset ne possède pas de champ content. Il est alimenté uniquement par binding ; le texte auparavant placé dans content n’atteignait jamais la sortie. Le champ a donc été supprimé plutôt que de laisser un emplacement où écrire n’a aucun effet.

Vérifier vos données avant le rendu

Le point de terminaison de validation répond à la même question qu’un rendu, sans consommer de quota : ces données respectent-elles les exigences du modèle ?

curl -X POST https://api.pdfgine.com/api/v1/templates/invoice/validate-data \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "referenceNo": "DOC-2026-0042", "currency": "USD" } }'

Les problèmes les plus courants

• Un champ n’appartenant pas au type de son élément provoque un échec de validation plutôt que d’être ignoré. C’est volontaire : un champ supprimé silencieusement produit un document incomplet, et personne ne cherche ce qui manque.
• En placement flow, layout.x et layout.y ne sont pas lus. Les définir puis se demander pourquoi rien ne bouge est la question de schéma la plus fréquente.
• Un dataset ne possède pas de champ content ; il est alimenté uniquement par binding. Le texte placé dans content n’atteint jamais la sortie.
• Les marges et dimensions sont en pixels CSS à 96 par pouce, pas en millimètres. Un 20 saisi en pensant à des millimètres sera environ trois fois trop petit.
• Effectuer un rendu pour vérifier les données consomme une page. Le point de terminaison de validation répond à la même question gratuitement.