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.20.0-beta(1mo ago)1535.3k↑436.2%40[2 issues](https://github.com/nfse-nacional/nfse-php/issues)[3 PRs](https://github.com/nfse-nacional/nfse-php/pulls)MITPHPPHP ^8.1CI passing

Since Dec 31Pushed 3d ago6 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 yesterday

READMEChangelog (10)Dependencies (56)Versions (40)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 96% of packages

Maintenance96

Actively maintained with recent releases

Popularity44

Moderate usage in the ecosystem

Community25

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 87% 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 ~5 days

Recently: every ~20 days

Total

31

Last Release

37d 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)")[![michelfranco17](https://avatars.githubusercontent.com/u/40202683?v=4)](https://github.com/michelfranco17 "michelfranco17 (3 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 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

[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.3k543.5M2.6k](/packages/aws-aws-sdk-php)[neuron-core/neuron-ai

The PHP Agentic Framework.

2.0k656.1k38](/packages/neuron-core-neuron-ai)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3741.3M47](/packages/tencentcloud-tencentcloud-sdk-php)[civicrm/civicrm-core

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

751291.4k43](/packages/civicrm-civicrm-core)[spatie/laravel-export

Create a static site bundle from a Laravel app

674146.0k6](/packages/spatie-laravel-export)[oat-sa/tao-core

TAO core extension

66143.7k122](/packages/oat-sa-tao-core)

PHPackages © 2026

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