PDF4me Python SDK Empezando

El pdf4me paquete en PyPI es el asíncrono oficial Python SDK para el PDF4me REST API. Incluye 106 funciones asíncronas tipificadas en 18 módulos que cubren conversión, optimización, fusión, división, estampado, firma electrónica, OCR, llenado de formularios, extracción, códigos de barras, ZUGFeRD facturación electrónica y AIExtracción de documentos basada en software a partir de facturas, recibos, contratos, extractos bancarios, documentos fiscales y nóminas.

Información del paquete

Campo	Valor
Nombre del paquete	pdf4me
Versión actual	1.0.2 (publicado el 14 de septiembre de 2026)
Licencia	MIT
Python apoyo	>=3.11 (probado en las versiones 3.11, 3.12, 3.13 y 3.14)
Estado de desarrollo	Producción/Estable
Estructura	E/S asíncrona
Fuente	github.com/pdf4me/pdf4me-clientapi-python
PyPI	pypi.org/project/pdf4me

Internamente, el cliente se genera con Microsoft. Kiota encima de httpx[http2]De esta forma, cada acción está completamente tipificada, devuelve resultados tipificados y reutiliza un único grupo de conexiones por cliente.

Requisitos previos

• Python 3.11 o posterior.
• A PDF4me cuenta y API llave.
• pip (o uv, poetry, o cualquier PyPI-instalador compatible).

Consigue tu API Llave

Ver en PyPI

Ver en GitHub

Instalar

pip

python -m pip install pdf4me

uv

uv add pdf4me

Poetry

poetry add pdf4me

Instalación pdf4me se detiene httpx[http2] y Microsoft Kiota paquetes de tiempo de ejecución (microsoft-kiota-abstractions, microsoft-kiota-httpy los backends de serialización JSON, formulario, texto y multipart).

Autenticar

Configura tu API clave en el entorno:

Bash / Zsh

export PDF4ME_API_KEY="your-api-key"

PowerShell

$env:PDF4ME_API_KEY = "your-api-key"

Windows CMD

set PDF4ME_API_KEY=your-api-key

Los ejemplos a continuación leen la clave de esa variable en tiempo de ejecución. También puede pasarla directamente a Pdf4meClient(api_key) Si prefiere cargarlo desde un administrador secreto, .env archivo u otra fuente.

Inicio rápido

El programa útil más sencillo: abre un cliente, ejecuta una acción y escribe el resultado en el disco.

import asyncio
import os
from pathlib import Path

from pdf4me import Pdf4meClient
from pdf4me.optimize import optimize


async def main() -> None:
    api_key = os.environ.get("PDF4ME_API_KEY")
    if not api_key:
        raise SystemExit("Set PDF4ME_API_KEY before running this example.")

    source = Path("input.pdf")
    async with Pdf4meClient(api_key) as client:
        result = await optimize(
            client, source.read_bytes(), doc_name=source.name
        )
    Path("optimized.pdf").write_bytes(result)
    print("Saved optimized.pdf")


if __name__ == "__main__":
    asyncio.run(main())

Tres cosas a tener en cuenta:

1. Un cliente, muchas llamadas. El async with Pdf4meClient(...) El contexto gestiona el subyacente httpx grupo de conexiones. Reutilizar el mismo cliente para cada llamada dentro main en lugar de abrir uno por acción.
2. Las acciones son funciones gratuitas, no métodos del cliente. Importa cada acción desde su módulo (from pdf4me.optimize import optimize, from pdf4me.pdf import get_pdf_metadata) y pasa el cliente como primer argumento. Esto mantiene la interfaz plana y te permite eliminar los módulos no utilizados en tu editor.
3. Bytes de entrada, bytes de salida. Acciones que generan un archivo devuelto bytesLas acciones que generan metadatos devuelven clases de datos tipadas. No hay almacenamiento temporal en disco, por lo que puede canalizar los resultados entre acciones sin modificar el sistema de archivos.

Dos llamadas más comunes

Sello a PDF:

