Download the PHP package hyperdevs/nfse without Composer
On this page you can find all versions of the php package hyperdevs/nfse. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package nfse
hyperdevs/nfse
Biblioteca PHP para emitir, consultar e cancelar NFS-e através da NFS-e Nacional (SEFIN/ADN — a plataforma unificada do governo para nota fiscal de serviço). Já inclui tudo que é necessário para assinar o XML e autenticar com o certificado digital — sem precisar instalar nenhuma biblioteca extra do NFePHP.
Este guia foi escrito para quem nunca integrou com a NFS-e Nacional antes. Siga os passos na ordem.
Seu sistema tem vários clientes, cada um com sua própria prefeitura/certificado? (ex.: um SaaS de gestão que emite nota em nome de cada empresa cadastrada) Os Passos 3 e 4 abaixo usam um único certificado fixo no
.env— ótimo para quem emite nota só para a própria empresa, mas não serve nesse caso. Pule direto para Vários clientes (multi-tenant/SaaS).
O que você precisa ter em mãos antes de começar
- PHP 8.3 ou superior, com as extensões
dom,curl,zlibeopensslhabilitadas (a maioria das instalações já vem com elas). - Um certificado digital A1 da empresa que vai emitir a nota, no formato
.pfxou.p12, e a senha dele. É esse arquivo que garante que só sua empresa pode emitir notas em seu nome. (Certificado A3 — em token/cartão — não é suportado, pois exige hardware específico.) - O código IBGE da prefeitura/município onde sua empresa está cadastrada (7 dígitos).
Ex.: São Paulo/SP =
3550308.
Passo 1 — Instalar o pacote
Passo 2 — Publicar o arquivo de configuração
Se seu projeto é Laravel, o pacote já se registra sozinho (autodiscovery). Rode:
Isso cria o arquivo config/nfse.php na sua aplicação.
Passo 3 — Configurar o .env da sua aplicação
Esta configuração fixa uma única prefeitura/certificado para toda a aplicação — use-a se você emite nota apenas em nome da sua própria empresa. Se são vários clientes com dados próprios, vá direto para Vários clientes (multi-tenant/SaaS).
Abra o .env do seu projeto (não do pacote) e adicione:
⚠️ Comece sempre com
NFSE_TP_AMB=2(homologação). Só mude para1(produção) depois de confirmar que as emissões de teste funcionam corretamente.
Com isso, o pacote já sabe ler seu certificado e assinar o XML sozinho — não precisa escrever nenhum código de segurança.
Passo 4 — Emitir sua primeira NFS-e (exemplo completo)
Passo 5 — Consultar ou cancelar uma nota já emitida
Vários clientes (multi-tenant/SaaS)
Se seu sistema emite nota em nome de vários clientes (cada um com sua própria prefeitura
e certificado digital — o cenário comum de um SaaS de gestão), não use o .env para isso:
prefeitura e certificado pertencem à conta de cada cliente, não à aplicação como um todo.
Use o NfseManager para montar uma Facade por cliente, a cada requisição, com os dados
vindos de onde quer que você os guarde (banco de dados, storage do certificado, etc.):
A partir daqui, use a $facade normalmente (emitirDps, consultarPorChave, cancelar, etc.),
igual ao Passo 4. O NfseManager não guarda estado entre clientes — cada chamada a make()
gera uma Facade isolada, então é seguro usar em uma aplicação com muitos clientes simultâneos.
💡 Guarde o certificado de cada cliente em local seguro (ex.: storage privado/criptografado), nunca versionado no código. O
.envcontinua útil apenas para valores padrão/globais, como o tipo de ambiente (homologação/produção) da aplicação toda, se fizer sentido no seu caso.
Usando fora do Laravel (PHP puro)
Problemas comuns
| Sintoma | Causa provável |
|---|---|
CertificateExpiredException |
O certificado .pfx está vencido — gere um novo com seu emissor. |
ValidationException ao emitir |
Algum campo obrigatório do DpsRequest está errado ou faltando (veja a mensagem, ela aponta o campo). |
ServiceException |
Falha de rede, timeout, ou o certificado não corresponde ao CNPJ configurado na prefeitura. |
RuntimeException ao usar app(NfseNacionalFacade::class) |
Faltou configurar NFSE_PREFEITURA/NFSE_CERTIFICADO_* no .env. Se seu sistema tem vários clientes, isso é esperado — use NfseManager::make() (veja Vários clientes (multi-tenant/SaaS)) em vez da Facade padrão. |
Se você quiser usar uma fonte de certificado diferente de um arquivo .pfx local (ex.: um
cofre de segredos ou HSM), implemente CertificateManagerInterface/XmlSignerInterface e
monte-as você mesmo, passando para NfseManager::make() — o mesmo caminho usado no cenário
multi-tenant, ou passando direto para NfseNacionalFacade::create() fora do Laravel.
Licença
MIT — veja LICENSE. O aviso de copyright deve ser mantido em cópias/distribuições do código.