PDF4me Python SDK Começando

O pdf4me pacote em PyPI é o assíncrono oficial Python SDK para o PDF4me REST APIEle fornece 106 funções assíncronas tipadas em 18 módulos que abrangem conversão, otimização, mesclagem, divisão, marcação, assinatura eletrônica, OCR, preenchimento de formulários, extração, códigos de barras, ZUGFeRD faturação eletrónica e AIExtração de documentos baseada em software a partir de faturas, recibos, contratos, extratos bancários, documentos fiscais e comprovantes de pagamento.

Informações sobre o pacote

Campo	Valor
Nome do pacote	pdf4me
Versão atual	1.0.2 (publicado em 14/09/2026)
Licença	MIT
Python apoiar	>=3.11 (testado nas versões 3.11, 3.12, 3.13 e 3.14)
Estado de desenvolvimento	Produção/Estável
Estrutura	E/S assíncrona
Fonte	github.com/pdf4me/pdf4me-clientapi-python
PyPI	pypi.org/project/pdf4me

Nos bastidores, o cliente é gerado com o Microsoft Office. Kiota além de httpx[http2]Assim, cada ação é totalmente tipada, retorna resultados tipados e reutiliza um pool de conexões por cliente.

Pré-requisitos

• Python 3.11 ou mais recente.
• A PDF4me conta e API chave.
• pip (ou uv, poetryou qualquer PyPI(instalador compatível).

Adquira o seu API Chave

Ver em PyPI

Ver em GitHub

Instalar

pip

python -m pip install pdf4me

uv

uv add pdf4me

Poetry

poetry add pdf4me

Instalação pdf4me puxa para dentro httpx[http2] e a Microsoft Kiota pacotes de tempo de execução (microsoft-kiota-abstractions, microsoft-kiota-httpe os backends de serialização JSON, de formulário, de texto e multipart).

Autenticar

Defina seu API chave no ambiente:

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

Os exemplos abaixo leem a chave dessa variável em tempo de execução. Você também pode passá-la diretamente para Pdf4meClient(api_key) Se preferir carregá-lo a partir de um gerenciador secreto, .env arquivo, ou outra fonte.

Início rápido

O programa útil mais simples: abra um cliente, execute uma ação e grave o resultado no 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())

Três coisas a observar:

1. Um cliente, muitas ligações. O async with Pdf4meClient(...) O contexto gerencia o subjacente httpx pool de conexões. Reutilize o mesmo cliente para cada chamada interna. main em vez de abrir uma por ação.
2. As ações são funções livres, não métodos do cliente. Importe cada ação de seu módulo (from pdf4me.optimize import optimize, from pdf4me.pdf import get_pdf_metadata) e passe o cliente como primeiro argumento. Isso mantém a superfície plana e permite que você remova módulos não utilizados do seu editor.
3. Entrada de bytes, saída de bytes. Ações que geram um arquivo de retorno bytesAs ações que produzem metadados retornam classes de dados tipadas. Não há armazenamento temporário em disco, portanto, você pode encaminhar os resultados entre ações sem acessar o sistema de arquivos.

Mais duas chamadas comuns

Carimbe um PDF:

from pdf4me.edit import StampAlignX, stamp

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

Ler PDF metadados:

from pdf4me.pdf import get_pdf_metadata

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

Cada valor passado como um enum (como StampAlignX.Center) é uma constante tipada, então seu IDE O sistema completa automaticamente os valores válidos e o mypy ou pyright detecta erros de digitação no momento da edição.

O que está disponível na caixa (106 ações em 18 módulos)

Módulo	Ações	Exemplo de importação
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

Os caminhos de importação acima são ilustrativos da superfície do módulo. Veja o PDF4me REST API referência Para obter a lista completa de parâmetros para cada ação e o repositório de origem. pdf4me/ A árvore de pacotes contém os nomes exatos dos símbolos exportados pela sua versão.

Para onde ir a seguir?

PDF4me REST API referência

Fonte em GitHub

Reportar um problema

Solução de problemas

ModuleNotFoundError: No module named 'pdf4me'. O pacote está instalado em um interpretador diferente daquele que executa seu script. Confirme com python -m pip show pdf4me dentro do mesmo ambiente virtual. Se você usar pyenv ou condaPrimeiro, ative o ambiente.

SystemExit: Set PDF4ME_API_KEY before running this example. A variável de ambiente não está visível para o seu processo. Reinicie o shell após exportou passe a chave diretamente com Pdf4meClient("your-api-key")No Windows, lembre-se de que set Dentro do CMD, os dados não persistem entre sessões; use setx por um valor permanente.

httpx.HTTPStatusError: 401 Unauthorized. O API A chave está presente, mas foi rejeitada. Gere-a novamente em PDF4me painel e tente novamente.

Primeira chamada lenta após um período de inatividade. HTTP/2 O recurso keep-alive reinicia em modo ocioso. Mantenha o Pdf4meClient Abrir uma janela durante toda a duração de um trabalho em lote, em vez de abrir uma nova para cada arquivo.

asyncio.run() cannot be called from a running event loop. Você está dentro Jupyter ou uma estrutura que já execute um loop de eventos. Use await main() no nível superior de uma célula do notebook, ou envolva seu código no ponto de entrada assíncrono próprio da estrutura.