PDF-Formulare mit KI-Agenten vorausfüllen mit SimplePDF
Ein KI-Agent kann eine Kunden-E-Mail, eine Datenbankzeile oder eine frühere Einreichung lesen und ermitteln, was in ein Formular gehört. Was ein Agent nicht tun sollte, ist ein Formular eigenständig einzureichen. Mit der Vorausfüll-API kann Ihr Agent ein vollständig ausgefülltes PDF vorbereiten und es einer Person zur Prüfung, Korrektur und Einreichung übergeben: Der Agent übernimmt den mühsamen Teil, ein Mensch bleibt für die entscheidende Entscheidung eingebunden.
So bleiben die Abschlussquoten hoch, die empfangende Person öffnet ein bereits ausgefülltes Dokument und kein leeres Formular, während ein Mensch für das verantwortlich bleibt, was eingereicht wird.
Dieser Leitfaden spricht von einem KI-Agenten, aber die Vorausfüll-API ist lediglich eine HTTP-(REST-)API. Jedes System, das eine HTTP-Anfrage senden kann, kann sie nutzen: ein KI-Agent, ein Backend-Job, eine Workflow-Automatisierung oder eine CRM-Integration. Sehen Sie sich die API-Dokumentation für eine lesbare Referenz an oder die OpenAPI-Spezifikation, um sie in Ihre Tools zu importieren oder einen Client zu generieren. Beide dokumentieren jeden Endpunkt und jedes Feld.
#Stattdessen über MCP verbinden
Wenn Ihr Agent das Model Context Protocol spricht, können Sie sich die reinen HTTP-Aufrufe sparen: SimplePDF stellt dieselben Vorgänge als entfernten MCP-Server unter https://simplepdf.com/mcp bereit (streamable HTTP; Sie melden sich an und wählen das Unternehmen, das die Verbindung verwendet). Headless-Agenten, die sich mit einem API-Schlüssel authentifizieren, verwenden die eigene URL Ihres Unternehmens, https://$COMPANY.simplepdf.com/mcp. Zu jedem Schritt in diesem Leitfaden gibt es ein passendes Tool (list_documents, list_fields, create_prefill, ...), dazu einen prefill-a-form-Prompt und eine Ressource mit einer Ablaufbeschreibung, die der Agent selbstständig lesen kann. Nur das Hochladen des Blobs in Schritt 3 bleibt ein einfaches HTTP PUT, und der Server liefert dem Agenten dafür fertige Befehle.
Zum Verbinden ist kein Code nötig. Fügen Sie SimplePDF so hinzu, wie Sie jeden anderen Connector hinzufügen, und melden Sie sich anschließend bei Aufforderung mit Ihrem SimplePDF-Konto an (Google inklusive):
- Claude (claude.ai oder Claude Desktop): Öffnen Sie Settings → Connectors, fügen Sie einen benutzerdefinierten Connector hinzu und fügen Sie die obige URL ein.
- ChatGPT: Öffnen Sie Settings → Connectors und fügen Sie die URL hinzu (in ChatGPT-Tarifen, die Connectors unterstützen).
- VS Code (1.106 oder neuer): Führen Sie MCP: Add Server aus, wählen Sie HTTP und fügen Sie die obige URL ein.
Mit der Anmeldung autorisieren Sie die Verbindung in Ihrem eigenen Namen: Aktionen werden Ihnen in den Audit-Protokollen zugeordnet, und Sie müssen Mitglied des Arbeitsbereichs sein. Jede App ist jeweils mit einem Unternehmen verbunden: Wenn Sie sie erneut mit einem anderen Unternehmen autorisieren, wechselt die Verbindung dorthin.
Clients, die sich nicht auf diese Weise anmelden können (Cursor, Gemini CLI, Le Chat, Microsoft Copilot Studio, Perplexity), verbinden sich stattdessen mit einem API-Schlüssel: Konfigurieren Sie sie mit der eigenen URL Ihres Unternehmens, https://$COMPANY.simplepdf.com/mcp, und dem Header Authorization: Bearer $API_KEY (derselbe Schlüssel, den dieser Leitfaden verwendet). Diese URL akzeptiert ausschließlich API-Schlüssel, was sich auch für Headless- oder gemeinsam genutzte Agenten eignet. Mit einem Schlüssel ausgeführte Aktionen werden in den Audit-Protokollen dem Schlüssel zugeordnet.
# 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"Der MCP-Server und die weiter unten beschriebene Vorausfüll-API über einfaches HTTP erfordern den Premium-Tarif. In beiden Fällen setzt das Vorausfüllen voraus, dass Ihr eigener Speicher konfiguriert ist. Der Rest dieses Leitfadens folgt dem einfachen HTTP-Weg.
#So funktioniert es
Eine Vorausfüllung ist ein Satz von Feldwerten, der in Ihrem eigenen Speicher liegt (S3, Azure Blob Storage oder SharePoint), niemals bei SimplePDF. Sie erstellen eine Vorausfüllung über die API, laden die Werte direkt in Ihren Speicher hoch und teilen einen Link. Wenn die empfangende Person den Link öffnet, liest der Editor die Werte aus Ihrem Speicher und zeigt das ausgefüllte Dokument zur Prüfung an.
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)Da die Werte direkt in Ihren Speicher geschrieben werden, erreichen die Feldwerte niemals SimplePDF. Die API verarbeitet ausschließlich Bezeichner und Links.
#Bevor Sie beginnen
Um diesem Leitfaden zu folgen, benötigen Sie:
- Einen API-Schlüssel. Erstellen Sie einen in Ihren Kontoeinstellungen unter Integrationen. Die Vorausfüll-API erfordert einen Tarif mit API-Zugriff: Premium.
- Ihren eigenen Speicher konfiguriert (S3, Azure Blob Storage oder SharePoint). Sehen Sie sich Ihren eigenen S3-Bucket verwenden, Azure Blob Storage, Scaleway Object Storage oder SharePoint an.
- Ein Dokument mit in Ihrem Dashboard konfigurierten Feldern.
Die folgenden Beispiele verwenden curl; ersetzen Sie $COMPANY durch Ihren Unternehmensbezeichner und $API_KEY durch Ihren API-Schlüssel.
#Schritt 1: Die Felder auflisten, die Sie vorausfüllen können
Fragen Sie das Dokument ab, welche Felder existieren und was sie akzeptieren. Jedes Feld hat eine stabile id, auf die Sie in der Vorausfüllung verweisen, einen type und (bei eingeschränkten Feldern) die zulässigen options.
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 }
]
}Der name eines Feldes sowie ob es required ist, einen default_value hat oder read_only ist, werden über Ihr Dashboard konfiguriert. Sehen Sie sich Dokumentfelder konfigurieren an. Schreibgeschützte Felder ignorieren alles, was Sie in der Vorausfüllung senden.
#Schritt 2: Eine Vorausfüllung erstellen
Erstellen Sie die Vorausfüllung, um zwei Dinge zurückzubekommen: ein upload-Objekt, das Ihnen genau mitteilt, wohin und wie Sie die Werte senden, und eine embed_url, die die empfangende Person öffnet.
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-..."
}Der optionale context ist Korrelations-Metadaten (zum Beispiel, welcher Agent die Vorausfüllung erzeugt hat). Er wird mit der Einreichung übermittelt, damit Sie sie Ihren eigenen Datensätzen zuordnen können. Halten Sie ihn frei von sensiblen Daten: Die Feldwerte selbst kommen in den Blob, niemals hierher.
#Schritt 3: Die Vorausfüllwerte in Ihren Speicher hochladen
Senden Sie einen JSON-Blob der Form { "fields": [{ "id", "value" }] } mit dem upload-Objekt aus dem vorherigen Schritt. Jede id stammt aus Schritt 1; jeder value ist eine Zeichenkette für Text- und Kontrollkästchenfelder oder eine Base64-Daten-URL für Signatur- und Bildfelder.
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..." }
]
}'Hinweise zu den Werten:
- Wenn das Feld
optionsauflistet (inGET /fields), muss der Wert eine dieser Optionen sein. Dies betrifft Kontrollkästchen, Dropdowns und Optionsfelder. - Andernfalls ist der Wert eine einfache Zeichenkette (Textfelder) oder eine Base64-Daten-URL wie
data:image/png;base64,...(Signatur- und Bildfelder). Signaturen sehen am besten als transparentes PNG in einem Seitenverhältnis von etwa 3:1 aus (zum Beispiel 1200x400). - Unbekannte IDs werden ignoriert, und Felder, die das Dokument als schreibgeschützt markiert, ignorieren die Werte der Vorausfüllung.
Wenn der upload.type graph_upload_session ist (SharePoint), setzen Sie außerdem Content-Length und Content-Range auf die Byte-Länge des Blobs.
#Schritt 4: Den Link zur Prüfung senden
Teilen Sie die embed_url mit der Person, die prüfen und einreichen soll. Sie öffnet ein bereits ausgefülltes Dokument, nimmt etwaige Korrekturen vor und reicht es ein. Sie können es eigenständig öffnen oder in Ihre eigene App einbetten.
Um benachrichtigt zu werden, wenn eingereicht wird, konfigurieren Sie einen Webhook: Das Einreichungsereignis enthält den context, den Sie in Schritt 2 festgelegt haben.
#Vorausfüllungen ordentlich halten
Vorausfüllungen werden aufbewahrt, bis Sie sie entfernen, sodass Sie einen Link erneut teilen oder prüfen können. Löschen Sie eine, wenn Sie sie nicht mehr benötigen:
curl -X DELETE https://$COMPANY.simplepdf.com/api/v1/documents/$DOCUMENT_ID/prefills/$PREFILL_ID \
-H "Authorization: Bearer $API_KEY"Das Erstellen und Löschen von Vorausfüllungen wird in Ihren Audit-Protokollen festgehalten.
Das war's! Ihr Agent kann nun ein PDF vorausfüllen, und eine Person prüft und reicht es ein, wobei ein Mensch eingebunden bleibt.
Wenn Sie Fragen haben, wenden Sie sich gerne an support@simplepdf.com