Skip to content
regisdiasPublic

About

Emissão de NFS-e pela API nacional (Sefin): biblioteca Python, linha de comando, AWS Lambda e skill para agentes de IA

Topics

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

O que atende e o que não atende

Confira antes de instalar. O que está em ❌ a configuração recusa com aviso, em vez de emitir uma nota errada.

✅ Atende ❌ Ainda não atende
Regime da empresa Simples Nacional, ME ou EPP (testado em produção)
🟡 Lucro Presumido e Lucro Real sem retenções (a nota é montada e validada, mas ainda não foi testada em produção)
MEI
Cliente Empresa (CNPJ) ou pessoa (CPF) no Brasil
Nota sem cliente identificado
Cliente no exterior (exportação de serviço)
ISS Tributável e recolhido pela própria empresa, no município dela ou em outro ISS retido pelo cliente
Imunidade, exportação, não incidência
Benefício municipal, exigibilidade suspensa
Tributos federais Sem retenção
🟡 PIS/COFINS de apuração própria (Lucro Presumido ou Real)
🟡 IR retido pelo tomador, com a dispensa até R$ 10,00
Retenção de PIS, COFINS, CSLL ou INSS
Reforma tributária Notas sem IBS/CBS, como as aceitas hoje
🟡 Grupo IBS/CBS com CST, classificação e indicador da operação (a Sefin calcula os valores)
Destinatário diferente do cliente, operação com ente governamental, reembolso e repasse, diferimento
Valores Valor do serviço e tributos aproximados (percentual do Simples, percentual ou valor) Desconto, dedução da base de cálculo
O que faz com a nota Emitir, consultar, baixar o XML e gerar o PDF Cancelar, substituir, registrar eventos
PDF (DANFSe) Leiaute oficial da Nota Técnica 008, com QR Code Marca d'água de nota cancelada ou substituída
Configuração A partir de uma nota anterior (XML, PDF ou chave) ou pergunta por pergunta
Onde roda macOS (testado), Linux e Windows
AWS Lambda
Cofre de senha no Linux e no Windows (por enquanto, a senha vai por variável de ambiente ou é digitada)
Agentes Claude Code, Codex e Antigravity

Se o seu caso está na coluna da direita, use por enquanto o Emissor Web do governo.


O que é

A NFS-e nacional tem uma API própria (Sefin Nacional), autenticada pelo certificado digital A1 da empresa. Este projeto conversa com ela diretamente: monta a nota, assina, confere contra o esquema oficial e envia.

São quatro peças, cada uma para um jeito de usar:

Peça Para quem O que faz
Skill Quem usa Claude Code, Codex ou Antigravity Você pede "emite a nota da Empresa X deste mês" e o agente faz o resto, conferindo tudo com você antes
nfse (linha de comando) Quem prefere o terminal Emite, consulta, baixa o XML e gera o PDF
nfse (biblioteca Python) Quem integra num sistema Funções sem estado: o sistema guarda numeração e cadastro, a biblioteca cuida da nota
nfse_lambda Quem roda na AWS Função pronta para AWS Lambda, com o certificado no Secrets Manager

Como a skill funciona

Na primeira vez: configurar

A skill precisa saber quem emite, que serviço é prestado e para quem. Há dois caminhos:

  • A partir de uma nota que você já emitiu (recomendado). Entregue o PDF, o XML ou a chave de acesso de uma nota anterior. A skill baixa o XML pela API com o seu certificado e copia dele o regime tributário, o código do serviço, o ISS, o cliente, o valor e a descrição. No fim, mostra um resumo em português para você confirmar.
  • Manual, para a primeira nota da empresa. A skill pergunta uma coisa de cada vez, e só o que se aplica ao seu caso: regime (MEI, Simples, Lucro Presumido), o serviço que você presta (você descreve com suas palavras e ela procura o código na tabela nacional), ISS, cliente (pelo CNPJ ela preenche nome e endereço), valor, e como você quer receber o PDF e o e-mail.

Os dois caminhos terminam com uma nota de teste em homologação, o ambiente de testes da Receita, que não tem valor fiscal. A produção só fica disponível depois disso.

Todo mês: emitir

flowchart LR
    A["Você pede a nota"] --> B{"Já emitida<br>este mês?"}
    B -- sim --> X["Avisa e para"]
    B -- não --> C["Compara com<br>a nota anterior"]
    C --> D["Mostra o resumo<br>e pede confirmação"]
    D --> E["Emite em produção"]
    E --> F["Gera o PDF<br>e salva na pasta"]
    F --> G["Prepara o e-mail<br>para você enviar"]
