Formulaires PDF

Ce qu'est un formulaire PDF

Un formulaire PDF est un modèle créé en téléversant un PDF qui contient déjà des champs AcroForm : champs de texte, cases à cocher, groupes de boutons radio, listes déroulantes. Sa category est fillable_form. Au lieu d'un corps HTML, sa mise en page est le PDF téléversé lui-même. Il n'y a aucun champ content à créer à la main, et aucun modèle HTML n'intervient.

Créer et modifier un formulaire PDF se fait exclusivement depuis le dashboard Doclift, qui téléverse le PDF pour vous. Il n'existe aucun endpoint de l'API classique pour cela.

Les variables proviennent du PDF, pas de vous

Téléverser un PDF extrait chaque champ AcroForm et le transforme en variable :

Comme title est copié tel quel depuis le nom de champ du PDF, rien ne garantit qu'il suive la convention de nommage que vous choisiriez par ailleurs pour les variables d'un modèle custom. Nommez les champs avec soin dans l'outil qui a produit le PDF.

Retéléverser une nouvelle version du PDF resynchronise les variables : un champ dont le nom correspond à une variable existante met à jour le field_type et les allowed_values de cette variable ; un nouveau nom de champ crée une nouvelle variable ; une variable dont le nom n'est plus parmi les champs du PDF est détruite.

Ce que l'API peut lire

Une fois publié, un formulaire PDF est listé et affiché exactement comme n'importe quel autre modèle :

• GET /api/v1/templates : apparaît dans la liste, uniquement id/title/description
• GET /api/v1/templates/:id : détail complet, avec variables portant title, description, field_type, et allowed_values pour chaque champ auto-détecté

{
  "id": 100021,
  "title": "Subscription form",
  "description": "Tax form uploaded as a fillable PDF",
  "content": null,
  "created_at": "2024-04-12T09:15:00+01:00",
  "updated_at": "2024-04-12T09:15:00+01:00",
  "variables": [
    {
      "title": "first_name",
      "description": "First name",
      "field_type": "text",
      "allowed_values": []
    },
    {
      "title": "plan",
      "description": "Subscription plan",
      "field_type": "select",
      "allowed_values": ["starter", "pro", "enterprise"]
    }
  ]
}

Voir API Modèles pour la référence complète des champs de cette réponse.

Ce que seul le dashboard peut faire

Chaque chemin d'écriture de cette API (POST/PATCH/DELETE sur /api/v1/templates, publish, unpublish, et toute action /api/v1/templates/:template_id/variables) est restreint aux modèles custom uniquement. Les appeler avec l'identifiant d'un formulaire PDF répond 404, identique à un identifiant qui n'existe pas. Voir Les écritures ne touchent que les modèles custom pour le corps exact de la réponse, et la même règle telle qu'elle s'applique aux endpoints d'écriture des modèles custom.

Il n'y a aucun moyen de créer, modifier, supprimer, publier, dépublier, ou gérer les variables d'un formulaire PDF via l'API. Tout cela (y compris le téléversement initial du PDF et toute resynchronisation) se passe depuis le dashboard Doclift.

Générer un document

Une fois publié, un formulaire PDF génère exactement comme un modèle custom : envoyez son id comme template_id et les valeurs des variables sous forme d'objet plat à POST /api/v1/document_requests. Voir API Demandes de document. La seule différence est que Doclift vérifie chaque valeur fournie par rapport aux allowed_values de sa variable, quand elles sont définies, et répond 422 avec un tableau structuré invalid_variables en cas d'écart. Voir Erreurs de validation des variables. orientation et les champs de marge n'ont aucun effet sur le rendu d'un formulaire PDF, puisque la mise en page est le PDF téléversé lui-même.