Search by

alves / nfse-php-brazil

andersonav

Pacote para emissao de NFS-e para municipios brasileiros usando componentes NFePHP (https://github.com/nfephp-org)

Package info

github.com/andersonav/nfse-php-brazil

pkg:composer/alves/nfse-php-brazil

Statistics

Installs: 230

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v7.0.0 2026-11-04 12:42 UTC

This package is auto-updated.

Last update: 2026-11-04 12:43:44 UTC


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.php
  • storage/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/schemes permanece 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.