Loading
  • Nada vai para produção sem você confirmar. O resumo da nota vem com um código, e a emissão só acontece com esse código: se qualquer dado mudar no meio do caminho, a nota não sai. Se o valor ou a descrição mudarem em relação ao mês anterior, a skill para e pergunta.
  • Se a conexão cair no meio, ela consulta a Receita antes de tentar de novo, para não emitir a mesma nota duas vezes.
  • O e-mail fica como rascunho, e quem envia é você. A skill pergunta qual programa você usa e abre o rascunho nele, com o PDF anexado: Outlook ou Mail no Mac, Thunderbird em qualquer sistema, ou um arquivo .eml. No Gmail e no Outlook web, a mensagem abre preenchida no navegador e a pasta do PDF abre ao lado, para você arrastar (nenhum webmail aceita anexo vindo de fora).
  • Avisa quando há versão nova. A Receita muda o leiaute de tempos em tempos; nfse atualizar atualiza o comando e a skill de uma vez.

Funciona com quais agentes

A skill segue o padrão aberto Agent Skills: um SKILL.md com as instruções e os scripts ao lado. O mesmo arquivo serve para os três agentes, e o instalador coloca uma cópia na pasta de cada um que encontrar na sua máquina:

Agente Pasta da skill
Claude Code ~/.claude/skills/nfse/
Codex (OpenAI) ~/.agents/skills/nfse/
Antigravity (Google) ~/.gemini/config/skills/nfse/

O agente precisa poder rodar comandos no terminal, porque é assim que a skill chama a linha de comando nfse. Outros agentes que leem SKILL.md devem funcionar também.

Instalação

macOS ou Linux, só no seu usuário, sem sudo:

curl -fsSL https://raw.githubusercontent.com/regisdias/nfse-cli/main/install.sh | bash

Depois, abra seu agente e peça "configura minha nota fiscal". Para saber antes de rodar, isto é o que o instalador faz (leia o script):

O quê Onde Para quê
Ambiente Python isolado ~/.local/share/nfse-cli/ Não mexe no Python do sistema nem em outros projetos
lxml e cryptography dentro desse ambiente Assinar e validar a nota (as únicas dependências do núcleo)
reportlab dentro desse ambiente Gerar o PDF da nota
Comando nfse ~/.local/bin/nfse A linha de comando, que a skill também usa
A skill as pastas da tabela acima, dos agentes que existirem Para o agente encontrar a skill
Sua configuração ~/.config/nfse-cli/ Criada na primeira vez que você configura; não sai da sua máquina

Pré-requisitos: Python 3.11 ou mais novo e o certificado A1 (.pfx) da empresa.

Para atualizar, nfse atualizar (a linha de comando avisa quando sai versão nova). Para desinstalar:

curl -fsSL https://raw.githubusercontent.com/regisdias/nfse-cli/main/install.sh | bash -s -- --desinstalar

A configuração em ~/.config/nfse-cli/ continua lá, para o caso de você reinstalar; apague à mão se quiser.

Windows: por enquanto, instalação manual (abaixo), com a senha na variável NFSE_CERT_SENHA.

Instalação manual

git clone https://github.com/regisdias/nfse-cli.git && cd nfse-cli
python3 -m venv .venv && .venv/bin/pip install -e '.[danfse]'
alias nfse="$PWD/.venv/bin/nfse"

Depois, a configuração (é o mesmo caminho que a skill segue por você):

nfse configurar certificado ~/Downloads/empresa.pfx    # pede a senha e guarda no Keychain
nfse configurar modelo ~/Downloads/nota-anterior.pdf   # ou o XML, ou a chave de acesso
nfse configurar salvar ~/.config/nfse-cli/rascunho.json
nfse emitir --tomador <cliente> --valor 100 --descricao "Teste"   # nota de teste em homologação

Primeira nota da empresa, sem nota anterior? Copie config.exemplo.toml para ~/.config/nfse-cli/config.toml e preencha; nfse servico, nfse nbs e nfse municipio ajudam a achar os códigos.

A senha do certificado fica no cofre do sistema, nunca em arquivo. Fora do macOS, por enquanto, use a variável NFSE_CERT_SENHA ou digite a senha quando o comando pedir.

Segurança

