API Templates : lister, récupérer, créer, modifier et supprimer des modèles

Dernière mise à jour le 23 mars 2026

Référence complète de l’API pour lister, récupérer, créer, modifier et supprimer des modèles dans PDFMonkey.

La plupart des utilisateurs n’ont pas besoin de l’API Modèles

Les modèles sont généralement conçus dans le Dashboard ou le Builder visuel. L’API Modèles est utile lorsque vous gérez des modèles par programmation (par exemple, synchronisation depuis un pipeline CI ou construction d’un éditeur personnalisé). Pour générer des documents à partir d’un modèle existant, consultez l’API Documents.

Authentification

Toutes les requêtes nécessitent un token Bearer dans l’en-tête Authorization :

Authorization: Bearer YOUR_SECRET_KEY

Consultez Authentification pour savoir comment trouver votre clé API.

L’objet DocumentTemplate

Un DocumentTemplate est le design réutilisable qui définit la mise en page d’un document. Il contient :

  • HTML + Liquid pour le contenu dynamique
  • CSS / SCSS pour le style
  • Données de test pour l’aperçu dans le Dashboard
  • Paramètres pour le format du papier, les marges, les en-têtes et les pieds de page

Propriétés brouillon et publiées

Chaque modèle maintient deux ensembles de propriétés :

  • Les propriétés brouillon (body_draft, scss_style_draft, settings_draft, sample_data_draft, pdf_engine_draft_id) pour le contenu en cours d’édition dans le Dashboard mais pas encore publié.
  • Les propriétés publiées (body, scss_style, settings, sample_data, pdf_engine_id) utilisées lors de la génération des documents.

Lorsque vous publiez un modèle dans le Dashboard, les valeurs brouillon sont copiées vers leurs équivalents publiés.

Attributs

{
  "id": "8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9",
  "app_id": "3161c5e5-9966-4630-9b07-63f718092784",
  "identifier": "Mon Super Modèle",
  "edition_mode": "code",
  "output_type": "pdf",
  "body": "<p>Bonjour {{name}}</p>",
  "body_draft": "<p>Bonjour, <strong>{{name}} !</strong></p>",
  "scss_style": "p { color: green; }",
  "scss_style_draft": "p { color: purple; }",
  "sample_data": "{ \"name\": \"Pierre Dupont\" }",
  "sample_data_draft": "{ \"name\": \"Spider-Man\" }",
  "settings": {
    "footer": {
      "center": null,
      "content": null,
      "left": null,
      "right": "page [page]/[topage]"
    },
    "header": {
      "center": null,
      "content": null,
      "left": null,
      "right": null
    },
    "inject_javascript": false,
    "margin": {
      "bottom": 0,
      "left": 0,
      "right": 0,
      "top": 0
    },
    "orientation": "portrait",
    "paper_format": "a4",
    "paper_height": 297,
    "paper_width": 210,
    "transparent_background": false,
    "use_emojis": false,
    "use_paged": false
  },
  "settings_draft": { /* même structure que settings */ },
  "pdf_engine_id": "5c709522-90db-4aea-b49f-15aeaa7180c7",
  "pdf_engine_draft_id": "5c709522-90db-4aea-b49f-15aeaa7180c7",
  "template_folder_id": null,
  "ttl": 86400,
  "created_at": "2050-01-02T03:04:05.678+02:00",
  "updated_at": "2050-01-02T03:04:05.678+02:00",
  "auth_token": "ZCsspcSZieyfdCUHYjKW1B9D8mnrz2ck",
  "checksum": "kfYsx6xzMx3JkYxLd4LW6YeU5rkcuTxQ",
  "preview_url": "https://preview.pdfmonkey.io/pdf/..."
}
AttributTypeDescription
idUUIDIdentifiant unique.
app_idUUIDIdentifiant unique de l’espace de travail du modèle.
identifierStringNom lisible (1 à 100 caractères).
edition_modeStringcode, visual (obsolète) ou builder.
output_typeStringpdf ou image. Détermine le format des documents générés.
bodyStringContenu HTML + Liquid publié, utilisé pour générer les documents.
body_draftStringContenu HTML + Liquid non publié, pas encore utilisé pour la génération.
scss_styleStringStyles CSS ou SCSS publiés, appliqués au contenu. Ne s’applique pas aux en-têtes ni aux pieds de page.
scss_style_draftStringStyles CSS ou SCSS non publiés.
sample_dataStringDonnées de test publiées. Non utilisées pour la génération ; servent de point de restauration pour les modifications brouillon.
sample_data_draftStringDonnées JSON brouillon utilisées pour prévisualiser le modèle. Non utilisées pour la génération.
settingsObjectParamètres d’impression publiés. Voir Paramètres ci-dessous.
settings_draftObjectParamètres d’impression non publiés. Voir Paramètres ci-dessous.
pdf_engine_idUUIDID du moteur PDF utilisé lors de la génération des documents. Voir Moteurs PDF ci-dessous.
pdf_engine_draft_idUUIDID du moteur PDF utilisé pour prévisualiser le contenu brouillon. Utile pour tester un nouveau moteur avant de basculer. Voir Moteurs PDF ci-dessous.
template_folder_idUUID ou nullID d’un dossier pour regrouper le modèle.
ttlNumberDurée de vie en secondes. Les documents générés depuis ce modèle sont automatiquement supprimés après ce délai. Voir Rétention et suppression.
created_atString (ISO 8601)Date de création du modèle.
updated_atString (ISO 8601)Date de dernière modification du modèle.
auth_tokenStringInterne. Non utilisé.
checksumStringInterne. Utilisé pour l’invalidation du cache d’aperçu.
preview_urlString (URL)URL pour prévisualiser le modèle avec les propriétés brouillon. À intégrer dans un <iframe> ou à ouvrir directement.

