Pular para o conteúdo principal

NFS-e Nacional PHP

Suporte completo às APIs de Contribuinte (empresas) e Município (prefeituras).

Emita, consulte e cancele notas fiscais de serviço (API Contribuinte) ou gerencie documentos fiscais do seu município (API Município) — tudo com validação automática de DTOs, assinatura digital integrada e tipagem completa.

Começar Agora 🚀
use Nfse\Dto\Nfse\DpsData;
use Nfse\Xml\DpsXmlBuilder;
use Illuminate\Validation\ValidationException;

// 1. Dados vindos da sua aplicação (ex: $request->all())
$dadosDoFormulario = [
    '@attributes' => ['versao' => '1.00'],
    'infDPS' => [
        '@attributes' => ['Id' => 'DPS123456'],
        'tpAmb' => 2, // Homologação
        'dhEmi' => '2023-10-27T10:00:00',
        'verAplic' => '1.0',
        'serie' => '1',
        'nDPS' => '100',
        'dCompet' => '2023-10-27',
        'tpEmit' => 1,
        'cLocEmi' => '3550308',
        'prest' => [
            'CNPJ' => '12345678000199',
            'IM' => '12345',
            'xNome' => 'Minha Empresa Ltda'
        ],
        'toma' => [
            'CPF' => '11122233344',
            'xNome' => 'Cliente Exemplo'
        ],
        'serv' => [
            'cServ' => [
                'cTribNac' => '01.01',
                'xDescServ' => 'Desenvolvimento de Software'
            ]
        ],
        'valores' => [
            'vServPrest' => [
                'vServ' => 1000.00
            ],
            'trib' => [
                'tribMun' => [
                    'tribISSQN' => 1,
                    'tpRetISSQN' => 1
                ]
            ]
        ]
    ]
];

try {
    // 2. Validar e criar o DTO
    $dps = new DpsData($dadosDoFormulario);

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

    // 4. Resultado
    header('Content-Type: application/xml');
    echo $xml;

} catch (ValidationException $e) {
    print_r($e->errors());
}

Padronização Nacional

Totalmente compatível com o padrão nacional da NFS-e (Receita Federal), seguindo rigorosamente os schemas e regras de validação.

DTOs Tipados e Validados

Utiliza spatie/laravel-data para garantir que seus dados estejam sempre corretos antes mesmo de gerar o XML.

Integração Simplificada

Abstraia a complexidade técnica dos webservices e foque no que importa: a lógica de negócio da sua aplicação.

Assinatura Digital Nativa

Suporte completo a certificados A1 (PKCS#12) e assinatura XML-DSig, garantindo a validade jurídica de todos os documentos gerados.

Arquitetura Moderna

Desenvolvido com PHP 8.2+, aproveitando as últimas funcionalidades da linguagem para um código limpo, seguro e performático.

APIs de Serviços e Utilitários

Integração com endpoints de utilidades e serviços — Contribuinte, Municípios e ADN — para emissão, consulta, eventos e parâmetros municipais.

Por que usamos DTOs?

🛡️Segurança de Tipagem
Esqueça os arrays associativos mágicos. Com DTOs, cada propriedade tem um tipo definido (string, int, float), garantindo que você nunca envie uma string onde deveria ser um número. O PHP 8+ cuida disso para você em tempo de execução.
📚Documentação Precisa e Viva
O código é a documentação. Ao instanciar um DTO, você sabe exatamente quais campos são obrigatórios, quais são opcionais e qual o formato esperado. Não é necessário consultar manuais externos de PDF o tempo todo.
🎯Redução de Erros Humanos
Erros de digitação em chaves de array (ex: 'cpl' vs 'cnpj') são eliminados. O compilador e a IDE alertam imediatamente se você tentar acessar ou definir uma propriedade que não existe.
🧠Semântica Interpretativa
O código expressa a intenção de negócio. Em vez de estruturas genéricas, você trabalha com objetos que representam conceitos reais: Tomador, Servico, Valores. Isso torna o código mais legível e fácil de entender para novos desenvolvedores.
⚡Autocompletar na IDE
Aproveite o poder do Intellisense no VSCode ou PHPStorm. Ao digitar $tomador->, sua IDE lista todas as propriedades disponíveis, acelerando o desenvolvimento e evitando a necessidade de memorizar o layout da NFS-e.
✅Validação Centralizada
As regras de validação vivem dentro dos DTOs. Se um campo tem tamanho máximo ou formato específico, o DTO garante isso. O XML só é gerado se os dados estiverem válidos, evitando rejeições da API por erros de schema.

Poderes do SDK

🔐Gestão de Certificados
Suporte nativo a certificados A1 (PFX). O SDK gerencia o carregamento, validação da senha e extração das chaves pública e privada automaticamente.
✒️Assinatura Digital (XAdES)
Assinatura automática do XML seguindo o padrão XAdES-BES. Canonicalização, digests e tags Signature são tratadas pelo SDK.
🛡️Validação Prévia
O SDK valida os dados (DTOs) localmente antes de enviar para a API, evitando rejeições desnecessárias e acelerando o desenvolvimento.
📦Respostas Tipadas
As respostas da API são convertidas em objetos PHP. Acesse$response->chaveAcesso ou $response->erroscom autocompletar.
🔄Ambientes Configuráveis
Altere entre Produção e Homologação com uma única configuração — o SDK ajusta automaticamente URLs e cabeçalhos.
⚠️Tratamento de Erros
Exceções claras (NfseContribuinteException) ajudam a identificar se o problema foi na validação, assinatura, rede ou rejeição.

Roadmap de Desenvolvimento

✓

Fase 1: Estrutura de Dados (DTOs) ✅

DTOs tipados com spatie/laravel-data, mapeamento de campos, validações robustas e enums nativos PHP 8.1+.

✓

Fase 2: Serialização XML ✅

Geração de XML (padrão Nacional NFSe) com DpsXmlBuilder e NfseXmlBuilder totalmente funcionais.

✓

Fase 3: Assinatura Digital ✅

Suporte completo a certificados A1, XmlSigner parametrizado (SHA-1/SHA-256), validação de elemento raiz.

✓

Fase 4: Utilitários ✅

IdGenerator (DPS/NFSe), CpfCnpjGenerator (CPF/CNPJ), validadores e helpers implementados.

Fase 5: Documentação & Busca 🚀

Docusaurus com busca local Spotlight-style, documentação completa de DTOs, assinatura e utilitários.

✓

Fase 6: Web Services (SDK) ✅

Integração nativa com SEFIN Nacional e ADN: emissão, consulta, eventos e parâmetros municipais.

Fase 7: Testes E2E & CI/CD

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

Perguntas Frequentes

Este pacote atua como uma biblioteca de modelagem e validação de dados para a NFS-e Nacional. Ele fornece:

  • Cliente SDK (API): Integração nativa com os Web Services da SEFIN Nacional e ADN (DANFSe, Parâmetros Municipais).
  • Geração de XML: Criação do XML final compatível com o padrão nacional a partir de objetos PHP.
  • Validação e Documentação: DTOs que documentam cada propriedade e validam os dados automaticamente antes da geração, prevenindo erros de schema.
  • Segurança de Tipos: Garante que você está passando os dados corretos (strings, inteiros, datas) para os campos certos.
🚧 Este projeto está em desenvolvimento ativo. Algumas funcionalidades podem estar incompletas ou sujeitas a alterações.