Download the PHP package sabbajohn/fiscal-core without Composer

🚀 FISCAL-CORE - Biblioteca PHP para Operações Fiscais

Biblioteca robusta e modular para operações fiscais brasileiras

NFe, NFCe, NFSe, Consultas Públicas, Tributação IBPT e muito mais!

📋 Sumário

• 📦 Instalação
• ⚡ Início Rápido
• 🎯 Funcionalidades
• 📚 Exemplos Práticos
• ⚙️ Configuração
• 🏗️ Arquitetura
• 📖 API das Facades
• 🚢 Release Packagist
• 📊 Casos de Uso
• 🔧 Requisitos
• 🚨 Troubleshooting
• 🗺️ Roadmap

📦 Instalação via Composer

Desenvolvimento local:

bash composer require sabbajohn/fiscal-core:@dev bash composer install

🎯 Funcionalidades Principais

📋 Consultas Públicas

📄 Documentos Fiscais

💰 Tributação

• IBPT - Cálculo automático de tributos
• Múltiplos produtos em lote
• Cache parcial em fluxos específicos
• Fallbacks por estado/federal

📚 Exemplos Práticos

🎓 Para Iniciantes (examples/basico/)

🏢 Para Produção (examples/avancado/)

📖 Guia Completo

📚 Veja todos os exemplos organizados em examples/README.md

⚙️ Configuração (Opcional)

🔐 Certificados NFe/NFCe

🧩 Compatibilidade NFe/NFCe

O fiscal-core usa nfephp-org/sped-nfe como motor NFe/NFCe. Para acompanhar novas Notas Técnicas sem alterar código de negócio, configure versão XML e pacote de schemas por ambiente ou por modelo:

Aliases aceitos para schema: PL_009, PL_010, NT_2025_002, reforma_tributaria e IBSCBS. O resolvedor usa o schema instalado no sped-nfe mais adequado, por exemplo PL_010_V1.30 quando disponível.

Também é possível sobrescrever por payload:

Para diagnóstico, FiscalFacade::getConfigInfo() retorna nfe_compatibility com versões instaladas, schemas disponíveis e suporte a tags IBS/CBS.

💰 IBPT (Tributação)

🏘️ NFSe Municípios

• O catálogo municipal atual está em config/nfse/
• FISCAL_IM continua obrigatório para emissões municipais reais
• A consulta pública de CNPJ ajuda com razão social/contato/endereço, mas não fornece inscrição municipal
• provider_config_overrides no catálogo aplica merge sobre a família técnica no runtime
• payload_defaults no catálogo acelera exemplos e homologação sem duplicar a família
• Emissão classificada como MEI usa sempre o provider nacional
• Para Belém, o DANFSe é disponibilizado pela prefeitura em URL oficial; a biblioteca retorna isso no contrato canônico em impressao.modo = url e impressao.url
• O playbook canônico para implementação municipal está em docs/NFSE-MUNICIPAL-PROVIDER-PLAYBOOK.md
• A migração de município municipal para nacional está em docs/NFSE-MIGRACAO-MUNICIPAL-PARA-NACIONAL.md
• A matriz operacional de famílias e providers está em docs/NFSE-PROVIDER-MATRIX.md

Cidades-UF já compatíveis

Status usados abaixo:

• HOMOLOGADO: fluxo real já validado
• DISPENSADO_NACIONAL: compatível via provider nacional; não exige homologação municipal individual
• PENDENTE_HOMOLOGACAO_REAL: compatível em catálogo/runtime/testes, mas ainda depende de evidência real por município

Lista completa e status detalhado:

• docs/NFSE-MUNICIPIOS-SUPORTADOS-HOMOLOGACAO.md
• docs/NFSE-CAPITAIS-HOMOLOGACAO-TRACKER.md
• docs/nfse-municipios-suportados.csv

Uso Detalhado

1) NFe: emitir, consultar e cancelar

2) Impressão: DANFE/DANFCE

3) NFSe: múltiplos municípios

4) NFSe municipal pronta para uso

5) DANFSe municipal

6) Salvar XML e PDF retornados

7) Consulta padronizada de XML

7.1) Contrato canônico e reconciliação de XML antigo

• documento.xml agora representa somente o XML fiscal imprimível.
• raw.response_body preserva payload bruto textual/JSON retornado pelo provedor.
• raw.response_xml preserva XML técnico bruto de transporte/resposta, quando existir.

Se você já salvou registros antigos com o XML errado na base:

• NFe:
  • Se houver raw.parsed_response.xml_assinado e raw.response_xml, tente remontar o nfeProc com NFePHP\NFe\Complements::toAuthorize(...).
  • Se não houver material suficiente, reconsulte/baixe pela chave de acesso e substitua o registro pelo documento.xml canônico.
• NFSe:
  • Se o registro salvo contiver JSON, XML administrativo ou envelope SOAP, tente reextrair o documento fiscal a partir de nfseXmlGZipB64, raw_xml ou por nova consulta com chave/protocolo/RPS.

Critérios práticos para identificar registros corrompidos:

• NFe: raiz retEnviNFe, retConsReciNFe, retConsSitNFe ou ausência de NFe/infNFe.
• NFSe: JSON, <string>, envelope SOAP sem CompNfse/Nfse/InfNfse ou XML administrativo sem a nota final.

8) Consultas Públicas

🏗️ Arquitetura

🎭 Sistema de Facades

🔄 Sistema de Respostas

🛡️ Error Handling

• Fallbacks automáticos entre providers
• Cache local em fluxos específicos, com política unificada ainda pendente
• Logging/diagnóstico em evolução
• Retry ainda não é uniforme entre adapters

