Modèles

Les modèles vous permettent de séparer la structure de votre document de vos données. Stockez une définition de document en tant que modèle une fois, puis générez des PDF personnalisés en transmettant différentes données à chaque fois.

Flux de travail du modèle

1. Créer le modèle (POST /templates)
         |
         v
2. Stocker le modèle dans la base de données
         |
         v
3. Générer le PDF avec des données (POST /documents/generate-from-template)
         |
         v
4. Recevoir le PDF personnalisé

Étape 1 : Créer un modèle

Un modèle est une définition de document contenant des références $data et/ou des liaisons source. Enregistrez-le via l'API Templates.

{
  "name": "Shipping Invoice",
  "content": "{\"document\":{\"styles\":{\"title\":{\"fontSize\":20,\"bold\":true},\"body\":{\"fontSize\":10}},\"contents\":[{\"p\":\"$data.document.title\",\"style\":\"title\"},{\"p\":\"Prepared for $data.client.companyName\"},{\"table\":{\"widths\":[3,1,1],\"rows\":[[{\"p\":\"[b]Item[/b]\"},{\"p\":\"[b]Qty[/b]\"},{\"p\":\"[b]Price[/b]\"}]]},\"source\":\"$data.lineItems\",\"map\":[\"item\",\"qty\",\"price\"]},{\"p\":\"Total: [b]$data.invoice.total[/b]\"}]}}",
  "createdBy": "laura.bennett@shipforge.io"
}

Le champ content contient la définition du document JSON sous forme de chaîne. Le champ name est une étiquette lisible par l'homme.

Étape 2 : Générer avec les données

Appelez le point de terminaison generate-from-template avec l'ID du modèle et votre objet de données.

curl -X POST https://api.docpayload.com/v1/{tenantId}/documents/generate-from-template \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "data": {
      "document": {
        "title": "Invoice #INV-2026-0330"
      },
      "client": {
        "companyName": "Meridian Logistics"
      },
      "lineItems": [
        { "item": "Express Shipping - Chicago to Toronto", "qty": "3", "price": "$450" },
        { "item": "Customs Clearance Fee", "qty": "1", "price": "$75" },
        { "item": "Insurance - Premium Coverage", "qty": "3", "price": "$120" }
      ],
      "invoice": {
        "total": "$645"
      }
    }
  }'

Étape 3 : Recevoir le PDF

La réponse inclut une URL de téléchargement et des métadonnées sur le document généré.

Qu'est-ce qui est résolu

Lors de la génération à partir d'un modèle, DocPayload résout :

Fonctionnalité	Description
Références scalaires	$data.path.to.value dans le texte du paragraphe
Références de formatage en ligne	Références $data à l'intérieur de [b], [color], etc.
Valeurs par défaut des champs de formulaire	Références $data dans les valeurs par défaut de [textfield], [checkbox], [textarea]
Source du tableau	Remplit les lignes du tableau à partir de tableaux d'objets
Source de liste	Remplit les éléments de liste à partir de tableaux de chaînes

Exemple réel : modèle de facture

Cet exemple complet montre un modèle de facture réaliste qui combine des références scalaires, un tableau piloté par les données et une liste pilotée par les données.

Définition du modèle

