README

Pacote Laravel para emissão de NFS-e pelo Sistema Nacional NFS-e (gov.br): monta e assina a DPS (layout oficial v1.01), transmite ao SEFIN Nacional, consulta Parâmetros Municipais no ADN, cancela, substitui e baixa o DANFSE — com suporte a homologação (Produção Restrita) e produção por configuração.

Foco de primeira classe: prestação de serviço de frete municipal (cTribNac 160201), com presets e validações específicas.

use Rumbleh\Nfse\Facades\Nfse;

$resultado = Nfse::emitir(
    Nfse::dps()
        ->numero(1)
        ->servicoFreteMunicipal('Frete de carga fracionada dentro de São Paulo', '3550308')
        ->valor(350.00)
);

$resultado->chaveAcesso;          // 50 dígitos
$resultado->nfseXml;              // XML da NFS-e autorizada
$resultado->urlConsultaPublica(); // link do QR Code

O que o pacote faz

Recurso	API	Endpoint
Emitir NFS-e (DPS assinada)	`Nfse::emitir()`	`POST {sefin}/nfse`
Consultar NFS-e pela chave	`Nfse::consultarNfse()`	`GET {sefin}/nfse/{chave}`
Chave a partir do nº da DPS	`Nfse::consultarChavePorNumero()`	`GET {sefin}/dps/{id}`
Verificar duplicidade	`Nfse::numeroJaEmitido()`	`HEAD {sefin}/dps/{id}`
Cancelar (evento e101101)	`Nfse::cancelar()`	`POST {sefin}/nfse/{chave}/eventos`
Substituir NFS-e	`Nfse::dps()->substituirNfse()`	via `POST /nfse` (evento e105102 automático)
Consultar eventos	`Nfse::consultarEventos()`	`GET {sefin}/nfse/{chave}/eventos`
DANFSE em PDF	`Nfse::danfse()`	ADN + fallback Emissor Nacional web
Convênio do município	`Nfse::parametros()->consultarConvenio()`	`GET {adn}/parametrizacao/{mun}/convenio`
Alíquota parametrizada	`Nfse::parametros()->consultarAliquota()`	`GET {adn}/parametrizacao/{mun}/{serv}/{comp}/aliquota`
Retenções/regimes/benefícios	`Nfse::parametros()->...`	`GET {adn}/parametrizacao/...`
Caixa de DF-e (distribuição)	`Nfse::adn()->distribuirDfe()`	`GET {adn}/contribuintes/DFe/{nsu}`

Por baixo: certificado A1 (PFX→PEM), mTLS, assinatura XMLDSig (rsa-sha1 padrão do manual oficial; sha256 opcional), GZip+Base64, validação local contra os XSDs oficiais distribuídos com o pacote, parser de erros tolerante às variações reais da API e retry para instabilidades do ambiente.

Requisitos

PHP ≥ 8.2 com ext-openssl, ext-dom, ext-zlib, ext-curl
Laravel 10, 11 ou 12 (ou uso standalone — ver examples/)
Certificado digital ICP-Brasil A1 (e-CNPJ) — arquivo .pfx/.p12 + senha
Município do prestador conveniado ao Sistema Nacional e aderente aos emissores públicos nacionais (verifique com php artisan nfse:status)

Instalação

composer require rumbleh/laravel-nfse
php artisan vendor:publish --tag=nfse-config

.env:

NFSE_AMBIENTE=homologacao            # ou "producao"
NFSE_CERT_PATH=/storage/certificado.pfx
NFSE_CERT_PASSWORD=senha-do-certificado
NFSE_PRESTADOR_CNPJ=12345678000195
NFSE_PRESTADOR_MUNICIPIO=3550308     # código IBGE (7 dígitos) do SEU estabelecimento
NFSE_SERIE=1

Diagnóstico inicial (certificado + convênio do município):

php artisan nfse:status

Primeira emissão de teste em homologação (frete municipal):

php artisan nfse:emitir-teste --valor=100.00

Homologação → Produção

O ambiente é uma configuração: NFSE_AMBIENTE=homologacao usa a Produção Restrita (sefin.producaorestrita.nfse.gov.br, tpAmb=2, notas sem validade jurídica); NFSE_AMBIENTE=producao usa sefin.nfse.gov.br com tpAmb=1. O pacote ajusta URLs e tpAmb juntos (evita a rejeição E0006). Checklist completo em docs/03-homologacao-e-producao.md.

Documentação

Guia	Conteúdo
01 · Conceitos	O Sistema Nacional: SEFIN, ADN, CNC, DPS, NFS-e, DANFSE, chave de acesso
02 · Instalação e configuração	Config completa, certificado A1, problemas comuns de PFX
03 · Homologação e produção	Produção Restrita passo a passo, checklist de virada
04 · Emissão	Builder da DPS campo a campo, numeração, substituição
05 · Frete	ISS×ICMS, código 160201, local de incidência, alíquota, retenção
06 · Consultas	Por chave, por DPS, eventos, distribuição de DF-e
07 · Cancelamento	Evento e101101, prazos municipais, substituição
08 · DANFSE	PDF: API suspensa (NT 008), fallback web, geração local
09 · Parâmetros municipais	Convênio, alíquotas, retenções, benefícios
10 · Erros comuns	Códigos E****, causas e correções

Exemplos executáveis (sem precisar de app Laravel) em examples/.

Testes

composer test                          # unitários (geram certificado fake em runtime)

# integração real com a Produção Restrita (requer seu certificado):
NFSE_CERT_PATH=/caminho/cert.pfx NFSE_CERT_PASSWORD=senha \
NFSE_PRESTADOR_CNPJ=... NFSE_PRESTADOR_MUNICIPIO=... \
vendor/bin/phpunit --filter Homologacao

Os testes validam os XMLs gerados contra os XSDs oficiais (NFSe-ESQUEMAS_XSD-v1.01-20260209) incluídos em resources/xsd/.

Limites e avisos importantes

Frete intermunicipal/interestadual NÃO é NFS-e — é ICMS, documentado por CT-e (modelo 57). Este pacote cobre apenas transporte de natureza municipal (LC 116/2003, item 16). Detalhes em docs/05-frete.md.
Emissão exclusivamente como prestador (tpEmit=1) — o Sistema Nacional rejeita emissão por tomador/intermediário na versão atual (E9996).
O grupo IBS/CBS (Reforma Tributária) é facultativo no layout v1.01 em produção (NT-004); há suporte via ->ibscbs([...]) para quando a obrigatoriedade for religada.
Guarde os XMLs retornados (storage_path na config) — eles são o documento fiscal; o DANFSE é só a representação impressa.

Licença

MIT.

rumbleh / laravel-nfse

Maintainers

Package info

Statistics

Security