Discussão: modelo arquitetural estável
A bibiloteca se mostrou bastante útil no dia a dia, mas nem tudo que parece “útil” é realmente bom de verdade. Com o tempo, a gente consegue enxergar com mais clareza o ruído gerado por determinadas interfaces e abstrações.
A experiência real de utilização permitiu identificar pontos da arquitetura que podem ser refinados e simplificados, principalmente nas responsabilidades, interfaces e abstrações entre objetos e classes.
Algumas ideias presentes no modelo atual foram úteis durante a evolução do projeto, mas certas decisões arquiteturais acabaram adicionando complexidade e ruído desnecessários em alguns cenários de uso. Esse processo de amadurecimento faz parte da evolução natural do SDK.
A próxima versão será uma oportunidade para consolidar uma arquitetura mais simples, previsível e sustentável no longo prazo, além de tornar a construção de uma versão estável algo mais aberto, democrático e colaborativo com a comunidade.
A ideia é evoluir o projeto sem perder o foco principal: oferecer uma das maneiras mais modernas e eficientes de integrar aplicações PHP com a NFS-e Nacional.
Conto com a ajuda e sugestões de todos para construirmos uma versão estável sólida e sustentável no longo prazo.
composer require nfse-nacional/nfse-phpO pacote expõe dois serviços principais através da NfseContext: ContribuinteService (para emissores) e MunicipioService (para prefeituras).
use Nfse\Nfse;
use Nfse\Http\NfseContext;
use Nfse\Enums\TipoAmbiente;
$context = new NfseContext(
ambiente: TipoAmbiente::Homologacao,
certificatePath: '/path/to/certificate.pfx',
certificatePassword: 'password'
);
$nfse = new Nfse($context);Focado nas necessidades de empresas que emitem notas.
$service = $nfse->contribuinte();
// Principais Métodos:
// 1. Emitir NFS-e
$nfseData = $service->emitir($dps); // Retorna NfseData
// 2. Consultar NFS-e
$nfseData = $service->consultar('CHAVE_ACESSO');
// 3. Baixar Documentos (Notas recebidas/emitidas)
$docs = $service->baixarDfe(nsu: 100);
// 4. Outros métodos úteis
$service->consultarDps('ID_DPS');
$service->downloadDanfse('CHAVE_ACESSO'); // Retorna PDF binário
$service->registrarEvento('CHAVE_ACESSO', $xmlEvento); // Ex: Cancelamento
$service->consultarParametrosConvenio('CODIGO_MUNICIPIO');Focado nas necessidades de prefeituras e órgãos gestores.
$service = $nfse->municipio();
// Principais Métodos:
// 1. Baixar Arrecadação e Notas
$docs = $service->baixarDfe(nsu: 100, tipoNSU: 'GERAL');
// 2. Consulta Cadastral (CNC)
$dados = $service->consultarContribuinte('CPF_CNPJ');
// 3. Parâmetros e Configurações
$params = $service->consultarParametrosConvenio('CODIGO_MUNICIPIO');
$aliquotas = $service->consultarAliquota('COD_MUN', 'COD_SERV', 'COMPETENCIA');Abaixo, um exemplo completo de como montar o objeto DPS para emissão.
use Nfse\Dto\Nfse\DpsData;
use Nfse\Support\IdGenerator;
// Gerar ID único para a DPS
$idDps = IdGenerator::generateDpsId('12345678000199', '3550308', '1', '1001');
$dps = new DpsData([
'@attributes' => ['versao' => '1.00'],
'infDPS' => [
'@attributes' => ['Id' => $idDps],
'tpAmb' => 2, // 1-Produção, 2-Homologação
'dhEmi' => date('Y-m-d\TH:i:s'),
'verAplic' => '1.0.0',
'serie' => '1',
'nDPS' => '1001',
'dCompet' => date('Y-m-d'),
'tpEmit' => 1, // 1-Prestador
'cLocEmi' => '3550308', // Código IBGE Município
'prest' => [
'CNPJ' => '12345678000199'
],
'toma' => [
'CPF' => '11122233344',
'xNome' => 'Cliente Exemplo'
],
'serv' => [
'locPrest' => [
'cLocPrestacao' => '3550308'
],
'cServ' => [
'cTribNac' => '01.01', // Código Tributação Nacional
'xDescServ' => 'Desenvolvimento de Software'
]
],
'valores' => [
'vServPrest' => [
'vReceb' => 1000.00,
'vServ' => 1000.00
],
'trib' => [
'tribMun' => [
'tribISSQN' => 1, // 1-Tributável
'tpRetISSQN' => 2, // 1-Retido, 2-Não Retido
'pAliq' => 5.00
]
]
]
]
]);
// Emitir
$nfse->contribuinte()->emitir($dps);A biblioteca é compatível com todos os municípios que aderiram ao padrão nacional da NFS-e. Você pode consultar a lista atualizada de municípios conveniados através dos links oficiais:
Alguns municípios utilizam servidores próprios, mas seguem rigorosamente o contrato da API Nacional (DPS). Então resolvemos corretamente os endpoints no pacote. Abaixo temos uma lista de municipios que foram testados nesse contexto.
| Município | UF | Status | Observação |
|---|---|---|---|
| Catanduva | SP | ✅ Testado | Utiliza infraestrutura própria (RLZ) seguindo contrato nacional. |
Para esses municípios o downloadDanfse() também busca o PDF no servidor da própria prefeitura
({endpoint}/danfse/{chaveAcesso}/pdf), em vez do ambiente nacional (que frequentemente responde 503).
A chamada não muda: basta informar o codigoMunicipio no NfseContext.
Para os demais municípios (que passam pelo ambiente nacional), as consultas e downloads são repetidos automaticamente até 2 vezes quando o servidor responde 502/503/504 ou derruba a conexão, com backoff de 1s e 2s. Envios (POST) nunca são repetidos, para não duplicar NFS-e ou evento.
O pacote também permite que você informe endpoints próprios caso você queira usar um servidor diferente.
use Nfse\Http\NfseContext;
use Nfse\Dto\Http\Endpoint;
use Nfse\Enums\TipoAmbiente;
$context = new NfseContext(
ambiente: TipoAmbiente::Producao,
certificatePath: '/path/to/cert.pfx',
certificatePassword: 'password',
endpoint: new Endpoint([
'production' => 'https://164.152.60.237/nota/nacional',
'homologation' => 'https://catanduva.prefeitura.rlz.com.br/nota/nacional',
])
);Ou enviar o código do município homologado pela nfse-nacional/nfse-php através do parâmetro correspondente
use Nfse\Http\NfseContext;
use Nfse\Dto\Http\Endpoint;
use Nfse\Enums\TipoAmbiente;
$context = new NfseContext(
ambiente: TipoAmbiente::Producao,
certificatePath: '/path/to/cert.pfx',
certificatePassword: 'password',
codigoMunicipio: '3511102' // Catanduva/SP
);Alguns municípios utilizam endpoints próprios mesmo seguindo o padrão nacional da NFS-e. Consulte a lista completa no arquivo:
Para detalhes profundos sobre cada DTO e configurações avançadas, visite nossa Documentação Oficial.
The MIT License (MIT). Please see License File for more information.