Come precompilare moduli PDF con agenti IA con SimplePDF

Benjamin André-Micolon

Un agente IA può leggere l'e-mail di un cliente, una riga di un database o un invio precedente e capire cosa va inserito in un modulo. Ciò che un agente non dovrebbe fare è inviare un modulo da solo. L'API di precompilazione consente al tuo agente di preparare un PDF completamente compilato e di consegnarlo a una persona affinché lo riveda, lo corregga e lo invii: l'agente svolge la parte noiosa, una persona resta coinvolta per la decisione che conta.

In questo modo i tassi di completamento restano alti, il destinatario apre un documento già pronto e non un modulo vuoto, mentre una persona rimane responsabile di ciò che viene inviato.

Questa guida parla di un agente IA, ma l'API di precompilazione è semplicemente un'API HTTP (REST). Qualsiasi sistema in grado di effettuare una richiesta HTTP può utilizzarla: un agente IA, un job di backend, un'automazione di un flusso di lavoro o un'integrazione CRM. Consulta la documentazione dell'API per un riferimento leggibile, oppure la specifica OpenAPI da importare nei tuoi strumenti o per generare un client. Entrambe documentano ogni endpoint e ogni campo.

Come funziona

Una precompilazione è un insieme di valori di campi che risiede nel tuo archivio (S3, Azure Blob Storage o SharePoint), mai su SimplePDF. Crei una precompilazione tramite l'API, carichi i valori direttamente nel tuo archivio e condividi un link. Quando il destinatario apre il link, l'editor legge i valori dal tuo archivio e mostra il documento compilato per la revisione.

    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)

Poiché i valori vengono scritti direttamente nel tuo archivio, i valori dei campi non raggiungono mai SimplePDF. L'API gestisce esclusivamente identificatori e link.

Prima di iniziare

Per seguire questa guida ti serve:

• Una chiave API. Creane una nelle impostazioni del tuo account, nella sezione integrazioni. L'API di precompilazione richiede un piano con accesso all'API: Pro o Premium.
• Il tuo archivio configurato (S3, Azure Blob Storage o SharePoint). Consulta usare il tuo bucket S3, Azure Blob Storage, Scaleway Object Storage o SharePoint.
• Un documento con i campi configurati nella tua dashboard.

Gli esempi seguenti usano curl; sostituisci $COMPANY con l'identificatore della tua azienda e $API_KEY con la tua chiave API.

Passaggio 1: Elencare i campi che puoi precompilare

Chiedi al documento quali campi esistono e cosa accettano. Ogni campo ha un id stabile a cui farai riferimento nella precompilazione, un type e (per i campi vincolati) le options consentite.

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 }
  ]
}

Il name di un campo, così come il fatto che sia required, abbia un default_value o sia read_only, vengono configurati dalla tua dashboard. Consulta configurare i campi di un documento. I campi di sola lettura mantengono il valore configurato e ignorano qualsiasi cosa tu invii nella precompilazione.

Passaggio 2: Creare una precompilazione

Crea la precompilazione per ottenere due cose: un oggetto upload che ti indica esattamente dove e come inviare i valori, e una embed_url che il destinatario aprirà.

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-..."
}

Il context opzionale è un metadato di correlazione (ad esempio quale agente ha prodotto la precompilazione). Viene consegnato insieme all'invio così da poterlo ricollegare ai tuoi registri. Tienilo privo di dati sensibili: i valori dei campi vanno nel blob, mai qui.

Passaggio 3: Caricare i valori della precompilazione nel tuo archivio

Invia un blob JSON della forma { "fields": [{ "id", "value" }] } usando l'oggetto upload del passaggio precedente. Ogni id proviene dal passaggio 1; ogni value è una stringa per i campi di testo e le caselle di controllo, oppure una data URL in base64 per i campi di firma e immagine.

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..." }
    ]
  }'

Note sui valori:

• Se il campo elenca delle options (in GET /fields), il valore deve essere una di quelle opzioni. Questo riguarda caselle di controllo, menu a tendina e pulsanti di opzione.
• Altrimenti, il valore è una semplice stringa (campi di testo) o una data URL in base64 come data:image/png;base64,... (campi di firma e immagine). Le firme rendono al meglio come PNG trasparente con un rapporto d'aspetto di circa 3:1 (ad esempio 1200x400).
• Gli id sconosciuti vengono ignorati, e i campi che il documento contrassegna come di sola lettura mantengono il loro valore esistente.

Se l'upload.type è presigned_post (caricamento tramite modulo S3), invia i fields elencati come dati di modulo multipart anziché come corpo PUT; per graph_upload_session (SharePoint), imposta anche Content-Length e Content-Range sulla lunghezza in byte del blob.

Passaggio 4: Inviare il link per la revisione

Condividi l'embed_url con la persona che deve rivedere e inviare. Apre un documento già compilato, apporta le eventuali correzioni e lo invia. Puoi aprirlo in modo autonomo oppure incorporarlo nella tua app.

Per ricevere una notifica quando invia, configura un webhook: l'evento di invio include il context che hai impostato al passaggio 2.

Mantenere ordinate le precompilazioni

Le precompilazioni vengono conservate finché non le rimuovi, così puoi ricondividere o controllare un link. Eliminane una quando non ti serve più:

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

La creazione e l'eliminazione delle precompilazioni vengono registrate nei tuoi registri di audit.

Ecco fatto! Il tuo agente può ora precompilare un PDF, e una persona lo rivede e lo invia mantenendo un essere umano nel processo.

Se hai domande, non esitare a contattare support@simplepdf.com