PHPackages                             jcf/espiaonfe - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. jcf/espiaonfe

ActiveLibrary[API Development](/categories/api)

jcf/espiaonfe
=============

Pacote Laravel para integração com a API do EspiãoNFe - Gerenciamento de certificados digitais, NF-e, CT-e, NFSe e XMLs

v0.0.4(6mo ago)01MITPHPPHP ^8.1

Since Nov 1Pushed 6mo agoCompare

[ Source](https://github.com/jotafurtado/espiaonfe-laravel)[ Packagist](https://packagist.org/packages/jcf/espiaonfe)[ Docs](https://github.com/jotacfurtado/espiaonfe-laravel)[ RSS](/packages/jcf-espiaonfe/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (4)Versions (5)Used By (0)

Jcf/EspiaoNfe
=============

[](#jcfespiaonfe)

[![Latest Version on Packagist](https://camo.githubusercontent.com/940a9c65c10f92bb37e2bf4c577c7c322aa5c223987aaf8191d109efc77eff1b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a63662f65737069616f6e66652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/jcf/espiaonfe)[![Total Downloads](https://camo.githubusercontent.com/ee89f09fb2648fc553593d8d41f00a7acd51d855236aaec91dd9cf9e57b51f10/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6a63662f65737069616f6e66652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/jcf/espiaonfe)

Pacote Laravel para integração com a API do EspiãoNFe. Este pacote fornece uma interface simples e elegante para interagir com todos os endpoints da API EspiãoNFe, facilitando o gerenciamento de certificados digitais, empresas, NFes, CTes, NFSe e muito mais.

Instalação
----------

[](#instalação)

Você pode instalar o pacote via Composer:

```
composer require jcf/espiaonfe
```

Configuração
------------

[](#configuração)

Após instalar o pacote, publique o arquivo de configuração:

```
php artisan vendor:publish --tag=config --provider="Jcf\EspiaoNfe\Providers\EspiaoNfeServiceProvider"
```

Isso criará o arquivo `config/espiaonfe.php` em sua aplicação.

Em seguida, configure as variáveis de ambiente no seu arquivo `.env`:

```
ESPIAONFE_CLOUD_TOKEN=seu_esp_cloud_token_aqui
ESPIAONFE_USER_TOKEN=seu_user_token_aqui
ESPIAONFE_BASE_URI=https://api.espiaonfe.com.br

# Configurações avançadas (opcionais)
ESPIAONFE_TIMEOUT=30                    # Timeout das requisições em segundos (padrão: 30)
ESPIAONFE_RETRY=3                      # Número de tentativas automáticas (padrão: 3)
ESPIAONFE_RETRY_DELAY=100               # Delay entre tentativas em milissegundos (padrão: 100)
ESPIAONFE_LOG_REQUESTS=false           # Habilitar logging de requisições (padrão: false)
```

> **Nota**: O `ESPIAONFE_BASE_URI` é opcional e já possui um valor padrão (`https://api.espiaonfe.com.br`). Use apenas se precisar apontar para um ambiente diferente.

Uso
---

[](#uso)

O pacote fornece uma **API fluente estilo Laravel** que torna o uso extremamente elegante e intuitivo:

### ✨ Métodos Intuitivos

[](#-métodos-intuitivos)

O pacote inclui métodos auto-explicativos que tornam o código mais limpo e fácil de entender:

#### Tipo de Período (XMLs)

[](#tipo-de-período-xmls)

```
// Consulta pelo período de emissão do documento
->tipoPeriodoEmissao()

// Consulta pelo período de inclusão no Espião Cloud
->tipoPeriodoInclusao()

// Ou use diretamente (E = emissão, I = inclusão)
->tipoPeriodo('E')
->tipoPeriodo('I')
```

#### Modelos de Documentos

[](#modelos-de-documentos)

```
// Métodos intuitivos para cada modelo
->modeloNfe()    // NF-e (modelo 55)
->modeloNfce()   // NFC-e (modelo 65)
->modeloCte()    // CT-e (modelo 57)
->modeloCteOs()  // CT-e OS (modelo 67)
->modeloSat()    // SAT (modelo 59)
->modeloNfse()   // NFS-e Nacional (modelo 41)

// Ou use diretamente com o código do modelo
->modelo('55') // 55, 65, 57, 67, 59, 41
```

### API Fluente ✨

[](#api-fluente-)

O pacote utiliza query builders que permitem encadear métodos de forma fluente, similar ao Eloquent do Laravel:

#### Exemplo: Obter Empresas com Paginação

[](#exemplo-obter-empresas-com-paginação)

```
use Jcf\EspiaoNfe\Facades\EspiaoNfe;

// Listar empresas (limite de 100 por página)
$empresas = EspiaoNfe::empresas()->get();

// Navegar para próxima página usando o código retornado
$codigoProxima = $empresas['codigoProximaPagina']; // Ex: "200"
if ($codigoProxima !== '-1') {
    $empresas = EspiaoNfe::empresas()
        ->codigoProximaPagina($codigoProxima)
        ->get();
}

// Filtrar por CNPJ/CPF
$empresa = EspiaoNfe::empresas()
    ->cnpjCpf('12345678000190')
    ->get();

// Criar uma nova empresa
$empresa = EspiaoNfe::empresas()->create([
    'cnpj' => '12345678000190',
    'razao_social' => 'Minha Empresa LTDA',
]);

// Atualizar uma empresa
$empresa = EspiaoNfe::empresas()
    ->find('12345678000190')
    ->update(['razao_social' => 'Nova Razão Social']);
```

#### Exemplo: Trabalhar com Certificados

[](#exemplo-trabalhar-com-certificados)

```
// Listar certificados (até 100 por página)
$certificados = EspiaoNfe::certificados()->get();

// Filtrar por serial
$certificado = EspiaoNfe::certificados()
    ->serial('4CAF1032F8C90902C81751D30FE47152')
    ->get();

// Criar certificado (multipart/form-data - requer arquivo)
$certificado = EspiaoNfe::certificados()->create([
    'arquivoCertificado' => /* arquivo .pfx */,
    'senha' => 'senha_do_certificado',
]);

// Atualizar certificado
$certificado = EspiaoNfe::certificados()
    ->find('4CAF1032F8C90902C81751D30FE47152')
    ->update([/* dados */]);

// Deletar certificado
EspiaoNfe::certificados()
    ->find('4CAF1032F8C90902C81751D30FE47152')
    ->delete(['comando' => 'cancelar']);
```

#### Exemplo: NF-e, CT-e e NFSe

[](#exemplo-nf-e-ct-e-e-nfse)

```
// Consultar NF-e por período (até 100 por página)
$nfeResumo = EspiaoNfe::nfe()
    ->cnpjCpf('12345678000190')
    ->periodo('01/01/2024', '31/01/2024')
    ->modeloNfe() // Método intuitivo para modelo 55 (NF-e)
    ->get();

// Consultar NFC-e (Nota Fiscal de Consumidor)
$nfceResumo = EspiaoNfe::nfe()
    ->cnpjCpf('12345678000190')
    ->periodo('01/01/2024', '31/01/2024')
    ->modeloNfce() // Método intuitivo para modelo 65 (NFC-e)
    ->get();

// Consultar SAT (Sistema Autenticador e Transmissor)
$satResumo = EspiaoNfe::nfe()
    ->cnpjCpf('12345678000190')
    ->periodo('01/01/2024', '31/01/2024')
    ->modeloSat() // Método intuitivo para modelo 59 (SAT)
    ->get();

// Ou usar modelo() diretamente
$nfeResumo = EspiaoNfe::nfe()
    ->cnpjCpf('12345678000190')
    ->periodo('01/01/2024', '31/01/2024')
    ->modelo('55') // 55 (NF-e), 65 (NFC-e) ou 59 (SAT)
    ->get();

// Manifestar NF-e
$resultado = EspiaoNfe::nfe()->manifestar([
    'chave' => '35191234567890123456789012345678901234567890',
    'tipo' => '210200',
]);

// Consultar CT-e por período (até 100 por página)
$cteResumo = EspiaoNfe::cte()
    ->cnpjCpf('12345678000190')
    ->periodo('01/01/2024', '31/01/2024')
    ->modeloCte() // Método intuitivo para modelo 57 (CT-e)
    ->get();

// Ou usar modelo() diretamente
$cteResumo = EspiaoNfe::cte()
    ->cnpjCpf('12345678000190')
    ->periodo('01/01/2024', '31/01/2024')
    ->modelo('57') // 57 (CT-e)
    ->get();

// Desacordo de CT-e
$resultado = EspiaoNfe::cte()->desacordo([
    'chave' => '35191234567890123456789012345678901234567890',
    'motivo' => 'Mercadoria não recebida',
]);

// Consultar NFSe por período (até 100 por página)
$nfseResumo = EspiaoNfe::nfse()
    ->cnpjCpf('12345678000190')
    ->periodo('01/01/2024', '31/01/2024')
    ->get();

// NFSe por cidade
$nfsePorCidade = EspiaoNfe::nfse()->porCidade([
    'cnpjCpf' => '12345678000190',
    'cidade' => '3550308',
    'dataInicial' => '01/01/2024',
    'dataFinal' => '31/01/2024',
]);

// Cidades homologadas
$cidades = EspiaoNfe::nfse()->cidadesHomologadas();
```

#### Exemplo: XMLs e PDFs

[](#exemplo-xmls-e-pdfs)

```
// Listar XMLs de NF-e por período de emissão
$xmls = EspiaoNfe::xmls()
    ->cnpjCpf('12345678000190')
    ->periodo('01/01/2024', '31/01/2024')
    ->tipoPeriodoEmissao() // Período de emissão
    ->modeloNfe() // Modelo 55 (NF-e)
    ->get();

// XMLs de NFC-e por período de inclusão
$xmls = EspiaoNfe::xmls()
    ->cnpjCpf('12345678000190')
    ->periodo('01/01/2024', '31/01/2024')
    ->tipoPeriodoInclusao() // Período de inclusão no sistema
    ->modeloNfce() // Modelo 65 (NFC-e)
    ->get();

// XMLs de CT-e
$xmls = EspiaoNfe::xmls()
    ->cnpjCpf('12345678000190')
    ->periodo('01/01/2024', '31/01/2024')
    ->tipoPeriodoEmissao()
    ->modeloCte() // Modelo 57 (CT-e)
    ->get();

// XMLs de CT-e OS (Outros Serviços)
$xmls = EspiaoNfe::xmls()
    ->cnpjCpf('12345678000190')
    ->periodo('01/01/2024', '31/01/2024')
    ->tipoPeriodoEmissao()
    ->modeloCteOs() // Modelo 67 (CT-e OS)
    ->get();

// XMLs de SAT
$xmls = EspiaoNfe::xmls()
    ->cnpjCpf('12345678000190')
    ->periodo('01/01/2024', '31/01/2024')
    ->tipoPeriodoEmissao()
    ->modeloSat() // Modelo 59 (SAT)
    ->get();

// XMLs de NFS-e Nacional
$xmls = EspiaoNfe::xmls()
    ->cnpjCpf('12345678000190')
    ->periodo('01/01/2024', '31/01/2024')
    ->tipoPeriodoInclusao()
    ->modeloNfse() // Modelo 41 (NFS-e Nacional)
    ->get();

// Ou usar tipoPeriodo() e modelo() diretamente
$xmls = EspiaoNfe::xmls()
    ->cnpjCpf('12345678000190')
    ->periodo('01/01/2024', '31/01/2024')
    ->tipoPeriodo('E') // E (emissão) ou I (inclusão)
    ->modelo('55') // 55, 65, 57, 67, 59, 41
    ->get();

// Obter XML por chave
$xml = EspiaoNfe::xmls()->porChave('35191234567890123456789012345678901234567890');

// Obter PDF por chave
$pdf = EspiaoNfe::xmls()->pdfPorChave('35191234567890123456789012345678901234567890');

// Importar XML
$resultado = EspiaoNfe::xmls()->importar([
    'xml' => '