Skip to content
PDF Oxide

Formularios XFA — Python, Rust, Node.js, Go, C#

Detecta y analiza formularios XFA — la única biblioteca que lee las plantillas XML nativamente, en lugar de depender del fallback de AcroForm:

from pdf_oxide import PdfDocument

doc = PdfDocument("government-form.pdf")
xfa = doc.analyze_xfa()
if xfa:
    print(f"XFA form with {len(xfa.fields)} fields")
    for field in xfa.fields:
        print(f"  {field.name}: {field.field_type}")

XFA (XML Forms Architecture) es un formato de formularios legado usado por muchas agencias gubernamentales, instituciones financieras y sistemas empresariales. La mayoría de las bibliotecas PDF de Python no pueden manejar formularios XFA en absoluto. PDF Oxide puede detectar, analizar y extraer datos de ellos.

¿Qué es XFA?

Los formularios XFA usan plantillas basadas en XML embebidas dentro de un PDF en lugar de campos AcroForm estándar. Fueron creados por Adobe y son comunes en:

  • Formularios gubernamentales — IRS, inmigración, documentos de agencias estatales
  • Formularios financieros — solicitudes de préstamos, reclamaciones de seguros
  • Formularios empresariales — incorporación de RRHH, adquisiciones, cumplimiento

XFA fue deprecado en PDF 2.0 (ISO 32000-2:2020), pero millones de documentos XFA existentes siguen en circulación.

XFA vs AcroForm

Feature AcroForm XFA
Format PDF objects XML templates
Supported by All PDF libraries Few PDF libraries
Dynamic layouts No Yes
PDF 2.0 status Supported Deprecated
Typical source Most form creators Adobe LiveCycle, Adobe Designer

Por qué PyMuPDF y pypdf no pueden manejar formularios XFA

Si ha intentado leer formularios XFA con bibliotecas PDF populares de Python, probablemente ha visto resultados vacíos sin error ni advertencia. Esto se debe a que PyMuPDF, pypdf, pdfplumber y pdfminer no tienen soporte XFA.

PyMuPDF (fitz) — retorna vacío silenciosamente

PyMuPDF’s doc.get_form_fields() and page .widgets() solo leen campos AcroForm. Cuando un PDF usa formularios solo XFA (común en documentos del IRS, inmigración y agencias estatales), PyMuPDF retorna resultados vacíos sin ninguna advertencia:

# PyMuPDF — silently misses XFA data
import fitz
doc = fitz.open("government-form.pdf")
fields = doc[0].widgets()  # Returns [] on XFA-only forms
form_data = doc.get_form_fields()  # Returns {} on XFA-only forms

Si el formulario XFA incluye una capa de respaldo AcroForm, PyMuPDF puede retornar un subconjunto parcial de campos — pero los datos XFA reales (diseños dinámicos, valores calculados, subformularios anidados) son invisibles.

pypdf — también retorna vacío en formularios XFA

pypdf’s la lectura de campos de formulario tiene la misma limitación. Solo puede acceder a campos AcroForm y no tiene soporte XFA:

# pypdf — cannot read XFA content
from pypdf import PdfReader
reader = PdfReader("government-form.pdf")
fields = reader.get_form_text_fields()  # Returns {} on XFA-only forms

pdfplumber y pdfminer — sin soporte XFA en absoluto

pdfplumber and pdfminer no intentan leer campos de formulario de formularios XFA. No tienen API para detección o extracción XFA.

PDF Oxide — lee XFA nativamente

PDF Oxide analiza las plantillas XML XFA directamente, extrayendo todos los campos, valores y estructura del formulario:

# PDF Oxide — reads XFA natively
from pdf_oxide import PdfDocument
doc = PdfDocument("government-form.pdf")
xfa = doc.analyze_xfa()
print(f"{len(xfa.fields)} fields found")  # All XFA fields extracted

Esto funciona en formularios gubernamentales, documentos del IRS, solicitudes de seguros y cualquier otro PDF basado en XFA — incluyendo formularios sin capa de respaldo AcroForm.

Instalación

