API REST

API Modèles

API v115 août 2026·6 min de lecture

Référence complète de l'API Modèles de Doclift : lister, afficher, créer, mettre à jour, supprimer, publier et dépublier.

L'objet modèle

id : identifiant unique
title, description : chaînes requises
category : custom, fillable_form, ou workflow. Seuls les modèles custom peuvent être créés ou modifiés via cette API. Voir Les écritures ne touchent que les modèles custom
orientation : portrait ou landscape
published : si le modèle peut être utilisé pour générer des documents
content : le corps HTML (modèles custom uniquement)
margin_top, margin_bottom, margin_left, margin_right : entiers, en millimètres, minimum 5
variables : voir l'API Variables
created_at, updated_at : ISO-8601

Les écritures ne touchent que les modèles custom

Chaque action mutante sur cette ressource (create, update, delete, publish, unpublish, et toute action sous /variables) résout le modèle via un scope restreint à category: "custom". create force aussi le category à "custom" côté serveur, quelle que soit la valeur portée par le corps de la requête : l'API classique ne peut pas faire exister un modèle fillable_form ou workflow.

Un identifiant fillable_form ou workflow répond 404 en écriture

Appeler update, delete, publish, unpublish, ou n'importe quel endpoint /variables avec l'identifiant d'un modèle fillable_form ou workflow renvoie le même 404 {"error": "Template not found"} qu'un identifiant qui n'existe pas du tout. Il n'y a aucun moyen de distinguer les deux à partir de la réponse. Voir Formulaires PDF pour cette famille, et notez que les modèles workflow ont leur propre surface de création dédiée.

Les lectures ne sont pas restreintes de la même façon : GET /api/v1/templates et GET /api/v1/templates/:id listent et affichent les modèles des trois catégories une fois publiés.

Lister les modèles

GET/api/v1/templates

cURL

curl https://app.doclift.io/api/v1/templates \
  --header "X-Api-Key: <your-api-key>"

200 OK · application/json

[
  {
    "id": 100011,
    "title": "Invoice",
    "description": "Monthly invoice template"
  },
  {
    "id": 100012,
    "title": "Subscription form",
    "description": "Uploaded PDF form"
  }
]

Renvoie les modèles publiés, non archivés de votre organisation (ceux de tous les membres, pas seulement de la clé appelante) des trois catégories, dans un tableau brut, uniquement id/title/description. content n'est jamais présent dans cette forme.

Paramètre	Où	Notes
page	query	optionnel, défaut `1`

Paginé à 30 par page. Voir Pagination. Une page au-delà de la dernière répond 200 avec un tableau vide.

Statut	Corps	Quand
200	tableau	toujours, y compris pour un compte vide ou une page hors limites
403	`{"error": "..."}`	clé d'API absente, inconnue, ou désactivée

Afficher un modèle

GET/api/v1/templates/:id

cURL

curl https://app.doclift.io/api/v1/templates/100011 \
  --header "X-Api-Key: <your-api-key>"

200 OK · application/json

{
  "id": 100011,
  "title": "Invoice",
  "description": "Monthly invoice template",
  "content": "<h1>Invoice</h1><p><variable>client_name</variable></p>",
  "created_at": "2024-01-15T10:30:00+01:00",
  "updated_at": "2024-01-15T10:30:00+01:00",
  "variables": [
    {
      "title": "client_name",
      "description": "Name of the client",
      "field_type": "text",
      "allowed_values": []
    }
  ]
}

variables ne porte ici que title, description, field_type, et allowed_values : ni id, ni seed_value. Fonctionne à l'identique pour les modèles fillable_form et workflow une fois publiés : la forme des champs est la même, content inclus (vide pour un fillable_form, puisque sa mise en page vient du PDF téléversé).

Statut	Corps	Quand
200	modèle	publié, non archivé, dans votre organisation
404	`{"error": "Template not found"}`	non publié, archivé, ou modèle d'une autre organisation
403	`{"error": "..."}`	clé d'API absente, inconnue, ou désactivée

Créer un modèle

POST/api/v1/templates

Crée toujours un modèle custom. Toute category envoyée dans le corps est ignorée.

cURL

curl https://app.doclift.io/api/v1/templates \
  --request POST \
  --header "X-Api-Key: <your-api-key>" \
  --header "Content-Type: application/json" \
  --data '{
    "template": {
      "title": "Invoice",
      "description": "A template for invoices",
      "orientation": "portrait",
      "content": "<h1>Invoice</h1><p><variable>client_name</variable></p>",
      "margin_top": 10,
      "margin_bottom": 10,
      "margin_left": 15,
      "margin_right": 15,
      "variables_attributes": [
        {
          "title": "client_name",
          "description": "Name of the client",
          "field_type": "text",
          "seed_value": "John Doe"
        }
      ]
    }
  }'

201 Created · application/json

