README

Um pacote Laravel elegante e pratico para integracao com o NFePHP, facilitando a emissao e gestao de Notas Fiscais Eletronicas (NFe) e Notas Fiscais de Consumidor Eletronicas (NFCe) em aplicacoes Laravel.

Caracteristicas

Integracao simplificada com o NFePHP
5 Facades independentes para separacao clara de responsabilidades
Geracao de DANFE (PDF) para NFe, NFCe, DANFE simplificado e eventos
Gerenciamento de contingencias automatico e manual
Validacoes robustas para CNPJ, CPF e chaves de acesso
Helpers utilitarios para formatacao e manipulacao de dados
Gerenciamento de certificados digitais
Configuracao flexivel via arquivo de configuracao
Testes abrangentes com PHPUnit

Requisitos

PHP 8.3 ou superior
Laravel 12.0 ou 13.0
NFePHP 5.1 ou superior
SPED-DA 1.0 ou superior (geracao de DANFE)

Instalação

Instale o pacote via Composer:

composer require diogo-graciano/nfephp-laravel

Publicar configuracoes

php artisan vendor:publish --provider="DiogoGraciano\Nfephp\NfephpServiceProvider" --tag="config"

Configurar variaveis de ambiente

Adicione as seguintes variaveis ao seu arquivo .env:

# Configuracoes basicas
NFEPHP_TP_AMB=2
NFEPHP_RAZAO_SOCIAL="Sua Razao Social"
NFEPHP_CNPJ="12345678000195"
NFEPHP_IE="123456789"
NFEPHP_SIGLA_UF="SP"
NFEPHP_SCHEMES="PL_009_V4"
NFEPHP_VERSAO="4.00"

# Certificado digital
NFEPHP_CERTIFICATE_PATH="/path/to/your/certificate.pfx"
NFEPHP_CERTIFICATE_PASSWORD="sua_senha"

# DANFE (logo opcional)
NFEPHP_DANFE_LOGO_PATH="/path/to/logo.png"

# Configuracoes opcionais
NFEPHP_TOKEN_IBPT="seu_token_ibpt"
NFEPHP_CSC="seu_csc"
NFEPHP_CSC_ID="seu_csc_id"

Arquitetura

O pacote utiliza 5 facades independentes, cada uma com responsabilidade bem definida:

Facade	Binding	Classe	Responsabilidade
`Nfe`	`'nfe'`	`NfeManager`	Operacoes NFe (criar, enviar, consultar, cancelar, inutilizar, manifestar)
`Danfe`	`'danfe'`	`DanfeManager`	Geracao de PDF (DANFE, DANFCe, DANFESimples, DAEvento)
`Contingency`	`'contingency'`	`ContingencyManager`	Ativar/desativar/verificar contingencia
`Certificate`	`'certificate'`	`CertificateManager`	Info, validade e expiracao do certificado
`Utils`	`'nfe-utils'`	`UtilsManager`	Validacao, formatacao, helpers de UF

Contexto compartilhado (NfeContext)

O NfeContext e um singleton que gerencia o estado compartilhado entre as facades NFe:

NfeContext (singleton)
├── config[]
├── Certificate ──compartilhado──> CertificateManager (facade Certificate)
├── Tools (NFePHP\NFe\Tools) ──usado por──> NfeManager
├── ContingencyManager ──callback──> NfeContext.reinitialize()

Quando a contingencia e ativada/desativada, o NfeContext reinicializa automaticamente o Tools.

Uso

Facade Nfe - Operacoes NFe/NFCe

use DiogoGraciano\Nfephp\Facades\Nfe;

// Criar XML da NFe
$make = Nfe::createNFe();

// Criar XML da NFCe
$make = Nfe::createNFCe();

// Enviar NFe (lote)
$response = Nfe::sendNFe([$xmlAssinado1, $xmlAssinado2]);

// Consultar NFe
$response = Nfe::consultNFe('12345678901234567890123456789012345678901234');

// Cancelar NFe
$response = Nfe::cancelNFe(
    '12345678901234567890123456789012345678901234',
    'Justificativa do cancelamento',
    '123456789012345'
);

// Inutilizar numeracao
$response = Nfe::inutilizeNFe(1, 1, 10, 'Justificativa da inutilizacao');

// Distribuicao DFe
$response = Nfe::distributionDFe(0);

// Manifestacao do destinatario
Nfe::confirmNFe($chaveNFe);         // Confirmacao da operacao
Nfe::acknowledgeNFe($chaveNFe);     // Ciencia da operacao
Nfe::unknownNFe($chaveNFe);         // Desconhecimento da operacao
Nfe::notPerformedNFe($chaveNFe, 'Justificativa'); // Operacao nao realizada

// Manifestacao em lote
Nfe::manifestNFeBatch($std);

// Gerar QR Code
Nfe::generateQRCode($dom, $token, $id, $versao, $urlQR, $urlChave);
Nfe::generateNFeQRCode($dom, $token, $id, $versao, $urlQR, $urlChave);

// Padronizar resposta XML
$response = Nfe::standardizeResponse($xmlResponse);

