Download the PHP package mendesalexandre/php-nfse-nacional without Composer

mendesalexandre/php-nfse-nacional

SDK PHP framework-agnostic para integração com NFS-e Nacional (Padrão Brasileiro SEFIN). Funciona em Laravel, Symfony, projeto vanilla — qualquer coisa com PHP 8.1+ e suporte a PSR-3/PSR-18.

📖 Documentação:

• Este README — quickstart, instalação, exemplos rápidos
• MANUAL.md — referência completa da API (cada método: assinatura, parâmetros, retorno, exceções)
• CHANGELOG.md — histórico de versões
• examples/ — scripts ponta-a-ponta (emitir, cancelar, substituir, consultar, download, danfse-local)

Status

Ciclo de vida da NFS-e completo: emissão, consulta, cancelamento, substituição, manifestação, download (com retry), DANFSe NT 008/2026 e Distribuição de DFe (caixa postal do CNPJ). Cobertura ampla do DPS conforme leiaute V1.00.02: Intermediário (<interm>), Informações Complementares (<infoCompl>), Deduções com documentos referenciados (<docDedRed>), PIS/COFINS e retenções federais (<tribFed>), <tribMun> completo (imunidade, exportação, benefício municipal, exigibilidade suspensa). XSDs oficiais versionados em docs/schemas/. PHPStan level 8 limpo, 336 testes verdes, validado ponta-a-ponta em homologação SEFIN. Pré-1.0 — API pode sofrer ajustes minor antes do 1.0.0; ver CHANGELOG.

Por que

• Suporte completo ao leiaute SefinNacional 1.6 / V1.00.02 do Sistema Nacional NFS-e
• Suporte à NT 008/2026 (novo DANFSe válido a partir de 1º/jul/2026)
• Cobertura tributária ampla: imunidade, exportação, benefício municipal, exigibilidade suspensa, dispensa de ISSQN para MEI
• Tabelas oficiais como enums tipados: ListaServicosNacional (335 cases da LC 116/2003) e ListaNbs (917 cases)
• Sem dependência de framework — funciona em Laravel, Symfony, projetos vanilla
• Intermediário (<interm>) — marketplaces, plataformas de delivery, agências de turismo
• Deduções com documentos (<docDedRed>) — construção civil (materiais/subempreitada), repasses, reembolsos
• PIS/COFINS + retenções federais (<tribFed>) — CST configurável
  • retenções de IRRF/CP/CSLL
• Distribuição de DFe paginada (caixa postal do CNPJ no SEFIN), com helpers chavesCanceladas, statusPorChave, agruparPorChave, etc.
• Detecção de cancelamento via $nfse->verificarCancelamento($chave) (forma canônica — consultar() retorna cStat=100 mesmo após cancelar)
• Retry automático com backoff exponencial no download de DANFSe (502/503/504)
• Verificação idempotente de DPS (HEAD /dps/{id}) antes de emitir
• Tipagem forte (PHPStan level 8)
• Comércio exterior (<comExt>) — exportação de serviços + códigos BACEN de moeda + mecanismos de fomento PROEX/BNDES-Exim
• Construção civil (<obra>) — CNO/CIB ou endereço
• Eventos (<atvEvento>) — shows, conferências, etc.
• Endereço internacional (<endExt>) em Tomador e Intermediário — exportação, marketplace global, tomador estrangeiro
• Testes desde o dia 1 — 336 testes verdes em CI (PHP 8.1–8.5)

Requisitos

• PHP ^8.1
• Extensões: dom, openssl, libxml, zlib, mbstring
• Certificado digital A1 (.pfx) do prestador
• OpenSSL com legacy provider habilitado (rsa-sha1) — ver Configuração OpenSSL

Instalação

Uso rápido

Cancelamento

Cenários tributários comuns

MEI (dispensa do ISSQN apurado):

Tomador estrangeiro (exportação de serviço):

Retenção do ISSQN (3 estados):

Imunidade (templos, partidos, livros, etc.):

Benefício Municipal (redução de BC concedida pelo município):

Códigos de serviço via enum (LC 116):

Intermediário (marketplace / plataforma):

Informações complementares na NFS-e:

Deduções com documentos (construção civil, repasses):

PIS/COFINS retido + IRRF/CP/CSLL:

Idempotência: verificar antes de emitir

Pra evitar dupla emissão (sequencial DPS reutilizado, retry agressivo do cliente, etc.), use verificarDps() antes de chamar emitir():

Usa HEAD /dps/{id} — leve, sem baixar o corpo.

Distribuição de DFe (caixa postal)

Quando alguém emite uma NFS-e contra o seu CNPJ (como tomador), o SEFIN guarda numa "caixa postal" associada ao CNPJ. O método sincronizarDfe() itera por todos os DFes desde o último NSU conhecido:

O loop interno paginado pega até 20 páginas (= até 1000 DFes) por chamada. Para auditoria de eventos vinculados a uma NFS-e específica, use listarEventos($chave).

Substituição

Cancela uma NFS-e e a vincula a uma substituidora previamente emitida. A substituidora precisa ter sido emitida antes via $nfse->emitir(...).

Eventos customizados

Pra outros tipos de evento que aparecerem no leiaute, implemente a interface EventoNfse e use o EventoBuilder diretamente — sem alterar o SDK:

Configuração OpenSSL

OpenSSL 3.5+ (Fedora 43, RHEL 9) desabilita SHA1 por padrão. A DPS do SEFIN usa rsa-sha1 — sem habilitar legacy, openssl_sign falha com error:03000098:digital envelope routines::invalid digest.

Opção 1 (recomendada em prod): env var

Criar /etc/ssl/openssl-sha1.cnf:

Setar no Supervisor/php-fpm:

Opção 2 (dev/local): runtime

Arquitetura

Roadmap

• [x] Estrutura + composer + DTOs + Config
• [x] Certificate + Signer rsa-sha1 (com fallback SAN OID 2.16.76.1.3.3)
• [x] DpsBuilder com cobertura completa <tribMun> (BM/exigSusp/imunidade)
• [x] SefinClient + EmissaoService
• [x] ConsultaService (status NFS-e, eventos)
• [x] CancelamentoService (e101101)
• [x] DownloadService (XML + PDF + retry exponencial no DANFSe)
• [x] DANFSe PDF local — NT 008/2026 (TCPDF + QR Code)
• [x] DANFSe customizável (logo do prestador, observações livres)
• [x] Substituição de NFS-e (evento e105102)
• [x] Manifestação (Confirmar / Rejeitar / Anular Rejeição)
• [x] DFe paginado (GET /contribuintes/DFe/{NSU}) — caixa postal do CNPJ
• [x] Listagem de eventos por NFS-e (GET /contribuintes/NFSe/{chave}/Eventos)
• [x] Verificação idempotente de DPS (HEAD /dps/{id})
• [x] Enums das tabelas oficiais: ListaServicosNacional (335), ListaNbs (917), TipoBeneficioMunicipal, TipoImunidadeIssqn, TipoExigibilidadeSuspensa, RegimeApuracaoSimplesNacional, TipoRetencaoIssqn, TipoTributacaoIssqn
• [x] PHPStan level 8 limpo, 336 testes unitários
• [x] CI no GitHub Actions (PHP 8.1 – 8.5)
• [x] Validação ponta-a-ponta em homologação SEFIN
• [x] Examples completos do ciclo de vida
• [x] <interm> (Intermediário) — v0.12.0
• [x] <serv/infoCompl> (Informações Complementares) — v0.13.0
• [x] <vDedRed/documentos>/<docDedRed> (Deduções com docs referenciados) — v0.13.0
• [x] <trib/tribFed>/<piscofins> + retenções federais — v0.13.0
• [x] <BM> + <exigSusp> + <tpImunidade> dentro de <tribMun> — v0.10.0
• [x] XSDs oficiais versionados em docs/schemas/ — v0.12.0
• [x] BC-break v0.14.0: Valores::$issqnRetido (bool) → tipoRetencaoIssqn (enum 3 estados) + $dispensadoIssqn (bool) → $motivoDispensaIssqn (enum 4 cases)
• [x] Onda 5: <comExt> (exportação), <obra> (construção civil), <atvEvento> (eventos) — v0.15.0. <explRod> e <lsadppu> fora-de-escopo (removidos do leiaute entre v1.00 e v1.01)
• [x] Endereço internacional (endExt) em Tomador e Intermediário — v0.16.0
• [x] Grupo <IBSCBS> configurável (Reforma Tributária) — Valores::$cstIbsCbs/$cClassTrib (v0.21.0), $cCredPres/$tribRegular (v0.25.0). Opt-in via Config::incluirIbsCbs
• [x] Servico::$cTribMun (código de tributação municipal do ISSQN, opcional) — v0.24.0
• [x] DANFSe local — bloco "Canhoto" (item 2.1.13, Anexo I) — DanfseCustomizacao::$canhoto (EmBranco | PreenchidoAutomaticamente) — v0.26.0
• [x] DANFSe local — 15 fixes de leiaute V2 (canhoto sem overflow, moldura sem gap, auto-fit de fonte com truncamento pra nomes/chaves longas, Ambiente Gerador correto, descrição de serviço com altura dinâmica, entre outros) — v0.26.1 a v0.26.10
• [ ] Endereço internacional em Prestador (caso raro: prestador estrangeiro)
• [ ] Grupo <fornec> dentro de <docDedRed> (fornecedor do documento de dedução)

Licença

MIT