PHPackages quantumtecnology/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. [PDF & Document Generation](/categories/documents) 4. / 5. quantumtecnology/nfse-nacional ActiveLibrary[PDF & Document Generation](/categories/documents) quantumtecnology/nfse-nacional ============================== Pacote para geração de NFSe Nacional usando componentes NFePHP (https://github.com/nfephp-org) 3.1.2(2w ago)1408↓69%2[1 issues](https://github.com/Quantum-Tecnology/nfse-nacional/issues)MITPHPPHP ^8.1 Since Oct 30Pushed 2w agoCompare [ Source](https://github.com/Quantum-Tecnology/nfse-nacional)[ Packagist](https://packagist.org/packages/quantumtecnology/nfse-nacional)[ RSS](/packages/quantumtecnology-nfse-nacional/feed)WikiDiscussions master Synced 3d ago READMEChangelogDependencies (28)Versions (32)Used By (0) NFSe Padrão Nacional — Quantum Tecnology ======================================== [](#nfse-padrão-nacional--quantum-tecnology) Pacote PHP para emissão, consulta e geração de DANFSe da **NFS-e Padrão Nacional** ([nfse.gov.br](https://www.nfse.gov.br/)), construído sobre os componentes [NFePHP](https://github.com/nfephp-org). Este é um **fork mantido pela [Quantum Tecnology](https://github.com/Quantum-Tecnology)** do excelente trabalho da equipe **Hadder** (ver [Créditos](#cr%C3%A9ditos)). Partindo daquela base, evoluímos o pacote com foco em **robustez em produção, suporte a prefeituras com emissor próprio e geração de DANFSe local** — recursos detalhados abaixo. > **Em uso em produção**, porém em evolução contínua. Contribuições são bem-vindas via PR. ✨ Melhorias desta versão (Quantum) ---------------------------------- [](#-melhorias-desta-versão-quantum) Além de tudo que já existia no pacote original, esta versão adiciona: ### 🧭 Roteamento inteligente por município (emissão × cancelamento × consulta) [](#-roteamento-inteligente-por-município-emissão--cancelamento--consulta) Municípios com **emissor próprio** (ex.: **Americana-SP**) aceitam o leiaute nacional, mas num endpoint específico da prefeitura — enquanto as **consultas** continuam no Ambiente Nacional (ADN/SEFIN). O pacote separa essas responsabilidades automaticamente: - **Emissão / cancelamento** → usam a URL configurada em `storage/prefeituras.json` (override da prefeitura). - **Consultas por chave** → usam sempre o Ambiente Nacional central. Isso elimina os erros `404` que ocorriam quando a consulta era enviada, por engano, ao endpoint de emissão da prefeitura. > ⚠️ **Emissão e cancelamento costumam ter endpoints DIFERENTES.** Em Americana-SP, por exemplo, a emissão vai para `.../api/adn/dps/recepcao` e o cancelamento (evento) para `.../api/adn/dps/evento`. Por isso o `storage/prefeituras.json` separa `urls` (base) de `operations` (caminho por operação): a URL final é `base + "/" + operação`. Se `cancelar_nfse` ficar vazio, o evento de cancelamento é postado na base de emissão e a prefeitura rejeita com **"DPS inválido ou não informado"**. Veja [Configuração da prefeitura](#configura%C3%A7%C3%A3o-da-prefeitura). ### 🧾 DANFSe local (sem depender do ADN) [](#-danfse-local-sem-depender-do-adn) Geração do PDF da DANFSe **diretamente a partir do XML**, sem precisar baixar o PDF oficial do Ambiente Nacional: - **`Danfse`** — DANFSe completa a partir do XML autorizado. - **`DanfseSimples`** — renderização tolerante (lê só a estrutura, não exige assinatura), ideal para **rascunhos, prévias e notas recebidas via DFe**. Útil quando o ADN está indisponível, para pré-visualização antes da transmissão, ou para notas importadas que não têm PDF oficial salvo. ### 🛡️ Validação que falha cedo e com mensagem clara [](#️-validação-que-falha-cedo-e-com-mensagem-clara) - **`cTribNac` obrigatório (6 dígitos)** é validado na montagem do DPS. Antes, um valor ausente gerava uma tag `` vazia e a SEFAZ rejeitava com **`L2103`** (XML fora do schema) — erro difícil de diagnosticar. Agora você recebe uma `InvalidArgumentException` clara, **antes** de assinar e transmitir. - **`getOperation()`** e a resolução de URL lançam exceção em chaves/origens desconhecidas, em vez de falhar silenciosamente. ### 🏷️ Namespace próprio [](#️-namespace-próprio) O namespace passou a ser **`QuantumTecnology\NfseNacional`**, alinhado aos demais pacotes da Quantum. > ⚠️ **Breaking change** ao migrar de versões anteriores: troque os `use Hadder\NfseNacional\...` por `use QuantumTecnology\NfseNacional\...`. ### 🧹 Limpeza e correções [](#-limpeza-e-correções) - Remoção de código morto e de um `dump()` que vazava no output em produção. - Correção de recursão sem `return` na geração de nomes de arquivos temporários de certificado. Instalação ---------- [](#instalação) Este pacote é distribuído via [Composer](https://getcomposer.org/): ``` composer require quantumtecnology/nfse-nacional ``` ### Requisitos [](#requisitos) - PHP 8.2+ - ext-dom, ext-curl, ext-zlib, ext-openssl, ext-mbstring Serviços implementados ---------------------- [](#serviços-implementados) MétodoDescrição`enviaDps`Emite a NFS-e (envia o DPS)`cancelaNfse`Cancela uma NFS-e autorizada`consultarNfseChave`Consulta a NFS-e pela chave (XML)`consultarDpsChave`Consulta o DPS pela chave`consultarNfseEventos`Consulta eventos de uma NFS-e`consultarDanfse`Baixa a DANFSe (PDF oficial) do ADN`Danfse` / `DanfseSimples`Gera a DANFSe **localmente** a partir do XMLExemplos de uso estão na pasta [`exemples/`](exemples/). ⚠️ Avisos importantes --------------------- [](#️-avisos-importantes) ### Configuração da prefeitura [](#configuração-da-prefeitura) A variável `prefeitura` aceita atualmente dois formatos: - Um identificador textual, por exemplo: `americana-sp` - O **código IBGE** do município (ex.: `3501608`) ⚠️ Ambos são aceitos por compatibilidade, mas **o padrão futuro será exclusivamente o código IBGE**. Recomenda-se já adotá-lo. As URLs e operações por município ficam em [`storage/prefeituras.json`](storage/prefeituras.json). #### Estrutura do `prefeituras.json` [](#estrutura-do-prefeiturasjson) Cada município tem `urls` (a **base** por ambiente) e `operations` (o **caminho** de cada operação). A URL final é montada como `base + "/" + operação` (a operação vazia `""` usa a base direta): ``` { "3501608": { // código IBGE (chave recomendada) "urls": { "sefin_producao": "https://nfse.americana.sp.gov.br/api/adn/dps", "sefin_homologacao": "https://americanahomologacao.nfe.com.br/api/adn/dps" }, "operations": { "emitir_nfse": "recepcao", // => .../api/adn/dps/recepcao "cancelar_nfse": "evento" // => .../api/adn/dps/evento } } } ``` > ⚠️ **Não deixe `cancelar_nfse` vazio quando o cancelamento usa um caminho diferente da emissão.** Se a base apontar para `.../recepcao` e `cancelar_nfse` for `""`, o evento de cancelamento será postado em `.../recepcao` e a prefeitura responderá **"DPS inválido ou não informado"**. Prefira manter a base no nível comum (`.../api/adn/dps`) e especificar cada operação. Consulte o manual da prefeitura para os endpoints corretos (emissão, evento/cancelamento, consulta por chave, download de XML/DANFSe). ### `consultarNfseChave()` e encoding [](#consultarnfsechave-e-encoding) O XML, após o `gzdecode`, vem em **ISO-8859-1**. Por padrão o método mantém ISO via `mb_convert_encoding`. Caso tenha problemas, passe `false` no segundo parâmetro para receber o XML cru: ``` // Retorna ISO-8859-1 (padrão) $tools->consultarNfseChave('CHAVE_NFSE'); // Retorna o XML cru, sem mb_convert_encoding $tools->consultarNfseChave('CHAVE_NFSE', false); ``` FAQ — E999 (erro não catalogado) -------------------------------- [](#faq--e999-erro-não-catalogado) Esse erro se refere a uma falha **não catalogada pela própria Receita**, incluindo erros de servidor (500) e problemas aleatórios. No ambiente de **homologação** costuma aparecer sem motivo aparente, enquanto em **produção** a nota normalmente é emitida sem problemas. Causa mais comum relatada: - CPF/CNPJ do **prestador** não existente / não cadastrado / não habilitado na NFS-e Nacional ou na prefeitura. Créditos -------- [](#créditos) Este fork é mantido pela **[Quantum Tecnology](https://github.com/Quantum-Tecnology)**, mas **não nasceu do zero**. Ele se apoia inteiramente no trabalho de quem veio antes. Nosso agradecimento à **equipe Hadder** e em especial ao **Fernando Friedrich** ([Rainzart/nfse-nacional](https://github.com/Rainzart/nfse-nacional)) por criar, manter e disponibilizar este pacote como Open Source. As melhorias desta versão só foram possíveis porque havia uma base sólida e bem estruturada para construir em cima. A seguir, o agradecimento original do autor — que mantemos na íntegra: > ### (por Fernando Friedrich) > > [](#por-fernando-friedrich) > > Este pacote **não caiu do céu**, **não apareceu por geração espontânea** e muito menos foi escrito do zero em um surto de genialidade de minha parte. > > Ele foi **copiado, clonado, analisado, desmontado, reaproveitado, adaptado e por fim ajustado por mim**, tendo como base pacotes de emissão de **NFSe** que eram disponibilizados como **Open Source** pelo Sr. **[Roberto L. Machado](https://github.com/robmachado)** e que, atualmente, não se encontram mais disponíveis publicamente. > > Sim, **variáveis, métodos, classes, estruturas e ideias de arquitetura** foram utilizadas como referência (copiadas) — algumas foram alteradas, outras melhoradas, outras apenas sobreviveram ao tempo — sempre tendo como principal base o projeto **[NFePHP](https://github.com/robmachado/sped-nfse)**. > > Na época da criação deste repositório, o cenário era simples: eu precisava **emitir notas fiscais para meus clientes**. Não existia nenhuma alternativa Open Source ativa e funcional em PHP, e depender de **APIs pagas** definitivamente não era uma opção para mim. > > Diante disso, fica aqui meu agradecimento **mais do que merecido** ao **Roberto**, por criar, manter e disponibilizar gratuitamente projetos como o **NFePHP**. > > Sem esse trabalho prévio, este repositório **muito provavelmente não existiria**. E, por fim, obrigado a **todas as pessoas que contribuem** com este projeto — enviando PRs, sugerindo melhorias, corrigindo bugs ou apontando problemas. A lista de contribuidores do projeto original pode ser vista em: Licença ------- [](#licença) MIT. ### Health Score 45 — FairBetter than 91% of packages Maintenance76 Regular maintenance activity Popularity20 Limited adoption so far Community18 Small or concentrated contributor base Maturity59 Maturing project, gaining track record Bus Factor2 2 contributors hold 50%+ of commits 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 ~20 days Recently: every ~0 days Total 31 Last Release 17d ago Major Versions 1.0.6 → 2.0.02026-01-03 2.3.4 → 3.0.02026-06-16 PHP version history (2 changes)1.0.0PHP ^8.2 2.3.0PHP ^8.1 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/60905574?v=4)[Luis Gustavo Santarosa Pinto](/maintainers/GustavoSantarosa)[@GustavoSantarosa](https://github.com/GustavoSantarosa) --- Top Contributors [![Rainzart](https://avatars.githubusercontent.com/u/563814?v=4)](https://github.com/Rainzart "Rainzart (30 commits)")[![GustavoSantarosa](https://avatars.githubusercontent.com/u/60905574?v=4)](https://github.com/GustavoSantarosa "GustavoSantarosa (28 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)")[![gersonfs](https://avatars.githubusercontent.com/u/293154?v=4)](https://github.com/gersonfs "gersonfs (2 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)")[![visio-simenes](https://avatars.githubusercontent.com/u/215207795?v=4)](https://github.com/visio-simenes "visio-simenes (1 commits)")[![brunoalvim](https://avatars.githubusercontent.com/u/24271696?v=4)](https://github.com/brunoalvim "brunoalvim (1 commits)")[![evandro-simenes](https://avatars.githubusercontent.com/u/215207795?v=4)](https://github.com/evandro-simenes "evandro-simenes (1 commits)")[![MarcelaBeh](https://avatars.githubusercontent.com/u/102764966?v=4)](https://github.com/MarcelaBeh "MarcelaBeh (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 nfsenfse-nacionalmei ### Code Quality Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/quantumtecnology-nfse-nacional/health.svg) ``` [![Health](https://phpackages.com/badges/quantumtecnology-nfse-nacional/health.svg)](https://phpackages.com/packages/quantumtecnology-nfse-nacional) ``` ### Alternatives [laravel/framework The Laravel Framework. 34.8k543.8M20.1k](/packages/laravel-framework)[pimcore/pimcore Content & Product Management Framework (CMS/PIM/E-Commerce) 3.8k3.8M508](/packages/pimcore-pimcore)[hadder/nfse-nacional Pacote para geração de NFSe Nacional usando componentes NFePHP (https://github.com/nfephp-org) 724.5k](/packages/hadder-nfse-nacional)[matomo/matomo Matomo is the leading Free/Libre open analytics platform 21.7k38.9k](/packages/matomo-matomo)[civicrm/civicrm-core Open source constituent relationship management for non-profits, NGOs and advocacy organizations. 751291.4k43](/packages/civicrm-civicrm-core)[prestashop/prestashop PrestaShop is an Open Source e-commerce platform, committed to providing the best shopping cart experience for both merchants and customers. 9.1k17.8k](/packages/prestashop-prestashop) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)