PDF-Formulare mit KI-Agenten vorausfüllen mit SimplePDF

Benjamin André-Micolon

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.

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: Pro oder 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 behalten ihren konfigurierten Wert und 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 options auflistet (in GET /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, behalten ihren bestehenden Wert.

Wenn der upload.type presigned_post ist (S3-Formular-Upload), senden Sie die aufgeführten fields als Multipart-Formulardaten anstelle eines PUT-Bodys; für graph_upload_session (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