Générer à partir d'un modèle

Générez un document en combinant un modèle stocké avec un objet de données. Toutes les références $data et les liaisons source du modèle sont résolues avec les données fournies avant le rendu. Ajoutez le format souhaité au chemin du point de terminaison.

POST /documents/generate-from-template/{format}

Point de terminaison

POST /v1/{tenantId}/documents/generate-from-template/{format}

`format`	Sortie
`pdf`	Document PDF (par défaut)
`docx`	Document Word

En-têtes

En-tête	Valeur	Requis
`Authorization`	`Bearer YOUR_ACCESS_TOKEN`	Oui
`Content-Type`	`application/json`	Oui

YOUR_ACCESS_TOKEN est le jeton d'accès obtenu en échangeant le Client ID et le secret de votre clé API ; voir Authentification.

Paramètres de chemin

Paramètre	Type	Description
`tenantId`	string	Votre identifiant de locataire

Corps de la requête

Champ	Type	Requis	Description
`templateId`	string (GUID)	Oui	ID du modèle stocké
`data`	object	Oui	Objet de données avec les valeurs à injecter dans le modèle

{
  "templateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "client": {
      "companyName": "Meridian Logistics",
      "contactName": "Sarah Mitchell",
      "address": "12 Harbor Road",
      "city": "Austin, TX"
    },
    "document": {
      "title": "Professional Services Invoice",
      "date": "March 30, 2026"
    },
    "lineItems": [
      { "service": "Platform setup", "hours": "80", "rate": "$150", "total": "$12,000" },
      { "service": "API integration", "hours": "40", "rate": "$175", "total": "$7,000" }
    ],
    "invoice": {
      "grandTotal": "$19,000"
    },
    "paymentTerms": [
      "Wire transfer to ShipForge Ltd account",
      "Net 30 days from invoice date"
    ]
  }
}

Réponse

Succès (200 OK)

Retourne les métadonnées du document généré avec une URL de téléchargement.

{
  "fileName": "docpayload_v1-d4e5f6a7b8c90123456789abcdef0123.pdf",
  "documentId": "d4e5f6a7b8c90123456789abcdef0123",
  "status": "Succeeded",
  "fileSizeBytes": 31744,
  "contentType": "application/pdf",
  "downloadUrl": "https://api.docpayload.com/v1/{tenantId}/assets/docs/docpayload_v1-d4e5f6a7b8c90123456789abcdef0123.pdf",
  "errorCodes": []
}

Les champs fileName et contentType reflètent le format demandé.

`errorCodes`

Un document peut être généré tout en étant privé d'un élément qu'il demandait : une image introuvable, un jeton sans valeur. Le document est écrit, stocké et comptabilisé, et errorCodes nomme ce qui manque, chaque code une seule fois. Le tableau est vide lorsque le document a obtenu tout ce qu'il demandait : vérifiez-le avant de transmettre un document.

Code	Ce qui manque au document
`IMAGE_NOT_LOADED`	une image : introuvable, illisible ou impossible à décoder
`FONT_NOT_LOADED`	un fichier de police déclaré : introuvable ou illisible, et son texte est composé dans une autre police
`SVG_NOT_LOADED`	un fichier svg : introuvable ou illisible
`ATTACHMENT_NOT_EMBEDDED`	une pièce jointe : le fichier est introuvable ou illisible
`UNRESOLVED_TOKEN`	une valeur : un jeton `$data` ou `$global` n'en avait pas, et son propre libellé figure sur la page
`CONFORMANCE_WITHHELD`	une conformité : le fichier ne respecte pas une déclaration PDF/A ou PDF/UA qu'il porterait, donc elle est retirée (Conformité). Un document chiffré n'est tout simplement pas archivable, et ne porte aucun code pour cela
`CONTENT_ERROR`	un autre élément demandé par la définition

Erreur (400 Bad Request) : la signature n'a pas pu être apposée

Retourné lorsque le document demande une signature et qu'elle ne peut pas être apposée. Un document signé qui ne l'est pas n'est pas le document demandé : rien n'est généré, stocké ni comptabilisé.

{
  "title": "Bad Request",
  "status": 400,
  "detail": "The document asks for a signature that could not be applied: its certificate was not found, could not be opened or holds no private key. Nothing was generated or billed.",
  "errorCode": "SIGNATURE_NOT_APPLIED",
  "isRetryable": false
}

Erreur (404 Not Found)

Retourné lorsque l'ID du modèle n'existe pas ou n'appartient pas à votre locataire.

{
  "message": "Template 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found."
}

Erreur (400 Bad Request)

Retourné lorsque le modèle ne contient pas une définition de document valide.

{
  "message": "The template does not contain a valid document definition."
}

Exemple

curl -X POST https://api.docpayload.com/v1/{tenantId}/documents/generate-from-template/pdf \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "data": {
      "client": {
        "companyName": "Meridian Logistics"
      },
      "document": {
        "title": "Delivery Receipt"
      }
    }
  }'

Résolution des données

Lorsque ce point de terminaison est appelé, les étapes de résolution suivantes se produisent :

Le modèle est récupéré de la base de données par templateId.
Le content du modèle (une chaîne JSON) est analysé en une définition de document.
Toutes les références scalaires $data.path.to.value dans le texte du paragraphe sont remplacées par les valeurs de l'objet data.
Toutes les références $data dans les valeurs par défaut des champs de formulaire (textfield, checkbox, textarea) sont résolues.
Toutes les liaisons source sur les tableaux et les listes sont résolues :
- Les tableaux source sont mappés aux lignes en utilisant map.
- Les tableaux source de listes sont convertis en éléments de liste.
La définition de document résolue est rendue au format demandé (PDF ou DOCX).

Ce qui est résolu

Fonctionnalité	Exemple	Description
Texte scalaire	`$data.client.name`	Remplacé par la valeur au chemin donné
Chemins imbriqués	`$data.client.address.city`	Traversée séparée par des points d'objets imbriqués
À l'intérieur du formatage	`[b]$data.total[/b]`	Référence résolue, puis formatage appliqué
Valeurs par défaut du formulaire	`'$data.applicant.email'`	Pré-remplit les champs de formulaire éditables
Lignes du tableau	`"source": "$data.items"`	Les éléments du tableau deviennent des lignes de tableau
Éléments de liste	`"source": "$data.notes"`	Les éléments du tableau deviennent des éléments de liste
Références non résolues	`$data.missing.key`	Conservées comme texte littéral

Téléchargement du document

Utilisez l'downloadUrl de la réponse pour récupérer le document généré :

curl -X GET "https://api.docpayload.com/v1/{tenantId}/assets/docs/docpayload_v1-d4e5f6a7b8c90123456789abcdef0123.pdf" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o invoice.pdf

POST /documents/generate-from-template/{format}​

Point de terminaison​

En-têtes​

Paramètres de chemin​

Corps de la requête​

Réponse​

errorCodes​

Exemple​

Résolution des données​

Ce qui est résolu​

Téléchargement du document​