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

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

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.