O certificado A1 assina notas em nome da empresa, e o projeto é construído em volta disso:

  • Nenhuma biblioteca de terceiros específica de NFS-e. O núcleo usa só lxml, cryptography e a biblioteca padrão do Python. Tudo o que toca o certificado está neste repositório, para você ler.
  • A senha nunca vai para arquivo. Fica no cofre do sistema (Keychain, no macOS) ou, na Lambda, no Secrets Manager. A chave privada fica em memória; ela só passa pelo disco cifrada e por instantes, porque o TLS do Python só aceita certificado de cliente vindo de arquivo.
  • Os logs nunca têm XML, dados do cliente nem senha.
  • Homologação é o padrão. Produção exige pedido explícito e confirmação: digitada no terminal, ou o código do resumo que você aprovou (na Lambda, liberação na própria função).
  • O agente nunca vê a senha. nfse configurar certificado só roda num terminal interativo, onde você digita.
  • Só conversa com a Receita, e com o GitHub para saber se há versão nova: uma consulta por dia, sem nenhum dado seu, só na linha de comando. Desliga com nfse atualizar --sem-aviso.

Achou uma falha? Veja SECURITY.md.

Linha de comando

nfse configurar certificado empresa.pfx            # copia o certificado e guarda a senha (no seu terminal)
nfse configurar modelo <xml | pdf | chave>         # lê uma nota já emitida e monta um rascunho
nfse configurar salvar rascunho.json               # valida o rascunho e grava a configuração
nfse configurar mostrar                            # a configuração atual, em português
nfse servico consultoria informática               # procura o código de tributação nacional
nfse nbs assessoria empresarial                    # procura o código NBS
nfse municipio campinas sp                         # procura o código IBGE do município
nfse skill instalar                                # copia a skill para os agentes instalados

nfse certificado                                   # titular, CNPJ e validade do certificado
nfse dps --tomador cliente --valor 9000 --descricao-arquivo desc.txt   # monta e valida, não envia
nfse emitir --tomador cliente --valor 9000 --descricao-arquivo desc.txt             # homologação
nfse emitir --producao --tomador cliente --valor 9000 --descricao-arquivo desc.txt  # produção (pede EMITIR)
nfse dps --producao --tomador cliente              # resumo com código de confirmação, sem enviar
nfse emitir --producao --tomador cliente --confirmacao A1B2C3   # emite só se nada mudou desde o resumo
nfse notas --tomador cliente                       # notas já emitidas; diz se o mês já tem nota
nfse arquivar <chave de acesso>                    # XML e PDF na pasta do cliente
nfse email <chave de acesso>                       # rascunho do e-mail com o PDF, no seu programa de e-mail
nfse email <chave de acesso> --para eu@empresa.com # teste: rascunho para você mesmo
nfse programas-de-email                            # programas de e-mail desta máquina
nfse atualizar                                     # atualiza o nfse e a skill (avisa quando há versão nova)
nfse consultar --numero 3                          # essa DPS virou nota?
nfse consultar --serie 70000 --numero 3            # idem, para uma nota do Emissor Web
nfse baixar <chave de acesso>                      # XML da nota
nfse danfse <chave de acesso>                      # PDF da nota
nfse danfse --xml nota.xml                         # PDF de um XML salvo, sem internet

Sem --valor e --descricao, valem os do cliente em [tomadores.<apelido>.recorrente]; a descrição aceita {mes}, {mes_min} e {ano}. A numeração da DPS fica em ~/.config/nfse-cli/numeracao.json, só avança depois que a nota sai e é conferida na Sefin antes de usar (um número que já virou nota é pulado). A série padrão é 1; o Emissor Web do governo usa 70000 em diante, então as duas numerações não se cruzam.

Biblioteca Python

import nfse

cfg = nfse.config_de_dict({
    "prestador": {"cnpj": "11222333000181", "cod_municipio": "3550308", "op_simp_nac": 3, "reg_ap_trib_sn": 1},
    "servico": {"c_trib_nac": "170101", "c_nbs": "114013900", "tot_trib": {"modo": "sn", "percentual": 6}},
})
cert = nfse.Certificado.de_pfx(pfx_bytes, senha)
tomador = nfse.tomador_de_dict({"documento": "11444777000161", "nome": "CLIENTE LTDA"})

r = nfse.emitir(cfg, cert, nfse.HOMOLOGACAO, serie="1", numero=1, valor="9000.00",
                descricao="Consultoria em tecnologia.", tomador=tomador)
print(r.numero_nfse, r.chave_acesso)
pdf = nfse.gerar_danfse(r.xml_nfse)

Em outro projeto, instale por versão: pip install 'nfse-cli @ git+https://github.com/regisdias/nfse-cli@v0.1.0'.

Documentação

Contribuir

Veja CONTRIBUTING.md. A regra principal: nenhum dado real (CNPJ, nome, endereço, certificado) em teste, exemplo ou issue.

Licença

MIT: use, modifique e redistribua à vontade. Este não é um software oficial da Receita Federal; confira com a sua contabilidade a configuração tributária da sua empresa.

About

Emissão de NFS-e pela API nacional (Sefin): biblioteca Python, linha de comando, AWS Lambda e skill para agentes de IA

Topics

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages