README

Biblioteca PHP para emissão e gestão de NFS-e (Nota Fiscal de Serviços Eletrônica) por meio dos webservices SOAP das prefeituras, no padrão ABRASF.

Ela esconde a parte difícil da integração fiscal: montar o XML, assinar com certificado digital ICP-Brasil, se comunicar via SOAP com cada prefeitura e interpretar as respostas. Para o sistema que a utiliza, sobra uma API simples, baseada em objetos.

Projeto desenvolvido entre 2016 e 2018 e hoje descontinuado. Este repositório fica como portfólio.

Destaques

Integração fiscal com prefeituras no padrão nacional ABRASF
Mais de 30 municípios atendidos em MG, SP, PR, RS, GO, MT e MS
Dois provedores de webservice com protocolos diferentes, atrás de uma única interface:
- ISSNET, usado por dezenas de prefeituras
- BHISS, da Prefeitura de Belo Horizonte
Assinatura digital XMLDSig com certificado A1 (.pfx), incluindo assinatura dupla (RPS e lote)
Alternância entre homologação e produção por configuração
Arquivamento automático de todos os XMLs enviados e recebidos, para auditoria fiscal
Arquitetura extensível: para incluir uma nova prefeitura, basta uma linha de configuração; para um novo provedor, duas classes

Funcionalidades

Operação	ISSNET	BHISS
Envio de lote de RPS	✔	✔
Consulta de situação do lote	✔	✔
Consulta de lote (NFS-e geradas)	✔	✔
Cancelamento de NFS-e	✔	—
Link de impressão / visualização	✔	—

Ciclo de vida coberto: emissão do RPS → envio em lote → protocolo → consulta do processamento → NFS-e autorizada (número e código de verificação) → impressão ou cancelamento.

Tecnologias

Área	Tecnologias
Linguagem	PHP (POO, namespaces, autoload PSR-4)
Integração	SOAP (`SoapClient`), WSDL, padrão ABRASF
XML	DOM, SimpleXML, XPath, namespaces, canonicalização C14N
Segurança	OpenSSL, certificado ICP-Brasil A1 (PKCS#12), XMLDSig RSA
Dependências	Composer, `sped-common` (NFePHP)
Testes	PHPUnit (integração com ambientes de homologação)

Arquitetura

flowchart LR
    A[Sistema cliente] -->|RequisicaoDTO| B[UtileNfseFrontController]
    B -->|código IBGE| C[(cidades_atendidas.xml)]
    C -->|provedor + URL| B
    B --> D[Conversor<br/>ISSNET / BHISS]
    B --> E[Service<br/>ISSNET / BHISS]
    D -->|XML assinado| E
    E <-->|SOAP| F[Webservice da Prefeitura]
    E -->|RetornoDTO| A
    E -->|remessas / retornos| G[(Arquivo XML)]

Padrões aplicados:

Front Controller: um único ponto de entrada para todas as operações.
Strategy + Factory: o provedor (conversor e serviço) é escolhido em tempo de execução a partir do código IBGE do município do prestador.
Template Method: as classes abstratas (AbstractConversor e AbstractService) concentram o tratamento do certificado, a assinatura e a comunicação SOAP; cada provedor especializa apenas o que é diferente.
DTOs: a entrada e a saída da biblioteca são independentes do formato XML de cada prefeitura.
Configuração externa: municípios, provedores e URLs de homologação e produção ficam em XML, sem alterar código.

Exemplo de uso

use UtileNfse\UtileNfseFrontController;
use UtileNfse\model\dto\{ConfiguracaoDTO, LoteDTO, RequisicaoDTO};
use UtileNfse\model\enumerated\AmbienteEnum;

$config = new ConfiguracaoDTO();
$config->setDiretorioCertificados('/certificados');
$config->setNomeCertificadoPfx('empresa.pfx');
$config->setSenhaCertificado('******');
$config->setDiretorioXML('/xml');
$config->setAmbiente(AmbienteEnum::HOMOLOGACAO);

$lote = new LoteDTO();
$lote->setNumero('1');
$lote->setListaRps([$rps]);          // RpsDTO com prestador, tomador e serviço

$requisicao = new RequisicaoDTO();
$requisicao->setConfiguracao($config);
$requisicao->setPrestador($prestador); // o município do prestador define a prefeitura
$requisicao->setLote($lote);

$nfse = new UtileNfseFrontController($requisicao);

// 1. Envia o lote e recebe o protocolo
$retorno = $nfse->enviarLoteRps($lote->getNumero());
$lote->setProtocolo($retorno->getLote()->getProtocolo());

// 2. Consulta as NFS-e geradas
$retorno = $nfse->consultarLoteRps($lote->getNumero());
foreach ($retorno->getListaNfse() as $nota) {
    echo $nota->getNumero() . ' - ' . $nota->getCodigoVerificacao();
}

Para cancelar ou obter o link de impressão, a mesma fachada oferece cancelarNfse() e consultarLinkImpressaoNfse().

Estrutura

src/UtileNfse/
├── UtileNfseFrontController.php   fachada / ponto de entrada
├── conversor/                     geração e assinatura de XML por provedor
├── service/                       comunicação SOAP por provedor
└── model/
    ├── dto/                       Requisição, Lote, RPS, Pessoa, Serviço, NFS-e, Retorno
    └── enumerated/                códigos do padrão ABRASF
resources/config/
└── cidades_atendidas.xml          municípios, provedores e URLs
tests/                             testes de integração por provedor e operação

Conceitos do domínio fiscal aplicados

RPS (Recibo Provisório de Serviços) e a conversão dele em NFS-e
Lote assíncrono: envio, protocolo e consulta posterior
Tributação do serviço: ISS (próprio e retido), PIS, COFINS, INSS, IR, CSLL, alíquota, descontos condicionados e incondicionados
Item da lista de serviços (LC 116/2003), CNAE e código de tributação municipal
Natureza da operação, regime especial de tributação e Simples Nacional
Códigos de cancelamento e situação do lote no padrão ABRASF

Autor

Adélio Júnior: adelionep@gmail.com

adelio-junior / utile-nfse-php

Package info

Security

Statistics