A maneira mais moderna e eficiente de integrar PHP com a NFS-e Nacional.

Este pacote é a fundação do ecossistema para integração com a NFS-e Nacional. O foco é garantir contratos sólidos, modelos de dados ricos (DTOs) e facilidade de uso para desenvolvedores PHP. Ele fornece um conjunto robusto de DTOs que simplificam a criação e validação dos XMLs, oferecendo uma interface fluida e uma documentação alinhada à realidade do desenvolvedor.

📚 Documentação Técnica: nfse.netlify.app

Você pode instalar o pacote via composer:

composer require nfse-nacional/nfse-php

Exemplo básico de utilização dos DTOs:

use Nfse\Dto\DpsData;

// Exemplo de instanciação (ajuste conforme sua necessidade)
$dps = DpsData::from([
    '@versao' => '1.00',
    'infDPS' => [
        // ... dados da DPS
    ]
]);

Abaixo, um exemplo de como gerar o ID, criar o objeto DPS, gerar o XML e assiná-lo digitalmente.

use Nfse\Dto\DpsData;
use Nfse\Xml\DpsXmlBuilder;
use Nfse\Signer\Certificate;
use Nfse\Signer\XmlSigner;
use Nfse\Support\IdGenerator;

// 1. Gerar o ID da DPS
// Formato: DPS + Cód.Mun.(7) + Tipo Inscr.(1) + Inscr.Fed.(14) + Série(5) + Número(15)
$id = IdGenerator::generateDpsId('12345678000199', '3550308', '1', '1001');

// 2. Instanciar o DTO (você pode usar arrays ou objetos)
$dps = DpsData::from([
    '@versao' => '1.00',
    'infDPS' => [
        '@Id' => $id,
        'tpAmb' => 2, // 2 - Homologação
        'dhEmi' => date('Y-m-d\TH:i:s'),
        'verAplic' => '1.0',
        'serie' => '1',
        'nDPS' => '1001',
        'dCompet' => date('Y-m-d'),
        'tpEmit' => 1, // 1 - Prestador
        'cLocEmi' => '3550308', // São Paulo - SP
        'prest' => [
            'CNPJ' => '12345678000199',
            'IM' => '12345',
        ],
        'toma' => [
            'CPF' => '11122233344',
            'xNome' => 'Tomador Exemplo',
        ],
        'serv' => [
            'locPrest' => [
                'cLocPrest' => '3550308',
            ],
            'cServ' => [
                'cTribNac' => '1.01',
                'xDescServ' => 'Analise de sistemas',
            ],
        ],
        'valores' => [
            'vServPrest' => [
                'vReceb' => 1000.00,
                'vServ' => 1000.00,
            ],
            'trib' => [
                'tribISSQN' => 1, // 1 - Operação tributável
                'tpRetISSQN' => 1, // 1 - Não Retido
            ],
        ],
    ]
]);

// 3. Gerar o XML
$builder = new DpsXmlBuilder();
$xml = $builder->build($dps);

// 4. Assinar o XML
// Carregue seu certificado A1 (PKCS#12)
$cert = new Certificate('/caminho/para/certificado.pfx', 'senha123');
$signer = new XmlSigner($cert);

// Assina a tag 'infDPS'
$signedXml = $signer->sign($xml, 'infDPS');

// Agora você pode enviar $signedXml para a API da Nacional
echo $signedXml;

O pacote agora inclui uma camada de serviços de alto nível para integração direta com a SEFIN Nacional e o ADN.

use Nfse\Nfse;
use Nfse\Http\NfseContext;
use Nfse\Enums\TipoAmbiente;

$context = new NfseContext(
    ambiente: TipoAmbiente::Homologacao,
    certificatePath: '/caminho/para/certificado.p12',
    certificatePassword: 'senha'
);

$nfse = new Nfse($context);

// Emitir uma nota (Contribuinte)
$contribuinte = $nfse->contribuinte();
$resultado = $contribuinte->emitir($dps);

// Baixar arrecadação (Município)
$municipio = $nfse->municipio();
$notas = $municipio->baixarDfe(100);

Este projeto está em desenvolvimento ativo. Abaixo estão as fases planejadas:

• Implementar DTOs usando spatie/laravel-data.
• Mapear campos do Excel usando atributos.
• Testes unitários de validação.

• Implementar Serializer para XML.
• Garantir conformidade com XSDs oficiais.

• Suporte a certificado A1 (PKCS#12).
• Implementação de XML-DSig.

• Integração com SEFIN Nacional (Emissão/Consulta).
• Integração com ADN (Distribuição/Parâmetros).
• Integração com CNC (Cadastro Nacional).
• Camada de serviços simplificada (ContribuinteService e MunicipioService).

• Docusaurus com busca local.
• Documentação completa de serviços e DTOs.

• Testes end-to-end com ambiente de homologação.
• GitHub Actions para CI/CD.
• Releases automáticas.

Para mais detalhes, consulte o arquivo ROADMAP.md.

composer test

Por favor, veja CHANGELOG para mais informações sobre o que mudou recentemente.

Por favor, veja CONTRIBUTING para detalhes.

Se você descobrir alguma vulnerabilidade de segurança, por favor, envie um e-mail para o mantenedor em vez de usar o rastreador de problemas.

Este projeto é mantido de forma independente e só é possível graças à parceria técnica com empresas e municípios parceiros. Por questões de compliance e confidencialidade, esses parceiros não podem ser citados nominalmente, mas seu apoio foi fundamental para chegarmos até aqui.

Para garantir a continuidade, manutenção e evolução constante do SDK, precisamos de novos patrocinadores. Os custos do projeto incluem:

• Infraestrutura de CI/CD: Execução de testes automatizados e builds via GitHub Actions.
• Agentes de IA: Utilização de ferramentas avançadas de codificação para acelerar o desenvolvimento.
• Café e Tempo: Manter um projeto desse porte exige dedicação exclusiva e, claro, muito café!

Se este projeto é útil para você ou sua empresa, considere nos apoiar através do GitHub Sponsors.

• A21ns1g4ts
• All Contributors

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