Biblioteca Python NFE.io

SDK oficial da NFE.io para Python: emite e gerencia NFS-e, cadastra empresas e certificados digitais, administra webhooks e consulta CNPJ, CPF e CEP. Publicado no PyPI como nfe-io e importado como nfeio.

• Dois clientes, a mesma superfície: NfeClient (síncrono) e AsyncNfeClient (async/await).
• Zero dependências de runtime: só a biblioteca padrão do Python.
• Emissão segura: o SDK nunca reenvia uma emissão sozinho depois que ela pode ter chegado à API.
• Tipado (py.typed, checado com mypy --strict), sem estado global e com TLS sempre verificado.
• Valores em Decimal nas propriedades tipadas; o corpo das requisições usa as mesmas chaves (camelCase) da referência da API.

Versão 0.1 (alfa)

Esta é a primeira versão pública (0.1.0, de 09/10/2026). Enquanto a versão for 0.x, uma minor pode trazer mudança incompatível, sempre anunciada no CHANGELOG.

Requisitos

• Python 3.10 a 3.14.
• Zero dependências de runtime.

Instalação

pip install nfe-io
# ou
uv add nfe-io

Primeiros passos

from decimal import Decimal

from nfeio import NfeClient

client = NfeClient()  # lê NFE_API_KEY e NFE_DATA_API_KEY do ambiente

invoice = client.service_invoices.create_and_wait(
    "ID_DA_EMPRESA",
    {
        "cityServiceCode": "10677",
        "description": "Consultoria em tecnologia",
        "servicesAmount": Decimal("150.00"),
        "borrower": {
            "type": "NaturalPerson",
            "name": "Maria Silva",
            "federalTaxNumber": "52998224725",
            "email": "[email protected]",
        },
    },
    external_id="pedido-1001",
)
print(invoice.flow_status, invoice["number"])

O passo a passo completo está em Primeiros passos.

Guias

Guia	Conteúdo
Primeiros passos	Instalação, cliente, primeira NFS-e e download do PDF.
Configuração	As duas chaves, variáveis de ambiente, timeouts, retry, TLS e opções por chamada.
Síncrono, assíncrono e polling	AsyncNfeClient, create_and_wait, wait e os estados da nota.
Tratamento de erros	Hierarquia de exceções, outcome_unknown e a reconciliação por external_id.
Webhooks	Verificação de assinatura com Flask, FastAPI e Django.
Paginação	Paginação por índice (NFS-e) e por cursor (empresas).
Downloads	PDF e XML em bytes, sem reenviar a chave no redirecionamento.
Emissão RTC	NFS-e no layout da Reforma Tributária (ibsCbs, nbsCode).
Cookbook por recurso	Um guia por recurso do cliente.

Recursos do cliente

Acessor	O que faz	Cookbook
client.service_invoices	Emitir, consultar, listar, cancelar e baixar NFS-e	Notas de serviço
client.companies	Cadastro de empresas (API v2)	Empresas
client.certificates	Envio e consulta do certificado digital A1	Certificados
client.webhooks	Webhooks da conta; a verificação fica em nfeio.webhooks	Webhooks
client.lookups.cnpj	Consulta de CNPJ (v3, numérico e alfanumérico)	Consulta de CNPJ
client.lookups.cpf	Situação cadastral de CPF	Consulta de CPF
client.lookups.cep	Endereço por CEP	Consulta de CEP

O que a versão 0.1 ainda não cobre

O SDK Python cobre só os recursos da tabela acima. Para estes, use a API REST diretamente (ou um dos SDKs Node.js, PHP ou Ruby):

• NF-e (modelo 55) e NFC-e (modelo 65): NF-e v2 e NFC-e v2.
• CT-e, distribuição DF-e e notas de entrada (inbound).
• Cálculo de impostos: API de Cálculo de Impostos.
• NFS-e v3 (CNPJ alfanumérico do prestador): a NFS-e do SDK usa a API v1.
• Inscrições municipais e estaduais da empresa, tomadores cadastrados (pessoas físicas e jurídicas) e consulta de notas por chave de acesso.
• Proxy HTTP: as variáveis HTTPS_PROXY/HTTP_PROXY são ignoradas. Quem precisa de proxy hoje injeta um transporte próprio (veja Configuração).

Segurança

Vulnerabilidades no SDK são tratadas pelo canal privado do GitHub (aba Security do repositório nfe/client-python, Report a vulnerability). Não abra issue pública e não inclua chaves, certificados ou dados fiscais reais no relato. Problemas da API em si vão para o suporte da NFE.io.