alves / nfse-php-brazil
Pacote para emissao de NFS-e para municipios brasileiros usando componentes NFePHP (https://github.com/nfephp-org)
Requires
- php: ^8.1
- ext-curl: *
- ext-dom: *
- ext-mbstring: *
- ext-openssl: *
- ext-zlib: *
- nfephp-org/sped-common: ^5.1
- setasign/fpdf: ^1.8
- symfony/var-dumper: *
- tecnickcom/tcpdf: *
Requires (Dev)
- phpunit/phpunit: ^10.5 || ^11.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Biblioteca PHP para integração de NFS-e em municípios brasileiros, com catálogo compilado de provedores, runtime por adapter e geração de DANFSe em PDF.
Visão geral
O projeto foi organizado para servir como base de uma API própria de NFS-e. Hoje ele entrega:
- resolução de município, provedor e URLs por ambiente;
- execução unificada de emissão, cancelamento, substituição e consultas;
- catálogo versionado dentro do próprio repositório;
- geração de DANFSe em PDF a partir do XML da NFS-e;
- interface web para operação, diagnóstico e testes.
Estado atual do catálogo
O projeto não depende mais de ACBr em runtime.
O catálogo já está consolidado e versionado em:
storage/municipios-catalog.phpstorage/municipios-catalog.js
Em produção, a biblioteca usa esses arquivos compilados diretamente.
Estrutura principal
src/Tools.php- fachada principal da biblioteca.
src/RestCurl.php- resolve contexto municipal, provedor e URLs.
src/Provider/- contracts, registry e adapters por provedor.
src/ProviderBuilders/- builders de envelopes e payloads por provedor.
src/Danfse/- geração de DANFSe em PDF.
storage/municipios-catalog.php- catálogo principal consumido em runtime.
storage/municipios-catalog.js- catálogo serializado para consumo auxiliar.
storage/schemes/- schemas e artefatos técnicos mantidos no projeto.
bin/municipio-info.php- utilitário simples para consulta do catálogo.
web/public/index.php- interface web de operação e homologação.
Instalação
composer require alves/nfse-php-brazil
Configuração mínima
Exemplo:
{
"tpamb": 2,
"prefeitura": "3550308",
"catalog_compiled_path": "/app/storage/municipios-catalog.php"
}
Operações principais
Consulta e diagnóstico:
detalhesMunicipio($prefeitura = null)diagnosticoMunicipio()listarMunicipios($uf = null, $provedor = null, $limit = null)municipioSuportado()
Operações municipais:
emitirNfseMunicipal($payload, $service = 'recepcionar')cancelarNfseMunicipal($payload, $service = 'cancelar_nfse')substituirNfseMunicipal($payload, $service = 'substituir_nfse')consultarMunicipal($service = 'consultar_nfse')consultarDanfseMunicipal($service = 'consultar_danfse')
Padrão nacional:
emitirNfsePadraoNacional($xmlDps)cancelarNfsePadraoNacional($evento)consultarNfseChave($chave, $encoding = true)
DANFSe
O componente já possui geração de DANFSe em PDF:
gerarDanfsePdf($xmlNfse, $outputPath = null)gerarDanfsePdfPorChave($chave, $outputPath = null)
Exemplo:
examples/GerarDanfsePdf.php
Interface web
A interface em web/public/index.php permite:
- consultar detalhes do município;
- executar diagnóstico;
- listar municípios;
- emitir, consultar, cancelar e substituir NFS-e;
- consultar NFS-e por chave;
- gerar DANFSe por chave ou por XML manual;
- visualizar request e response técnicos.
Utilitário de catálogo
Consultar um município pelo terminal:
php bin/municipio-info.php 3550308
Saída em JSON:
php bin/municipio-info.php 3550308 --json
Testes
Executar a suíte principal:
composer test
Somente municípios:
composer test:municipios
Integração:
composer test:integration
Observações
- O catálogo está versionado no repositório e pronto para uso em novos clones.
- O arquivo
.phpé a fonte principal de runtime. - O arquivo
.jsé mantido como serialização auxiliar do mesmo catálogo. - A pasta
storage/schemespermanece como apoio técnico para validações e integração com provedores.
XML nacional autorizado via SpeedGov
Além da consulta SOAP municipal, Tools::consultarXmlNacionalSpeedGov($chave, $baseUrl, $ambiente) consulta GET /{municipio}/api/v1/nfse/{chave} e devolve nota.xml_nota sem modificar os bytes do XML. A URL deve ser HTTPS e incluir o prefixo do município e /api/v1. Confirme com o provedor o endereço e a disponibilidade de notas originadas no SOAP; o catálogo SOAP não define essa URL.
$xmlNacional = $tools->consultarXmlNacionalSpeedGov($chave, $urlRestConfirmada, $tpAmb); if ($xmlNacional !== null) { // Armazene separadamente do CompNfse municipal e priorize no DANFSe. }
O retorno é null enquanto não houver XML autorizado; falhas HTTP, chave divergente ou XML inválido lançam RuntimeException. São conferidos namespace, chave de 50 dígitos, cStat=100, número da nota, DPS e ambiente. Uma DPS isolada nunca é aceita como NFS-e autorizada. A conferência estrutural não substitui validação criptográfica da assinatura. Uma falha nessa recuperação complementar não deve desfazer a autorização municipal; tente novamente na próxima consulta. O tenant integracao é sandbox e não aceita consultas de produção neste método.
Contrato: https://tributario.speedgov.com.br/integracao/api/docs/nfse
Consulta de eventos no ADN por chave
Tools::consultarEventosAdn($chave, $ambiente) consulta exclusivamente GET /contribuintes/NFSe/{ChaveAcesso}/Eventos, no host adn.nfse.gov.br para ambiente 1 ou adn.producaorestrita.nfse.gov.br para ambiente 2. Utiliza o certificado do construtor, autenticação mútua e validação TLS. Não faz consulta nem mantém controle de NSU.
O retorno contém HTTP_STATUS, STATUS_PROCESSAMENTO, ERROS, ALERTAS e DOCUMENTOS. Cada documento traz TIPO_DOCUMENTO, TIPO_EVENTO, CODIGO_EVENTO, DATA e XML descompactado de Base64/GZip, conferido quanto à chave e ao ambiente. Eventos devem ser guardados separadamente da NFS-e autorizada. E2240 significa ausência de eventos; E2241 significa falta de vínculo/acesso e não deve ser tratado como uma consulta vazia bem-sucedida. Falhas de transporte ou conteúdo inválido lançam RuntimeException.
O enum TipoDocumento é compartilhado pelo Swagger: sua opção NFSE não constitui um parâmetro para pedir o XML da nota em /Eventos. Caso o servidor efetivamente devolva tipo NFSE, a biblioteca exige o XML nacional autorizado correspondente antes de aceitá-lo. Não infira autorização/rejeição da nota a partir da ausência de eventos.
Para SpeedGov, o serviço municipal consultar_nfse monta ConsultarNfseEnvio com os campos prestador_cnpj, prestador_im e numero_nfse. O número utilizado é o municipal autorizado, não o RPS ou a DPS.