PDF-formulieren voorinvullen met AI-agents met SimplePDF

Benjamin André-Micolon

Een AI-agent kan een klant-e-mail, een databaserij of een eerdere inzending lezen en bepalen wat in een formulier hoort. Wat een agent niet zou moeten doen, is een formulier op eigen houtje indienen. Met de voorinvul-API kan uw agent een volledig ingevuld PDF voorbereiden en het overhandigen aan een persoon om het te controleren, te corrigeren en in te dienen: de agent doet het saaie werk, een mens blijft betrokken bij de beslissing die ertoe doet.

Zo blijven de voltooiingspercentages hoog, de ontvanger opent een document dat al klaar is en geen leeg formulier, terwijl een mens verantwoordelijk blijft voor wat er wordt ingediend.

Deze handleiding gaat over een AI-agent, maar de voorinvul-API is gewoon een HTTP-(REST-)API. Elk systeem dat een HTTP-verzoek kan doen, kan deze gebruiken: een AI-agent, een backendtaak, een workflowautomatisering of een CRM-integratie. Raadpleeg de API-documentatie voor een leesbare referentie, of de OpenAPI-specificatie om in uw tools te importeren of een client te genereren. Beide documenteren elk eindpunt en elk veld.

Hoe het werkt

Een voorinvulling is een set veldwaarden die in uw eigen opslag staat (S3, Azure Blob Storage of SharePoint), nooit bij SimplePDF. U maakt een voorinvulling via de API, uploadt de waarden rechtstreeks naar uw opslag en deelt een link. Wanneer de ontvanger de link opent, leest de editor de waarden uit uw opslag en toont het ingevulde document ter controle.

    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)

Omdat de waarden rechtstreeks naar uw opslag worden geschreven, bereiken de veldwaarden SimplePDF nooit. De API verwerkt uitsluitend identifiers en links.

Voordat u begint

Om deze handleiding te volgen heeft u nodig:

• Een API-sleutel. Maak er een aan in uw accountinstellingen onder integraties. De voorinvul-API vereist een abonnement met API-toegang: Pro of Premium.
• Uw eigen opslag geconfigureerd (S3, Azure Blob Storage of SharePoint). Zie uw eigen S3-bucket gebruiken, Azure Blob Storage, Scaleway Object Storage of SharePoint.
• Een document met velden geconfigureerd in uw dashboard.

De onderstaande voorbeelden gebruiken curl; vervang $COMPANY door de identifier van uw bedrijf en $API_KEY door uw API-sleutel.

Stap 1: De velden vermelden die u kunt voorinvullen

Vraag het document welke velden bestaan en wat ze accepteren. Elk veld heeft een stabiele id waarnaar u in de voorinvulling verwijst, een type en (voor beperkte velden) de toegestane 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 }
  ]
}

De name van een veld, en of het required is, een default_value heeft of read_only is, worden geconfigureerd vanuit uw dashboard. Zie documentvelden configureren. Alleen-lezen velden behouden hun geconfigureerde waarde en negeren alles wat u in de voorinvulling verstuurt.

Stap 2: Een voorinvulling maken

Maak de voorinvulling om twee dingen terug te krijgen: een upload-object dat u precies vertelt waar en hoe u de waarden verstuurt, en een embed_url die de ontvanger opent.

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

De optionele context is correlatiemetadata (bijvoorbeeld welke agent de voorinvulling heeft gemaakt). Deze wordt met de inzending meegeleverd, zodat u die aan uw eigen records kunt koppelen. Houd hem vrij van gevoelige gegevens: de veldwaarden zelf gaan in de blob, nooit hier.

Stap 3: De voorinvulwaarden naar uw opslag uploaden

Verstuur een JSON-blob met de vorm { "fields": [{ "id", "value" }] } met het upload-object uit de vorige stap. Elke id komt uit stap 1; elke value is een tekenreeks voor tekst- en selectievakjevelden, of een base64 data-URL voor handtekening- en afbeeldingsvelden.

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

Opmerkingen over de waarden:

• Als het veld options vermeldt (in GET /fields), moet de waarde een van die opties zijn. Dit geldt voor selectievakjes, vervolgkeuzelijsten en keuzerondjes.
• Anders is de waarde een gewone tekenreeks (tekstvelden) of een base64 data-URL zoals data:image/png;base64,... (handtekening- en afbeeldingsvelden). Handtekeningen zien er het best uit als een transparante PNG met een verhouding van ongeveer 3:1 (bijvoorbeeld 1200x400).
• Onbekende id's worden genegeerd, en velden die het document als alleen-lezen markeert behouden hun bestaande waarde.

Als het upload.type presigned_post is (S3-formulierupload), verstuur dan de vermelde fields als multipart-formuliergegevens in plaats van een PUT-body; voor graph_upload_session (SharePoint) stelt u ook Content-Length en Content-Range in op de bytelengte van de blob.

Stap 4: De link versturen ter controle

Deel de embed_url met de persoon die moet controleren en indienen. Die opent een document dat al is ingevuld, brengt eventuele correcties aan en dient het in. U kunt het zelfstandig openen of in uw eigen app insluiten.

Om een melding te krijgen wanneer er wordt ingediend, configureert u een webhook: de inzendingsgebeurtenis bevat de context die u in stap 2 hebt ingesteld.

Voorinvullingen netjes houden

Voorinvullingen worden bewaard totdat u ze verwijdert, zodat u een link opnieuw kunt delen of controleren. Verwijder er een wanneer u die niet meer nodig heeft:

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

Het aanmaken en verwijderen van voorinvullingen wordt vastgelegd in uw auditlogboeken.

Dat is alles! Uw agent kan nu een PDF voorinvullen, en een persoon controleert en dient het in, met een mens in de lus.

Als u vragen heeft, neem dan gerust contact op met support@simplepdf.com