README

Biblioteca PHP para integração com NFSe Nacional - Pacote Composer reutilizável para emissão, consulta e cancelamento de Notas Fiscais de Serviço Eletrônicas no padrão nacional.

Clean Architecture • SOLID • PSR-12 • PSR-3 (logging) • PHP 8.3+ • PHPStan Level 8

📦 Instalação

composer require marcelabeh/emissor-nfse-nacional

🚀 Uso Rápido

use MarcelaBeh\EmissorNfseNacional\Presentation\Facade\NfseNacionalFacade;
use MarcelaBeh\EmissorNfseNacional\Presentation\Factory\ConfigFactory;
use NFePHP\Common\Certificate;

// 1. Carregar certificado
$certificado = Certificate::readPfx(file_get_contents($caminhoCertificado), $senha);

// 2. Criar configuração
$config = ConfigFactory::createHomologacao('codigo-ibge-municipio');

// 3. Criar facade (aceita Configuration|array — sem cast)
$nfse = NfseNacionalFacade::create($config, $certificado);

// 4. Emitir DPS
$response = $nfse->emitirDps($dpsRequest);

📚 Documentação

✅ Requisitos

• PHP 8.3+
• ext-dom, ext-curl, ext-zlib, ext-openssl, ext-mbstring

🔧 Qualidade de Código

composer test    # PHPUnit
composer cs      # PHP-CS-Fixer (dry-run)
composer cs:fix  # PHP-CS-Fixer (aplicar)
composer stan    # PHPStan nível 8
composer check   # Tudo junto

Métricas:

• ✅ Suíte completa de testes unitários e de integração
• ✅ PHPStan nível 8 (máximo rigor) - 0 erros
• ✅ Clean Architecture com SOLID
• ✅ PSR-12 (estilo) e PSR-3 (logging)
• ✅ Conformidade com os schemas NFSe Nacional v1.00 e v1.01

📁 Estrutura

src/
├── Domain/           # Entidades e Value Objects
├── Application/     # Services e DTOs
├── Infrastructure/  # HTTP, XML, Segurança
└── Presentation/    # Facade e Factories

🏛️ Padrões Aplicados

🔄 Fluxo de Uso

1. Carregar certificado → Certificate::readPfx()
2. Criar configuração → ConfigFactory::createHomologacao() ou createProducao()
3. Instanciar facade → NfseNacionalFacade::create()
4. Montar request → DpsRequest / EventoRequest
5. Executar operação → facade->emitirDps() / consultarPorChave() / cancelar()

📄 API Principal

NfseNacionalFacade - Ponto único de entrada:

• emitirDps(DpsRequest) → NfseResponse
• consultarPorChave(string) → NfseResponse|null
• consultarDpsPorChave(string) → array
• cancelar(EventoRequest) → EventoResponse
• consultarEventos(string) → array

⚠️ Avisos Importantes

Configuração do Município

A variável prefeitura deve receber o código IBGE do município (7 dígitos), conforme especificação dos XSDs da NFSe (ABRASF).

Encoding XML

O XML pode vir em ISO-8859-1. Use o segundo parâmetro se necessário:

$nfse->consultarPorChave('CHAVE', false);

🐛 Erros da SEFIN

Quando a emissão/evento é rejeitado, a SEFIN retorna os erros estruturados. A resposta os expõe:

$response->mensagem;  // primeiro erro, ex.: "E0617 - Não é permitido informar alíquota..."
$response->erros;     // lista completa: [['codigo' => 'E0617', 'descricao' => '...'], ...]
$response->dados;     // payload cru da SEFIN

Os códigos (E0617, E1860, ...) e suas descrições vêm da própria SEFIN. Causas comuns de rejeição:

• CNPJ/CPF do prestador não habilitado na NFS-e Nacional
• Dados fiscais inconsistentes com o município/regime
• Indisponibilidade do ambiente de homologação

🤝 Créditos e Agradecimentos

Este projeto é uma reestruturação completa com Clean Architecture do projeto original.

📦 Projeto Original

• Repositório: hadder/nfse-nacional
• Autor: Fernando Friedrich (@fernando-friedrich)
• Contribuição: Base inicial e compreensão das regras de negócio NFSe Nacional

🔐 Dependências

• NFePHP/sped-common - Manipulação de certificados digitais A1/A3 e assinatura XML
  • Projeto mantido pela comunidade brasileira desde 2008
  • github.com/nfephp-org/sped-common
  • Criado por Roberto L. Machado (@robmachado)

👩‍💻 Manutenção Atual

• Marcela Beatriz (@marcelabeh)
• Arquitetura: Clean Architecture + SOLID + DDD
• Análise estática: PHPStan level 8

📜 Licença

LGPL-3.0-or-later (GNU Lesser General Public License v3.0 ou posterior)

Veja o arquivo LICENSE para detalhes completos.

💼 O que isso significa?

✅ Você PODE:

• Usar comercialmente (grátis)
• Modificar o código
• Distribuir em projetos proprietários
• Vender produtos que usam esta biblioteca

⚠️ Você DEVE:

• Manter o copyright original
• Se modificar A BIBLIOTECA, compartilhar as mudanças (LGPL)
• Incluir uma cópia da licença LGPL