from pdf4me.edit import StampAlignX, stamp

stamped = await stamp(client, data, text="DRAFT", align_x=StampAlignX.Center)
Path("stamped.pdf").write_bytes(stamped)

Leer PDF metadatos:

from pdf4me.pdf import get_pdf_metadata

metadata = await get_pdf_metadata(client, data, doc_name="input.pdf")
print(metadata.page_count)

Cada valor pasado como una enumeración (como StampAlignX.Center) es una constante tipada, por lo que su IDE Completa automáticamente los valores legales y mypy o pyright detectan los errores tipográficos en el momento de la edición.

¿Qué incluye la caja? (106 acciones repartidas en 18 módulos)

Módulo	Comportamiento	Ejemplo de importación
pdf4me.ai_document_extraction	14	from pdf4me.ai_document_extraction import extract_invoice_data
pdf4me.barcode	7	from pdf4me.barcode import create_barcode, read_barcodes
pdf4me.convert	13	from pdf4me.convert import html_to_pdf, url_to_pdf, word_to_pdf
pdf4me.edit	7	from pdf4me.edit import stamp, add_page_number, add_html_header_footer
pdf4me.excel	1	from pdf4me.excel import excel_to_pdf
pdf4me.extract	8	from pdf4me.extract import extract_text, extract_attachments
pdf4me.find_search	2	from pdf4me.find_search import find_and_replace_text
pdf4me.forms	2	from pdf4me.forms import fill_pdf_form, get_form_fields
pdf4me.generate	6	from pdf4me.generate import generate_document_single
pdf4me.image	13	from pdf4me.image import resize_image, add_watermark_to_image
pdf4me.merge_split	5	from pdf4me.merge_split import merge_pdfs, split_pdf_by_barcode
pdf4me.optimize	1	from pdf4me.optimize import optimize
pdf4me.organize	5	from pdf4me.organize import rotate_pdf, extract_pages
pdf4me.pdf	16	from pdf4me.pdf import get_pdf_metadata, sign_pdf
pdf4me.pdf4me	1	from pdf4me.pdf4me import ping
pdf4me.security	2	from pdf4me.security import protect_document, unlock_pdf
pdf4me.word	2	from pdf4me.word import add_tracked_changes
pdf4me.zugferd	1	from pdf4me.zugferd import create_zugferd_invoice

Las rutas de importación anteriores ilustran la superficie del módulo. Consulte el PDF4me REST API referencia para la lista completa de parámetros para cada acción y el repositorio de origen pdf4me/ Árbol de paquetes para los nombres de símbolos exactos que exporta su versión.

¿Adónde ir después?

PDF4me REST API referencia

Fuente en GitHub

Informar de un problema

Solución de problemas

ModuleNotFoundError: No module named 'pdf4me'. El paquete está instalado en un intérprete diferente al que ejecuta su script. Confirme con python -m pip show pdf4me dentro del mismo entorno virtual. Si utiliza pyenv o conda, active primero el entorno.

SystemExit: Set PDF4ME_API_KEY before running this example. La variable de entorno no es visible para su proceso. Reinicie su shell después exporto pasar la clave directamente con Pdf4meClient("your-api-key"). En Windows, recuerda que set dentro de CMD no persiste entre sesiones; utilice setx para un valor permanente.

httpx.HTTPStatusError: 401 Unauthorized. El API La clave está presente pero ha sido rechazada. Vuelva a generarla en el PDF4me panel y vuelve a intentarlo.

Primera llamada lenta tras un período de inactividad. HTTP/2 keep-alive se reinicia en estado inactivo. Mantenga el Pdf4meClient permanecer abierto durante toda la vida útil de un trabajo por lotes, en lugar de abrir uno nuevo para cada archivo.

asyncio.run() cannot be called from a running event loop. Estás dentro Jupyter o un marco que ya ejecuta un bucle de eventos. await main() en el nivel superior de una celda del cuaderno, o bien, envuelva su código en el punto de entrada asíncrono del propio framework.