Comment pré-remplir des formulaires PDF avec des agents IA avec SimplePDF

Benjamin André-Micolon

Un agent IA peut lire un e-mail client, une ligne de base de données ou une soumission précédente et déterminer ce qui doit figurer dans un formulaire. Ce qu'un agent ne devrait pas faire, c'est envoyer un formulaire de lui-même. L'API de pré-remplissage permet à votre agent de préparer un PDF entièrement rempli et de le confier à une personne pour qu'elle le relise, le corrige et l'envoie : l'agent se charge de la partie fastidieuse, un humain reste impliqué pour la décision qui compte.

Cela maintient des taux de complétion élevés, le destinataire ouvre un document déjà rempli et non un formulaire vierge, tout en gardant un humain responsable de ce qui est envoyé.

Ce guide parle d'un agent IA, mais l'API de pré-remplissage n'est qu'une API HTTP (REST). Tout système capable d'effectuer une requête HTTP peut l'utiliser : un agent IA, une tâche backend, une automatisation de workflow ou une intégration CRM. Consultez la documentation de l'API pour une référence lisible, ou la spécification OpenAPI à importer dans vos outils ou pour générer un client. Les deux documentent chaque point d'accès et chaque champ.

Comment ça marche

Un pré-remplissage est un ensemble de valeurs de champs qui réside dans votre propre stockage (S3, Azure Blob Storage ou SharePoint), jamais sur SimplePDF. Vous créez un pré-remplissage via l'API, vous téléversez les valeurs directement vers votre stockage, et vous partagez un lien. Lorsque le destinataire ouvre le lien, l'éditeur lit les valeurs depuis votre stockage et affiche le document rempli pour relecture.

    Your agent              SimplePDF              Your storage          Your recipient
   ┌────────────┐         ┌────────────┐        ┌─────────────────┐    ┌────────────┐
   │   .----.   │         │            │        │                 │    │  ( ^_^ )   │
   │  [ o  o ]  │         │  SimplePDF │        │  Your storage   │    │   /| |\    │
   │  [  __  ]  │         │     API    │        │ S3/Azure/ShareP │    │    | |     │
   │   '-||-'   │         │            │        │                 │    │   _/ \_    │
   │  a robot   │         │            │        │                 │    │  a human   │
   └──────┬─────┘         └──────┬─────┘        └────────┬────────┘    └──────┬─────┘
          │                      │                       │                    │
          │  1. POST /prefills   │                       │                    │
          │ ───────────────────> │                       │                    │
          │   upload + embed_url │                       │                    │
          │ <─────────────────── │                       │                    │
          │                      │                       │                    │
          │  2. upload the prefill blob (field values never reach SimplePDF)  │
          │ ───────────────────────────────────────────> │                    │
          │                      │                       │                    │
          │                      │   3. opens embed_url; editor loads values  │
          │                      │                       │ <──────────────────│
          │                      │                       │                    │
          │                      │  4. reviews, edits if needed, then submits │

   ───────────>  API call (identifiers + links only, no field values)
   ───────────────────────────────────────────>  Direct upload / download (bypasses SimplePDF)

Comme les valeurs sont écrites directement dans votre stockage, les valeurs des champs n'atteignent jamais SimplePDF. L'API ne manipule jamais que des identifiants et des liens.

Avant de commencer

Pour suivre ce guide, vous avez besoin de :

• Une clé API. Créez-en une dans les paramètres de votre compte, sous les intégrations. L'API de pré-remplissage nécessite un forfait avec accès à l'API : Pro ou Premium.
• Votre propre stockage configuré (S3, Azure Blob Storage ou SharePoint). Consultez utiliser votre propre bucket S3, Azure Blob Storage, Scaleway Object Storage, ou SharePoint.
• Un document avec des champs configurés dans votre tableau de bord.

Les exemples ci-dessous utilisent curl ; remplacez $COMPANY par l'identifiant de votre entreprise et $API_KEY par votre clé API.

Étape 1 : Lister les champs que vous pouvez pré-remplir

Demandez au document quels champs existent et ce qu'ils acceptent. Chaque champ possède un id stable que vous référencerez dans le pré-remplissage, un type, et (pour les champs contraints) les options autorisées.

curl https://$COMPANY.simplepdf.com/api/v1/documents/$DOCUMENT_ID/fields \
  -H "Authorization: Bearer $API_KEY"

