---
title: "Biblioteca NFE.io em Python para Emissão de Nota Fiscal de Serviço (NFS-e)"
description: "SDK Python oficial da NFE.io — Python 3.10+, zero dependências de runtime, clientes síncrono e assíncrono, NFS-e, empresas, certificados, webhooks e consultas de CNPJ, CPF e CEP."
source_url: https://nfe.io/docs/desenvolvedores/bibliotecas/python/
product: bibliotecas
last_updated: 2026-10-14
tags: ["python", "how-to", "nfse"]
integration: ["sdk"]
---

# Biblioteca Python NFE.io

SDK oficial da [NFE.io](https://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`](https://pypi.org/project/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](/desenvolvedores/rest-api/nota-fiscal-de-servico-v1).

:::info 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](https://github.com/nfe/client-python/blob/master/CHANGELOG.md).
:::

## Requisitos

- Python **3.10** a **3.14**.
- **Zero dependências de runtime.**

## Instalação

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

## Primeiros passos

```python
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": "maria@example.com",
        },
    },
    external_id="pedido-1001",
)
print(invoice.flow_status, invoice["number"])
```

O passo a passo completo está em [Primeiros passos](./getting-started.md).

## Guias

| Guia | Conteúdo |
|---|---|
| [Primeiros passos](./getting-started.md) | Instalação, cliente, primeira NFS-e e download do PDF. |
| [Configuração](./configuration.md) | As duas chaves, variáveis de ambiente, timeouts, retry, TLS e opções por chamada. |
| [Síncrono, assíncrono e polling](./async-and-polling.md) | `AsyncNfeClient`, `create_and_wait`, `wait` e os estados da nota. |
| [Tratamento de erros](./errors.md) | Hierarquia de exceções, `outcome_unknown` e a reconciliação por `external_id`. |
| [Webhooks](./webhooks.md) | Verificação de assinatura com Flask, FastAPI e Django. |
| [Paginação](./pagination.md) | Paginação por índice (NFS-e) e por cursor (empresas). |
| [Downloads](./downloads.md) | PDF e XML em `bytes`, sem reenviar a chave no redirecionamento. |
| [Emissão RTC](./rtc-emission.md) | NFS-e no layout da Reforma Tributária (`ibsCbs`, `nbsCode`). |
| [Cookbook por recurso](/desenvolvedores/bibliotecas/python/recursos) | 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](./recursos/service-invoices.md) |
| `client.companies` | Cadastro de empresas (API v2) | [Empresas](./recursos/companies.md) |
| `client.certificates` | Envio e consulta do certificado digital A1 | [Certificados](./recursos/certificates.md) |
| `client.webhooks` | Webhooks da conta; a verificação fica em `nfeio.webhooks` | [Webhooks](./recursos/webhooks.md) |
| `client.lookups.cnpj` | Consulta de CNPJ (v3, numérico e alfanumérico) | [Consulta de CNPJ](./recursos/legal-entity-lookup.md) |
| `client.lookups.cpf` | Situação cadastral de CPF | [Consulta de CPF](./recursos/natural-person-lookup.md) |
| `client.lookups.cep` | Endereço por CEP | [Consulta de CEP](./recursos/addresses.md) |

## 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](/desenvolvedores/bibliotecas/node), [PHP](/desenvolvedores/bibliotecas/php) ou
[Ruby](/desenvolvedores/bibliotecas/ruby)):

- **NF-e** (modelo 55) e **NFC-e** (modelo 65): [NF-e v2](/desenvolvedores/rest-api/nota-fiscal-de-produto-v2)
  e [NFC-e v2](/desenvolvedores/rest-api/nota-fiscal-de-consumidor-v2).
- **CT-e**, distribuição DF-e e notas de entrada (inbound).
- **Cálculo de impostos**: [API de Cálculo de Impostos](/desenvolvedores/rest-api/calculo-de-impostos-v1).
- **NFS-e v3** (CNPJ alfanumérico do prestador): a NFS-e do SDK usa a
  [API v1](/desenvolvedores/rest-api/nota-fiscal-de-servico-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](./configuration.md#transporte-próprio)).

## Segurança

Vulnerabilidades no SDK são tratadas pelo canal privado do GitHub (aba **Security** do repositório
[`nfe/client-python`](https://github.com/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.