pip install pdf_oxide

Detectar formularios XFA

Verifique si un PDF contiene contenido XFA:

Python

from pdf_oxide import PdfDocument

doc = PdfDocument("form.pdf")
xfa = doc.analyze_xfa()

if xfa:
    print("This PDF uses XFA forms")
    print(f"  Fields: {len(xfa.fields)}")
    print(f"  Has template: {xfa.has_template}")
    print(f"  Has datasets: {xfa.has_datasets}")
else:
    print("Standard AcroForm (or no forms)")

WASM

En WASM, puede detectar formularios XFA y recurrir a leer campos AcroForm:

import { WasmPdfDocument } from "pdf-oxide-wasm";

const doc = new WasmPdfDocument(bytes);
if (doc.hasXfa()) {
  console.log("This PDF uses XFA forms");
  // Read any AcroForm fallback fields
  const fields = doc.getFormFields();
  console.log(`AcroForm fallback fields: ${fields.length}`);
}
doc.free();

Analizar campos XFA

Obtenga detalles de cada campo en el formulario XFA:

from pdf_oxide import PdfDocument

doc = PdfDocument("tax-form.pdf")
xfa = doc.analyze_xfa()

if xfa:
    for field in xfa.fields:
        print(f"Name: {field.name}")
        print(f"  Type: {field.field_type}")
        print(f"  Value: {field.value}")
        print()

Leer datos XFA

Extraiga valores de campo actuales de los datasets XFA:

from pdf_oxide import PdfDocument

doc = PdfDocument("filled-xfa.pdf")
xfa = doc.analyze_xfa()

if xfa and xfa.has_datasets:
    data = {}
    for field in xfa.fields:
        if field.value:
            data[field.name] = field.value
    print(data)

Procesamiento por lotes XFA Forms

Escanee un directorio para identificar qué PDFs usan XFA:

from pdf_oxide import PdfDocument, PdfError
from pathlib import Path

pdf_dir = Path("government-forms/")
xfa_files = []
acroform_files = []

for pdf_path in pdf_dir.glob("*.pdf"):
    try:
        doc = PdfDocument(str(pdf_path))
        xfa = doc.analyze_xfa()
        if xfa:
            xfa_files.append(pdf_path.name)
        else:
            acroform_files.append(pdf_path.name)
    except PdfError as e:
        print(f"Error: {pdf_path.name}: {e}")

print(f"XFA forms: {len(xfa_files)}")
print(f"Standard forms: {len(acroform_files)}")

API de Rust

use pdf_oxide::PdfDocument;
use pdf_oxide::xfa::analyze_xfa_document;

let mut doc = PdfDocument::open("xfa-form.pdf")?;
let analysis = analyze_xfa_document(&mut doc)?;

println!("XFA form detected: {} fields", analysis.fields.len());
for field in &analysis.fields {
    println!("  {} ({:?}): {:?}", field.name, field.field_type, field.value);
}

Por qué XFA importa

La mayoría de las bibliotecas PDF de Python ignoran silenciosamente el contenido XFA — extract_text() y las APIs de campos de formulario solo ven la capa de respaldo AcroForm (si existe). Muchos formularios solo XFA no tienen respaldo AcroForm, haciéndolos invisibles para otras herramientas:

  • Formularios XFA de PyMuPDF (pymupdf) — get_form_fields() y .widgets() retornan vacío en PDFs solo XFA. PyMuPDF no tiene soporte XFA y no planea agregarlo.
  • Soporte XFA de pypdf — get_form_text_fields() de pypdf no puede leer contenido XFA. Solo los campos de respaldo AcroForm son visibles, si es que existen.
  • pdfplumber — sin soporte XFA. La extracción de formularios está limitada a campos AcroForm.
  • pdfminer — sin soporte XFA. No puede detectar ni extraer datos de formularios XFA.

PDF Oxide es la única biblioteca PDF de Python que lee plantillas XML XFA directamente, dándole acceso a la estructura del formulario y datos que PyMuPDF, pypdf, pdfplumber y pdfminer no pueden ver.

Páginas relacionadas