Paramètres

L’attribut settings (et son équivalent brouillon settings_draft) contrôle la mise en page, le formatage et le comportement des documents générés.

Tous les paramètres ne s’appliquent pas à chaque configuration de modèle. La colonne S’applique à indique les modes d’édition et types de sortie concernés par chaque paramètre.

AttributTypeS’applique àDescription
footerObjectPDF (code, builder)Configure le pied de page.
footer.left / footer.center / footer.rightStringPDF (code, builder)Contenu pour les parties gauche, centre ou droite du pied de page. Les tokens magiques [page] et [topage] insèrent le numéro de page courant et le nombre total de pages. HTML + Liquid non pris en charge.
footer.contentStringPDF (code, builder)Contenu pleine largeur pour le pied de page. Remplace left, center et right lorsqu’il est défini.
headerObjectPDF (code, builder)Configure l’en-tête.
header.left / header.center / header.rightStringPDF (code, builder)Contenu pour les parties gauche, centre ou droite de l’en-tête. Les tokens magiques [page] et [topage] peuvent être utilisés. HTML + Liquid non pris en charge.
header.contentStringPDF (code, builder)Contenu pleine largeur pour l’en-tête. Remplace left, center et right lorsqu’il est défini.
inject_javascriptBooleanTousLorsque true, le payload du document (ou les données de test) est accessible en JavaScript via la variable $docPayload. Peut impacter les performances avec de gros payloads. Toujours activé pour les modèles builder.
marginObjectPDF (code, builder)Définit les marges du document.
margin.bottom / margin.left / margin.right / margin.topNumberPDF (code, builder)Marge en millimètres. Valeur par défaut : 10 si défini à null ou omis.
orientationStringPDF (code, builder)Orientation de la page : portrait ou landscape.
paper_formatStringPDF (code, builder)Format du papier : a0, a1, a2, a3, a4, a5, a6, letter ou custom.
paper_heightNumberPDF (code, builder)Hauteur du papier en millimètres. Utilisé uniquement lorsque paper_format est custom ; sinon dérivé du format.
paper_widthNumberLargeur du papier en millimètres. Utilisé uniquement lorsque paper_format est custom ; sinon dérivé du format.
transparent_backgroundBooleanImageLorsque true, l’image générée a un fond transparent au lieu de blanc.
use_emojisBooleanTousLorsque true, active le rendu des emojis (via Noto Color Emoji) dans le document généré.
use_pagedBooleanPDF (code, builder)Spécifique au moteur PDF v3. Lorsque true, le moteur attend que le rendu Paged.js soit terminé avant de générer le PDF. Les autres moteurs ignorent ce paramètre.

Moteurs PDF

PDFMonkey propose plusieurs moteurs PDF, chacun avec des capacités différentes. Nous recommandons fortement d’utiliser le v4, le plus récent et le plus puissant. Consultez Nos moteurs pour une comparaison détaillée.

Pour récupérer la liste des moteurs disponibles :