# Response
{
  "data": [
    { "id": "f_abc1455", "name": "first_name", "type": "text", "options": null },
    { "id": "f_9k2m7d3q", "name": "plan", "type": "checkbox", "options": ["checked", "xchecked", "unchecked"] },
    { "id": "f_5t8w0r6z", "name": "logo", "type": "picture", "options": null }
  ]
}

Le name d'un champ, ainsi que le fait qu'il soit required, qu'il ait une default_value ou qu'il soit read_only, sont configurés depuis votre tableau de bord. Consultez configurer les champs d'un document. Les champs en lecture seule conservent leur valeur configurée et ignorent tout ce que vous envoyez dans le pré-remplissage.

Étape 2 : Créer un pré-remplissage

Créez le pré-remplissage pour récupérer deux choses : un objet upload qui vous indique exactement où et comment envoyer les valeurs, et une embed_url que le destinataire ouvrira.

curl -X POST https://$COMPANY.simplepdf.com/api/v1/documents/$DOCUMENT_ID/prefills \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "context": { "agent": "intake-bot", "user_id": "u_123" } }'

# Response
{
  "id": "05666d45-96d0-42ce-b24b-f1f1af228f57",
  "upload": { "type": "presigned_put", "url": "https://your-storage/...", "method": "PUT", "headers": { "Content-Type": "application/json" } },
  "embed_url": "https://$COMPANY.simplepdf.com/documents/$DOCUMENT_ID?prefill=05666d45-..."
}

Le context optionnel est une métadonnée de corrélation (par exemple, quel agent a produit le pré-remplissage). Il est transmis avec la soumission afin que vous puissiez la rattacher à vos propres enregistrements. Gardez-le exempt de données sensibles : les valeurs des champs elles-mêmes vont dans le blob, jamais ici.

Étape 3 : Téléverser les valeurs du pré-remplissage vers votre stockage

Envoyez un blob JSON de la forme { "fields": [{ "id", "value" }] } en utilisant l'objet upload de l'étape précédente. Chaque id provient de l'étape 1 ; chaque value est une chaîne pour les champs de texte et les cases à cocher, ou une data URL en base64 pour les champs de signature et d'image.

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      { "id": "f_abc1455", "value": "Bob" },
      { "id": "f_9k2m7d3q", "value": "checked" },
      { "id": "f_5t8w0r6z", "value": "data:image/png;base64,iVBORw0KGgo..." }
    ]
  }'

Remarques sur les valeurs :

• Si le champ liste des options (dans GET /fields), la valeur doit être l'une de ces options. Cela concerne les cases à cocher, les listes déroulantes et les boutons radio.
• Sinon, la valeur est une chaîne simple (champs de texte) ou une data URL en base64 telle que data:image/png;base64,... (champs de signature et d'image). Les signatures rendent mieux sous forme de PNG transparent dans un rapport d'environ 3:1 (par exemple 1200x400).
• Les id inconnus sont ignorés, et les champs que le document marque comme en lecture seule conservent leur valeur existante.

Si le upload.type est presigned_post (téléversement de formulaire S3), envoyez les fields listés en tant que données de formulaire multipart au lieu d'un corps PUT ; pour graph_upload_session (SharePoint), définissez également Content-Length et Content-Range sur la taille en octets du blob.

Étape 4 : Envoyer le lien pour relecture

Partagez l'embed_url avec la personne qui doit relire et envoyer. Elle ouvre un document déjà rempli, apporte des corrections et l'envoie. Vous pouvez l'ouvrir en autonome ou l'intégrer dans votre propre application.

Pour être averti lorsqu'elle envoie, configurez un webhook : l'événement de soumission inclut le context que vous avez défini à l'étape 2.

Garder les pré-remplissages bien rangés

Les pré-remplissages sont conservés jusqu'à ce que vous les supprimiez, afin que vous puissiez repartager ou auditer un lien. Supprimez-en un lorsque vous n'en avez plus besoin :

curl -X DELETE https://$COMPANY.simplepdf.com/api/v1/documents/$DOCUMENT_ID/prefills/$PREFILL_ID \
  -H "Authorization: Bearer $API_KEY"

La création et la suppression de pré-remplissages sont enregistrées dans vos journaux d'audit.

C'est tout ! Votre agent peut désormais pré-remplir un PDF, et une personne le relit et l'envoie en gardant un humain dans la boucle.

Si vous avez des questions, n'hésitez pas à contacter support@simplepdf.com