✅ 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.

Por que existe

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).

Duas confusões que este projeto já resolve

1. 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.
2. ambGer não é ambiente. O indicador Produção/Homologação é o tpAmb, não o ambGer (toda nota nacional tem ambGer=2). Confundir os dois marca nota de produção como "sem validade".

✨ Destaques

• 🧾 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.

📦 Instalação

# 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 nome PyNFSeNacional esbarra na proteção do PyPI por semelhança com outro projeto); o import continua pynfsenacional. Pin recomendado: PyNFSeNacionalGT>=1.2.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. O histórico de cada versão está no CHANGELOG.

🚀 Quickstart

Em Python

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 localmente

Depois 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)

caixa = emissor.sincronizar_dfe(nsu=0)              # emitidas, recebidas e eventos do CNPJ
for doc in caixa.documentos:
    print(doc.nsu, doc.classificar(emissor.cfg.prestador.cnpj), doc.chave_acesso)
proximo_nsu = caixa.ultimo_nsu                      # guarde: a próxima leitura parte daqui

Pela linha de comando

nfse-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.pdf

nfse-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/

Os 00000000000 acima 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 em out/numero_<id>_<ambiente>.txt — quem atribui o nNFSe é 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 → devolve ja_emitida com o XML; é outra (contador atrasado) → pula o número. Quem passa numero= explícito controla a numeração. Para acompanhar o passo a passo, rode nfse-nacional -v emitir … (o -v vem antes do subcomando).

🔧 Configuração (passo a passo)

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).

{
  "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)
  }
}

O que cada prestador precisa fornecer

🔒 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.

🧩 Como funciona

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

🗺️ Status e roadmap

✅ 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 DigestValue do 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 cTribMun omitido onde o município não usa — v0.5.0
• ✅ Margem anti-E0008 no dhEmi e 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
• ⏳ Grupo IBS/CBS do Simples Nacional (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; pAliq (ISS retido de ME/EPP, município não conveniado)
• ✅ 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 "—" (o BrazilFiscalReport não lê esse campo)

Detalhes em docs/roadmap.md e CHANGELOG.md.

🧪 Desenvolvimento

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.

🏛️ Origem

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.

⚖️ Aviso legal

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).

📄 Licença

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.

🙏 Créditos

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.