PyNFSeNacionalGT 0.1.0__tar.gz

pynfsenacionalgt-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,50 @@
+name: 🐞 Reportar um bug
+description: Algo não funcionou como esperado
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Obrigado por reportar! ⚠️ **NÃO cole dados reais** — nada de certificados (`.pfx`), senhas,
+        CNPJ/CPF ou XML/PDF de notas reais. Reproduza com dados **fictícios** (ex.: CNPJ `11222333000181`).
+        Para **vulnerabilidades de segurança**, use o canal privado (ver `SECURITY.md`), não esta issue.
+  - type: textarea
+    id: o-que-aconteceu
+    attributes:
+      label: O que aconteceu?
+      description: Descreva o problema e o que você esperava que acontecesse.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduzir
+    attributes:
+      label: Como reproduzir
+      description: Passos / trecho de código mínimo (com dados fictícios).
+      render: python
+    validations:
+      required: true
+  - type: textarea
+    id: erro
+    attributes:
+      label: Mensagem de erro / E-code do SEFIN
+      description: Cole o traceback ou o código de erro (ex.: E0312). Remova qualquer dado real.
+      render: text
+  - type: input
+    id: versao
+    attributes:
+      label: Versão do PyNFSeNacional
+      placeholder: "0.1.0.dev0"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Versão do Python
+      placeholder: "3.12"
+    validations:
+      required: true
+  - type: dropdown
+    id: ambiente
+    attributes:
+      label: Ambiente
+      options: ["homologacao", "producao", "não cheguei a enviar (validação/local)"]

pynfsenacionalgt-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 🔒 Vulnerabilidade de segurança
+    url: https://github.com/Gomes343/PyNFSeNacional/security/advisories/new
+    about: Reporte em PRIVADO (não abra issue pública). Ver SECURITY.md.
+  - name: 💬 Dúvidas e discussões
+    url: https://github.com/Gomes343/PyNFSeNacional/discussions
+    about: Para perguntas de uso, ideias e ajuda da comunidade.

pynfsenacionalgt-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,36 @@
+name: 💡 Sugerir uma melhoria
+description: Propor um recurso, suporte a município/regime, ou melhoria
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problema
+    attributes:
+      label: Qual problema isso resolve?
+      description: O contexto fiscal/operacional por trás da ideia.
+    validations:
+      required: true
+  - type: textarea
+    id: proposta
+    attributes:
+      label: Proposta
+      description: O que você gostaria que o pacote fizesse.
+    validations:
+      required: true
+  - type: textarea
+    id: alternativas
+    attributes:
+      label: Alternativas consideradas
+  - type: dropdown
+    id: area
+    attributes:
+      label: Área
+      options:
+        - "Emissão (DPS/assinatura/transporte)"
+        - "DANFSe (PDF)"
+        - "Validação fiscal / E-codes"
+        - "Suporte a município/regime"
+        - "Eventos (cancelamento)"
+        - "IBS/CBS (reforma tributária)"
+        - "CLI / DX"
+        - "Documentação"
+        - "Outro"

pynfsenacionalgt-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+<!-- Obrigado pela contribuição! Preencha o que se aplica. -->
+
+## O que muda e por quê
+
+<!-- Descreva a mudança e a motivação (o "porquê", não só o "como"). -->
+
+## Como testei
+
+<!-- pytest / emissão em homologação / etc. Use sempre dados fictícios. -->
+
+## Checklist
+
+- [ ] `ruff check .`, `mypy` e `pytest` passam localmente
+- [ ] **Nenhum** dado sensível no diff (certificado, senha, `.env`, CNPJ/CPF ou nota real)
+- [ ] Regra fiscal nova documentada em `docs/conhecimento-fiscal.md` (se aplicável)
+- [ ] Mexeu em DPS/assinatura? O *golden* foi atualizado e o motivo está explicado (se aplicável)
+- [ ] Atualizei o `CHANGELOG.md` (se for mudança relevante ao usuário)

pynfsenacionalgt-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install (package + dev)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check .
+
+      - name: Type-check (mypy)
+        run: mypy
+
+      - name: Tests (pytest)
+        # requires_cert: precisa de um .pfx real — roda só localmente, nunca no CI.
+        run: pytest -m "not requires_cert"
+
+  lock:
+    # Verifica que o lock com hashes instala de forma reproduzível (ambiente canônico).
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      - name: Install from locked requirements
+        run: |
+          python -m pip install --upgrade pip
+          pip install --require-hashes -r requirements-dev.txt
+          pip install -e . --no-deps
+      - name: Smoke
+        run: pytest -m "not requires_cert and not golden"

