PHPackages                             marcelabeh/emissor-nfse-nacional - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. marcelabeh/emissor-nfse-nacional

ActiveLibrary[Payment Processing](/categories/payments)

marcelabeh/emissor-nfse-nacional
================================

Biblioteca PHP para emissão, consulta e cancelamento de NFS-e Nacional (Sefin) — Clean Architecture, validação XSD v1.01, assinatura SHA-256, suporte IBS/CBS

v2.3.0(1mo ago)1171LGPL-3.0-or-laterPHPPHP ^8.3CI passing

Since May 12Pushed 1mo agoCompare

[ Source](https://github.com/MarcelaBeh/emissor-nfse-nacional)[ Packagist](https://packagist.org/packages/marcelabeh/emissor-nfse-nacional)[ Docs](https://github.com/marcelabeh/emissor-nfse-nacional)[ RSS](/packages/marcelabeh-emissor-nfse-nacional/feed)WikiDiscussions master Synced 3w ago

READMEChangelog (10)Dependencies (7)Versions (20)Used By (0)

NFSe Padrão Nacional
====================

[](#nfse-padrão-nacional)

 [![NFSe Nacional](images/logo-nfs-e-horizontal.png)](images/logo-nfs-e-horizontal.png)

[![Packagist](https://camo.githubusercontent.com/94c6835b73451592a1df28e1b2a8a1c9309de1e5dc8b4f81992657ed44a006b8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d617263656c616265682f656d6973736f722d6e6673652d6e6163696f6e616c2e737667)](https://packagist.org/packages/marcelabeh/emissor-nfse-nacional)[![PHP Version](https://camo.githubusercontent.com/d7c4f27dd0348b109205b0fc7e563091cecc355551565680ddeac0febed65b11/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e332b2d3737374242343f6c6f676f3d706870)](https://www.php.net/)[![PHPStan](https://camo.githubusercontent.com/ff3c7f8c8667ce643f47e74532748f673482a5f95d7d4269f925f2eebbe5117e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c253230382d627269676874677265656e)](https://phpstan.org/)[![Tests](https://camo.githubusercontent.com/d940ad7f0752e2cbe0d63c50dcebf329078807390051c41fe63258f1b5c4e182/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f74657374732d70617373696e672d627269676874677265656e)](https://phpunit.de/)[![License](https://camo.githubusercontent.com/614d00210a2a803b31960d39ad46afca4b23218a83c84cf994c4cebe1929cd6f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4c47504c2d2d332e302d626c75652e737667)](LICENSE)

**Biblioteca PHP para integração com NFSe Nacional** - Pacote Composer reutilizável para emissão, consulta e cancelamento de Notas Fiscais de Serviço Eletrônicas no padrão nacional.

**Clean Architecture** • **SOLID** • **PSR-12** • **PSR-3 (logging)** • **PHP 8.3+** • **PHPStan Level 8**

---

📦 Instalação
------------

[](#-instalação)

```
composer require marcelabeh/emissor-nfse-nacional
```

🚀 Uso Rápido
------------

[](#-uso-rápido)

```
use MarcelaBeh\EmissorNfseNacional\Presentation\Facade\NfseNacionalFacade;
use MarcelaBeh\EmissorNfseNacional\Presentation\Factory\ConfigFactory;
use NFePHP\Common\Certificate;

// 1. Carregar certificado
$certificado = Certificate::readPfx(file_get_contents($caminhoCertificado), $senha);

// 2. Criar configuração
$config = ConfigFactory::createHomologacao('codigo-ibge-municipio');

// 3. Criar facade (aceita Configuration|array — sem cast)
$nfse = NfseNacionalFacade::create($config, $certificado);

// 4. Emitir DPS
$response = $nfse->emitirDps($dpsRequest);
```

📚 Documentação
--------------

[](#-documentação)

DocumentoDescrição[GUIA\_IMPLEMENTACAO.md](docs/GUIA_IMPLEMENTACAO.md)Guia completo de uso com exemplos[ARQUITETURA.md](docs/ARQUITETURA.md)Arquitetura do sistema e decisões de design[SEGURANCA\_COMPLIANCE.md](docs/SEGURANCA_COMPLIANCE.md)Diretrizes de segurança[CONTRIBUTING.md](CONTRIBUTING.md)Como contribuir[CHANGELOG.md](CHANGELOG.md)Histórico de alterações[examples/](examples/)Exemplos práticos de uso✅ Requisitos
------------

[](#-requisitos)

- PHP 8.3+
- ext-dom, ext-curl, ext-zlib, ext-openssl, ext-mbstring

🔧 Qualidade de Código
---------------------

[](#-qualidade-de-código)

```
composer test    # PHPUnit
composer cs      # PHP-CS-Fixer (dry-run)
composer cs:fix  # PHP-CS-Fixer (aplicar)
composer stan    # PHPStan nível 8
composer check   # Tudo junto
```

**Métricas:**

- ✅ Suíte completa de testes unitários e de integração
- ✅ **PHPStan nível 8** (máximo rigor) - 0 erros
- ✅ **Clean Architecture** com SOLID
- ✅ **PSR-12** (estilo) e **PSR-3** (logging)
- ✅ Conformidade com os schemas NFSe Nacional v1.00 e v1.01

📁 Estrutura
-----------

[](#-estrutura)

```
src/
├── Domain/           # Entidades e Value Objects
├── Application/     # Services e DTOs
├── Infrastructure/  # HTTP, XML, Segurança
└── Presentation/    # Facade e Factories

```

🏛️ Padrões Aplicados
--------------------

[](#️-padrões-aplicados)

PadrãoOndeClean ArchitectureSeparação em camadas (Domain → Application → Infrastructure → Presentation)Facade`NfseNacionalFacade` - ponto único de entradaFactory`ServiceFactory`, `ConfigFactory` - criação de dependênciasDTO`DpsRequest`, `NfseResponse`, `EventoRequest` - transporte de dadosValue Object`Cnpj`, `Cpf`, `Money`, `ChaveAcesso` - imutáveis e auto-validáveisValidator`DpsValidator`, `XsdValidator` - validação de entrada e XML🔄 Fluxo de Uso
--------------

[](#-fluxo-de-uso)

```
1. Carregar certificado → Certificate::readPfx()
2. Criar configuração → ConfigFactory::createHomologacao() ou createProducao()
3. Instanciar facade → NfseNacionalFacade::create()
4. Montar request → DpsRequest / EventoRequest
5. Executar operação → facade->emitirDps() / consultarPorChave() / cancelar()

```

📄 API Principal
---------------

[](#-api-principal)

**NfseNacionalFacade** - Ponto único de entrada:

- `emitirDps(DpsRequest)` → `NfseResponse`
- `consultarPorChave(string)` → `NfseResponse|null`
- `consultarDpsPorChave(string)` → `array`
- `cancelar(EventoRequest)` → `EventoResponse`
- `consultarEventos(string)` → `array`

⚠️ Avisos Importantes
---------------------

[](#️-avisos-importantes)

### Configuração do Município

[](#configuração-do-município)

A variável `prefeitura` deve receber o **código IBGE do município** (7 dígitos), conforme especificação dos XSDs da NFSe (ABRASF).

### Encoding XML

[](#encoding-xml)

O XML pode vir em ISO-8859-1. Use o segundo parâmetro se necessário:

```
$nfse->consultarPorChave('CHAVE', false);
```

🐛 Erros da SEFIN
----------------

[](#-erros-da-sefin)

Quando a emissão/evento é rejeitado, a SEFIN retorna os erros estruturados. A resposta os expõe:

```
$response->mensagem;  // primeiro erro, ex.: "E0617 - Não é permitido informar alíquota..."
$response->erros;     // lista completa: [['codigo' => 'E0617', 'descricao' => '...'], ...]
$response->dados;     // payload cru da SEFIN
```

Os códigos (`E0617`, `E1860`, ...) e suas descrições vêm da própria SEFIN. Causas comuns de rejeição:

- CNPJ/CPF do prestador não habilitado na NFS-e Nacional
- Dados fiscais inconsistentes com o município/regime
- Indisponibilidade do ambiente de homologação

🤝 Créditos e Agradecimentos
---------------------------

[](#-créditos-e-agradecimentos)

Este projeto é uma **reestruturação completa** com Clean Architecture do projeto original.

### 📦 Projeto Original

[](#-projeto-original)

- **Repositório:** [hadder/nfse-nacional](https://github.com/Rainzart/nfse-nacional)
- **Autor:** Fernando Friedrich ([@fernando-friedrich](https://github.com/Rainzart))
- **Contribuição:** Base inicial e compreensão das regras de negócio NFSe Nacional

### 🔐 Dependências

[](#-dependências)

- **NFePHP/sped-common** - Manipulação de certificados digitais A1/A3 e assinatura XML
    - Projeto mantido pela comunidade brasileira desde 2008
    - [github.com/nfephp-org/sped-common](https://github.com/nfephp-org/sped-common)
    - Criado por Roberto L. Machado ([@robmachado](https://github.com/robmachado))

### 👩‍💻 Manutenção Atual

[](#‍-manutenção-atual)

- **Marcela Beatriz** ([@marcelabeh](https://github.com/marcelabeh))
- Arquitetura: Clean Architecture + SOLID + DDD
- Análise estática: PHPStan level 8

📜 Licença
---------

[](#-licença)

**LGPL-3.0-or-later** (GNU Lesser General Public License v3.0 ou posterior)

Veja o arquivo [LICENSE](LICENSE) para detalhes completos.

### 💼 O que isso significa?

[](#-o-que-isso-significa)

✅ **Você PODE:**

- Usar comercialmente (grátis)
- Modificar o código
- Distribuir em projetos proprietários
- Vender produtos que usam esta biblioteca

⚠️ **Você DEVE:**

- Manter o copyright original
- Se modificar A BIBLIOTECA, compartilhar as mudanças (LGPL)
- Incluir uma cópia da licença LGPL

###  Health Score

48

—

FairBetter than 94% of packages

Maintenance92

Actively maintained with recent releases

Popularity18

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 54.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~2 days

Total

18

Last Release

39d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/5282c6cc82e016260bf64a68012a32317ea056f82c4d869dbfe08f2e546b726b?d=identicon)[Marcela Beh](/maintainers/Marcela%20Beh)

---

Top Contributors

[![MarcelaBeh](https://avatars.githubusercontent.com/u/102764966?v=4)](https://github.com/MarcelaBeh "MarcelaBeh (59 commits)")[![Rainzart](https://avatars.githubusercontent.com/u/563814?v=4)](https://github.com/Rainzart "Rainzart (29 commits)")[![BangemannGuilherme](https://avatars.githubusercontent.com/u/65203625?v=4)](https://github.com/BangemannGuilherme "BangemannGuilherme (3 commits)")[![jonathanpmartins](https://avatars.githubusercontent.com/u/6137992?v=4)](https://github.com/jonathanpmartins "jonathanpmartins (3 commits)")[![leandro-mafra](https://avatars.githubusercontent.com/u/17616770?v=4)](https://github.com/leandro-mafra "leandro-mafra (3 commits)")[![muriloelias](https://avatars.githubusercontent.com/u/2312096?v=4)](https://github.com/muriloelias "muriloelias (2 commits)")[![OswaldoAranda](https://avatars.githubusercontent.com/u/42947585?v=4)](https://github.com/OswaldoAranda "OswaldoAranda (2 commits)")[![gersonfs](https://avatars.githubusercontent.com/u/293154?v=4)](https://github.com/gersonfs "gersonfs (2 commits)")[![visio-simenes](https://avatars.githubusercontent.com/u/215207795?v=4)](https://github.com/visio-simenes "visio-simenes (1 commits)")[![evandro-simenes](https://avatars.githubusercontent.com/u/215207795?v=4)](https://github.com/evandro-simenes "evandro-simenes (1 commits)")[![mskamot](https://avatars.githubusercontent.com/u/11540014?v=4)](https://github.com/mskamot "mskamot (1 commits)")[![nagualcode](https://avatars.githubusercontent.com/u/13026978?v=4)](https://github.com/nagualcode "nagualcode (1 commits)")[![TI-Einov](https://avatars.githubusercontent.com/u/146743576?v=4)](https://github.com/TI-Einov "TI-Einov (1 commits)")[![ahwelp](https://avatars.githubusercontent.com/u/14235495?v=4)](https://github.com/ahwelp "ahwelp (1 commits)")

---

Tags

dpsnfsenfse-nacionalnfephpbrasilfiscalsefinnota-fiscal-servicoibscbs

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/marcelabeh-emissor-nfse-nacional/health.svg)

```
[![Health](https://phpackages.com/badges/marcelabeh-emissor-nfse-nacional/health.svg)](https://phpackages.com/packages/marcelabeh-emissor-nfse-nacional)
```

###  Alternatives

[symfony/symfony

The Symfony PHP framework

31.4k87.2M2.2k](/packages/symfony-symfony)[laravel/framework

The Laravel Framework.

34.8k543.8M20.5k](/packages/laravel-framework)[drupal/core

Drupal is an open source content management platform powering millions of websites and applications.

19566.0M1.8k](/packages/drupal-core)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)[wikimedia/parsoid

Parsoid, a bidirectional parser between wikitext and HTML5

187557.3k3](/packages/wikimedia-parsoid)[shopware/platform

The Shopware e-commerce core

3.4k1.5M3](/packages/shopware-platform)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)