PHPackages jonathanpmartins/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. [Utility & Helpers](/categories/utility) 4. / 5. jonathanpmartins/nfse-nacional ActiveLibrary[Utility & Helpers](/categories/utility) jonathanpmartins/nfse-nacional ============================== Pacote Laravel para emissão de NFSe Nacional 01PHPCI failing Since Feb 11Pushed 1mo agoCompare [ Source](https://github.com/jonathanpmartins/nfse-nacional)[ Packagist](https://packagist.org/packages/jonathanpmartins/nfse-nacional)[ RSS](/packages/jonathanpmartins-nfse-nacional/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependenciesVersions (4)Used By (0) NFSe Nacional ============= [](#nfse-nacional) [![CI](https://github.com/jonathanpmartins/nfse-nacional/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/jonathanpmartins/nfse-nacional/actions)[![Latest Version on Packagist](https://camo.githubusercontent.com/46ba7869938a3dccaabd950f11bf9332f23ad0efa34c180306339fdd0f6750d4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a6f6e617468616e706d617274696e732f6e6673652d6e6163696f6e616c2e737667)](https://packagist.org/packages/jonathanpmartins/nfse-nacional)[![PHP Version](https://camo.githubusercontent.com/b5588d568f30b62e541aea8418057b2099c9092e504f146313a23863c4248d2f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6a6f6e617468616e706d617274696e732f6e6673652d6e6163696f6e616c2e737667)](https://packagist.org/packages/jonathanpmartins/nfse-nacional)[![License](https://camo.githubusercontent.com/5ccf93cf886b5156641bef03c3d24dab384ce6fbe941b4501b9004df487d1433/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6a6f6e617468616e706d617274696e732f6e6673652d6e6163696f6e616c2e737667)](LICENSE) Pacote PHP para emissão, cancelamento, substituição e consulta de **NFSe Padrão Nacional** ([nfse.gov.br](https://www.nfse.gov.br/)) via API REST. Funciona com Laravel 11/12 ou standalone (sem framework). Funcionalidades --------------- [](#funcionalidades) - Emissão de NFSe (`emitir`) e emissão por decisão judicial (`emitirDecisaoJudicial`) - Cancelamento de NFSe (`cancelar`) - Substituição de NFSe (`substituir`) - Consulta por chave de acesso, DPS, DANFSE (URL do PDF), eventos e verificação de DPS - Assinatura digital XML com certificado A1 (PFX/P12) - Validação XSD dos documentos - Eventos Laravel opcionais (`NfseEmitted`, `NfseCancelled`, `NfseRejected`, etc.) - mTLS sem escrita nomeada em disco - 100% de cobertura de testes e tipos Requisitos ---------- [](#requisitos) - PHP 8.2+ - Extensões: `curl`, `dom`, `zlib`, `openssl`, `mbstring`, `libxml` - Laravel 11 ou 12 (opcional — funciona standalone) Instalação ---------- [](#instalação) ``` composer require jonathanpmartins/nfse-nacional ``` Configuração ------------ [](#configuração) ### Laravel [](#laravel) Publique o arquivo de configuração: ``` php artisan vendor:publish --tag=nfse-nacional-config ``` Adicione as variáveis de ambiente no `.env`: ``` NFSE_AMBIENTE=2 # 1 = Producao, 2 = Homologacao NFSE_PREFEITURA=3550308 # Codigo IBGE do municipio (7 digitos) NFSE_CERT_PATH=/caminho/cert.pfx # Caminho do certificado PFX/P12 NFSE_CERT_SENHA=senha # Senha do certificado NFSE_TIMEOUT=30 NFSE_CONNECT_TIMEOUT=10 NFSE_SIGNING_ALGORITHM=sha1 NFSE_SSL_VERIFY=true ``` ### Standalone (sem Laravel) [](#standalone-sem-laravel) ``` use Pulsar\NfseNacional\Enums\NfseAmbiente; use Pulsar\NfseNacional\NfseClient; $client = NfseClient::forStandalone( pfxContent: file_get_contents('/caminho/certificado.pfx'), senha: 'senha_certificado', prefeitura: '3550308', ambiente: NfseAmbiente::HOMOLOGACAO, ); ``` Uso --- [](#uso) ### Emitir NFSe [](#emitir-nfse) ``` $response = $client->emitir([ 'infDPS' => [ 'tpAmb' => '2', // 1 = Producao, 2 = Homologacao 'dhEmi' => date('Y-m-d\TH:i:sP'), // Data/hora emissao 'verAplic' => 'MeuSistema_v1.0', 'serie' => '1', 'nDPS' => '1', 'dCompet' => date('Y-m-d'), // Data de competencia 'tpEmit' => '1', // 1 = Prestador 'cLocEmi' => '3550308', // Codigo IBGE 7 digitos ], 'prest' => [ 'CNPJ' => '00000000000000', 'fone' => '11999999999', 'regTrib' => [ 'opSimpNac' => '2', // 1 = Nao Optante, 2 = MEI, 3 = ME/EPP 'regEspTrib' => '0', // 0 = Nenhum ], ], 'toma' => [ 'xNome' => 'Tomador Exemplo Ltda', 'CPF' => '00000000000', 'end' => [ 'xLgr' => 'Rua Exemplo', 'nro' => '100', 'xBairro' => 'Centro', 'endNac' => [ 'cMun' => '3550308', 'CEP' => '01001000', ], ], ], 'serv' => [ 'cLocPrestacao' => '3550308', 'cServ' => [ 'cTribNac' => '010101', 'xDescServ' => 'Desenvolvimento de software sob encomenda', 'cNBS' => '116030000', 'cIntContrib' => '1234', ], ], 'valores' => [ 'vServPrest' => ['vServ' => '1000.00'], 'trib' => [ 'tribMun' => [ 'tribISSQN' => '1', // 1 = Operacao tributavel 'tpRetISSQN' => '1', // 1 = Nao retido ], 'indTotTrib' => '0', ], ], ]); if ($response->sucesso) { echo "Chave: {$response->chave}\n"; echo "XML: {$response->xml}\n"; } else { foreach ($response->erros as $erro) { echo "[{$erro->codigo}] {$erro->mensagem} - {$erro->descricao}"; } } ``` ### Cancelar NFSe [](#cancelar-nfse) ``` use Pulsar\NfseNacional\Enums\CodigoJustificativaCancelamento; $response = $client->cancelar( chave: '00000000000000000000000000000000000000000000000000', codigoMotivo: CodigoJustificativaCancelamento::ErroEmissao, descricao: 'Erro na emissao da nota fiscal', ); ``` Codigos de cancelamento: `ErroEmissao`, `ServicoNaoPrestado`, `Outros`. ### Substituir NFSe [](#substituir-nfse) O método `substituir()` emite uma DPS com o grupo `subst` preenchido automaticamente. O ADN (Ambiente de Dados Nacional) cancela a nota original ao processar a DPS substituta — uma única requisição. > **Nota:** O registro do evento de cancelamento por substituição (`e105102`) via API Eventos (`POST /nfse/{chave}/eventos`) é restrito a sistemas municipais conveniados com o ADN — o autor desse evento é o município emissor (MEmis), não o contribuinte. O cancelamento da nota original ocorre automaticamente ao emitir a DPS com o grupo `subst` preenchido. ``` use Pulsar\NfseNacional\Enums\CodigoJustificativaSubstituicao; $response = $client->substituir( chave: '00000000000000000000000000000000000000000000000000', dps: $dpsSubstituta, // DPS da nota substituta (mesma estrutura do emitir) codigoMotivo: CodigoJustificativaSubstituicao::Outros, descricao: 'Substituicao por correcao de dados', ); // NfseResponse (mesmo retorno do emitir) if ($response->sucesso) { echo "Chave substituta: {$response->chave}"; } else { foreach ($response->erros as $erro) { echo "[{$erro->codigo}] {$erro->descricao}\n"; } } ``` Codigos de substituição: `DesenquadramentoSimplesNacional`, `EnquadramentoSimplesNacional`, `InclusaoRetroativaImunidadeIsencao`, `ExclusaoRetroativaImunidadeIsencao`, `RejeicaoTomadorIntermediario`, `Outros`. ### Consultas [](#consultas) ``` use Pulsar\NfseNacional\Enums\TipoEvento; // Consultar NFSe por chave de acesso $response = $client->consultar()->nfse($chave); // Consultar DPS por ID $response = $client->consultar()->dps($idDps); // Obter PDF do DANFSE $response = $client->consultar()->danfse($chave); // $response->pdf contém o conteúdo binário do PDF file_put_contents('danfse.pdf', $response->pdf); // Consultar eventos $response = $client->consultar()->eventos( chave: $chave, tipoEvento: TipoEvento::CancelamentoPorIniciativaPrestador, nSequencial: 1, ); // Verificar se DPS foi processada $processada = $client->consultar()->verificarDps($idDps); // true ou false ``` ### Laravel Facade [](#laravel-facade) ``` use Pulsar\NfseNacional\Facades\NfseNacional; // Emitir $response = NfseNacional::emitir($dps); // Cancelar $response = NfseNacional::cancelar($chave, $motivo, $descricao); // Consultar $response = NfseNacional::consultar()->nfse($chave); $danfse = NfseNacional::consultar()->danfse($chave); // Usar certificado diferente por requisicao $client = NfseNacional::for($pfxContent, $senha, '3550308'); $response = $client->emitir($dps); // Sobrescrever ambiente (ignorar config) use Pulsar\NfseNacional\Enums\NfseAmbiente; $client = NfseNacional::for($pfxContent, $senha, '3550308', NfseAmbiente::PRODUCAO); $response = $client->emitir($dps); ``` Eventos ------- [](#eventos) O pacote dispara eventos Laravel que podem ser escutados na sua aplicação: EventoPropriedadesDescricao`NfseEmitted``chave`NFSe emitida com sucesso`NfseCancelled``chave`NFSe cancelada com sucesso`NfseSubstituted``chave`, `chaveSubstituta`NFSe substituída com sucesso`NfseQueried``operacao`Consulta realizada`NfseRequested``operacao`, `metadata`Operação iniciada`NfseRejected``operacao`, `codigoErro`Operação rejeitada pela API`NfseFailed``operacao`, `message`Falha na operação**Substituição:** como `substituir` delega ao `emitir` internamente, a sequência de eventos disparados é: `NfseRequested('emitir')` → `NfseEmitted` → `NfseSubstituted` Exemplos -------- [](#exemplos) Exemplos completos de cada operação estão disponíveis no diretório [`examples/`](examples/). Testes ------ [](#testes) ``` composer test ``` Para executar todas as verificações de qualidade: ``` composer quality ``` Contribuindo ------------ [](#contribuindo) Veja [CONTRIBUTING.md](CONTRIBUTING.md) para detalhes. Créditos -------- [](#créditos) Este pacote teve como base o trabalho do projeto original [nfse-nacional](https://github.com/Rainzart/nfse-nacional) de **Fernando Friedrich**, que por sua vez foi construído sobre o [NFePHP](https://github.com/nfephp-org) de **Roberto L. Machado**. Agradecimento a todos os contribuidores que ajudaram a evoluir este projeto. Licença ------- [](#licença) MIT. Veja [LICENSE](LICENSE). ### Health Score 23 — LowBetter than 27% of packages Maintenance60 Regular maintenance activity Popularity2 Limited adoption so far Community14 Small or concentrated contributor base Maturity16 Early-stage or recently created project Bus Factor1 Top contributor holds 83.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. ### Community Maintainers ![](https://www.gravatar.com/avatar/df52d610b41e6ab418dfdb8a4b7607ebdf39dc129d60b452788827267b123985?d=identicon)[jonathanpmartins](/maintainers/jonathanpmartins) --- Top Contributors [![jonathanpmartins](https://avatars.githubusercontent.com/u/6137992?v=4)](https://github.com/jonathanpmartins "jonathanpmartins (212 commits)")[![Rainzart](https://avatars.githubusercontent.com/u/563814?v=4)](https://github.com/Rainzart "Rainzart (28 commits)")[![leandro-mafra](https://avatars.githubusercontent.com/u/17616770?v=4)](https://github.com/leandro-mafra "leandro-mafra (3 commits)")[![BangemannGuilherme](https://avatars.githubusercontent.com/u/65203625?v=4)](https://github.com/BangemannGuilherme "BangemannGuilherme (3 commits)")[![OswaldoAranda](https://avatars.githubusercontent.com/u/42947585?v=4)](https://github.com/OswaldoAranda "OswaldoAranda (2 commits)")[![muriloelias](https://avatars.githubusercontent.com/u/2312096?v=4)](https://github.com/muriloelias "muriloelias (2 commits)")[![visio-simenes](https://avatars.githubusercontent.com/u/215207795?v=4)](https://github.com/visio-simenes "visio-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)") ### Embed Badge ![Health badge](/badges/jonathanpmartins-nfse-nacional/health.svg) ``` [![Health](https://phpackages.com/badges/jonathanpmartins-nfse-nacional/health.svg)](https://phpackages.com/packages/jonathanpmartins-nfse-nacional) ``` ### Alternatives [incoming/incoming Transform loose and complex input into consistent, strongly-typed data structures 21986.9k](/packages/incoming-incoming)[orchestra/html HTML Component for Orchestra Platform 40112.6k2](/packages/orchestra-html)[bariew/yii2-event-component Attaches events to all models 2149.2k](/packages/bariew-yii2-event-component)[orchestra/memory Memory Component for Orchestra Platform 11150.0k11](/packages/orchestra-memory)[marvinrabe/laravel-wizards Simple Wizard Controller for Laravel. 301.6k](/packages/marvinrabe-laravel-wizards)[johndoh/swipe Adds swipe actions to the message list of Roundcube 115.3k](/packages/johndoh-swipe) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)