✦API

Remplir vos documents à distance

Déposez un PDF depuis votre code, laissez l'IA poser ses questions, répondez, récupérez le document rempli. Le même moteur que le site, sans le site.

Votre clé

Une clé s'obtient depuis votre compte, jamais par l'API elle-même. Elle se présente dans l'en-tête Authorization, comme un jeton Bearer.

curl https://plumeai.fr/api/v2/dossiers \
  -H "Authorization: Bearer plume_sk_votre_cle"

Ce qu'une clé peut faire

Chaque clé porte des portées, choisies à sa création. Une clé n'a que les droits que vous lui donnez, et vous pouvez en créer une par usage : lecture seule pour un tableau de bord, écriture pour un automate.

Le parcours

Le contrat v2 suit le même dossier que le site : consentement, documents, personnes, renseignements et exports. Chaque appel exige la portée indiquée ; cumulez lecture, écriture et export pour le parcours complet.

Un exemple complet

Du consentement au document rempli, sans jamais ouvrir de navigateur.

Remplacez PLUME_CLE par votre clé ; CONSENT_ID et DOSSIER_ID proviennent des réponses précédentes. Chaque nouvelle opération reçoit sa propre clé de reprise. L’exemple suppose un consentement accordé et un fichier formulaire.pdf disponible.

curl -X POST https://plumeai.fr/api/v1/consents \
  -H "Authorization: Bearer $PLUME_CLE" \
  -H "Idempotency-Key: consent-001" \
  -H "Content-Type: application/json" \
  -d '{"purpose":"form_fill"}'

curl -X POST https://plumeai.fr/api/v2/dossiers \
  -H "Authorization: Bearer $PLUME_CLE" \
  -H "Idempotency-Key: import-001" \
  -F "file=@formulaire.pdf" \
  -F "consent_id=$CONSENT_ID" \
  -F "include_fill=true" \
  -F "pages_spec=all"

curl https://plumeai.fr/api/v2/dossiers/$DOSSIER_ID/etat \
  -H "Authorization: Bearer $PLUME_CLE"

curl https://plumeai.fr/api/v2/dossiers/$DOSSIER_ID/questions \
  -H "Authorization: Bearer $PLUME_CLE"

curl -X POST https://plumeai.fr/api/v2/dossiers/$DOSSIER_ID/chat \
  -H "Authorization: Bearer $PLUME_CLE" \
  -H "Idempotency-Key: message-001" \
  -H "Content-Type: application/json" \
  -d '{"message":"Mon prénom est Alice. Remplis les champs correspondants."}'

Après la préparation, INSTANTANE reprend instantane. Le POST d’export rend 202 : conservez status_url dans STATUS_URL, puis attendez succeeded avant de reprendre download_url dans DOWNLOAD_URL. Une réponse 202 n’est pas un PDF.

curl https://plumeai.fr/api/v2/dossiers/$DOSSIER_ID/export/preparation \
  -H "Authorization: Bearer $PLUME_CLE"

curl -X POST https://plumeai.fr/api/v2/dossiers/$DOSSIER_ID/export/acroform \
  -H "Authorization: Bearer $PLUME_CLE" \
  -H "Idempotency-Key: export-001" \
  -H "Content-Type: application/json" \
  -d "{\"instantane\":\"$INSTANTANE\"}"

curl "https://plumeai.fr$STATUS_URL" \
  -H "Authorization: Bearer $PLUME_CLE"

curl --fail "https://plumeai.fr$DOWNLOAD_URL" \
  -H "Authorization: Bearer $PLUME_CLE" -OJ

Après une coupure, renvoyez la même requête avec la même clé. OPERATION_RUNNING demande d’attendre ; OPERATION_OUTCOME_UNKNOWN demande de relire conversation et valeurs avant de décider de la suite.

Détecter sans remplir

Utilisez le même dépôt avec include_fill=false. Aucun renseignement personnel n’est requis. Pour relancer, envoyez source_fill_id, analyse_explicite=true et les pages choisies. Ajoutez fills:export à moteur:carte pour télécharger le PDF éditable.

