Como pré-preencher formulários PDF com agentes de IA com o SimplePDF

Benjamin André-Micolon

Um agente de IA pode ler o e-mail de um cliente, uma linha de uma base de dados ou uma submissão anterior e determinar o que pertence a cada campo de um formulário. O que um agente não deve fazer é submeter um formulário por conta própria. A API de pré-preenchimento permite que o seu agente prepare um PDF totalmente preenchido e o entregue a uma pessoa para que o reveja, corrija e submeta: o agente trata da parte tediosa, e uma pessoa mantém-se envolvida na decisão que importa.

Assim, as taxas de conclusão mantêm-se elevadas, o destinatário abre um documento que já está pronto e não um formulário em branco, ao mesmo tempo que uma pessoa continua responsável pelo que é submetido.

Este guia fala de um agente de IA, mas a API de pré-preenchimento é apenas uma API HTTP (REST). Qualquer sistema capaz de fazer um pedido HTTP pode usá-la: um agente de IA, uma tarefa de backend, uma automatização de fluxo de trabalho ou uma integração com um CRM. Consulte a documentação da API para uma referência legível, ou a especificação OpenAPI para importar nas suas ferramentas ou gerar um cliente. Ambas documentam cada endpoint e cada campo.

Como funciona

Um pré-preenchimento é um conjunto de valores de campos que reside no seu próprio armazenamento (S3, Azure Blob Storage ou SharePoint), nunca no SimplePDF. Cria um pré-preenchimento através da API, carrega os valores diretamente para o seu armazenamento e partilha uma ligação. Quando o destinatário abre a ligação, o editor lê os valores a partir do seu armazenamento e apresenta o documento preenchido para revisão.

    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)

Como os valores são escritos diretamente no seu armazenamento, os valores dos campos nunca chegam ao SimplePDF. A API só manipula identificadores e ligações.

Antes de começar

Para seguir este guia, precisa de:

• Uma chave de API. Crie uma nas definições da sua conta, na secção de integrações. A API de pré-preenchimento requer um plano com acesso à API: Pro ou Premium.
• O seu próprio armazenamento configurado (S3, Azure Blob Storage ou SharePoint). Consulte usar o seu próprio bucket S3, Azure Blob Storage, Scaleway Object Storage ou SharePoint.
• Um documento com campos configurados no seu painel.

Os exemplos abaixo usam curl; substitua $COMPANY pelo identificador da sua empresa e $API_KEY pela sua chave de API.

Passo 1: Listar os campos que pode pré-preencher

Pergunte ao documento que campos existem e o que aceitam. Cada campo tem um id estável que irá referenciar no pré-preenchimento, um type e (para campos restritos) as options permitidas.

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

O name de um campo, bem como o facto de ser required, ter um default_value ou ser read_only, são configurados a partir do seu painel. Consulte configurar os campos de um documento. Os campos só de leitura mantêm o seu valor configurado e ignoram tudo o que enviar no pré-preenchimento.

Passo 2: Criar um pré-preenchimento

Crie o pré-preenchimento para receber duas coisas: um objeto upload que lhe indica exatamente onde e como enviar os valores, e uma embed_url que o destinatário irá abrir.

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

O context opcional são metadados de correlação (por exemplo, que agente produziu o pré-preenchimento). É entregue com a submissão para que a possa associar aos seus próprios registos. Mantenha-o livre de dados sensíveis: os valores dos campos vão no blob, nunca aqui.

Passo 3: Carregar os valores do pré-preenchimento para o seu armazenamento

Envie um blob JSON com a forma { "fields": [{ "id", "value" }] } usando o objeto upload do passo anterior. Cada id vem do passo 1; cada value é uma cadeia de texto para campos de texto e de caixa de verificação, ou um data URL em base64 para campos de assinatura e de imagem.

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

Notas sobre os valores:

• Se o campo listar options (em GET /fields), o valor deve ser uma dessas opções. Isto abrange caixas de verificação, listas pendentes e botões de opção.
• Caso contrário, o valor é uma cadeia de texto simples (campos de texto) ou um data URL em base64 como data:image/png;base64,... (campos de assinatura e de imagem). As assinaturas ficam melhor como um PNG transparente com uma proporção de cerca de 3:1 (por exemplo, 1200x400).
• Os id desconhecidos são ignorados, e os campos que o documento marca como só de leitura mantêm o seu valor existente.

Se o upload.type for presigned_post (carregamento por formulário S3), envie os fields indicados como dados de formulário multipart em vez de um corpo PUT; para graph_upload_session (SharePoint), defina também Content-Length e Content-Range com o comprimento em bytes do blob.

Passo 4: Enviar a ligação para revisão

Partilhe a embed_url com a pessoa que deve rever e submeter. Abre um documento que já está preenchido, faz quaisquer correções e submete-o. Pode abri-lo de forma autónoma ou incorporá-lo na sua própria aplicação.

Para ser notificado quando submeter, configure um webhook: o evento de submissão inclui o context que definiu no passo 2.

Manter os pré-preenchimentos organizados

Os pré-preenchimentos são mantidos até os remover, para que possa voltar a partilhar ou auditar uma ligação. Elimine um quando já não precisar dele:

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

A criação e a eliminação de pré-preenchimentos são registadas nos seus registos de auditoria.

É tudo! O seu agente pode agora pré-preencher um PDF, e uma pessoa revê-o e submete-o, mantendo uma pessoa no processo.

Se tiver alguma questão, não hesite em contactar support@simplepdf.com