Cómo prerellenar formularios PDF con agentes de IA con SimplePDF

Benjamin André-Micolon

Un agente de IA puede leer el correo de un cliente, una fila de una base de datos o un envío anterior y determinar qué corresponde a cada campo de un formulario. Lo que un agente no debería hacer es enviar un formulario por su cuenta. La API de prerelleno permite que tu agente prepare un PDF completamente rellenado y se lo entregue a una persona para que lo revise, lo corrija y lo envíe: el agente se encarga de la parte tediosa, y una persona se mantiene involucrada en la decisión que importa.

Esto mantiene altas las tasas de finalización, el destinatario abre un documento que ya está listo y no un formulario en blanco, a la vez que mantiene a una persona responsable de lo que se envía.

Esta guía habla de un agente de IA, pero la API de prerelleno no es más que una API HTTP (REST). Cualquier sistema capaz de realizar una solicitud HTTP puede usarla: un agente de IA, una tarea de backend, una automatización de flujo de trabajo o una integración con un CRM. Consulta la documentación de la API para una referencia legible, o la especificación OpenAPI para importarla en tus herramientas o generar un cliente. Ambas documentan cada endpoint y cada campo.

Cómo funciona

Un prerelleno es un conjunto de valores de campos que reside en tu propio almacenamiento (S3, Azure Blob Storage o SharePoint), nunca en SimplePDF. Creas un prerelleno mediante la API, subes los valores directamente a tu almacenamiento y compartes un enlace. Cuando el destinatario abre el enlace, el editor lee los valores desde tu almacenamiento y muestra el documento rellenado para su revisión.

    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 los valores se escriben directamente en tu almacenamiento, los valores de los campos nunca llegan a SimplePDF. La API solo maneja identificadores y enlaces.

Antes de empezar

Para seguir esta guía necesitas:

• Una clave API. Crea una en la configuración de tu cuenta, en la sección de integraciones. La API de prerelleno requiere un plan con acceso a la API: Pro o Premium.
• Tu propio almacenamiento configurado (S3, Azure Blob Storage o SharePoint). Consulta usar tu propio bucket de S3, Azure Blob Storage, Scaleway Object Storage o SharePoint.
• Un documento con campos configurados en tu panel.

Los ejemplos siguientes usan curl; reemplaza $COMPANY por el identificador de tu empresa y $API_KEY por tu clave API.

Paso 1: Listar los campos que puedes prerellenar

Pregunta al documento qué campos existen y qué aceptan. Cada campo tiene un id estable que referenciarás en el prerelleno, un type y (para los campos restringidos) las 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 }
  ]
}

El name de un campo, así como si es required, tiene un default_value o es read_only, se configuran desde tu panel. Consulta configurar los campos de un documento. Los campos de solo lectura conservan su valor configurado e ignoran cualquier cosa que envíes en el prerelleno.

Paso 2: Crear un prerelleno

Crea el prerelleno para obtener dos cosas: un objeto upload que te indica exactamente dónde y cómo enviar los valores, y una embed_url que el destinatario 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-..."
}

El context opcional son metadatos de correlación (por ejemplo, qué agente produjo el prerelleno). Se entrega junto con el envío para que puedas vincularlo a tus propios registros. Mantenlo libre de datos sensibles: los valores de los campos van en el blob, nunca aquí.

Paso 3: Subir los valores del prerelleno a tu almacenamiento

Envía un blob JSON con la forma { "fields": [{ "id", "value" }] } usando el objeto upload del paso anterior. Cada id proviene del paso 1; cada value es una cadena para los campos de texto y de casilla de verificación, o una data URL en base64 para los campos de firma e imagen.

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 los valores:

• Si el campo lista options (en GET /fields), el valor debe ser una de esas opciones. Esto abarca casillas de verificación, listas desplegables y botones de opción.
• De lo contrario, el valor es una cadena simple (campos de texto) o una data URL en base64 como data:image/png;base64,... (campos de firma e imagen). Las firmas se ven mejor como un PNG transparente con una relación de aspecto de aproximadamente 3:1 (por ejemplo, 1200x400).
• Los id desconocidos se ignoran, y los campos que el documento marca como de solo lectura conservan su valor existente.

Si el upload.type es presigned_post (subida mediante formulario de S3), envía los fields indicados como datos de formulario multipart en lugar de un cuerpo PUT; para graph_upload_session (SharePoint), establece además Content-Length y Content-Range con la longitud en bytes del blob.

Paso 4: Enviar el enlace para su revisión

Comparte la embed_url con la persona que debe revisar y enviar. Abre un documento que ya está rellenado, hace las correcciones necesarias y lo envía. Puedes abrirlo de forma independiente o incrustarlo en tu propia aplicación.

Para recibir una notificación cuando lo envíe, configura un webhook: el evento de envío incluye el context que estableciste en el paso 2.

Mantener los prerellenos ordenados

Los prerellenos se conservan hasta que los elimines, de modo que puedes volver a compartir o auditar un enlace. Elimina uno cuando ya no lo necesites:

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

La creación y la eliminación de prerellenos quedan registradas en tus registros de auditoría.

¡Eso es todo! Tu agente ya puede prerellenar un PDF, y una persona lo revisa y lo envía manteniendo a un humano en el proceso.

Si tienes alguna pregunta, no dudes en escribir a support@simplepdf.com