Leer campos de un formulario PDF

El problema que resuelve

Cualquiera que haya intentado autocompletar un trámite gubernamental, un cuestionario de admisión o la plantilla de contrato de un proveedor conoce el primer obstáculo: no puede llenar campos que no ve. Los nombres de campo suelen ser crípticos, inconsistentes o repetidos dentro del mismo documento, y las herramientas de autoría de PDF rara vez exportan un esquema limpio junto con el archivo. Este endpoint existe para desarrolladores que reciben PDFs de terceros — clientes, agencias, socios — y necesitan descubrir programáticamente la forma del formulario antes de escribir una sola línea de lógica de llenado.

Qué le devuelve

Llama a POST /pdf/form-read y recibe un task_id de inmediato. El resultado enumera cada campo de cada página: su nombre interno, su tipo (texto, casilla, botón de opción, lista de selección o marcador de firma), su valor actual y, cuando existen, las opciones permitidas en listas desplegables y grupos de opciones. Nada se infiere ni se adivina: es una lectura directa de lo que el diccionario AcroForm del documento realmente declara, así que el resultado coincide con lo que un visor como Acrobat mostraría campo por campo.

Una breve historia del PDF rellenable

Los formularios interactivos forman parte de la especificación PDF desde mediados de los años noventa, construidos sobre la tecnología AcroForm que Adobe heredó de su formato FDF anterior. Décadas después, buena parte de los trámites gubernamentales, de recursos humanos, de seguros y legales sigue circulando como estos PDF con formulario, precisamente porque el diseño es fijo y el modelo de datos está estandarizado. Esa estabilidad también explica por qué vale la pena leerlos de forma programática: la estructura de campos de un formulario bien construido rara vez cambia, así que un mapeo que construye una vez suele seguir funcionando.

Dónde encaja en su flujo

Trátelo como el paso de descubrimiento antes de cualquier lógica de llenado o validación. Lea una plantilla una sola vez para construir un mapa de campos, guárdelo en caché y úselo luego para impulsar la automatización siguiente: poblar el mismo formulario miles de veces, verificar que un PDF enviado tenga completos todos los campos obligatorios, o conciliar valores contra un registro de base de datos. Como cada llamada es una tarea pequeña y autónoma, encaja de forma natural al inicio de un flujo de admisión o incorporación.

Entrega y retención

Los resultados se entregan a un webhook firmado, la vía recomendada para automatización, o mediante un enlace firmado válido durante 24 horas. Los documentos y los datos extraídos se conservan solo durante la ventana de retención y luego se eliminan, y nada de lo que envía se usa jamás para entrenar un modelo. Una tarea fallida — un archivo dañado, un formulario sin AcroForm alguno — se reintenta tres veces y, si aun así no puede leerse, devuelve un error claro sin costo.