// Configuracao
$config = Nfe::getConfig();
$nfeConfig = Nfe::getNFeConfig();
Nfe::setConfig(['chave' => 'valor']);
Nfe::setNFeConfig(['tpAmb' => 1]);

// Obter Tools diretamente
$tools = Nfe::getTools();

Facade Danfe - Geracao de PDF

use DiogoGraciano\Nfephp\Facades\Danfe;

$xmlAutorizado = '...'; // XML autorizado da NFe

// Gerar PDF do DANFE (retorna string binaria do PDF)
$pdf = Danfe::generateDanfe($xmlAutorizado);

// Salvar DANFE no Storage do Laravel
Danfe::saveDanfe($xmlAutorizado, 'danfes/nota-001.pdf');         // disco padrao
Danfe::saveDanfe($xmlAutorizado, 'danfes/nota-001.pdf', 's3');   // disco especifico

// Retornar como download HTTP
return Danfe::downloadDanfe($xmlAutorizado, 'nota-001.pdf');

// Retornar para visualizacao inline no navegador
return Danfe::renderDanfe($xmlAutorizado, 'nota-001.pdf');

DANFE para NFCe

$pdf = Danfe::generateDanfce($xmlNfce);
Danfe::saveDanfce($xmlNfce, 'danfces/cupom-001.pdf');
return Danfe::downloadDanfce($xmlNfce, 'cupom-001.pdf');
return Danfe::renderDanfce($xmlNfce, 'cupom-001.pdf');

DANFE Simplificado

$pdf = Danfe::generateDanfeSimples($xmlAutorizado);
Danfe::saveDanfeSimples($xmlAutorizado, 'danfes/simples-001.pdf');
return Danfe::downloadDanfeSimples($xmlAutorizado, 'simples-001.pdf');
return Danfe::renderDanfeSimples($xmlAutorizado, 'simples-001.pdf');

Documento de Evento (Cancelamento, CCe, etc.)

$xmlEvento = '...';

$dadosEmitente = [
    'razao' => 'Empresa Teste LTDA',
    'logradouro' => 'Rua Exemplo',
    'numero' => '123',
    'complemento' => 'Sala 1',
    'bairro' => 'Centro',
    'CEP' => '01001000',
    'municipio' => 'Sao Paulo',
    'UF' => 'SP',
    'telefone' => '1199999999',
    'email' => 'contato@empresa.com',
];

$pdf = Danfe::generateDaevento($xmlEvento, $dadosEmitente);
Danfe::saveDaevento($xmlEvento, 'eventos/cancelamento-001.pdf', $dadosEmitente);
return Danfe::downloadDaevento($xmlEvento, $dadosEmitente, 'cancelamento-001.pdf');
return Danfe::renderDaevento($xmlEvento, $dadosEmitente, 'cancelamento-001.pdf');

Logo do DANFE

// Via .env: NFEPHP_DANFE_LOGO_PATH="/path/to/logo.png"

// Ou em tempo de execucao
Danfe::setLogo('/path/to/logo.png');
Danfe::setLogo(null); // remover logo

Facade Contingency - Gerenciamento de Contingencia

use DiogoGraciano\Nfephp\Facades\Contingency;

// Ativar contingencia
$json = Contingency::activate('SP', 'SEFAZ fora do ar', 'SVCAN');

// Verificar se esta em contingencia
if (Contingency::isActive()) {
    echo "Sistema em modo de contingencia";
}

// Obter informacoes da contingencia ativa
$info = Contingency::getInfo();
// Retorna: ['type' => 'SVCAN', 'motive' => '...', 'timestamp' => '...', 'tpEmis' => '...']

// Ajustar XML para contingencia
$xmlAjustado = Contingency::adjustXml($xml);

// Carregar contingencia de JSON salvo
Contingency::load($jsonContingencia);

// Desativar contingencia
Contingency::deactivate();

Facade Certificate - Gerenciamento de Certificado

use DiogoGraciano\Nfephp\Facades\Certificate;

// Verificar se o certificado esta valido
if (Certificate::isValid()) {
    echo "Certificado valido!";
}

// Obter informacoes do certificado
$info = Certificate::getInfo();
// Retorna: ['cnpj', 'cpf', 'name', 'valid_from', 'valid_to', 'icp', 'ca_url', 'csp']

// Dias para expirar
$dias = Certificate::getDaysToExpire();

// Verificar se esta proximo do vencimento
if (Certificate::isNearExpiration(30)) {
    echo "Certificado expira em menos de 30 dias!";
}

// Obter dados especificos
$cnpj = Certificate::getCnpj();
$cpf = Certificate::getCpf();
$empresa = Certificate::getCompanyName();

Facade Utils - Validacoes e Helpers (NFe + NFSe)

use DiogoGraciano\Nfephp\Facades\Utils;

// Validacoes
Utils::validateCnpj('12345678000195');
Utils::validateCpf('12345678901');
Utils::validateNFeKey('12345678901234567890123456789012345678901234');
Utils::validateXml($xmlString);

// Formatacao
$cnpj = Utils::formatCnpj('12345678000195');  // 12.345.678/0001-95
$cpf = Utils::formatCpf('12345678901');         // 123.456.789-01