Après une relance complète, POST /conversation/amorcer reprend l’historique enregistré ; PUT /remplacement relie les deux dossiers. Les lectures suivent la nouvelle version (307), les anciennes écritures sont refusées (409) et les exports déjà demandés restent disponibles. Une relance partielle ne remplace pas implicitement tout le document. La réanalyse d’un dossier déjà attribué à plusieurs personnes n’est pas encore disponible.

Webhooks : être prévenu au lieu d'attendre

Sans webhook, il ne vous reste qu'à interroger l'état du dossier en boucle, pour n'apprendre presque jamais rien. Déclarez une adresse et Plume l'appelle une fois, quand le dossier est fini — ou quand il a échoué. L'échec compte autant : sans lui, votre programme attend un document qui ne viendra jamais.

Une adresse se déclare par l'appel ci-dessous, et par lui seul : il n'existe pas d'écran de gestion des webhooks. L'appel s'authentifie avec votre session de connexion — vous devez être owner ou admin de l'espace ; présenté avec une clé d'API, il répond 403. Cinq adresses au maximum par espace.

POST https://plumeai.fr/api/v1/tenants/{espace}/webhooks
{"url": "https://votre-serveur.fr/plume/webhook"}

# → {"id": "whk_…", "secret": "whsec_…"}
# Le secret n'est rendu QU'ICI. Copiez-le : il ne sera plus jamais affiché.

# Un envoi de test, tout de suite, pour valider votre point de terminaison :
POST /api/v1/tenants/{espace}/webhooks/{id}/ping

Ce que votre serveur reçoit :

POST https://votre-serveur.fr/plume/webhook
Content-Type: application/json
X-Plume-Event: fill.done
X-Plume-Timestamp: 2026-08-27T10:00:00+00:00
X-Plume-Delivery: 3f9a1c4e7b20d8a6
X-Plume-Signature: sha256=21e667659d1a7a94…

{"created_at":"2026-08-27T10:00:00+00:00","event":"fill.done",
 "fill_id":"fill_abc","pages":3,"status":"succeeded","tenant_id":"tenant_x"}

# event   : "fill.done" (terminé, même partiellement) ou "fill.failed" ;
#           "fill.share_completed" / "fill.share_declined" : une personne a
#           rempli, ou refusé, la partie confiée par un lien
# status  : succeeded | partial | awaiting_answers | failed
#           (termine | refuse pour un lien)
# pages   : nombre de pages demandées au dépôt, ou null si « all »

Vérifiez toujours la signature avant de traiter l'appel. Sans elle, n'importe qui connaissant votre adresse peut vous annoncer de faux dossiers.

# Les OCTETS BRUTS du corps, jamais un JSON re-sérialisé.
corps    = requête.corps_brut
attendue = "sha256=" + hmac_sha256(clé = votre_secret, message = corps).hex()

si non comparaison_à_temps_constant(attendue, en_tête("X-Plume-Signature")):
    répondre 401 et s'arrêter

# L'horodatage n'entre PAS dans la signature : refusez simplement ce qui est
# plus vieux que quelques minutes.
si maintenant() - date(en_tête("X-Plume-Timestamp")) > 5 minutes:
    répondre 400 et s'arrêter

# fill_id est votre clé d'idempotence : le même dossier peut arriver deux
# fois si notre réseau a coupé après votre réponse.
si déjà_traité(corps.fill_id): répondre 200 et s'arrêter

Seules les adresses https publiques sont acceptées. Une adresse locale ou privée est refusée à l'enregistrement, et de nouveau au moment de l'envoi : un nom de domaine qui pointerait vers un réseau interne ne recevra rien.

Les erreurs

Sécurité

Les documents envoyés par l'API suivent exactement les mêmes règles que ceux déposés sur le site : mêmes durées de conservation, même chiffrement, même fournisseur d'IA. Voir la politique de confidentialité.