README

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

Instalação

Você pode instalar o pacote via composer:

composer require nfse-nacional/nfse-php

Uso

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

Exemplo Completo

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;

Web Services (SDK) ????

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

????️ Roadmap

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

Fase 1: Estrutura de Dados (DTOs) ✅

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

Fase 2: Serialização ✅

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

Fase 3: Assinatura Digital ✅

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

Fase 4: Web Services (SDK) ✅

• 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).

Fase 5: Documentação & Busca ✅

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

Fase 6: Testes E2E & CI/CD ????

• 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.

Testing

composer test

Changelog

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

Contributing

Por favor, veja CONTRIBUTING para detalhes.

Security

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.

???? Sponsors

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.

Credits

• A21ns1g4ts
• All Contributors

License

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