// Manipulacao de strings
$limpa = Utils::cleanString('Texto com acentos!@#');
$ascii = Utils::stringToAscii('Texto com acentuacao');
$params = Utils::equilizeParameters($string, $length);

// Helpers de UF
$codigo = Utils::getUfCode('SP');              // 35
$uf = Utils::getUfByCode(35);                  // SP
$timezone = Utils::getTimezoneByUf('SP');       // America/Sao_Paulo

// Gerar chave de acesso
$chave = Utils::generateNFeKey('35', '2401', '12345678000195', '55', '1', '1', '1', '12345678');

Uso sem Facade (injecao de dependencia)

// Via container
$nfe = app('nfe');           // NfeManager
$danfe = app('danfe');       // DanfeManager
$contingency = app('contingency'); // ContingencyManager
$certificate = app('certificate'); // CertificateManager
$utils = app('nfe-utils');   // UtilsManager

// Ou via type-hint no construtor/metodo
use DiogoGraciano\Nfephp\NfeContext;

public function __construct(NfeContext $context)
{
    $tools = $context->getTools();
    $cert = $context->getCertificate();
}

Testes

Execute os testes com:

composer test

Para executar com cobertura de codigo:

composer test-coverage

Estrutura do Pacote

src/
├── Helpers/
│   ├── StringHelper.php        # Helpers para manipulacao de strings
│   ├── UfHelper.php            # Helpers para codigos de UF
│   └── ValidationHelper.php    # Helpers para validacoes
├── Managers/
│   ├── CertificateManager.php  # Gerenciamento de certificados
│   ├── ContingencyManager.php  # Gerenciamento de contingencias
│   ├── DanfeManager.php        # Geracao de DANFE (PDF)
│   ├── NfeManager.php          # Operacoes NFe/NFCe
│   └── UtilsManager.php        # Validacoes e helpers
├── Facades/
│   ├── Nfe.php                 # Facade NFe
│   ├── Danfe.php               # Facade DANFE
│   ├── Contingency.php         # Facade Contingencia
│   ├── Certificate.php         # Facade Certificado
│   └── Utils.php               # Facade Utils
├── NfeContext.php               # Contexto compartilhado (singleton)
└── NfephpServiceProvider.php    # Service Provider

Migracao da versao anterior

Se voce usava a facade Nfephp unica, atualize para as novas facades:

Antes (Nfephp::)	Agora
`Nfephp::createNFe()`	`Nfe::createNFe()`
`Nfephp::sendNFe()`	`Nfe::sendNFe()`
`Nfephp::generateDanfe()`	`Danfe::generateDanfe()`
`Nfephp::saveDanfe()`	`Danfe::saveDanfe()`
`Nfephp::activateContingency()`	`Contingency::activate()`
`Nfephp::isInContingency()`	`Contingency::isActive()`
`Nfephp::deactivateContingency()`	`Contingency::deactivate()`
`Nfephp::isCertificateValid()`	`Certificate::isValid()`
`Nfephp::getCertificateInfo()`	`Certificate::getInfo()`
`Nfephp::validateCnpj()`	`Utils::validateCnpj()`
`Nfephp::formatCnpj()`	`Utils::formatCnpj()`
`Nfephp::getUfCode()`	`Utils::getUfCode()`
`Nfephp::setDanfeLogo()`	`Danfe::setLogo()`

Troubleshooting

Problemas Comuns

Erro de certificado invalido
- Verifique se o caminho do certificado esta correto
- Confirme se a senha esta correta
- Verifique se o certificado nao expirou
- Use Certificate::getDaysToExpire() para verificar a validade
Erro de contingencia
- Verifique se a sigla da UF esta correta
- Confirme se o motivo tem entre 15-255 caracteres
- Verifique se o tipo de contingencia e valido (SVCAN, SVCRS)
Tools nao inicializado
- O certificado precisa estar configurado para usar operacoes NFe
- Verifique as variaveis NFEPHP_CERTIFICATE_PATH e NFEPHP_CERTIFICATE_PASSWORD

Documentacao Adicional

Contribuindo

Contribuicoes sao bem-vindas! Por favor, leia o guia de contribuicao antes de enviar pull requests.

Processo de Contribuicao

Fork o projeto
Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
Commit suas mudancas (git commit -m 'Add some AmazingFeature')
Push para a branch (git push origin feature/AmazingFeature)
Abra um Pull Request

Seguranca

Se voce descobrir alguma vulnerabilidade de seguranca, por favor envie um email para diogo.dg691@gmail.com ao inves de usar o issue tracker.

Changelog

Veja o CHANGELOG para informacoes sobre mudancas recentes.

Creditos

Diogo Graciano Comin - Desenvolvedor principal
NFePHP Community - Biblioteca base
Todos os Contribuidores

Licenca

Este projeto esta licenciado sob a Licenca MIT - veja o arquivo LICENSE para detalhes.

Se este pacote foi util para voce, considere dar uma estrela no GitHub!

diogo-graciano / nfephp-laravel

Maintainers

Package info

Statistics

Security