PHPackages vagnerkaefer/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. [API Development](/categories/api) 4. / 5. vagnerkaefer/nfse-nacional ActiveLibrary[API Development](/categories/api) vagnerkaefer/nfse-nacional ========================== Biblioteca PHP para integração com o Sistema Nacional de Nota Fiscal de Serviço Eletrônica (NFS-e) v1.0.0(5mo ago)22061[1 issues](https://github.com/vagkaefer/nfse-nacional/issues)[1 PRs](https://github.com/vagkaefer/nfse-nacional/pulls)MITPHPPHP >=8.2CI failing Since Jan 9Pushed 5mo agoCompare [ Source](https://github.com/vagkaefer/nfse-nacional)[ Packagist](https://packagist.org/packages/vagnerkaefer/nfse-nacional)[ GitHub Sponsors](https://github.com/vagkaefer)[ Patreon](https://www.patreon.com/vagkaefer)[ RSS](/packages/vagnerkaefer-nfse-nacional/feed)WikiDiscussions main Synced yesterday READMEChangelogDependencies (3)Versions (3)Used By (0) NFS-e Nacional - Biblioteca PHP =============================== [](#nfs-e-nacional---biblioteca-php) [![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![PHP Version](https://camo.githubusercontent.com/7404ac2849f95f99ace60c4b949c4e57e3188dfc0d5df7a913378138ac571fb6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344372e342d626c7565)](https://www.php.net) Biblioteca PHP para integração com o **Sistema Nacional de Nota Fiscal de Serviço Eletrônica (NFS-e)** do governo brasileiro. Características --------------- [](#características) - ✅ Emissão de NFS-e - ✅ Consulta de NFS-e - ✅ Cancelamento de NFS-e - ✅ Suporte a ambientes de Produção e Homologação - ✅ Assinatura digital com certificado A1 (PFX) - ✅ Suporte ao Simples Nacional - ✅ Validação completa de XML conforme schema do governo Requisitos ---------- [](#requisitos) - PHP >= 8.2 - Extensões PHP: OpenSSL, DOM, cURL, JSON - Certificado Digital A1 (formato .pfx) Instalação ---------- [](#instalação) ``` composer require vagnerkaefer/nfse-nacional ``` Uso Básico ---------- [](#uso-básico) ### 1. Configuração [](#1-configuração) ``` use NFSe\Config\Config; use NFSe\Services\NFSeClient; use NFSe\Models\DPS; // Configurar o cliente $config = new Config( Config::AMBIENTE_PRODUCAO, // ou Config::AMBIENTE_HOMOLOGACAO '/caminho/para/certificado.pfx', // Caminho do certificado A1 'senha_do_certificado', // Senha do certificado '4216909', // Código IBGE do município emissor 'MeuSistema/1.0.0' // Identificação da aplicação ); $client = new NFSeClient($config); ``` ### 2. Emitir NFS-e [](#2-emitir-nfs-e) ``` // Criar DPS (Declaração de Prestação de Serviço) $dps = new DPS(); // Configurações básicas $dps->setTpAmb(Config::AMBIENTE_PRODUCAO) ->setVerAplic('MeuSistema/1.0.0') ->setSerie('900') ->setNDPS('1') ->setDCompet((new DateTime('-1 day'))->format('Y-m-d')) ->setTpEmit(1) // 1=Prestador ->setCLocEmi('4216909'); // Código IBGE do município // Dados do Prestador (quem emite a nota) $dps->setPrestador([ 'cnpj' => '00.000.000/0001-00', 'xNome' => 'RAZAO SOCIAL DO PRESTADOR', 'fone' => '4999999999', 'email' => 'contato@empresa.com.br', 'regTrib' => [ 'opSimpNac' => 3, // 3=Simples Nacional ME/EPP 'regApTribSN' => 1, // Regime de apuração 'regEspTrib' => 0 // 0=Nenhum regime especial ] ]); // Dados do Tomador (quem contrata o serviço) $dps->setTomador([ 'cnpj' => '11.111.111/0001-11', 'xNome' => 'NOME DO TOMADOR', 'endereco' => [ 'cMun' => '4204202', // Código IBGE do município 'CEP' => '89802-112', 'xLog' => 'Rua Exemplo', 'nLog' => '123', 'xBairro' => 'Centro' ], 'fone' => '4999999999', 'email' => 'tomador@email.com.br' ]); // Dados do Serviço $dps->setServico([ 'cTribNac' => '010601', // Código de tributação nacional 'xDescServ' => 'Consultoria em TI', 'cLocPrestacao' => '4216909', // Local da prestação 'xInfComp' => 'Informações adicionais aqui' ]); // Valores $valorServico = 1000.00; $dps->setValores([ 'vServ' => $valorServico, 'pTotTribSN' => 6.00, // Percentual de tributos (Simples Nacional) ]); // Emitir NFS-e try { $resultado = $client->emitirNFSe($dps); if (isset($resultado['chNFSe'])) { echo "NFS-e emitida com sucesso!\n"; echo "Chave: " . $resultado['chNFSe'] . "\n"; } } catch (Exception $e) { echo "Erro: " . $e->getMessage() . "\n"; } ``` ### 3. Consultar NFS-e [](#3-consultar-nfs-e) ``` $chaveAcesso = '42169092230797305000137000000000000321019889323870'; try { $nfse = $client->consultarNFSe($chaveAcesso); print_r($nfse); } catch (Exception $e) { echo "Erro: " . $e->getMessage() . "\n"; } ``` ### 4. Cancelar NFS-e [](#4-cancelar-nfs-e) ``` $chaveAcesso = '42169092230797305000137000000000000321019889323870'; $motivo = 'Nota emitida por engano'; try { $resultado = $client->cancelarNFSe($chaveAcesso, $motivo); echo "NFS-e cancelada com sucesso!\n"; } catch (Exception $e) { echo "Erro: " . $e->getMessage() . "\n"; } ``` Ambientes --------- [](#ambientes) ### Homologação [](#homologação) ``` $config = new Config( Config::AMBIENTE_HOMOLOGACAO, '/caminho/certificado.pfx', 'senha', '4216909', 'MeuApp/1.0' ); ``` ### Produção [](#produção) ``` $config = new Config( Config::AMBIENTE_PRODUCAO, '/caminho/certificado.pfx', 'senha', '4216909', 'MeuApp/1.0' ); ``` Códigos Importantes ------------------- [](#códigos-importantes) ### Tipo de Emitente (tpEmit) [](#tipo-de-emitente-tpemit) - `1` - Prestador - `2` - Tomador - `3` - Intermediário ### Regime Tributário (opSimpNac) [](#regime-tributário-opsimpnac) - `1` - Não Optante pelo Simples Nacional - `2` - MEI - `3` - ME/EPP (Simples Nacional) ### Tributação do ISSQN (tribISSQN) [](#tributação-do-issqn-tribissqn) - `1` - Tributável - `2` - Isento - `3` - Imune - `4` - Exigibilidade Suspensa - `5` - Não Tributável ### Retenção do ISSQN (tpRetISSQN) [](#retenção-do-issqn-tpretissqn) - `1` - Não retido - `2` - Retido pelo tomador - `3` - Retido pelo intermediário Estrutura do Projeto -------------------- [](#estrutura-do-projeto) ``` nfse-nacional/ ├── src/ │ └── NFSe/ │ ├── Config/ │ │ └── Config.php │ ├── Models/ │ │ └── DPS.php │ ├── Services/ │ │ └── NFSeClient.php │ └── Utils/ │ └── AssinaturaDigital.php ├── examples/ │ └── emitir_nfse.php ├── composer.json ├── README.md └── LICENSE ``` Exemplos -------- [](#exemplos) Veja a pasta `examples/` para exemplos de uso. Observações Importantes ----------------------- [](#observações-importantes) 1. **Certificado Digital**: Você precisa de um certificado A1 válido no formato .pfx 2. **Códigos IBGE**: Use os códigos corretos do município (7 dígitos) 3. **Série**: Em produção, utilize a série fornecida pela prefeitura (geralmente "900") 4. **Data de Competência**: Não pode ser posterior à data de emissão 5. **Endereço do Prestador**: Quando o prestador é o emitente (tpEmit=1), o endereço não deve ser informado 6. **Inscrição Municipal**: Pode não ser obrigatória em alguns municípios Documentação Oficial -------------------- [](#documentação-oficial) - [Portal NFS-e Nacional](https://www.gov.br/nfse/) - [Documentação Técnica SEFIN](https://www.gov.br/nfse/pt-br/documentacao) - [ADN API Docs (Produção)](https://adn.nfse.gov.br/docs/index.html) - [ADN API Docs (Homologação)](https://adn.producaorestrita.nfse.gov.br/docs/index.html) Tratamento de Erros ------------------- [](#tratamento-de-erros) ``` try { $resultado = $client->emitirNFSe($dps); } catch (Exception $e) { echo "Erro: " . $e->getMessage(); // Tratar erro conforme necessidade } ``` ### Erros Comuns [](#erros-comuns) - Certificado inválido ou expirado - Senha incorreta do certificado - XML inválido (não conforme schema) - Dados obrigatórios ausentes - Município não conveniado - NFS-e já cancelada - Data de competência posterior à data de emissão - Endereço do prestador informado quando não deveria Licença ------- [](#licença) MIT License - veja o arquivo [LICENSE](LICENSE) para mais detalhes. Suporte ------- [](#suporte) Para reportar problemas ou sugerir melhorias, abra uma issue no GitHub. Contribuindo ------------ [](#contribuindo) Contribuições são bem-vindas! Por favor: 1. Fork o projeto 2. Crie uma branch para sua feature (`git checkout -b feature/MinhaFeature`) 3. Commit suas mudanças (`git commit -m 'Adiciona MinhaFeature'`) 4. Push para a branch (`git push origin feature/MinhaFeature`) 5. Abra um Pull Request Autor ----- [](#autor) Vagner Kaefer - Agradecimentos -------------- [](#agradecimentos) - Governo Federal pela documentação e infraestrutura do Sistema Nacional de NFS-e, por não lançar uma portaria em Dezembro, obrigando o uso do ambiente nacional já em Janeiro, época boa de implantar mudanças, evitando que todas as empresas do país tenham suas integrações quebradas do dia pra noite, e não posso deixar de citar, obrigado por fornecer o serviço com eficiência e sem erros em Janeiro (Contem Ironia (e bastante)) ### Health Score 36 — LowBetter than 79% of packages Maintenance60 Regular maintenance activity Popularity20 Limited adoption so far Community7 Small or concentrated contributor base Maturity48 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% 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 177d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/8e726db9f91cbc1132a44a79ef44f93d45045fe9b8dc937c94c59467b9ccf204?d=identicon)[vagkaefer](/maintainers/vagkaefer) --- Top Contributors [![vagkaefer](https://avatars.githubusercontent.com/u/7691920?v=4)](https://github.com/vagkaefer "vagkaefer (2 commits)") --- Tags nota fiscalnfsenfs-efiscalsistema nacionalsefin ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/vagnerkaefer-nfse-nacional/health.svg) ``` [![Health](https://phpackages.com/badges/vagnerkaefer-nfse-nacional/health.svg)](https://phpackages.com/packages/vagnerkaefer-nfse-nacional) ``` ### Alternatives [matomo/matomo Matomo is the leading Free/Libre open analytics platform 21.7k38.9k](/packages/matomo-matomo)[nfe/nfe NFe.io PHP Library 42126.6k](/packages/nfe-nfe)[kaleu62/notafiscalsp Integração com o WebService da Prefeitura de São Paulo para emissão de NFS e NTFS utilizando a API da nota do milhão 5833.7k](/packages/kaleu62-notafiscalsp)[enotas/php-client eNotas GW API client for PHP 3157.1k](/packages/enotas-php-client)[tecnospeedsa/plugnotas Pacote para utilização do Plugnotas em PHP 2228.0k](/packages/tecnospeedsa-plugnotas)[nfephp-org/sped-nfse-ginfes API para geração e comunicação de RPS e NFSe no padão Ginfes. 455.9k](/packages/nfephp-org-sped-nfse-ginfes) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)