curl https://api.pdfmonkey.io/api/v1/engines \
  -H "Authorization: Bearer VOTRE_CLE_SECRETE"
{
  "pdf_engines": [
    { "id": "5c709522-90db-4aea-b49f-15aeaa7180c7", "name": "v4", "deprecated_on": null },
    { "id": "61749ef7-6aca-4edb-84ca-685adb638c34", "name": "v3", "deprecated_on": null },
    { "id": "1f8da2ab-29c4-455c-a5fb-8771e44148c3", "name": "v2", "deprecated_on": null }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1
  }
}

Lister les modèles

GET /api/v1/document_template_cards

Renvoie une liste paginée de fiches modèle. Les fiches modèle sont des objets légers qui omettent le corps, les styles et les données de test du modèle.

Paramètres de requête

NomTypeRequisDescription
q[workspace_id]String (UUID)OuiL’espace de travail dont lister les modèles. Accepte aussi q[workspaceId], q[app_id] ou q[appId].
q[folders]StringNonListe d’IDs de dossiers séparés par des virgules. Utilisez "none" pour les modèles hors dossier, ou "all" (par défaut) pour tous les modèles.
pageIntegerNonNuméro de page pour la pagination.
sortStringNonAttribut de tri.

Requête

curl -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  'https://api.pdfmonkey.io/api/v1/document_template_cards?q[workspace_id]=3161c5e5-9966-4630-9b07-63f718092784'

Réponse

{
  "document_template_cards": [
    {
      "id": "8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9",
      "app_id": "3161c5e5-9966-4630-9b07-63f718092784",
      "auth_token": "ZCsspcSZieyfdCUHYjKW1B9D8mnrz2ck",
      "created_at": "2050-01-02T03:04:05.678+02:00",
      "edition_mode": "code",
      "identifier": "Mon Super Modèle",
      "is_draft": true,
      "output_type": "pdf",
      "pdf_engine_deprecated_on": null,
      "pdf_engine_name": "v4",
      "template_folder_id": null,
      "template_folder_identifier": null,
      "updated_at": "2050-01-02T03:04:05.678+02:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1
  }
}

Fiches modèle et modèles complets

Les fiches modèle sont légères : elles incluent les métadonnées comme identifier, edition_mode et is_draft, mais pas le corps du modèle, les styles ni les données de test. Pour obtenir le contenu complet d’un modèle, utilisez Récupérer un modèle.

Récupérer un modèle

GET /api/v1/document_templates/{id}

Renvoie l’objet DocumentTemplate complet incluant le corps, les styles, les données de test et les paramètres.

Requête

curl -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  https://api.pdfmonkey.io/api/v1/document_templates/8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9

Réponse

Renvoie 200 OK avec un objet document_template :

{
  "document_template": {
    "id": "8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9",
    "app_id": "3161c5e5-9966-4630-9b07-63f718092784",
    "identifier": "Mon Super Modèle",
    "edition_mode": "code",
    "output_type": "pdf",
    "body": "<p>Bonjour {{name}}</p>",
    "body_draft": "<p>Bonjour, <strong>{{name}} !</strong></p>",
    "scss_style": "p { color: green; }",
    "scss_style_draft": "p { color: purple; }",
    "sample_data": "{ \"name\": \"Pierre Dupont\" }",
    "sample_data_draft": "{ \"name\": \"Spider-Man\" }",
    "settings": { "...": "..." },
    "settings_draft": { "...": "..." },
    "pdf_engine_id": "5c709522-90db-4aea-b49f-15aeaa7180c7",
    "pdf_engine_draft_id": "5c709522-90db-4aea-b49f-15aeaa7180c7",
    "template_folder_id": null,
    "ttl": 86400,
    "created_at": "2050-01-02T03:04:05.678+02:00",
    "updated_at": "2050-01-02T03:04:05.678+02:00",
    "auth_token": "ZCsspcSZieyfdCUHYjKW1B9D8mnrz2ck",
    "checksum": "kfYsx6xzMx3JkYxLd4LW6YeU5rkcuTxQ",
    "preview_url": "https://preview.pdfmonkey.io/pdf/..."
  }
}

Créer un modèle

POST /api/v1/document_templates

Crée un nouveau modèle. Dans la plupart des cas, il est préférable de créer les modèles via le Dashboard, mais l’API est disponible pour les workflows programmatiques.

Paramètres

Tous les paramètres sont imbriqués sous une clé document_template.

NomTypeRequisDescription
app_idString (UUID)OuiL’espace de travail dans lequel créer le modèle.
identifierStringOuiNom lisible (1 à 100 caractères).
bodyStringNonContenu HTML + Liquid publié.
body_draftStringNonContenu HTML + Liquid brouillon.
scss_styleStringNonStyles CSS/SCSS publiés.
scss_style_draftStringNonStyles CSS/SCSS brouillon.
sample_dataStringNonDonnées de test publiées (chaîne JSON).
sample_data_draftStringNonDonnées de test brouillon (chaîne JSON).
settingsObject ou StringNonParamètres d’impression publiés. Voir Paramètres.
settings_draftObject ou StringNonParamètres d’impression brouillon.
pdf_engine_idString (UUID)NonMoteur PDF pour la génération. Par défaut, le dernier moteur. Voir Moteurs PDF.
pdf_engine_draft_idString (UUID)NonMoteur PDF pour l’aperçu. Par défaut, le dernier moteur.
template_folder_idString (UUID)NonDossier dans lequel placer le modèle.
ttlIntegerNonDurée de vie en secondes des documents générés. Les valeurs autorisées dépendent de votre plan. Voir Rétention et suppression.
edition_modeStringNoncode (par défaut) ou builder.
output_typeStringNonpdf (par défaut) ou image. Voir Format de sortie.

Requête

curl https://api.pdfmonkey.io/api/v1/document_templates \
  -X POST \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "document_template": {
      "app_id": "3161c5e5-9966-4630-9b07-63f718092784",
      "identifier": "Invoice Template",
      "body_draft": "<h1>Invoice #{{number}}</h1><p>Total: {{total}}</p>",
      "scss_style_draft": "h1 { color: #333; }",
      "sample_data_draft": "{ \"number\": \"INV-001\", \"total\": \"$123.50\" }",
      "settings_draft": {
        "paper_format": "a4",
        "orientation": "portrait",
        "margin": { "top": 20, "bottom": 20, "left": 15, "right": 15 }
      }
    }
  }'