📊 Casos de Uso

💼 E-commerce

🏭 ERP/Contabilidade

🏢 Software House

🔧 Requisitos Técnicos

• PHP >=8.1
• OpenSSL (para certificados)
• cURL (para APIs externas)
• JSON (manipulação de dados)

📦 Dependências Principais

🧪 Testes

// App\Providers\AppServiceProvider.php use NfePHP\NFe\Tools; use sabbajohn\FiscalCore\Adapters\NFeAdapter;

public function register() { $this->app->bind(NFeAdapter::class, function () { $configJson = json_encode([ /sua config NFe/ ]); return new NFeAdapter(new Tools($configJson)); }); }

src/ Contracts/ # Interfaces (contratos de domínio) NotaFiscalInterface.php NotaServicoInterface.php ImpressaoInterface.php TributacaoInterface.php ProdutoInterface.php DocumentoInterface.php ConsultaPublicaInterface.php

Adapters/ # Implementações que integram com bibliotecas externas NFeAdapter.php NFCeAdapter.php NFSeAdapter.php ImpressaoAdapter.php IBPTAdapter.php GTINAdapter.php DocumentoAdapter.php BrasilAPIAdapter.php

Support/ # Classes utilitárias e gerenciamento centralizado CertificateManager.php # Singleton para certificados digitais ConfigManager.php # Singleton para configurações fiscais ToolsFactory.php # Factory para NFePHP Tools IBPTAdapter.php GTINAdapter.php

🚨 Troubleshooting

❓ Problemas Comuns

🔍 Debug Mode

📞 Suporte

• Ver exemplos em examples/
• Logs detalhados em modo debug
• Issues no repositório

🗺️ Roadmap

O status consolidado e a lista priorizada de pendências estão em docs/STATUS-E-PENDENCIAS.md.

✅ Concluído ou operacional

• [x] Facades principais: FiscalFacade, NFeFacade, NFCeFacade, NFSeFacade, ImpressaoFacade, TributacaoFacade e UtilsFacade
• [x] Adapters principais para documentos fiscais, impressão, consultas públicas, IBPT e GTIN
• [x] NFSe provider-based com catálogo municipal, families, resolver, registry, bootstrap e scripts operacionais
• [x] Playbook municipal e matriz operacional NFSe
• [x] Cache local em fluxos específicos, como catálogo nacional e instâncias NFSe por município
• [x] Nome Composer canônico definido como sabbajohn/fiscal-core
• [x] Scripts Composer, CI mínimo e PHPStan inicial preparados para release v1.2.4

🔄 Pendente ou parcial

• [ ] Publicar/atualizar o Packagist no pacote canônico sabbajohn/fiscal-core
• [ ] Expandir homologação municipal real seguindo o playbook, sem contar roteamento em catálogo como homologação
• [ ] Fechar contrato público uniforme das facades para respostas, erros, XML, impressão e eventos
• [ ] Criar Service Provider Laravel com publish de config e bindings
• [ ] Criar middleware de validação automática depois de estabilizar contrato/config Laravel
• [ ] Consolidar política de cache para consultas remotas e configurações
• [ ] Publicar/documentar GitHub Packages, se este canal for necessário
• [x] Criar referência inicial por Facade
• [ ] Criar referência detalhada por Adapter
• [ ] Definir formatter

🛠️ Configuração Avançada

Para informações detalhadas sobre configuração de certificados e providers, consulte:

• 📄 docs/providers-and-config.md
• 📄 docs/API-FACADES.md
• 📄 docs/RELEASE-PACKAGIST.md
• 📄 docs/NFSE-MUNICIPAL-PROVIDER-PLAYBOOK.md
• 📄 config/nfse/providers-catalog.json
• 📄 config/nfse/nfse-provider-families.json

Fluxo canônico de resolução NFSe:

config/nfse/providers-catalog.json -> config/nfse/nfse-provider-families.json -> NFSeProviderResolver -> ProviderRegistry -> NFSeRuntimeBootstrap -> provider concreto

🧪 Estrutura de Testes

Gerenciamento Centralizado (Singletons)

📁 Estrutura do Projeto

$configManager->set('uf', 'SP'); $configManager->set('csc', 'SEU_CSC');

// Acesso em qualquer adapter $isProduction = $configManager->isProduction(); $nfeConfig = $configManager->getNFeConfig();

php use sabbajohn\FiscalCore\Support\ToolsFactory;

// Setup rápido para desenvolvimento ToolsFactory::setupForDevelopment(['uf' => 'SP']);

// Cria Tools pré-configurados $nfeTools = ToolsFactory::createNFeTools(); $adapter = new NFeAdapter($nfeTools);

// Validação de ambiente $validation = ToolsFactory::validateEnvironment(); bash

Ver estrutura de NFSe

tree src/Providers/NFSe config/nfse docs/nfse-providers

Listar overrides operacionais

php scripts/nfse/provider-switch.php --list

Gerar tabela de cobertura por provider

php scripts/nfse/generate-providers-municipios-doc.php

Reconciliar catalogo local com base Uninfe

php scripts/nfse/reconcile-uninfe-providers.php --fail-on-unexpected

Ler playbook municipal

cat docs/NFSE-MUNICIPAL-PROVIDER-PLAYBOOK.md

Contribuição

- Issues e PRs são bem-vindos. Antes de abrir PR:
  - Rode `vendor/bin/phpunit` e garanta verde.
  - Siga o estilo existente e mantenha mudanças focadas.

Licença

- MIT. Veja `composer.json`.