pynfsenacionalgt-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Release
+
+# Publica no PyPI ao empurrar uma tag vX.Y.Z. Usa Trusted Publishing (OIDC) —
+# sem token/segredo no repo: configurar o publisher confiável no PyPI antes.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write          # OIDC para o Trusted Publishing do PyPI
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build (sdist + wheel)
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pynfsenacionalgt-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# ── Segredos e dados de cliente (NUNCA versionar) ─────────────────────────────
+# Certificados A1 ICP-Brasil e qualquer material criptográfico
+*.pfx
+*.p12
+*.pem
+*.key
+*.crt
+*.cer
+*.der
+*.jks
+*.keystore
+certs/
+# Configs reais de cliente (contêm CNPJ, senha do certificado, etc.)
+config/
+!examples/config-exemplo.jsonc
+!examples/config-exemplo.json
+# Variáveis de ambiente e segredos (.env, secrets.env, *.env, etc.)
+.env
+.env.*
+*.env
+secrets*
+
+# ── Saídas de emissão (XML/PDF/contadores) ────────────────────────────────────
+out/
+*.xml
+*.pdf
+!docs/**/*.pdf
+# Gabarito de teste (XML assinado pela referência PHP, cert de teste descartável — sem
+# chave privada, sem dado real): versionado de propósito p/ o golden rodar no CI.
+!tests/golden/*.xml
+
+# ── Python ────────────────────────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# ── Editores / SO ─────────────────────────────────────────────────────────────
+.vscode/
+.idea/
+.DS_Store

pynfsenacionalgt-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+Formato baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/);
+versionamento [SemVer](https://semver.org/lang/pt-BR/).
+
+## [0.1.0] - 2026-06-24
+
+### Adicionado
+- **Emissão ponta a ponta** de NFS-e pela API SEFIN Nacional (DPS):
+  `config` → `certificado` → `montar_dps` → `assinar` → **transporte mTLS** → `Nota`.
+- `dps.montar_dps`/`id_dps`: montagem da DPS (lxml, ordem do XSD AnexoI) com a lógica
+  fiscal dos E-codes; o C14N do `infDPS` bate **byte a byte** com a referência PHP.
+- `assinatura.assinar_dps`: XMLDSIG enveloped (RSA-SHA1) via `erpbrasil.assinatura` —
+  mesmo `DigestValue` do gabarito de referência.
+- `sefin.SefinClient`: transporte mTLS (`requests-pkcs12`, PKCS#12 direto), `POST /nfse`
+  (gzip+base64), `verificarDps` (idempotência) e mapeamento de E-codes. **Emissão real validada
+  em homologação** (certificado A1 real, Simples Nacional/RJ: nNFSe + chave de 50 díg + DANFSe).
+- Correção **E1229**: o XML assinado precisa do prolog `<?xml encoding="UTF-8"?>` (o SEFIN rejeita
+  sem ele) — `assinar_dps` reserializa com `xml_declaration=True`.
+- `danfse.render`: DANFSe local (PDF) via `BrazilFiscalReport` ≥ 1.0 — **dependência opcional**
+  (`pip install "PyNFSeNacionalGT[danfse]"`); o núcleo de emissão não a puxa (import lazy).
+- `config.validar`/`validar_tomador`: portão de validação fiscal (E0312/E0712/E1235…,
+  CPF/CNPJ mód-11) + loader tolerante (`ConfigError`).
+- `Certificado`: leitura do `.pfx` A1 via `cryptography` (+ fallback de cifra legada §9).
+- CLI `nfse-nacional emitir` (`--pdf`, `--xml-out`, `--verbose`); logging com redação
+  (nunca loga senha do `.pfx` nem o XML com dados do tomador).
+- Reprodutibilidade: lock com hashes (`requirements-dev.txt`), `mypy --strict`, CI em
+  matriz 3.10–3.14, golden harness (`tests/golden/`).
+
+### Limitações conhecidas / próximas versões
+- Reportar upstream o classifier de licença errado da BrazilFiscalReport (LICENSE/README=LGPL-3.0,
+  mas o classifier do pyproject diz AGPL-3.0).
+- Tomador estrangeiro/sem documento; não-optantes (Lucro Presumido/Real); eventos
+  (cancelamento); IBS/CBS (reforma tributária).

pynfsenacionalgt-0.1.0/CLAUDE.md

@@ -0,0 +1,91 @@
+# CLAUDE.md — PyNFSeNacional
+
+> Guia de desenvolvimento deste repositório. **Antes de qualquer tarefa, leia
+> [`docs/conhecimento-fiscal.md`](docs/conhecimento-fiscal.md)** — é onde mora a regra fiscal
+> (estrutura da DPS, E-codes, numeração, DANFSe). E o [`docs/roadmap.md`](docs/roadmap.md) para o
+> escopo e a ordem de build.
+
+## O que é
+
+Pacote Python público (MIT) que emite **NFS-e pela API SEFIN Nacional** (DPS) e gera o **DANFSe
+localmente**. Vai para GitHub/PyPI. Feito por um contador, para a comunidade que vai bater na
+obrigatoriedade nacional (~set/2026).
+
+## Origem
+
+- Este projeto **porta para Python puro** o conhecimento de uma **implementação de referência em
+  PHP** (privada, fora deste repositório) que já emite em produção.
+- Essa referência serve de **gabarito**: ao montar/assinar a DPS aqui, a saída é comparada byte a
+  byte com a dela (ver `tests/golden/` e o roadmap), desriscando o ponto mais delicado
+  (canonicalização XMLDSIG). O mantenedor aponta a referência via env `NFSE_PHP_REF` só ao
+  regenerar o gabarito; o CI usa o XML já versionado e não precisa dela.
+- Este repo é **autocontido e público** — **nada** de certificado, config real ou segredo entra no
+  git (ver `.gitignore`). Dados de exemplo são fictícios.
+
+## Princípio central: integrar, não reinventar
+
+Não reimplementar criptografia. Cada peça tem uma lib madura do ecossistema fiscal Python; nós
+costuramos e escrevemos só o que falta (transporte ao SEFIN + acabamento). Mapa no roadmap.
+
+| Peça | Lib | Módulo |
+|---|---|---|
+| Montar/serializar XML da DPS | `lxml` | `dps.py` |
+| Assinar XMLDSIG | `erpbrasil.assinatura` | `assinatura.py` |
+| Ler `.pfx` A1 | `cryptography` | `certificado.py` |
+| Transporte mTLS SEFIN | `requests` + próprio | `sefin.py` |
+| DANFSe (PDF) | `BrazilFiscalReport` | `danfse.py` |
+| Orquestração + CLI | — | `emissor.py`, `cli.py` |
+
+## Estrutura
+
+```
+src/pynfsenacional/  # o pacote (config/cert/dps/assinatura/sefin/danfse/cli — pipeline completo)
+docs/                # conhecimento-fiscal.md (regra) + roadmap.md (plano)
+examples/            # config-exemplo.jsonc (fictício) + emitir_exemplo.py
+tests/               # smoke + (futuro) testes de DPS/assinatura contra gabarito
+```
+
+## Como desenvolver
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest                     # smoke
+ruff check .               # lint
+```
+
+## Estado atual
+
+**Alpha — pipeline completo.** Todas as peças estão implementadas; `Emissor.emitir()` roda
+ponta a ponta: **validar → montar DPS → assinar → transporte mTLS → Nota** (+ `nota.danfse()`).
+
+- `config.py` — dataclasses + `validar()` (E-codes) + loader tolerante. ✅
+- `certificado.py` — leitura do `.pfx` via `cryptography` (+ fallback cifra legada §9). ✅
+- `dps.py` — `montar_dps`/`id_dps`; o C14N do `infDPS` bate **byte-a-byte** com o PHP (golden). ✅
+- `assinatura.py` — `assinar_dps` via `erpbrasil.assinatura`; mesmo `DigestValue` do gabarito. ✅
+- `sefin.py` — transporte mTLS (`requests-pkcs12`, P12 direto), `POST /nfse`, `verificarDps`.
+  **mTLS validado ao vivo** em homologação (handshake + `HEAD /dps`, read-only). ✅
+- `danfse.py` — DANFSe local via `BrazilFiscalReport` ≥ 1.0 (validado com XML de NFS-e real). ✅
+- `cli.py` — `nfse-nacional emitir` (`--pdf`/`--xml-out`/`--verbose`); logging com redação. ✅
+
+**Emissão real VALIDADA em homologação** (24/06): com um certificado A1 real (Simples Nacional, RJ) o
+SEFIN devolveu o `nNFSe` + a chave de 50 díg e o DANFSe foi gerado localmente. (No caminho, corrigido o
+**E1229**: faltava o prolog `<?xml encoding="UTF-8"?>` no XML assinado.)
+
+**DANFSe é dependência OPCIONAL** (`pip install PyNFSeNacionalGT[danfse]`): o núcleo de emissão usa só
+deps permissivas; a `BrazilFiscalReport` (LGPL-3.0 pelo LICENSE/README upstream — o classifier AGPL do
+pyproject deles parece engano) só entra para gerar o PDF. Import lazy em `danfse.py`.
+
+**Falta (pré-publicação):** (1) criar o repo no GitHub + reservar o nome no PyPI; (2) endurecimento a
+partir de emissões reais; (3) reportar o classifier de licença errado upstream.
+
+Tooling: `pip install -e ".[dev]"` (deps instalam no 3.10–3.14), lock com hashes
+(`requirements-dev.txt`), CI (`.github/workflows/ci.yml`), release por tag (`release.yml`).
+Testes: `pytest` (67, +2 skip locais), `ruff check .`, `mypy --strict` — tudo verde.
+
+## Regras
+
+- **Nunca** commitar `.pfx`, `config/` real, `.env`, XML/PDF de nota real.
+- Toda regra fiscal nova vai **primeiro** para `docs/conhecimento-fiscal.md`, depois para o código.
+- Ao implementar DPS/assinatura: **diffar contra o gabarito PHP** antes de mandar pro SEFIN.
+- Mensagem de commit termina com a linha de co-autoria do Claude Code quando aplicável.

pynfsenacionalgt-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Código de Conduta
+
+## Nosso compromisso
+
+No interesse de promover um ambiente aberto e acolhedor, nós, como contribuidores e mantenedores,
+nos comprometemos a fazer da participação neste projeto uma experiência livre de assédio para todos —
+independentemente de idade, identidade ou expressão de gênero, deficiência, etnia, nível de
+experiência, nacionalidade, aparência, raça, religião ou orientação sexual.
+
+## Nossos padrões
+
+Exemplos de comportamento que contribuem para um ambiente positivo:
+
+- usar linguagem acolhedora e inclusiva;
+- respeitar pontos de vista e experiências diferentes;
+- aceitar críticas construtivas com elegância;
+- focar no que é melhor para a comunidade.
+
+Comportamentos inaceitáveis incluem assédio, comentários depreciativos, ataques pessoais ou políticos,
+e divulgação de informação privada de terceiros sem permissão.
+
+## Aplicação
+
+Casos de comportamento abusivo ou inaceitável podem ser reportados de forma privada ao mantenedor
+através do GitHub ([@Gomes343](https://github.com/Gomes343)) ou pelo canal de
+**Security Advisories** do repositório. Todas as queixas serão analisadas e investigadas, resultando
+em uma resposta apropriada às circunstâncias.
+
+## Atribuição
+
+Adaptado do [Contributor Covenant](https://www.contributor-covenant.org), versão 2.1.

pynfsenacionalgt-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Como contribuir
+
+Obrigado pelo interesse! Este é um projeto da comunidade fiscal Python brasileira. Toda ajuda é
+bem-vinda — relatos de erro, melhorias de documentação, suporte a mais municípios/regimes, testes.
+
+## Antes de tudo: regra de ouro 🔒
+
+**NUNCA** inclua material sensível em commits, issues ou PRs:
+
+- certificados A1 (`.pfx`/`.p12`/`.pem`/`.key`), senhas, `.env`, tokens;
+- CNPJ/CPF, nomes ou XML/PDF de **notas reais**.
+
+O [`.gitignore`](.gitignore) já bloqueia esses padrões; os dados de exemplo e fixtures são **fictícios**.
+Se precisar reproduzir um problema, **anonimize** (use CNPJ/CPF de teste, ex.: `11222333000181`).
+
+## Ambiente de desenvolvimento
+
+```bash
+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]
+```
+
+## Antes de abrir o PR
+
+Tudo precisa passar (é o que a CI roda, na matriz 3.10–3.14):
+
+```bash
+ruff check .          # lint + ordenação de imports
+mypy                  # tipos (strict)
+pytest                # testes (inclui o golden contra a referência)
+```
+
+- **Regra fiscal nova** vai **primeiro** para [`docs/conhecimento-fiscal.md`](docs/conhecimento-fiscal.md),
+  depois para o código (o porquê fiscal precisa estar documentado).
+- Mexeu na **montagem da DPS ou na assinatura**? O *golden* (`tests/golden/`) compara a saída ao
+  gabarito de referência byte a byte. Se a mudança for legítima, regenere com
+  `bash tests/golden/regenerar_gabarito.sh` e explique o porquê no PR.
+- Mantenha o **núcleo de emissão sem dependências pesadas**; PDF/extras ficam atrás de `[danfse]`.
+
+## Estilo de commit
+
+Mensagens em **português**, no imperativo, dizendo **o quê** e **por quê** (não só o "como").
+Um assunto curto + corpo quando precisar de contexto.
+
+## Pull Requests
+
+1. Crie um branch a partir de `main`.
+2. Mantenha o PR focado num assunto.
+3. Descreva o **porquê**, como testou, e marque itens do checklist do template.
+4. CI verde é pré-requisito de merge.
+
+Dúvidas? Abra uma [issue](https://github.com/Gomes343/PyNFSeNacional/issues) — de preferência antes de
+um PR grande, para alinharmos a abordagem.

pynfsenacionalgt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Murilo Gomes Teixeira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.