PHPackages ownerpro/nfsen-php-sdk - 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. [Parsing & Serialization](/categories/parsing) 4. / 5. ownerpro/nfsen-php-sdk ActiveLibrary[Parsing & Serialization](/categories/parsing) ownerpro/nfsen-php-sdk ====================== Pacote Laravel para emissão de NFSe Nacional v1.0.0(1mo ago)01↑2900%[1 PRs](https://github.com/OwnerPro-Software/nfsen-php-sdk/pulls)MITPHPPHP ^8.2CI passing Since Mar 24Pushed 1mo agoCompare [ Source](https://github.com/OwnerPro-Software/nfsen-php-sdk)[ Packagist](https://packagist.org/packages/ownerpro/nfsen-php-sdk)[ Docs](https://github.com/OwnerPro-Software/nfsen-php-sdk)[ RSS](/packages/ownerpro-nfsen-php-sdk/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (14)Versions (3)Used By (0) NFSe Nacional ============= [](#nfse-nacional) [![CI](https://github.com/OwnerPro-Software/nfsen-php-sdk/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/OwnerPro-Software/nfsen-php-sdk/actions)[![PHPStan Level 10](https://camo.githubusercontent.com/d18b9a987aa81e64470a11caecf72caa66597c9ebd6b307bd1c2cb7a752b0dff/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c25323031302d627269676874677265656e2e737667)](https://phpstan.org/)[![Latest Version on Packagist](https://camo.githubusercontent.com/ac2284d27c0df60973be1492949b13901e2ec9ea5700bd9029500b9e767afccc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f776e657270726f2f6e6673656e2d7068702d73646b2e737667)](https://packagist.org/packages/ownerpro/nfsen-php-sdk)[![PHP Version](https://camo.githubusercontent.com/80046c0cdbe37282603141940b9281a9d3b54039a807fe9f7a938dc1817ea0af/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6f776e657270726f2f6e6673656e2d7068702d73646b2e737667)](https://packagist.org/packages/ownerpro/nfsen-php-sdk)[![License](https://camo.githubusercontent.com/294a159af788a7c4822c57a37f7fcec5a5f578c47339307e8ce61844e8071aaf/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6f776e657270726f2f6e6673656e2d7068702d73646b2e737667)](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 ownerpro/nfsen-php-sdk ``` Configuração ------------ [](#configuração) ### Laravel [](#laravel) Publique o arquivo de configuração: ``` php artisan vendor:publish --tag=nfsen-config ``` Adicione as variáveis de ambiente no `.env`: ``` NFSE_AMBIENTE=2 # 1 = Producao, 2 = Homologacao (aceita: 'producao', 'production', 'homologacao', 'homologation') 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 OwnerPro\Nfsen\Enums\NfseAmbiente; use OwnerPro\Nfsen\NfsenClient; $client = NfsenClient::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}"; } } ``` ### Emitir NFSe por decisão judicial [](#emitir-nfse-por-decisão-judicial) Utiliza endpoint diferente (`emit_court_order`) para notas emitidas por determinação judicial: ``` $response = $client->emitirDecisaoJudicial($dps); // Mesma estrutura de DPS e mesmo NfseResponse do emitir() ``` ### Cancelar NFSe [](#cancelar-nfse) ``` use OwnerPro\Nfsen\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 OwnerPro\Nfsen\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 OwnerPro\Nfsen\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 (tipoEvento é obrigatório) $response = $client->consultar()->eventos( chave: $chave, tipoEvento: TipoEvento::CancelamentoPorIniciativaPrestador, // e101101 nSequencial: 1, ); // Tipos disponíveis: CancelamentoPorIniciativaPrestador, CancelamentoPorIniciativaFisco, // CancelamentoPorSubstituicao, AnulacaoCancelamento // Verificar se DPS foi processada $processada = $client->consultar()->verificarDps($idDps); // true ou false ``` ### Laravel Facade [](#laravel-facade) ``` use OwnerPro\Nfsen\Facades\Nfsen; // Emitir $response = Nfsen::emitir($dps); // Cancelar $response = Nfsen::cancelar($chave, $motivo, $descricao); // Consultar $response = Nfsen::consultar()->nfse($chave); $danfse = Nfsen::consultar()->danfse($chave); // Usar certificado diferente por requisicao $client = Nfsen::for($pfxContent, $senha, '3550308'); $response = $client->emitir($dps); // Sobrescrever ambiente (ignorar config) use OwnerPro\Nfsen\Enums\NfseAmbiente; $client = Nfsen::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`, `mensagem`Falha na operação**Substituição:** como `substituir` delega ao `emitir` internamente, a sequência de eventos disparados é: `NfseRequested('emitir')` → `NfseEmitted` → `NfseSubstituted` Objetos de Resposta ------------------- [](#objetos-de-resposta) Cada operação retorna um DTO tipado e imutável: ### `NfseResponse` [](#nfseresponse) Retornado por `emitir()`, `emitirDecisaoJudicial()`, `cancelar()`, `substituir()`, `consultar()->nfse()` e `consultar()->dps()`. PropriedadeTipoDescricao`sucesso``bool`Se a operação foi aceita`chave``?string`Chave de acesso da NFSe (50 dígitos)`xml``?string`XML da NFSe processada`idDps``?string`Identificador da DPS`alertas``list`Alertas não-bloqueantes`erros``list`Erros de processamento`tipoAmbiente``?int`1 = Produção, 2 = Homologação`versaoAplicativo``?string`Versão do aplicativo da SEFIN`dataHoraProcessamento``?string`Data/hora do processamento### `DanfseResponse` [](#danfseresponse) Retornado por `consultar()->danfse()`. PropriedadeTipoDescricao`sucesso``bool`Se o PDF foi obtido`pdf``?string`Conteúdo binário do PDF`erros``list`Erros de processamento### `EventsResponse` [](#eventsresponse) Retornado por `consultar()->eventos()`. PropriedadeTipoDescricao`sucesso``bool`Se a consulta teve sucesso`xml``?string`XML do evento`erros``list`Erros de processamento`tipoAmbiente``?int`1 = Produção, 2 = Homologação`versaoAplicativo``?string`Versão do aplicativo da SEFIN`dataHoraProcessamento``?string`Data/hora do processamento### `ProcessingMessage` [](#processingmessage) Representa uma mensagem de erro ou alerta da API: PropriedadeTipoDescricao`mensagem``?string`Mensagem principal`codigo``?string`Código do erro/alerta`descricao``?string`Descrição detalhada`complemento``?string`Informação complementarExceções -------- [](#exceções) ExceçãoPaiQuando`NfseException``RuntimeException`Erros gerais (XML inválido, falha de compressão, etc.)`HttpException``NfseException`Erros HTTP 5xx sem corpo JSON. Acesse `getResponseBody()` para detalhes`CertificateExpiredException``NfseException`Certificado PFX/P12 expirado`InvalidDpsArgument``InvalidArgumentException`Campos mutuamente exclusivos ou obrigatórios violados na DPS``` use OwnerPro\Nfsen\Exceptions\CertificateExpiredException; use OwnerPro\Nfsen\Exceptions\HttpException; use OwnerPro\Nfsen\Exceptions\InvalidDpsArgument; use OwnerPro\Nfsen\Exceptions\NfseException; try { $response = $client->emitir($dps); } catch (CertificateExpiredException $e) { // Certificado expirado -- renovar } catch (InvalidDpsArgument $e) { // Dados da DPS inválidos -- corrigir payload } catch (HttpException $e) { // Erro HTTP -- $e->getCode() para status, $e->getResponseBody() para corpo } catch (NfseException $e) { // Outros erros (XML, compressão, etc.) } ``` 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 41 — FairBetter than 88% of packages Maintenance98 Actively maintained with recent releases Popularity2 Limited adoption so far Community14 Small or concentrated contributor base Maturity47 Maturing project, gaining track record Bus Factor1 Top contributor holds 84.4% 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 Unknown Total 1 Last Release 45d ago ### 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 (233 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)") --- Tags phplaravelxmlnota fiscalnfsenfse-nacionalcertificado-digitalnota-fiscal-servicoprefeitura ### Code Quality TestsPest Static AnalysisPHPStan, Psalm, Rector Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/ownerpro-nfsen-php-sdk/health.svg) ``` [![Health](https://phpackages.com/badges/ownerpro-nfsen-php-sdk/health.svg)](https://phpackages.com/packages/ownerpro-nfsen-php-sdk) ``` ### Alternatives [larastan/larastan Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel 6.4k43.5M5.2k](/packages/larastan-larastan)[laragear/preload Effortlessly make a Preload script for your Laravel application. 119363.5k](/packages/laragear-preload)[ultrono/laravel-sitemap Sitemap generator for Laravel 11, 12 and 13 36412.6k6](/packages/ultrono-laravel-sitemap) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)