Réponse

Renvoie 201 Created avec l’objet document_template complet.

Erreurs de validation

Si des champs requis sont manquants ou invalides, l’API renvoie 422 Unprocessable Entity :

{
  "errors": {
    "identifier": ["can't be blank"]
  }
}

Modifier un modèle

PUT /api/v1/document_templates/{id}

Met à jour un modèle existant. Seuls les champs inclus dans le corps de la requête sont modifiés.

Paramètres

Tous les paramètres sont imbriqués sous une clé document_template. Les mêmes champs que Créer un modèle sont acceptés.

Requête

curl https://api.pdfmonkey.io/api/v1/document_templates/8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9 \
  -X PUT \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "document_template": {
      "body_draft": "<h1>Invoice #{{number}}</h1><p>Due: {{due_date}}</p><p>Total: {{total}}</p>",
      "sample_data_draft": "{ \"number\": \"INV-001\", \"due_date\": \"2050-04-01\", \"total\": \"$123.50\" }"
    }
  }'

Réponse

Renvoie 200 OK avec l’objet document_template mis à jour.

Supprimer un modèle

DELETE /api/v1/document_templates/{id}

Supprime définitivement un modèle.

La suppression d’un modèle est irréversible. Tous les documents liés à ce modèle perdront leur référence de modèle.

Requête

curl https://api.pdfmonkey.io/api/v1/document_templates/8ac0d8f7-dbd3-46dd-b2d3-af036a2776d9 \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_SECRET_KEY'

Réponse

Renvoie 204 No Content avec un corps vide.

Questions fréquentes

Qu’est-ce qu’un DocumentTemplate dans PDFMonkey ?
Un DocumentTemplate est le design réutilisable qui définit la mise en page d’un document. Il contient du HTML + Liquid pour le contenu dynamique, du CSS/SCSS pour le style, des données de test pour la prévisualisation et des paramètres de format papier, marges, en-têtes et pieds de page.
Comment lister tous les modèles avec l’API PDFMonkey ?
Envoyez une requête GET à /api/v1/document_template_cards avec un paramètre q[workspace_id]. La réponse renvoie une liste paginée d’objets template card légers.
Peut-on créer et modifier des modèles via l’API ?
Oui. Envoyez un POST à /api/v1/document_templates pour créer un modèle et un PUT à /api/v1/document_templates/{id} pour le modifier. La plupart des utilisateurs conçoivent les modèles dans le Dashboard.