PHPackages                             nfse-nacional/nfse-php - 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. [Utility & Helpers](/categories/utility)
4. /
5. nfse-nacional/nfse-php

ActiveLibrary[Utility & Helpers](/categories/utility)

nfse-nacional/nfse-php
======================

This is my package nfse

v1.21.0-beta(3w ago)1648.4k↑496.4%43[2 issues](https://github.com/nfse-nacional/nfse-php/issues)[1 PRs](https://github.com/nfse-nacional/nfse-php/pulls)MITPHPPHP ^8.1CI passing

Since Dec 31Pushed 3w ago8 watchersCompare

[ Source](https://github.com/nfse-nacional/nfse-php)[ Packagist](https://packagist.org/packages/nfse-nacional/nfse-php)[ Docs](https://github.com/nfse-nacional/nfse-php)[ RSS](/packages/nfse-nacional-nfse-php/feed)WikiDiscussions main Synced 2w ago

READMEChangelog (10)Dependencies (70)Versions (41)Used By (0)

🚀 NFS-e Nacional PHP SDK
========================

[](#-nfs-e-nacional-php-sdk)

[![Latest Version on Packagist](https://camo.githubusercontent.com/96349b43cb0b179cc9a396f5ea2a09bff3a08a47a225fa863a56709f334c6ac4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6e6673652d6e6163696f6e616c2f6e6673652d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/nfse-nacional/nfse-php)[![Coverage](https://camo.githubusercontent.com/273d3179bb8daec3e9c5c718d3e7c60d97855b2cb4e5ca0ba18e78c2d63da922/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f6e6673652d6e6163696f6e616c2f6e6673652d7068702f6d61696e3f7374796c653d666c61742d737175617265)](https://codecov.io/gh/nfse-nacional/nfse-php)[![Total Downloads](https://camo.githubusercontent.com/fe7eadd38960a9af27ac0224211ba39c9818b0d50372cec9ea67881de25b3d4f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6e6673652d6e6163696f6e616c2f6e6673652d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/nfse-nacional/nfse-php)

Versão estável aberta para sugestões e melhorias
------------------------------------------------

[](#versão-estável-aberta-para-sugestões-e-melhorias)

[Discussão: modelo arquitetural estável](https://github.com/nfse-nacional/nfse-php/issues/13)

> *A bibiloteca se mostrou bastante útil no dia a dia, mas nem tudo que parece **“útil”** é realmente *bom de verdade*. Com o tempo, a gente consegue enxergar com mais clareza o ruído gerado por determinadas interfaces e abstrações.*

A experiência real de utilização permitiu identificar pontos da arquitetura que podem ser refinados e simplificados, principalmente nas responsabilidades, interfaces e abstrações entre objetos e classes.

Algumas ideias presentes no modelo atual foram úteis durante a evolução do projeto, mas certas decisões arquiteturais acabaram adicionando complexidade e ruído desnecessários em alguns cenários de uso. Esse processo de amadurecimento faz parte da evolução natural do SDK.

A próxima versão será uma oportunidade para consolidar uma arquitetura mais simples, previsível e sustentável no longo prazo, além de tornar a construção de uma versão estável algo mais aberto, democrático e colaborativo com a comunidade.

A ideia é evoluir o projeto sem perder o foco principal: oferecer uma das maneiras mais modernas e eficientes de integrar aplicações PHP com a NFS-e Nacional.

Conto com a ajuda e sugestões de todos para construirmos uma versão estável sólida e sustentável no longo prazo.

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

[](#-instalação)

```
composer require nfse-nacional/nfse-php
```

🛠️ Uso dos Serviços
-------------------

[](#️-uso-dos-serviços)

O pacote expõe dois serviços principais através da `NfseContext`: **ContribuinteService** (para emissores) e **MunicipioService** (para prefeituras).

### Configuração Inicial

[](#configuração-inicial)

```
use Nfse\Nfse;
use Nfse\Http\NfseContext;
use Nfse\Enums\TipoAmbiente;

$context = new NfseContext(
    ambiente: TipoAmbiente::Homologacao,
    certificatePath: '/path/to/certificate.pfx',
    certificatePassword: 'password'
);

$nfse = new Nfse($context);
```

### 🏢 ContribuinteService

[](#-contribuinteservice)

Focado nas necessidades de empresas que emitem notas.

```
$service = $nfse->contribuinte();

// Principais Métodos:

// 1. Emitir NFS-e
$nfseData = $service->emitir($dps); // Retorna NfseData

// 2. Consultar NFS-e
$nfseData = $service->consultar('CHAVE_ACESSO');

// 3. Baixar Documentos (Notas recebidas/emitidas)
$docs = $service->baixarDfe(nsu: 100);

// 4. Outros métodos úteis
$service->consultarDps('ID_DPS');
$service->downloadDanfse('CHAVE_ACESSO'); // Retorna PDF binário
$service->registrarEvento('CHAVE_ACESSO', $xmlEvento); // Ex: Cancelamento
$service->consultarParametrosConvenio('CODIGO_MUNICIPIO');
```

### 🏛️ MunicipioService

[](#️-municipioservice)

Focado nas necessidades de prefeituras e órgãos gestores.

```
$service = $nfse->municipio();

// Principais Métodos:

// 1. Baixar Arrecadação e Notas
$docs = $service->baixarDfe(nsu: 100, tipoNSU: 'GERAL');

// 2. Consulta Cadastral (CNC)
$dados = $service->consultarContribuinte('CPF_CNPJ');

// 3. Parâmetros e Configurações
$params = $service->consultarParametrosConvenio('CODIGO_MUNICIPIO');
$aliquotas = $service->consultarAliquota('COD_MUN', 'COD_SERV', 'COMPETENCIA');
```

📝 Exemplo de DPS (Declaração de Prestação de Serviço)
-----------------------------------------------------

[](#-exemplo-de-dps-declaração-de-prestação-de-serviço)

Abaixo, um exemplo completo de como montar o objeto DPS para emissão.

```
use Nfse\Dto\Nfse\DpsData;
use Nfse\Support\IdGenerator;

// Gerar ID único para a DPS
$idDps = IdGenerator::generateDpsId('12345678000199', '3550308', '1', '1001');

$dps = new DpsData([
    '@attributes' => ['versao' => '1.00'],
    'infDPS' => [
        '@attributes' => ['Id' => $idDps],
        'tpAmb' => 2,                // 1-Produção, 2-Homologação
        'dhEmi' => date('Y-m-d\TH:i:s'),
        'verAplic' => '1.0.0',
        'serie' => '1',
        'nDPS' => '1001',
        'dCompet' => date('Y-m-d'),
        'tpEmit' => 1,               // 1-Prestador
        'cLocEmi' => '3550308',      // Código IBGE Município
        'prest' => [
            'CNPJ' => '12345678000199'
        ],
        'toma' => [
            'CPF' => '11122233344',
            'xNome' => 'Cliente Exemplo'
        ],
        'serv' => [
            'locPrest' => [
                'cLocPrestacao' => '3550308'
            ],
            'cServ' => [
                'cTribNac' => '01.01',  // Código Tributação Nacional
                'xDescServ' => 'Desenvolvimento de Software'
            ]
        ],
        'valores' => [
            'vServPrest' => [
                'vReceb' => 1000.00,
                'vServ' => 1000.00
            ],
            'trib' => [
                'tribMun' => [
                    'tribISSQN' => 1,    // 1-Tributável
                    'tpRetISSQN' => 2,   // 1-Retido, 2-Não Retido
                    'pAliq' => 5.00
                ]
            ]
        ]
    ]
]);

// Emitir
$nfse->contribuinte()->emitir($dps);
```

🌍 Municípios Atendidos
----------------------

[](#-municípios-atendidos)

A biblioteca é compatível com todos os municípios que aderiram ao padrão nacional da NFS-e. Você pode consultar a lista atualizada de municípios conveniados através dos links oficiais:

- [Monitoramento de Adesões (Portal Gov.br)](https://www.gov.br/nfse/pt-br/municipios/monitoramento-adesoes)
- [Painel Geoestatístico de Adesões (Power BI)](https://app.powerbi.com/view?r=eyJrIjoiNGQ4YTcxNmMtMzdhNC00Mzc5LTllM2EtMjY1MTM3NWQyZDgyIiwidCI6IjZmNDlhYTQzLTgyMmEtNGMyMC05NjcwLWRiNzcwMGJmMWViMCJ9&pageName=608609c2e0a53d7a3c6e)

### 🚀 Municípios Testados (Mesmo Contrato API)

[](#-municípios-testados-mesmo-contrato-api)

Alguns municípios utilizam servidores próprios, mas seguem rigorosamente o contrato da API Nacional (DPS). Então resolvemos corretamente os endpoints no pacote. Abaixo temos uma lista de municipios que foram testados nesse contexto.

MunicípioUFStatusObservaçãoCatanduvaSP✅ TestadoUtiliza infraestrutura própria (RLZ) seguindo contrato nacional.#### Exemplo com Endpoint Customizado:

[](#exemplo-com-endpoint-customizado)

O pacote também permite que você informe endpoints próprios caso você queira usar um servidor diferente.

```
use Nfse\Http\NfseContext;
use Nfse\Dto\Http\Endpoint;
use Nfse\Enums\TipoAmbiente;

$context = new NfseContext(
    ambiente: TipoAmbiente::Producao,
    certificatePath: '/path/to/cert.pfx',
    certificatePassword: 'password',
    endpoint: new Endpoint([
        'production'   => 'https://164.152.60.237/nota/nacional',
        'homologation' => 'https://catanduva.prefeitura.rlz.com.br/nota/nacional',
    ])
);
```

Ou enviar o código do município homologado pela nfse-nacional/nfse-php através do parâmetro correspondente

```
use Nfse\Http\NfseContext;
use Nfse\Dto\Http\Endpoint;
use Nfse\Enums\TipoAmbiente;

$context = new NfseContext(
    ambiente: TipoAmbiente::Producao,
    certificatePath: '/path/to/cert.pfx',
    certificatePassword: 'password',
    codigoMunicipio: '3511102' // Catanduva/SP
);
```

Endpoints por Município
-----------------------

[](#endpoints-por-município)

Alguns municípios utilizam endpoints próprios mesmo seguindo o padrão nacional da NFS-e. Consulte a lista completa no arquivo:

👉 [Endpoints por Município](endpoints.md)

📚 Documentação Completa
-----------------------

[](#-documentação-completa)

Para detalhes profundos sobre cada DTO e configurações avançadas, visite nossa [Documentação Oficial](https://nfse-php.netlify.app/).

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

54

—

FairBetter than 97% of packages

Maintenance95

Actively maintained with recent releases

Popularity45

Moderate usage in the ecosystem

Community26

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 84.7% 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 ~6 days

Recently: every ~34 days

Total

32

Last Release

25d ago

Major Versions

v0.2.0-beta → v1.0.0-beta2026-01-02

PHP version history (3 changes)v0.1.0-betaPHP ^8.4

v1.10.0-betaPHP ^8.2

v1.12.0-betaPHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/8ef934abfc0e93bb150f57a7a8826d29b04829e3e60d62358e87d42705d4be21?d=identicon)[a21ns1g4ts](/maintainers/a21ns1g4ts)

---

Top Contributors

[![a21ns1g4ts](https://avatars.githubusercontent.com/u/11599205?v=4)](https://github.com/a21ns1g4ts "a21ns1g4ts (127 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (5 commits)")[![michelfranco17](https://avatars.githubusercontent.com/u/40202683?v=4)](https://github.com/michelfranco17 "michelfranco17 (4 commits)")[![josuearaujomoreira](https://avatars.githubusercontent.com/u/66573553?v=4)](https://github.com/josuearaujomoreira "josuearaujomoreira (2 commits)")[![andrevabo](https://avatars.githubusercontent.com/u/1074177?v=4)](https://github.com/andrevabo "andrevabo (2 commits)")[![AlanRezende](https://avatars.githubusercontent.com/u/7322595?v=4)](https://github.com/AlanRezende "AlanRezende (2 commits)")[![sicoksoftware](https://avatars.githubusercontent.com/u/48847005?v=4)](https://github.com/sicoksoftware "sicoksoftware (1 commits)")[![skydogtk](https://avatars.githubusercontent.com/u/5466576?v=4)](https://github.com/skydogtk "skydogtk (1 commits)")[![wagnercrosa](https://avatars.githubusercontent.com/u/11972961?v=4)](https://github.com/wagnercrosa "wagnercrosa (1 commits)")[![alissonlinneker](https://avatars.githubusercontent.com/u/1760923?v=4)](https://github.com/alissonlinneker "alissonlinneker (1 commits)")[![BrunoMichael](https://avatars.githubusercontent.com/u/23379795?v=4)](https://github.com/BrunoMichael "BrunoMichael (1 commits)")[![flavio89](https://avatars.githubusercontent.com/u/64870322?v=4)](https://github.com/flavio89 "flavio89 (1 commits)")[![jalesc](https://avatars.githubusercontent.com/u/140724308?v=4)](https://github.com/jalesc "jalesc (1 commits)")[![Joao-Bittencourt](https://avatars.githubusercontent.com/u/24395717?v=4)](https://github.com/Joao-Bittencourt "Joao-Bittencourt (1 commits)")

---

Tags

nfsenfse-contribuintenfse-meinfse-municipionfse-nacionalnfse-padrao-nacionalnfse-sdknfse-webservicenfse-xmlnfse

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/nfse-nacional-nfse-php/health.svg)

```
[![Health](https://phpackages.com/badges/nfse-nacional-nfse-php/health.svg)](https://phpackages.com/packages/nfse-nacional-nfse-php)
```

###  Alternatives

[neuron-core/neuron-ai

The PHP Agentic Framework.

2.0k832.6k54](/packages/neuron-core-neuron-ai)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

762297.9k53](/packages/civicrm-civicrm-core)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3661.3M49](/packages/tencentcloud-tencentcloud-sdk-php)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

353.6k](/packages/eslazarev-wildberries-sdk)[oat-sa/tao-core

TAO core extension

64147.9k151](/packages/oat-sa-tao-core)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

265.2k](/packages/aedart-athenaeum)

PHPackages © 2026

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