PHPackages                             ownerpro/nfsen-php-sdk - 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. [Parsing &amp; Serialization](/categories/parsing)
4. /
5. ownerpro/nfsen-php-sdk

ActiveLibrary[Parsing &amp; Serialization](/categories/parsing)

ownerpro/nfsen-php-sdk
======================

Pacote Laravel para emissão de NFSe Nacional

v1.0.0(today)01↑2900%[1 PRs](https://github.com/OwnerPro-Software/nfsen-php-sdk/pulls)MITPHPPHP ^8.2CI passing

Since Mar 24Pushed todayCompare

[ Source](https://github.com/OwnerPro-Software/nfsen-php-sdk)[ Packagist](https://packagist.org/packages/ownerpro/nfsen-php-sdk)[ Docs](https://github.com/OwnerPro-Software/nfsen-php-sdk)[ RSS](/packages/ownerpro-nfsen-php-sdk/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (14)Versions (3)Used By (0)

NFSe Nacional
=============

[](#nfse-nacional)

[![CI](https://github.com/OwnerPro-Software/nfsen-php-sdk/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/OwnerPro-Software/nfsen-php-sdk/actions)[![PHPStan Level 10](https://camo.githubusercontent.com/d18b9a987aa81e64470a11caecf72caa66597c9ebd6b307bd1c2cb7a752b0dff/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c25323031302d627269676874677265656e2e737667)](https://phpstan.org/)[![Latest Version on Packagist](https://camo.githubusercontent.com/ac2284d27c0df60973be1492949b13901e2ec9ea5700bd9029500b9e767afccc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f776e657270726f2f6e6673656e2d7068702d73646b2e737667)](https://packagist.org/packages/ownerpro/nfsen-php-sdk)[![PHP Version](https://camo.githubusercontent.com/80046c0cdbe37282603141940b9281a9d3b54039a807fe9f7a938dc1817ea0af/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6f776e657270726f2f6e6673656e2d7068702d73646b2e737667)](https://packagist.org/packages/ownerpro/nfsen-php-sdk)[![License](https://camo.githubusercontent.com/294a159af788a7c4822c57a37f7fcec5a5f578c47339307e8ce61844e8071aaf/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6f776e657270726f2f6e6673656e2d7068702d73646b2e737667)](LICENSE)

Pacote PHP para emissão, cancelamento, substituição e consulta de **NFSe Padrão Nacional** ([nfse.gov.br](https://www.nfse.gov.br/)) via API REST. Funciona com Laravel 11/12 ou standalone (sem framework).

Funcionalidades
---------------

[](#funcionalidades)

- Emissão de NFSe (`emitir`) e emissão por decisão judicial (`emitirDecisaoJudicial`)
- Cancelamento de NFSe (`cancelar`)
- Substituição de NFSe (`substituir`)
- Consulta por chave de acesso, DPS, DANFSE (URL do PDF), eventos e verificação de DPS
- Assinatura digital XML com certificado A1 (PFX/P12)
- Validação XSD dos documentos
- Eventos Laravel opcionais (`NfseEmitted`, `NfseCancelled`, `NfseRejected`, etc.)
- mTLS sem escrita nomeada em disco
- 100% de cobertura de testes e tipos

Requisitos
----------

[](#requisitos)

- PHP 8.2+
- Extensões: `curl`, `dom`, `zlib`, `openssl`, `mbstring`, `libxml`
- Laravel 11 ou 12 (opcional — funciona standalone)

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

[](#instalação)

```
composer require ownerpro/nfsen-php-sdk
```

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

[](#configuração)

### Laravel

[](#laravel)

Publique o arquivo de configuração:

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

Adicione as variáveis de ambiente no `.env`:

```
NFSE_AMBIENTE=2                   # 1 = Producao, 2 = Homologacao (aceita: 'producao', 'production', 'homologacao', 'homologation')
NFSE_PREFEITURA=3550308           # Codigo IBGE do municipio (7 digitos)
NFSE_CERT_PATH=/caminho/cert.pfx  # Caminho do certificado PFX/P12
NFSE_CERT_SENHA=senha             # Senha do certificado
NFSE_TIMEOUT=30
NFSE_CONNECT_TIMEOUT=10
NFSE_SIGNING_ALGORITHM=sha1
NFSE_SSL_VERIFY=true
```

### Standalone (sem Laravel)

[](#standalone-sem-laravel)

```
use OwnerPro\Nfsen\Enums\NfseAmbiente;
use OwnerPro\Nfsen\NfsenClient;

$client = NfsenClient::forStandalone(
    pfxContent: file_get_contents('/caminho/certificado.pfx'),
    senha: 'senha_certificado',
    prefeitura: '3550308',
    ambiente: NfseAmbiente::HOMOLOGACAO,
);
```

Uso
---

[](#uso)

### Emitir NFSe

[](#emitir-nfse)

```
$response = $client->emitir([
    'infDPS' => [
        'tpAmb'    => '2',                          // 1 = Producao, 2 = Homologacao
        'dhEmi'    => date('Y-m-d\TH:i:sP'),       // Data/hora emissao
        'verAplic' => 'MeuSistema_v1.0',
        'serie'    => '1',
        'nDPS'     => '1',
        'dCompet'  => date('Y-m-d'),                // Data de competencia
        'tpEmit'   => '1',                          // 1 = Prestador
        'cLocEmi'  => '3550308',                    // Codigo IBGE 7 digitos
    ],
    'prest' => [
        'CNPJ'    => '00000000000000',
        'fone'    => '11999999999',
        'regTrib' => [
            'opSimpNac'   => '2',                   // 1 = Nao Optante, 2 = MEI, 3 = ME/EPP
            'regEspTrib'  => '0',                   // 0 = Nenhum
        ],
    ],
    'toma' => [
        'xNome' => 'Tomador Exemplo Ltda',
        'CPF'   => '00000000000',
        'end'   => [
            'xLgr'   => 'Rua Exemplo',
            'nro'    => '100',
            'xBairro' => 'Centro',
            'endNac' => [
                'cMun' => '3550308',
                'CEP'  => '01001000',
            ],
        ],
    ],
    'serv' => [
        'cLocPrestacao' => '3550308',
        'cServ' => [
            'cTribNac'    => '010101',
            'xDescServ'   => 'Desenvolvimento de software sob encomenda',
            'cNBS'        => '116030000',
            'cIntContrib' => '1234',
        ],
    ],
    'valores' => [
        'vServPrest' => ['vServ' => '1000.00'],
        'trib' => [
            'tribMun' => [
                'tribISSQN'  => '1',               // 1 = Operacao tributavel
                'tpRetISSQN' => '1',               // 1 = Nao retido
            ],
            'indTotTrib' => '0',
        ],
    ],
]);

if ($response->sucesso) {
    echo "Chave: {$response->chave}\n";
    echo "XML: {$response->xml}\n";
} else {
    foreach ($response->erros as $erro) {
        echo "[{$erro->codigo}] {$erro->mensagem} - {$erro->descricao}";
    }
}
```

### Emitir NFSe por decisão judicial

[](#emitir-nfse-por-decisão-judicial)

Utiliza endpoint diferente (`emit_court_order`) para notas emitidas por determinação judicial:

```
$response = $client->emitirDecisaoJudicial($dps);
// Mesma estrutura de DPS e mesmo NfseResponse do emitir()
```

### Cancelar NFSe

[](#cancelar-nfse)

```
use OwnerPro\Nfsen\Enums\CodigoJustificativaCancelamento;

$response = $client->cancelar(
    chave: '00000000000000000000000000000000000000000000000000',
    codigoMotivo: CodigoJustificativaCancelamento::ErroEmissao,
    descricao: 'Erro na emissao da nota fiscal',
);
```

Codigos de cancelamento: `ErroEmissao`, `ServicoNaoPrestado`, `Outros`.

### Substituir NFSe

[](#substituir-nfse)

O método `substituir()` emite uma DPS com o grupo `subst` preenchido automaticamente. O ADN (Ambiente de Dados Nacional) cancela a nota original ao processar a DPS substituta — uma única requisição.

> **Nota:** O registro do evento de cancelamento por substituição (`e105102`) via API Eventos (`POST /nfse/{chave}/eventos`) é restrito a sistemas municipais conveniados com o ADN — o autor desse evento é o município emissor (MEmis), não o contribuinte. O cancelamento da nota original ocorre automaticamente ao emitir a DPS com o grupo `subst` preenchido.

```
use OwnerPro\Nfsen\Enums\CodigoJustificativaSubstituicao;

$response = $client->substituir(
    chave: '00000000000000000000000000000000000000000000000000',
    dps: $dpsSubstituta, // DPS da nota substituta (mesma estrutura do emitir)
    codigoMotivo: CodigoJustificativaSubstituicao::Outros,
    descricao: 'Substituicao por correcao de dados',
);

// NfseResponse (mesmo retorno do emitir)
if ($response->sucesso) {
    echo "Chave substituta: {$response->chave}";
} else {
    foreach ($response->erros as $erro) {
        echo "[{$erro->codigo}] {$erro->descricao}\n";
    }
}
```

Codigos de substituição: `DesenquadramentoSimplesNacional`, `EnquadramentoSimplesNacional`, `InclusaoRetroativaImunidadeIsencao`, `ExclusaoRetroativaImunidadeIsencao`, `RejeicaoTomadorIntermediario`, `Outros`.

### Consultas

[](#consultas)

```
use OwnerPro\Nfsen\Enums\TipoEvento;

// Consultar NFSe por chave de acesso
$response = $client->consultar()->nfse($chave);

// Consultar DPS por ID
$response = $client->consultar()->dps($idDps);

// Obter PDF do DANFSE
$response = $client->consultar()->danfse($chave);
// $response->pdf contém o conteúdo binário do PDF
file_put_contents('danfse.pdf', $response->pdf);

// Consultar eventos (tipoEvento é obrigatório)
$response = $client->consultar()->eventos(
    chave: $chave,
    tipoEvento: TipoEvento::CancelamentoPorIniciativaPrestador, // e101101
    nSequencial: 1,
);
// Tipos disponíveis: CancelamentoPorIniciativaPrestador, CancelamentoPorIniciativaFisco,
// CancelamentoPorSubstituicao, AnulacaoCancelamento

// Verificar se DPS foi processada
$processada = $client->consultar()->verificarDps($idDps); // true ou false
```

### Laravel Facade

[](#laravel-facade)

```
use OwnerPro\Nfsen\Facades\Nfsen;

// Emitir
$response = Nfsen::emitir($dps);

// Cancelar
$response = Nfsen::cancelar($chave, $motivo, $descricao);

// Consultar
$response = Nfsen::consultar()->nfse($chave);
$danfse   = Nfsen::consultar()->danfse($chave);

// Usar certificado diferente por requisicao
$client = Nfsen::for($pfxContent, $senha, '3550308');
$response = $client->emitir($dps);

// Sobrescrever ambiente (ignorar config)
use OwnerPro\Nfsen\Enums\NfseAmbiente;

$client = Nfsen::for($pfxContent, $senha, '3550308', NfseAmbiente::PRODUCAO);
$response = $client->emitir($dps);
```

Eventos
-------

[](#eventos)

O pacote dispara eventos Laravel que podem ser escutados na sua aplicação:

EventoPropriedadesDescricao`NfseEmitted``chave`NFSe emitida com sucesso`NfseCancelled``chave`NFSe cancelada com sucesso`NfseSubstituted``chave`, `chaveSubstituta`NFSe substituída com sucesso`NfseQueried``operacao`Consulta realizada`NfseRequested``operacao`, `metadata`Operação iniciada`NfseRejected``operacao`, `codigoErro`Operação rejeitada pela API`NfseFailed``operacao`, `mensagem`Falha na operação**Substituição:** como `substituir` delega ao `emitir` internamente, a sequência de eventos disparados é: `NfseRequested('emitir')` → `NfseEmitted` → `NfseSubstituted`

Objetos de Resposta
-------------------

[](#objetos-de-resposta)

Cada operação retorna um DTO tipado e imutável:

### `NfseResponse`

[](#nfseresponse)

Retornado por `emitir()`, `emitirDecisaoJudicial()`, `cancelar()`, `substituir()`, `consultar()->nfse()` e `consultar()->dps()`.

PropriedadeTipoDescricao`sucesso``bool`Se a operação foi aceita`chave``?string`Chave de acesso da NFSe (50 dígitos)`xml``?string`XML da NFSe processada`idDps``?string`Identificador da DPS`alertas``list`Alertas não-bloqueantes`erros``list`Erros de processamento`tipoAmbiente``?int`1 = Produção, 2 = Homologação`versaoAplicativo``?string`Versão do aplicativo da SEFIN`dataHoraProcessamento``?string`Data/hora do processamento### `DanfseResponse`

[](#danfseresponse)

Retornado por `consultar()->danfse()`.

PropriedadeTipoDescricao`sucesso``bool`Se o PDF foi obtido`pdf``?string`Conteúdo binário do PDF`erros``list`Erros de processamento### `EventsResponse`

[](#eventsresponse)

Retornado por `consultar()->eventos()`.

PropriedadeTipoDescricao`sucesso``bool`Se a consulta teve sucesso`xml``?string`XML do evento`erros``list`Erros de processamento`tipoAmbiente``?int`1 = Produção, 2 = Homologação`versaoAplicativo``?string`Versão do aplicativo da SEFIN`dataHoraProcessamento``?string`Data/hora do processamento### `ProcessingMessage`

[](#processingmessage)

Representa uma mensagem de erro ou alerta da API:

PropriedadeTipoDescricao`mensagem``?string`Mensagem principal`codigo``?string`Código do erro/alerta`descricao``?string`Descrição detalhada`complemento``?string`Informação complementarExceções
--------

[](#exceções)

ExceçãoPaiQuando`NfseException``RuntimeException`Erros gerais (XML inválido, falha de compressão, etc.)`HttpException``NfseException`Erros HTTP 5xx sem corpo JSON. Acesse `getResponseBody()` para detalhes`CertificateExpiredException``NfseException`Certificado PFX/P12 expirado`InvalidDpsArgument``InvalidArgumentException`Campos mutuamente exclusivos ou obrigatórios violados na DPS```
use OwnerPro\Nfsen\Exceptions\CertificateExpiredException;
use OwnerPro\Nfsen\Exceptions\HttpException;
use OwnerPro\Nfsen\Exceptions\InvalidDpsArgument;
use OwnerPro\Nfsen\Exceptions\NfseException;

try {
    $response = $client->emitir($dps);
} catch (CertificateExpiredException $e) {
    // Certificado expirado -- renovar
} catch (InvalidDpsArgument $e) {
    // Dados da DPS inválidos -- corrigir payload
} catch (HttpException $e) {
    // Erro HTTP -- $e->getCode() para status, $e->getResponseBody() para corpo
} catch (NfseException $e) {
    // Outros erros (XML, compressão, etc.)
}
```

Exemplos
--------

[](#exemplos)

Exemplos completos de cada operação estão disponíveis no diretório [`examples/`](examples/).

Testes
------

[](#testes)

```
composer test
```

Para executar todas as verificações de qualidade:

```
composer quality
```

Contribuindo
------------

[](#contribuindo)

Veja [CONTRIBUTING.md](CONTRIBUTING.md) para detalhes.

Créditos
--------

[](#créditos)

Este pacote teve como base o trabalho do projeto original [nfse-nacional](https://github.com/Rainzart/nfse-nacional) de **Fernando Friedrich**, que por sua vez foi construído sobre o [NFePHP](https://github.com/nfephp-org) de **Roberto L. Machado**.

Agradecimento a todos os contribuidores que ajudaram a evoluir este projeto.

Licença
-------

[](#licença)

MIT. Veja [LICENSE](LICENSE).

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance100

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 84.4% 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

Unknown

Total

1

Last Release

0d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/df52d610b41e6ab418dfdb8a4b7607ebdf39dc129d60b452788827267b123985?d=identicon)[jonathanpmartins](/maintainers/jonathanpmartins)

---

Top Contributors

[![jonathanpmartins](https://avatars.githubusercontent.com/u/6137992?v=4)](https://github.com/jonathanpmartins "jonathanpmartins (233 commits)")[![Rainzart](https://avatars.githubusercontent.com/u/563814?v=4)](https://github.com/Rainzart "Rainzart (28 commits)")[![leandro-mafra](https://avatars.githubusercontent.com/u/17616770?v=4)](https://github.com/leandro-mafra "leandro-mafra (3 commits)")[![BangemannGuilherme](https://avatars.githubusercontent.com/u/65203625?v=4)](https://github.com/BangemannGuilherme "BangemannGuilherme (3 commits)")[![OswaldoAranda](https://avatars.githubusercontent.com/u/42947585?v=4)](https://github.com/OswaldoAranda "OswaldoAranda (2 commits)")[![muriloelias](https://avatars.githubusercontent.com/u/2312096?v=4)](https://github.com/muriloelias "muriloelias (2 commits)")[![visio-simenes](https://avatars.githubusercontent.com/u/215207795?v=4)](https://github.com/visio-simenes "visio-simenes (1 commits)")[![mskamot](https://avatars.githubusercontent.com/u/11540014?v=4)](https://github.com/mskamot "mskamot (1 commits)")[![nagualcode](https://avatars.githubusercontent.com/u/13026978?v=4)](https://github.com/nagualcode "nagualcode (1 commits)")[![TI-Einov](https://avatars.githubusercontent.com/u/146743576?v=4)](https://github.com/TI-Einov "TI-Einov (1 commits)")[![ahwelp](https://avatars.githubusercontent.com/u/14235495?v=4)](https://github.com/ahwelp "ahwelp (1 commits)")

---

Tags

phplaravelxmlnota fiscalnfsenfse-nacionalcertificado-digitalnota-fiscal-servicoprefeitura

###  Code Quality

TestsPest

Static AnalysisPHPStan, Psalm, Rector

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/ownerpro-nfsen-php-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/ownerpro-nfsen-php-sdk/health.svg)](https://phpackages.com/packages/ownerpro-nfsen-php-sdk)
```

###  Alternatives

[ultrono/laravel-sitemap

PHP 8 sitemap generator for Laravel 8, 9, 10 and 11

37389.7k3](/packages/ultrono-laravel-sitemap)[tucker-eric/laravel-xml-middleware

A Laravel Middleware to accept XML requests

181.2M](/packages/tucker-eric-laravel-xml-middleware)

PHPackages © 2026

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