{
  "document": {
    "metadata": {
      "title": "Invoice",
      "author": "ShipForge"
    },
    "pageSetup": {
      "size": "A4",
      "orientation": "portrait",
      "margins": [50, 40, 50, 40]
    },
    "styles": {
      "title": { "fontSize": 20, "fontWeight": "bold" },
      "subtitle": { "fontSize": 12, "fontStyle": "italic", "color": "#555555" },
      "total": { "fontWeight": "bold", "fontSize": 14 },
      "footer": { "fontSize": 8, "color": "#999999", "textAlign": "center" }
    },
    "header": {
      "content": [
        { "p": "[image, /assets/shipforge-logo.png, 80|24][tab, 400, 0]INVOICE", "style": "footer" }
      ],
      "hr": { "borderStyle": "solid", "height": 0.5, "color": "#CCCCCC" },
      "skipPages": [1]
    },
    "footer": {
      "content": [
        { "p": "Page $global.PAGE of $global.NUMPAGES", "style": "footer" }
      ]
    },
    "content": [
      { "p": "$data.document.title", "style": "title" },
      { "p": "Date: $data.document.date", "style": "subtitle" },
      {
        "hr": {
          "borderStyle": "solid",
          "height": 1,
          "color": "#000000"
        }
      },
      {
        "columns": {
          "widths": [1, 1],
          "gap": 20,
          "rows": [
            [
              { "p": "[b]From:[/b] $data.company.name" },
              { "p": "$data.company.address" },
              { "p": "$data.company.city" }
            ],
            [
              { "p": "[b]To:[/b] $data.client.companyName" },
              { "p": "$data.client.address" },
              { "p": "$data.client.city" }
            ]
          ]
        }
      },
      {
        "table": {
          "source": "$data.lineItems",
          "map": ["service", "hours", "rate", "total"],
          "widths": [4, 1, 1, 1],
          "rows": [
            [
              { "p": "[b]Service[/b]" },
              { "p": "[b]Hours[/b]" },
              { "p": "[b]Rate[/b]" },
              { "p": "[b]Total[/b]" }
            ]
          ]
        }
      },
      { "p": "Grand Total: $data.invoice.grandTotal", "style": "total" },
      { "p": "" },
      { "p": "Payment Terms:" },
      {
        "ol": {
          "source": "$data.paymentTerms"
        }
      },
      { "p": "" },
      { "p": "Thank you for your business, $data.client.contactName." }
    ]
  }
}

Objet de données

{
  "document": {
    "title": "Professional Services Invoice",
    "date": "March 29, 2026"
  },
  "company": {
    "name": "ShipForge Ltd",
    "address": "45 Innovation Drive",
    "city": "London, UK"
  },
  "client": {
    "companyName": "Meridian Logistics",
    "contactName": "Sarah Mitchell",
    "address": "742 Evergreen Terrace",
    "city": "Denver, CO"
  },
  "lineItems": [
    { "service": "Platform setup", "hours": "80", "rate": "$150", "total": "$12,000" },
    { "service": "API integration", "hours": "40", "rate": "$175", "total": "$7,000" },
    { "service": "User training", "hours": "16", "rate": "$125", "total": "$2,000" }
  ],
  "invoice": {
    "grandTotal": "$21,000"
  },
  "paymentTerms": [
    "Wire transfer to ShipForge Ltd account",
    "Reference: INV-SF-2026-0329",
    "Net 30 days from invoice date"
  ]
}

Sortie générée

Le même modèle, appelé avec différents objets de données, produit des factures personnalisées pour chaque client -- noms, adresses, articles et totaux différents -- tout cela à partir d'un seul modèle stocké.

Composition de modèles à partir de composants

Les modèles se composent : extrayez les en-têtes, pieds de page et blocs communs partagés dans des composants réutilisables et intégrez-les dans n'importe quel modèle avec use, au lieu de les dupliquer entre les modèles.

Voir Composition pour le guide complet — définition des composants, référencement, portée des données, cascade de styles, règles de fusion et assemblage multi-sections.

Révisions du modèle

Les modèles supportent le versioning via des révisions. Lorsque vous mettez à jour un modèle, la version précédente est conservée en tant que révision parent. Voir l'API Templates pour les points de terminaison de gestion des révisions.

Données de test

Les modèles supportent un champ testData optionnel qui stocke les données d'exemple aux côtés du modèle. Ceci est utilisé dans le Playground pour prévisualiser le modèle sans nécessiter une charge utile de données séparée.

{
  "name": "Shipping Invoice",
  "content": "{ ... document definition ... }",
  "testData": "{ \"client\": { \"companyName\": \"Test Corp\" }, ... }",
  "createdBy": "laura.bennett@shipforge.io"
}