nfse-nacional/nfse-php

🚀 NFS-e Nacional PHP SDK

Versão estável aberta para sugestões e melhorias

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.

📦 Instalação

composer require nfse-nacional/nfse-php

🛠️ Uso dos Serviços

O pacote expõe dois serviços principais através da NfseContext: ContribuinteService (para emissores) e MunicipioService (para prefeituras).

Configuração Inicial

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);

🏢 ContribuinteService

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');

🏛️ MunicipioService

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');

📝 Exemplo de DPS (Declaração de Prestação de Serviço)

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);

🌍 Municípios Atendidos

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:

• Monitoramento de Adesões (Portal Gov.br)
• Painel Geoestatístico de Adesões (Power BI)

🚀 Municípios Testados (Mesmo Contrato API)

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.

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.

Exemplo com Endpoint Customizado:

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
);

Endpoints por Município

Alguns municípios utilizam endpoints próprios mesmo seguindo o padrão nacional da NFS-e. Consulte a lista completa no arquivo:

👉 Endpoints por Município

📚 Documentação Completa

Para detalhes profundos sobre cada DTO e configurações avançadas, visite nossa Documentação Oficial.

License

The MIT License (MIT). Please see License File for more information.