Emissão de NFS-e pela API do Sistema Nacional (SEFIN) e geração do DANFSe — em Python.
Feito por um contador da GT Contabilidade, para contadores e desenvolvedores que precisam emitir nota fiscal de serviço no padrão nacional sem depender de robô de navegador nem da API de PDF do governo.
✅ Lançado — v1.x. Em produção real desde junho de 2026: é o motor que emite as NFS-e de um escritório de contabilidade, mês após mês, para prestadores de vários municípios — centenas de notas autorizadas pelo SEFIN Nacional. O pipeline completo (
config → certificado → DPS → assinatura → transporte mTLS → DANFSe) é validado byte a byte contra uma implementação de referência e coberto por testes. A responsabilidade pela nota é sempre do emitente: valide cada emissão.
🗓️ Reforma tributária: a NT 009 já está implementada (v1.3.0), pensada para 01/01/2027. O leiaute novo da DPS, que a homologação do SEFIN aplica desde 31/10/2026, já emite pela lib — inclusive o grupo IBS/CBS do Simples Nacional, autorizado em homologação. Fica em fase de testes até a produção virar de pacote; até lá a produção segue no leiaute atual, sem mudar um byte, e a lib escolhe sozinha pelo ambiente. Detalhes em
docs/conhecimento-fiscal.md§19.
Com o Sistema Nacional NFS-e virando o padrão do país — e a reforma tributária (IBS/CBS) passando por ele —, todo escritório de contabilidade precisa emitir NFS-e pelo padrão nacional. O ecossistema PHP já tem bibliotecas maduras para isso; o Python, não — falta uma solução turnkey, ponta a ponta. Este projeto preenche essa lacuna, integrando o que o ecossistema fiscal Python já tem de melhor e adicionando o que faltava (o transporte ao SEFIN nacional + o acabamento).
- Existem duas APIs do governo. A de emissão (SEFIN Nacional) recebe a DPS assinada e devolve a NFS-e — é viva e é o futuro. A de geração de PDF/DANFSe (ADN) está sendo descontinuada (NT-008/2026). Por isso, aqui o DANFSe é gerado localmente.
ambGernão é ambiente. O indicador Produção/Homologação é otpAmb, não oambGer(toda nota nacional temambGer=2). Confundir os dois marca nota de produção como "sem validade".
- 🧾 Emite NFS-e pela API oficial (SEFIN Nacional) com certificado A1 — sem robô de navegador.
- 🖨️ DANFSe gerado localmente (PDF), antecipando o fim da API de PDF do governo.
- 🔐 Assinatura XMLDSIG por biblioteca madura (
erpbrasil.assinatura), validada byte a byte. - ✅ Validação fiscal antes de enviar — pega E0312/E0712/E1235… e CPF/CNPJ (mód-11) localmente.
- 🔁 Idempotência nativa (
verificarDps) — não duplica nota num reenvio, e a nota recuperada volta com o XML (dá para gerar o DANFSe). - ❌ Cancelamento direto (e101101) ou por análise fiscal (e101103), para os municípios que não aceitam o direto.
- 🔎 Consulta pela chave e 📬 caixa postal DF-e: as notas emitidas, as recebidas como tomador e os eventos do CNPJ, por NSU.
- 💰 Valor em
Decimal(também aceita"1.262,90"), sem erro de arredondamento binário. - 🔒 Certificado do servidor conferido (mTLS nos dois sentidos).
- 🧩 Núcleo enxuto e MIT-limpo; a geração de PDF é uma dependência opcional.
- 🐍 Tipado (
mypy --strict), testado (incl. golden contra a referência) e com CLI turnkey.
# núcleo: emite a NFS-e (sem gerar PDF)
pip install PyNFSeNacionalGT
# + geração local do DANFSe (PDF) — dependência opcional
pip install "PyNFSeNacionalGT[danfse]"Requer Python 3.10+. No PyPI o pacote se chama
PyNFSeNacionalGT(o nomePyNFSeNacionalesbarra na proteção do PyPI por semelhança com outro projeto); o import continuapynfsenacional. Pin recomendado:PyNFSeNacionalGT>=1.6.0— a 1.2.0 corrige o contador de nDPS que travava depois de uma resposta perdida (toda emissão seguinte voltava "já emitida") e traz cancelamento, consulta pela chave e a caixa postal DF-e; a 1.3.1 faz a caixa DF-e distinguir a RECUSA (ex.: consulta por procuração sem a procuração, E2245) de uma caixa vazia; a 1.3.2 faz a conferência doja_emitidaler o tomador como a DPS o escreve (cnpj/cpf), sem reenviar a própria nota em número novo; a 1.4.0 traz o grupo Atividade/Evento, obrigatório no item 12 (E0390); a 1.5.0 consulta o convênio e as alíquotas do município; a 1.6.0 emite opAliqdo ISS retido do ME/EPP; a 1.7.0 separa o cancelamento recusado do ambíguo, põe prazo na caixa DF-e e diz se o certificado é e-CNPJ ou e-CPF. O histórico de cada versão está no CHANGELOG.
from decimal import Decimal
from pynfsenacional import Emissor
emissor = Emissor("config/cliente.json") # certificado A1 + dados do prestador
nota = emissor.emitir( # monta DPS → assina → envia ao SEFIN
valor=Decimal("150.00"), # também aceita "150,00", 150 ou 150.0
descricao="Sessão de psicoterapia",
tomador={"cpf_cnpj": "00000000000", "nome": "Fulano de Tal"},
)
print(nota.emitida, nota.numero_nfse, nota.chave_acesso)
nota.danfse("nota.pdf") # gera o PDF do DANFSe localmenteDepois da emissão:
nota = emissor.consultar(chave) # a NFS-e (e o XML) pela chave; None se não existe
r = emissor.cancelar(chave, justificativa="Erro na emissão da nota fiscal", motivo=1)
# motivo: 1=Erro na Emissão · 2=Serviço não Prestado · 9=Outros
# município que não aceita o cancelamento direto (E0823): modo="analise"
print(r.ok, r.cancelada, r.erro_msg)
# r.desfecho: "registrado" | "recusado" | "nao_enviado" | "ambiguo"
if r.ambiguo: # o pedido saiu e a resposta não veio: PODE ter cancelado
... # confira a nota antes de repetir (repetido, volta E0840)
# no direto, o E0840 ("já vinculado") é a nota que já estava cancelada: r.ja_estava_cancelada
caixa = emissor.sincronizar_dfe(nsu=0, prazo_s=120) # emitidas, recebidas e eventos do CNPJ
for doc in caixa.documentos:
print(doc.nsu, doc.classificar(emissor.cfg.prestador.cnpj), doc.nome_arquivo())
doc.gravar("caixa/") # bytes do XML, gravação atômica
proximo_nsu = caixa.ultimo_nsu # guarde: a próxima leitura parte daquinfse-nacional emitir config/cliente.json \
--valor 150,00 --descricao "Sessão de psicoterapia" \
--tomador-doc 00000000000 --tomador-nome "Fulano de Tal" \
--ambiente homologacao \
--pdf nota.pdfnfse-nacional consultar config/cliente.json <chave> --pdf nota.pdf
nfse-nacional cancelar config/cliente.json <chave> --justificativa "Erro na emissão da nota fiscal"
nfse-nacional dfe config/cliente.json --nsu 0 --destino xmls/| Saída | Significado |
|---|---|
✅ emitida — nNFSe 13 · chave 3304… |
nota emitida; o nNFSe é atribuído pelo SEFIN |
❌ não emitida: [E0312] … |
rejeitada pelo SEFIN, com o código do erro |
❌ config inválida: … |
barrada antes do envio pela validação local |
Os
00000000000acima são placeholders: o tomador precisa de CPF/CNPJ válido (a lib confere o dígito mód-11 localmente). Sem tomador, a nota sai como consumidor final (omite<toma>).
Operação: o
nDPSé um contador interno por prestador+ambiente, persistido emout/numero_<id>_<ambiente>.txt— quem atribui onNFSeé o SEFIN. Reenviar a mesma DPS é idempotente (verificarDps): não duplica. Se a DPS daquele número já existe, a lib busca a nota e compara valor e tomador: é a mesma → devolveja_emitidacom o XML; é outra (contador atrasado) → pula o número. Quem passanumero=explícito controla a numeração. Para acompanhar o passo a passo, rodenfse-nacional -v emitir …(o-vvem antes do subcomando).
Cada prestador é descrito por um JSON puro. Comece copiando o exemplo anotado:
- 📄
examples/config-exemplo.json— pronto para copiar (JSON puro). - 📝
examples/config-exemplo.jsonc— o mesmo, comentado campo a campo. - 📚 Schema completo em
docs/conhecimento-fiscal.md(§3).
| Dado | Onde obter |
|---|---|
| Certificado A1 (.pfx) + senha | do próprio prestador (anuência); renove antes de vencer |
| CNPJ | cadastro |
| Código do município (IBGE) | município de atuação do prestador |
Regime (opSimpNac/regApTribSN) |
contabilidade (é Simples? MEI ou ME/EPP?) |
cTribNac (6 díg) |
item da LC116 da atividade (mesmo código do portal) |
cTribMun (desdobro) |
o que o município administra p/ aquele cTribNac (alguns não usam) |
| Inscrição Municipal | o CNC do município, por CNPJ — não é "por cidade" (§10) |
pTotTribSN (% Simples) |
alíquota efetiva do Simples (contabilidade) |
🔒 Nada sensível vai para o git. O
.pfx, as configs reais (config/) e os XML/PDF de notas são ignorados por padrão (ver.gitignore). Os dados de exemplo são fictícios.
Este pacote integra as libs maduras do ecossistema fiscal Python e escreve só o que faltava
(o transporte ao SEFIN nacional + o acabamento). Ver docs/roadmap.md.
config (JSON) → montar DPS (XML) → assinar (XMLDSIG) → gzip+base64 → POST /nfse (mTLS)
│ │ │
lxml erpbrasil.assinatura SEFIN Nacional
│
NFS-e (XML)
│
render DANFSe local (PDF)
│
BrazilFiscalReport
| Peça | Biblioteca | Módulo |
|---|---|---|
| Montar/serializar o XML da DPS | lxml |
dps.py |
| Assinatura digital XMLDSIG | erpbrasil.assinatura |
assinatura.py |
Ler o certificado A1 .pfx |
cryptography |
certificado.py |
| Transporte mTLS ao SEFIN | requests + requests-pkcs12 + código próprio |
sefin.py |
| Gerar o DANFSe (PDF) | BrazilFiscalReport |
danfse.py |
| Validação fiscal + CLI | — | config.py, cli.py |
✅ Implementado e validado · ⏳ próximo
- ✅ Config + validação fiscal (E-codes, CPF/CNPJ mód-11)
- ✅ Leitura do certificado A1 (
.pfx) - ✅ Montagem da DPS — C14N idêntico, byte a byte, à referência PHP (golden)
- ✅ Assinatura XMLDSIG (mesmo
DigestValuedo gabarito) - ✅ Transporte mTLS + idempotência — emissão real validada em homologação e produção
- ✅ DANFSe local (PDF)
- ✅ CLI turnkey + logging
- ✅ Publicado no PyPI (
PyNFSeNacionalGT) - ✅ Tomador completo:
IM, endereço, telefone e e-mail no<toma>(v0.2.0) - ✅ Leiaute RTC 1.01 da DPS (NT 004 v2.0 / NT 007) — alinhado à revisão oficial do XSD (defensivo p/ o endurecimento das validações RTC)
- ✅ MEI (
opSimpNac=2) com DPS própria e CNPJ alfanumérico (NT 2025.001) — v0.4.0 - ✅ Inscrição Municipal opcional (regra do CNC por CNPJ) e
cTribMunomitido onde o município não usa — v0.5.0 - ✅ Margem anti-E0008 no
dhEmie informações complementares (xInfComp) — v1.0.0 - ⏳ Endurecimento a partir de mais emissões reais
- ✅ Regime Regular (Não Optante — Lucro Presumido/Real):
pTotTrib,tpRetPisCofins, Item da NBS e o grupo IBS/CBS (classificação:cIndOp,CST,cClassTrib) — v1.1.0 - ✅ ISS retido pelo tomador (
tpRetISSQN=2), com a recusa local de E0204/E0237 — v1.1.0 - ✅ NT 009 — os dois leiautes do XSD (produção 09/02/2026 e NT 009 de 20/10/2026, que a homologação já aplica), escolhidos pelo ambiente; o grupo IBS/CBS do Simples autorizado em homologação — v1.3.0, em testes até a produção virar
- ⏳ Os campos do Simples da NT 009 (
regApIBSCBSSN,cAtvSN) quando entrarem no esquema; o grupo IBS/CBS do Simples é obrigatório a partir de 01/01/2027 (Ato Conjunto RFB/CGIBS nº 4/2026). E os casos ainda não cobertos do grupo: destinatário ≠ adquirente, compra governamental - ⏳ Tomador estrangeiro / sem documento
- ✅ Cancelamento (e101101 direto / e101103 análise fiscal), consulta pela chave e
distribuição DF-e por NSU; valor em
Decimal; certificado do servidor conferido — v1.2.0 - ⏳ Evento de substituição (e105102) e manifestação do tomador
- ⏳ DANFSe: exibir o total aproximado de tributos do Simples (
pTotTribSN, Lei 12.741) — hoje sai como "—" (oBrazilFiscalReportnão lê esse campo)
Detalhes em docs/roadmap.md e CHANGELOG.md.
git clone https://github.com/Gomes343/PyNFSeNacional.git
cd PyNFSeNacional
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]" # dev já inclui o extra [danfse]
pytest # testes (inclui o golden contra a referência)
ruff check . # lint
mypy # tipos (strict)Como contribuir: CONTRIBUTING.md. Reportar vulnerabilidades: SECURITY.md.
Esta biblioteca nasceu dentro da GT Contabilidade — escritório
contábil que emite NFS-e pelo padrão nacional, mês após mês, para empresas espalhadas por municípios
com regras diferentes entre si. Cada regra de docs/conhecimento-fiscal.md
foi paga com nota real: emissão travada, mensagem críptica do SEFIN, distância entre o que a
documentação diz e o que o município de fato aceita.
Esse conhecimento é vantagem competitiva e poderia ter ficado guardado. A GT preferiu publicá-lo sob licença MIT — a obrigatoriedade do Sistema Nacional chega para todo mundo ao mesmo tempo, e ninguém deveria precisar pagar duas vezes pela mesma descoberta. O que está aqui é a regra fiscal destilada e o código que a implementa; nunca dado de contribuinte.
Biblioteca para emissão de NFS-e. Use por sua conta e risco e valide cada emissão — a responsabilidade pela nota é sempre do contribuinte/emitente. Não é um produto fiscal homologado/certificado e não substitui orientação contábil. Sem garantia de qualquer tipo (ver LICENSE).
MIT — ver LICENSE. O núcleo usa só dependências permissivas. A geração do DANFSe
(opcional, [danfse]) usa a BrazilFiscalReport (LGPL-3.0), empregada como dependência — quem
só emite não a instala.
Construído sobre o trabalho da comunidade fiscal Python brasileira — Akretion/erpbrasil
(erpbrasil.assinatura) e Engenere (BrazilFiscalReport).
Mantido pela GT Contabilidade, que bancou as emissões reais em que cada regra deste repositório foi descoberta e validada.
{ "id": "exemplo", "nome_cliente": "EMPRESA EXEMPLO LTDA", "ambiente": "homologacao", // homologacao (teste) | producao (nota real) "certificado": { // ★ certificado A1 do PRÓPRIO prestador (.pfx) "path": "certs/exemplo.pfx", // NUNCA versionar — fica fora do git "senha": "0000" }, "prestador": { "cnpj": "00000000000000", // ★ 14 dígitos "codigo_municipio": "0000000", // ★ IBGE 7 díg do município do emitente "inscricao_municipal": null, // OPCIONAL — quem decide é o CNC, POR CNPJ (E0116 × // E0120). Sem IM no CNC: deixe null. Nunca "de enfeite" "regime": { // ★ regime tributário "opSimpNac": 3, // 1=Não Optante · 2=MEI · 3=Optante ME/EPP "regApTribSN": 1, // só ME/EPP (Não Optante e MEI: omitido, E0162) "regEspTrib": 0 } // nome/endereço do prestador NÃO entram aqui: o SEFIN puxa do cadastro (E0128/E0121) }, "servico": { "codigo_municipio_prestacao": "0000000", // ★ IBGE do local da prestação "cTribNac": "041601", // ★ Código de Tributação NACIONAL (6 díg, LC116) "cTribMun": "001", // desdobro municipal — obrigatório onde o município // usa desdobro (senão E0312); município sem desdobro // REJEITA o campo (E0315): deixe "" e ele é omitido "descricao_padrao": "Serviço Prestado", "tributos": { "pTotTribSN": "6.00", // ★ se Simples ME/EPP: % efetiva do Simples Nacional "piscofins_cst": "08" // CST do PIS/COFINS: "08"=sem incidência (default), // "00"=nenhum. Confira no XML do próprio contribuinte // "tpRetISSQN": 2, // ISS retido pelo tomador (por NOTA — §15) // "tpRetPisCofins": "0", // tipo de retenção do PIS/COFINS (NT 007 — §12) // "pTotTrib": {"pTotTribFed": "11.33", "pTotTribEst": "0", "pTotTribMun": "3"} // Não Optante: % aproximado em 3 parcelas (§14) } // "cNBS": "120015000", // Item da NBS (9 díg) — Regime Regular (§14) // "ibscbs": {"cIndOp": "050101", "CST": "000", "cClassTrib": "000001", "indFinal": "0"} // grupo IBS/CBS — obrigatório no Regime Regular (§8); // exige o cNBS (E0322) } // "leiaute": "20261020" // pacote do XSD (§19). Vazio = o do ambiente: // homologação 20261020 (NT 009), produção 20260209 }