Come precompilare moduli PDF con agenti IA con SimplePDF
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.
#Collegarsi tramite MCP in alternativa
Se il tuo agente parla il Model Context Protocol, puoi evitare le chiamate HTTP dirette: SimplePDF espone le stesse operazioni come server MCP remoto all'indirizzo https://simplepdf.com/mcp (streamable HTTP; accedi e scegli l'azienda che la connessione utilizza). Gli agenti headless che si autenticano con una chiave API usano l'URL della tua azienda, https://$COMPANY.simplepdf.com/mcp. Ogni passaggio di questa guida ha uno strumento corrispondente (list_documents, list_fields, create_prefill, ...), oltre a un prompt prefill-a-form e a una risorsa con la guida al flusso di lavoro che l'agente può leggere da solo. Solo il caricamento del blob al passaggio 3 resta un semplice HTTP PUT, e il server fornisce all'agente i comandi pronti all'uso.
Per collegarlo non serve scrivere codice. Aggiungi SimplePDF come aggiungeresti qualsiasi altro connettore, poi accedi con il tuo account SimplePDF (Google incluso) quando ti viene richiesto:
- Claude (claude.ai o Claude Desktop): apri Settings → Connectors, aggiungi un connettore personalizzato e incolla l'URL qui sopra.
- ChatGPT: apri Settings → Connectors e aggiungi l'URL (sui piani ChatGPT che supportano i connettori).
- VS Code (1.106 o successiva): esegui MCP: Add Server, scegli HTTP e incolla l'URL qui sopra.
L'accesso autorizza il collegamento a tuo nome: le azioni vengono attribuite a te nei registri di audit e devi essere membro dello spazio di lavoro. Ogni app si collega a una sola azienda alla volta: se la autorizzi di nuovo con un'altra azienda, il collegamento si sposta su quest'ultima.
I client che non possono accedere in questo modo (Cursor, Gemini CLI, Le Chat, Microsoft Copilot Studio, Perplexity) si collegano invece con una chiave API: configurali con l'URL della tua azienda, https://$COMPANY.simplepdf.com/mcp, e l'header Authorization: Bearer $API_KEY (la stessa chiave usata in questa guida). Questo URL accetta solo chiavi API, soluzione adatta anche ad agenti headless o condivisi. Le azioni eseguite con una chiave vengono attribuite alla chiave nei registri di audit.
# Sign in through OAuth when prompted and choose the organization
claude mcp add --transport http simplepdf https://simplepdf.com/mcp
# Headless agents with an API key: your organization's own URL
claude mcp add --transport http simplepdf https://$COMPANY.simplepdf.com/mcp \
--header "Authorization: Bearer $API_KEY"Il server MCP e l'API di precompilazione in HTTP semplice descritta qui sotto richiedono il piano Premium. In entrambi i casi, la precompilazione richiede che il tuo storage sia configurato. Il resto di questa guida segue il percorso HTTP semplice.
#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: 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 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(inGET /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 ignorano i valori della precompilazione.
Se l'upload.type è 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