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 para Laravel com a FocusNFe

0.0.50(2mo ago)088MITPHPPHP >=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 1mo ago

READMEChangelog (3)Dependencies (8)Versions (39)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)

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 permite que o usuário escolha entre utilizar Services ou acessar os recursos diretamente por meio de rotas.

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.

Swagger
-------

[](#swagger)

Todas as rotas estão bem documentadas seguindo o padrão do Swagger, permitindo que você disponibilize uma documentação clara e acessível. Caso queira uma solução rápida e prática, basta implementar o Swagger no seu projeto Laravel para oferecer uma referência detalhada da API. [Swagger](https://github.com/DarkaOnLine/L5-Swagger)

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 a rota de webhook é estimulada

[](#evento-quando-a-rota-de-webhook-é-estimulada)

```
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)

### Recebimento de webhooks no Laravel

[](#recebimento-de-webhooks-no-laravel)

O package já oferece o client HTTP para cadastro e gestão de webhooks e também o evento `HooksReceived` para você integrar o payload recebido à sua aplicação.

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 rota/controller para receber o webhook:

```
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\Route;
use Symfony\Component\HttpFoundation\Response;
use Sysborg\FocusNfe\app\Events\HooksReceived;

Route::post('/focusnfe/webhooks', function (Request $request) {
    $expectedHeader = 'Authorization';
    $expectedValue = 'Bearer meu-token-interno';

    if ($request->header($expectedHeader) !== $expectedValue) {
        abort(Response::HTTP_UNAUTHORIZED, 'Webhook nao autorizado.');
    }

    Event::dispatch(new HooksReceived(
        $request->all(),
        (string) $request->headers->get('referer', '')
    ));

    return response()->json(['ok' => true]);
});
```

Se quiser trocar o nome do cabeçalho, configure o campo `authorization_header` no `WebhookDTO` e valide o mesmo nome no seu endpoint.

### 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 entrada de webhook, 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\EmpresaCreated

```

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)

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

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

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

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance87

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 62.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 ~7 days

Recently: every ~2 days

Total

36

Last Release

76d ago

### 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 (56 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)")

###  Code Quality

TestsPHPUnit

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

[echolabsdev/prism

A powerful Laravel package for integrating Large Language Models (LLMs) into your applications.

2.3k388.3k10](/packages/echolabsdev-prism)[aimeos/aimeos-headless

Aimeos headless ecommerce system

2.5k2.3k](/packages/aimeos-aimeos-headless)[rupadana/filament-api-service

A simple api service for supporting filamentphp

204103.8k7](/packages/rupadana-filament-api-service)[sburina/laravel-whmcs-up

WHMCS API client and user provider for Laravel

271.3k](/packages/sburina-laravel-whmcs-up)

PHPackages © 2026

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