Comment pré-remplir des formulaires PDF avec des agents IA avec SimplePDF
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.
#Se connecter via MCP à la place
Si votre agent parle le Model Context Protocol, vous pouvez vous passer des appels HTTP bruts : SimplePDF expose les mêmes opérations sous la forme d'un serveur MCP distant à l'adresse https://$COMPANY.simplepdf.com/mcp (streamable HTTP). Chaque étape de ce guide dispose d'un outil correspondant (list_documents, list_fields, create_prefill, ...), auxquels s'ajoutent un prompt prefill-a-form et une ressource décrivant le déroulement, que l'agent peut consulter de lui-même. Seul le téléversement du blob à l'étape 3 reste un simple HTTP PUT, et le serveur fournit à l'agent les commandes prêtes à l'emploi pour le faire.
Aucun code n'est nécessaire pour se connecter. Ajoutez SimplePDF comme vous ajoutez n'importe quel autre connecteur, puis connectez-vous avec votre compte SimplePDF (Google inclus) lorsque cela vous est demandé :
- Claude (claude.ai ou Claude Desktop) : ouvrez Settings → Connectors, ajoutez un connecteur personnalisé et collez l'URL ci-dessus.
- ChatGPT : ouvrez Settings → Connectors et ajoutez l'URL (sur les forfaits ChatGPT qui prennent en charge les connecteurs).
- Cursor et les autres clients MCP : collez l'URL dans les paramètres MCP du client.
La connexion autorise l'accès en votre nom : les actions vous sont attribuées dans les journaux d'audit, et vous devez être membre de l'espace de travail. Vous préférez une clé ? Configurez plutôt le client avec l'en-tête Authorization: Bearer $API_KEY (la même clé que celle utilisée dans ce guide), ce qui convient aux agents headless ou partagés.
claude mcp add --transport http simplepdf https://$COMPANY.simplepdf.com/mcp \
--header "Authorization: Bearer $API_KEY"
# Or without the header to sign in via OAuth insteadLe serveur MCP nécessite le même forfait que l'API : Premium. La suite de ce guide suit la voie HTTP simple.
#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 : 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 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(dansGET /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
idinconnus sont ignorés, et les champs que le document marque comme en lecture seule ignorent les valeurs de pré-remplissage.
Si le upload.type est 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