{
  "id": 100013,
  "title": "Invoice",
  "description": "A template for invoices",
  "content": "<h1>Invoice</h1><p><variable>client_name</variable></p>",
  "category": "custom",
  "orientation": "portrait",
  "published": false,
  "margin_top": 10,
  "margin_bottom": 10,
  "margin_left": 15,
  "margin_right": 15,
  "created_at": "2024-01-15T10:30:00+01:00",
  "updated_at": "2024-01-15T10:30:00+01:00",
  "variables": [
    {
      "id": 200003,
      "title": "client_name",
      "description": "Name of the client",
      "seed_value": "John Doe",
      "field_type": "text",
      "allowed_values": []
    }
  ]
}

Champ	Type	Requis	Notes
title	string	oui
description	string	oui
content	string	non	corps HTML
orientation	string	non	`portrait` ou `landscape`, défaut `portrait`
margin_top	integer	non	`>= 5`, défaut `10`
variables_attributes	array	non	voir API Variables

C'est la seule réponse qui expose seed_value avec id

Les réponses de création/mise à jour/publication/dépublication rendent chaque variable avec id, title, description, seed_value, field_type, et allowed_values. Aucun autre endpoint ne renvoie id et seed_value sur le même objet variable.

Statut	Corps	Quand
201	modèle, vue détaillée	succès
422	`{"errors": ["..."]}`	échec de validation (ex. titre vide)
403	`{"error": "..."}`	clé d'API absente, inconnue, ou désactivée

Mettre à jour un modèle

PATCH/api/v1/templates/:id

category n'est pas accepté ici. Il ne peut pas être modifié après création, pas même entre deux écritures sur le même modèle custom.

cURL

curl https://app.doclift.io/api/v1/templates/100013 \
  --request PATCH \
  --header "X-Api-Key: <your-api-key>" \
  --header "Content-Type: application/json" \
  --data '{
    "template": {
      "title": "Updated invoice",
      "variables_attributes": [
        { "id": 200003, "_destroy": true },
        { "title": "invoice_number", "field_type": "text" }
      ]
    }
  }'

200 OK · application/json

{
  "id": 100013,
  "title": "Updated invoice",
  "description": "A template for invoices",
  "content": "<h1>Invoice</h1><p><variable>client_name</variable></p>",
  "category": "custom",
  "orientation": "portrait",
  "published": false,
  "margin_top": 10,
  "margin_bottom": 10,
  "margin_left": 15,
  "margin_right": 15,
  "created_at": "2024-01-15T10:30:00+01:00",
  "updated_at": "2024-01-15T11:02:00+01:00",
  "variables": [
    {
      "id": 200004,
      "title": "invoice_number",
      "description": null,
      "seed_value": null,
      "field_type": "text",
      "allowed_values": []
    }
  ]
}

Mêmes champs que la création (moins category). Dans variables_attributes : un hash sans id crée une variable, {"id": ..., "_destroy": true} supprime celle qui correspond, tout autre hash avec un id la met à jour.

Statut	Corps	Quand
200	modèle, vue détaillée	succès
422	`{"errors": ["..."]}`	échec de validation
404	`{"error": "Template not found"}`	pas `custom`, archivé, ou d'une autre organisation
403	`{"error": "..."}`	clé d'API absente, inconnue, ou désactivée

Supprimer un modèle

DELETE/api/v1/templates/:id

cURL

curl https://app.doclift.io/api/v1/templates/100013 \
  --request DELETE \
  --header "X-Api-Key: <your-api-key>"

204 No Content. Ceci archive le modèle plutôt que de l'effacer : il cesse d'apparaître dans la liste et ne peut plus servir à générer. Il n'y a pas de suppression définitive via l'API.

Statut	Corps	Quand
204	aucun	succès
404	`{"error": "Template not found"}`	pas `custom`, déjà archivé, ou d'une autre organisation
403	`{"error": "..."}`	clé d'API absente, inconnue, ou désactivée

Publier ou dépublier un modèle

PUT/api/v1/templates/:id/publish

PUT/api/v1/templates/:id/unpublish

cURL

curl https://app.doclift.io/api/v1/templates/100013/publish \
  --request PUT \
  --header "X-Api-Key: <your-api-key>"

Les deux renvoient 200 OK avec la même vue détaillée que création/mise à jour, reflétant la nouvelle valeur de published. Les deux sont idempotents : publier un modèle déjà publié (ou dépublier un modèle déjà dépublié) répond toujours 200, jamais une erreur.

Statut	Corps	Quand
200	modèle, vue détaillée	succès, y compris un appel sans effet
404	`{"error": "Template not found"}`	pas `custom`, archivé, ou d'une autre organisation
403	`{"error": "..."}`	clé d'API absente, inconnue, ou désactivée

PrécédentBases de l'API

SuivantAPI Variables