PHPackages                             sysborg/focusnfe - 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. sysborg/focusnfe

ActiveLibrary[API Development](/categories/api)

sysborg/focusnfe
================

Integração Laravel com a FocusNFe para NFe, NFCe, CTe, MDFe e NFSe

1.0.0(2mo ago)0339MITPHPPHP >=8.0CI failing

Since Mar 8Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/sysborg/focusnfe)[ Packagist](https://packagist.org/packages/sysborg/focusnfe)[ RSS](/packages/sysborg-focusnfe/feed)WikiDiscussions main Synced yesterday

READMEChangelog (4)Dependencies (15)Versions (42)Used By (0)

Sysborg FocusNFe
================

[](#sysborg-focusnfe)

[![CI](https://github.com/sysborg/focusnfe/actions/workflows/ci.yml/badge.svg)](https://github.com/sysborg/focusnfe/actions/workflows/ci.yml)[![Packagist Version](https://camo.githubusercontent.com/fe8887409000c47831122b0e2cdf8caa7d8fbbedbaadf5abfc36882c319a17db/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f737973626f72672f666f6375736e6665)](https://packagist.org/packages/sysborg/focusnfe)[![Packagist Downloads](https://camo.githubusercontent.com/55ec164104f5f6d66310e47d6b86490d226e819e72cfae85beb2b50faaed683c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f737973626f72672f666f6375736e6665)](https://packagist.org/packages/sysborg/focusnfe)[![License](https://camo.githubusercontent.com/0f0766d19fe127f6eb2ddd9d7e5619d249bbca3479e018c8f9037505bf40f8dc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f737973626f72672f666f6375736e6665)](https://packagist.org/packages/sysborg/focusnfe)

Pacote de implementação da FocusNFe para Laravel por Sysborg
------------------------------------------------------------

[](#pacote-de-implementação-da-focusnfe-para-laravel-por-sysborg)

Introdução
----------

[](#introdução)

O projeto tem como objetivo facilitar a integração de aplicações Laravel com a FocusNFe, utilizando uma abordagem consistente e bem estruturada. Ele expõe uma camada focada em `services`, `DTOs`, `helpers` e eventos Laravel para integração com a API da FocusNFe.

O pacote expõe services para os módulos documentados pela FocusNFe e, nos fluxos já implementados, dispara eventos Laravel para facilitar integrações internas.

Quick Start
-----------

[](#quick-start)

```
composer require sysborg/focusnfe
php artisan vendor:publish --tag=config
```

```
FOCUSNFE_TOKEN=seu-token-focusnfe
FOCUSNFE_AMBIENTE=production
```

```
use Sysborg\FocusNfe\app\Services\NFe;

$nfe = app(NFe::class);
$response = $nfe->get('pedido-123');
```

Guias
-----

[](#guias)

- [Instalação](docs/instalacao.md)
- [Configuração](docs/configuracao.md)
- [Exemplos](docs/exemplos.md)
- [Erros e respostas](docs/erros-e-respostas.md)
- [Eventos](docs/eventos.md)
- [FAQ](docs/faq.md)
- [Migração](docs/migracao.md)
- [Contribuição](CONTRIBUTING.md)
- [Changelog](CHANGELOG.md)

Eventos
-------

[](#eventos)

- status: É o status code do http [Saiba mais](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)
- data: É o retorno da FocusNFe sem nenhum tipo de alteração.
- success: Se a ação esperada foi realizada efetivamente ou não.

### Evento quando um webhook é normalizado pela aplicação consumidora

[](#evento-quando-um-webhook-é-normalizado-pela-aplicação-consumidora)

```
use \Sysborg\FocusNfe\app\Events\HooksReceived

```

O retorno é transparente e idêntico ao que a FocusNFe fornece. Neste caso, a explicação introdutória sobre eventos não se aplica, pois trata-se de um Webhook, um tipo diferente de evento.

[Webhook - FocusNFe](https://focusnfe.com.br/doc/#gatilhos-webhooks_eventos)

### Webhooks no Laravel

[](#webhooks-no-laravel)

O pacote oferece o service de gestão de webhooks na FocusNFe, o `WebhookDTO`, o evento `HooksReceived` e o helper `WebhookPayloadNormalizer` para padronizar dados na aplicação consumidora.

Pelo manual da FocusNFe, os campos relevantes para autenticação do webhook são `authorization` e `authorization_header`. Em vez de depender de uma assinatura HMAC não documentada, a estratégia recomendada é configurar um token compartilhado no cadastro do webhook e validá-lo no seu endpoint de recepção.

Exemplo de cadastro do webhook:

```
use Sysborg\FocusNfe\app\DTO\WebhookDTO;
use Sysborg\FocusNfe\app\Services\Webhooks;

$webhooks = app(Webhooks::class);

$webhooks->cadastrar(new WebhookDTO(
    cnpj_emitente: '07504505000132',
    url: 'https://seu-dominio.com/focusnfe/webhooks',
    evento: 'nfe_autorizada',
    authorization: 'Bearer meu-token-interno',
    authorization_header: 'Authorization',
));
```

Exemplo simples de normalização em um listener/serviço da aplicação consumidora:

```
use Illuminate\Support\Facades\Event;
use Sysborg\FocusNfe\app\Events\HooksReceived;
use Sysborg\FocusNfe\app\Services\WebhookPayloadNormalizer;

$payload = [
    'event' => 'nfe_autorizada',
    'cnpjEmitente' => '07504505000132',
    'ref' => 'pedido-123',
];

WebhookPayloadNormalizer::dispatch($payload, 'focusnfe:webhook');
```

Se quiser trocar o nome do cabeçalho, configure o campo `authorization_header` no `WebhookDTO` e valide o mesmo nome na camada HTTP da sua aplicação. Essa camada não faz parte do package.

### Padrão de dados para os eventos abaixo

[](#padrão-de-dados-para-os-eventos-abaixo)

Todos os eventos abaixo retornam a mesma estrutura de dados.

```
[
    'status' => int,
    'data' => array, // retorno transparente da FocusNFe
    'success' => bool
]

```

### Cobertura atual de eventos

[](#cobertura-atual-de-eventos)

Eventos atualmente disponíveis no package:

- `EmpresaCreated`
- `EmpresaUpdated`
- `EmpresaDeleted`
- `HooksReceived`
- `NFeAutorizada`
- `NFeCancelada`
- `NFeInutilizada`
- `NFCeAutorizada`
- `NFCeCancelada`
- `CTeAutorizado`
- `CTeCancelado`
- `MDFeAutorizado`
- `MDFeCancelado`
- `MDFeEncerrado`
- `NFSeEnviada`
- `NFSeCancelada`
- `NFSeNacionalAutorizada`
- `NFSeNacionalCancelada`

Observação importante:

- os eventos acima refletem a cobertura atual do código
- nem todo endpoint existente no pacote já dispara evento
- `HooksReceived` é um evento de normalização/entrada disparado pela aplicação consumidora, diferente dos eventos de retorno de service

### Eventos por módulo

[](#eventos-por-módulo)

#### Empresa

[](#empresa)

#### Criação da empresa

[](#criação-da-empresa)

```
use \Sysborg\FocusNfe\app\Events\EmpresaCreated

```

Os dados enviados pelo evento são explicados no início da sessão eventos. [Criação de empresa](https://focusnfe.com.br/doc/#empresas_criacao-de-empresa)

#### Alteração da empresa

[](#alteração-da-empresa)

```
use \Sysborg\FocusNfe\app\Events\EmpresaUpdated

```

Os dados enviados pelo evento são explicados no início da sessão eventos. [Alteração de empresa](https://focusnfe.com.br/doc/#empresas_alteracao-de-empresa)

#### Exclusão da empresa

[](#exclusão-da-empresa)

```
use \Sysborg\FocusNfe\app\Events\EmpresaDeleted

```

Os dados enviados pelo evento são explicados no início da sessão eventos. [Exclusão de empresa](https://focusnfe.com.br/doc/#empresas_exclusao-de-empresa)

#### NFe

[](#nfe)

```
use \Sysborg\FocusNfe\app\Events\NFeAutorizada;
use \Sysborg\FocusNfe\app\Events\NFeCancelada;
use \Sysborg\FocusNfe\app\Events\NFeInutilizada;

```

#### NFCe

[](#nfce)

```
use \Sysborg\FocusNfe\app\Events\NFCeAutorizada;
use \Sysborg\FocusNfe\app\Events\NFCeCancelada;

```

#### CTe

[](#cte)

```
use \Sysborg\FocusNfe\app\Events\CTeAutorizado;
use \Sysborg\FocusNfe\app\Events\CTeCancelado;

```

#### MDFe

[](#mdfe)

```
use \Sysborg\FocusNfe\app\Events\MDFeAutorizado;
use \Sysborg\FocusNfe\app\Events\MDFeCancelado;
use \Sysborg\FocusNfe\app\Events\MDFeEncerrado;

```

#### NFSe Municipal

[](#nfse-municipal)

```
use \Sysborg\FocusNfe\app\Events\NFSeEnviada

```

Os dados enviados pelo evento são explicados no início da sessão eventos. [NFSe - Envio](https://focusnfe.com.br/doc/#nfse_envio)

#### NFSe - Cancelada

[](#nfse---cancelada)

```
use \Sysborg\FocusNfe\app\Events\NFSeCancelada

```

Os dados enviados pelo evento são explicados no início da sessão eventos. [NFSe - Cancelamento](https://focusnfe.com.br/doc/#nfse_cancelamento)

#### NFSe Nacional

[](#nfse-nacional)

```
use \Sysborg\FocusNfe\app\Events\NFSeNacionalAutorizada;
use \Sysborg\FocusNfe\app\Events\NFSeNacionalCancelada;

```

#### Documentação Oficial do Laravel

[](#documentação-oficial-do-laravel)

[Documentação Laravel de Eventos](https://laravel.com/docs/12.x/events)

Rotas
-----

[](#rotas)

Controllers
-----------

[](#controllers)

Services
--------

[](#services)

Os services atualmente disponíveis no pacote são:

- `Backups`
- `CEP`
- `CFOP`
- `CNAE`
- `Cnpjs`
- `ConsultaEmails`
- `CTe`
- `CTERecebidas`
- `Empresas`
- `MDFe`
- `Municipios`
- `NCM`
- `NFCe`
- `NFe`
- `NFeRecebidas`
- `NFSe`
- `NFSeArquivo`
- `NFSeNacional`
- `NFSeRecebidas`
- `Webhooks`

### Exemplo básico de resolução via container

[](#exemplo-básico-de-resolução-via-container)

```
use Sysborg\FocusNfe\app\Services\NFe;

$service = app(NFe::class);
```

### NFe

[](#nfe-1)

Operações atualmente suportadas:

- `envia`
- `get`
- `cancela`
- `cartaCorrecao`
- `inutilizar`
- `inutilizacoes`
- `reenviaEmail`
- `downloadXml`
- `insucessoEntrega`
- `atorInteressado`
- `prorrogacaoIcms`
- `registraEconf`
- `consultaEconf`
- `cancelaEconf`

Exemplo:

```
use Sysborg\FocusNfe\app\DTO\NFeDTO;
use Sysborg\FocusNfe\app\Services\NFe;

$nfe = app(NFe::class);

$response = $nfe->get('minha-referencia');
```

### NFCe

[](#nfce-1)

Operações atualmente suportadas:

- `envia`
- `get`
- `cancela`
- `inutilizacoes`
- `reenviaEmail`
- `registraEconf`
- `consultaEconf`
- `cancelaEconf`

Exemplo:

```
use Sysborg\FocusNfe\app\Services\NFCe;

$nfce = app(NFCe::class);
$response = $nfce->get('minha-referencia');
```

### CTe

[](#cte-1)

Operações atualmente suportadas:

- `envia`
- `consulta`
- `cancela`
- `cartaCorrecao`
- `desacordo`
- `registroMultimodal`
- `dadosGtv`

Exemplo:

```
use Sysborg\FocusNfe\app\Services\CTe;

$cte = app(CTe::class);
$response = $cte->consulta('minha-referencia');
```

### MDFe

[](#mdfe-1)

Operações atualmente suportadas:

- `envia`
- `consulta`
- `cancela`
- `incluiCondutor`
- `incluiDFe`
- `encerra`

Exemplo:

```
use Sysborg\FocusNfe\app\Services\MDFe;

$mdfe = app(MDFe::class);
$response = $mdfe->consulta('minha-referencia');
```

### NFSe Municipal

[](#nfse-municipal-1)

Operações atualmente suportadas:

- `envia`
- `get`
- `cancela`
- `reenviaEmail`

Exemplo:

```
use Sysborg\FocusNfe\app\Services\NFSe;

$nfse = app(NFSe::class);
$response = $nfse->get('minha-referencia');
```

### NFSe Nacional

[](#nfse-nacional-1)

Operações atualmente suportadas:

- `envia`
- `consulta`
- `cancela`

Exemplo:

```
use Sysborg\FocusNfe\app\Services\NFSeNacional;

$nfsen = app(NFSeNacional::class);
$response = $nfsen->consulta('minha-referencia');
```

### Webhooks

[](#webhooks)

Operações atualmente suportadas:

- `cadastrar`
- `listar`
- `consultar`
- `atualizar`
- `remover`
- `testar`

Exemplo:

```
use Sysborg\FocusNfe\app\Services\Webhooks;

$webhooks = app(Webhooks::class);
$response = $webhooks->listar();
```

Testes automáticos
------------------

[](#testes-automáticos)

O repositório já possui cobertura para DTOs e services principais, incluindo cenários adicionados recentemente para:

- `NFe`
- `NFCe`
- `CTe`
- `MDFe`
- `NFSeNacional`
- `Webhooks`
- `EmpresaDTO`
- `Cnpjs` com `getDto()`

DTOs utilitários recentes
-------------------------

[](#dtos-utilitários-recentes)

### CNPJ tipado

[](#cnpj-tipado)

Além da `Response` bruta do service `Cnpjs`, o pacote agora expõe conversão tipada para os campos documentados no manual local.

```
use Sysborg\FocusNfe\app\Services\Cnpjs;

$cnpjs = app(Cnpjs::class);
$empresa = $cnpjs->getDto('07504505000132');

if ($empresa) {
    $razaoSocial = $empresa->razao_social;
    $uf = $empresa->endereco?->uf;
}
```

### EmpresaDTO

[](#empresadto)

O `EmpresaDTO` cobre os campos atualmente documentados no manual local para:

- habilitação de `NFSe Nacional`
- `CSC` e `ID Token` de produção e homologação
- séries e próximas numerações de `NFe`, `NFCe`, `NFSe`, `NFSe Nacional`, `CTe`, `CTe OS` e `MDFe`
- flags operacionais como manifestação, contingência offline e emissão síncrona

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

[](#instalação)

### Requisitos

[](#requisitos)

- PHP 8.0+
- Laravel 9+
- Token da API FocusNFe

### Composer

[](#composer)

```
composer require sysborg/focusnfe
```

### Publicar configuração

[](#publicar-configuração)

```
php artisan vendor:publish --tag=config
```

### Variáveis de ambiente

[](#variáveis-de-ambiente)

```
FOCUSNFE_TOKEN=seu-token-focusnfe
FOCUSNFE_AMBIENTE=production
FOCUSNFE_LOG_CHANNEL=stack
FOCUSNFE_LOG_LEVEL=error
FOCUSNFE_RETRY_TIMES=3
FOCUSNFE_RETRY_SLEEP=1000
FOCUSNFE_RATE_LIMIT_ENABLED=true
FOCUSNFE_RATE_LIMIT_MAX_ATTEMPTS=60
FOCUSNFE_RATE_LIMIT_DECAY_SECONDS=60
```

### Documentação complementar

[](#documentação-complementar)

- [Guia de instalação detalhado](docs/instalacao.md)
- [Guia de configuração](docs/configuracao.md)
- [Exemplos por fluxo](docs/exemplos.md)
- [Tratamento de erros e respostas](docs/erros-e-respostas.md)
- [Eventos disponíveis](docs/eventos.md)
- [FAQ](docs/faq.md)
- [Guia de migração](docs/migracao.md)

Apoio
-----

[](#apoio)

Se este pacote te ajudou no dia a dia e você quiser apoiar o projeto de forma opcional, você pode me pagar um café via Buy Me a Coffee.

O apoio é totalmente voluntário e o foco principal deste repositório continua sendo qualidade técnica, documentação e evolução aberta do package.

Documentação da FocusNFe
------------------------

[](#documentação-da-focusnfe)

[Documentação](https://focusnfe.com.br/doc/#introducao)

###  Health Score

45

—

FairBetter than 91% of packages

Maintenance89

Actively maintained with recent releases

Popularity17

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 64.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~10 days

Recently: every ~30 days

Total

39

Last Release

7d ago

Major Versions

0.0.50 → 1.0.02026-04-08

### Community

Maintainers

![](https://www.gravatar.com/avatar/3a6c206a9669758146bf810648f37de32eb5cd5c07b8faa66c987b84fe3da696?d=identicon)[sysborg](/maintainers/sysborg)

---

Top Contributors

[![andmarruda](https://avatars.githubusercontent.com/u/29872593?v=4)](https://github.com/andmarruda "andmarruda (61 commits)")[![Edervenancio](https://avatars.githubusercontent.com/u/79012996?v=4)](https://github.com/Edervenancio "Edervenancio (31 commits)")[![sysborg](https://avatars.githubusercontent.com/u/59512284?v=4)](https://github.com/sysborg "sysborg (2 commits)")

---

Tags

laravelfocusnfenfcectemdfesefazfiscal

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/sysborg-focusnfe/health.svg)

```
[![Health](https://phpackages.com/badges/sysborg-focusnfe/health.svg)](https://phpackages.com/packages/sysborg-focusnfe)
```

###  Alternatives

[unopim/unopim

UnoPim Laravel PIM

10.5k2.4k](/packages/unopim-unopim)[bagisto/bagisto

Bagisto Laravel E-Commerce

27.6k172.1k9](/packages/bagisto-bagisto)[statamic/cms

The Statamic CMS Core Package

4.8k3.6M984](/packages/statamic-cms)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)