NAME

Business::BR::NFSe - Consulta e emissão de NFS-e (Nota Fiscal de Serviços Eletrônica) via API REST do Emissor Nacional (Sefin)

SYNOPSIS

use Business::BR::NFSe;

my $nfse = Business::BR::NFSe->new(
    cert_pem_path  => 'certificado.pem',
    key_pem_path   => 'chave_privada.pem',
    cnpj_prestador => '26744350000156',
    ibge_cidade    => '3304557',
    # Simples Nacional ME/EPP - ajuste como necessário
    op_simples_nacional => '3',
    reg_ap_trib_sn      => '1',
    regime_especial     => '0',
    p_tot_trib_sn       => '17.99',
);

my $resp = $nfse->emitir(
    serie                    => '1',
    n_dps                    => '12345',   # obrigatório incrementar por emissão
    data_emissao             => '2026-06-23T12:59:00-03:00',
    cpf_tomador              => '12345678909',
    nome_tomador             => 'Fulano de Tal',
    cod_tributacao_nacional  => '100201',
    cod_tributacao_municipal => '001',
    descricao_servico        => 'Descrição do serviço prestrado.',
    valor_servico            => '49.99',
);

if ($resp->{success}) {
    say 'OK ' . $resp->{content};
} else {
    say "ERRO $resp->{status}: $resp->{content}\n";
}

DESCRIPTION

This module provides a way to query and emit Brazilian service tax invoices via the government's official REST API. Since the main audience for this module are Brazilian developers, the documentation is provided in portuguese only. If you need help with this module but don't speak portuguese, please contact the author.

DESCRIÇÃO

Este módulo permite a consulta e emissão de Notas Fiscais de Serviço Eletrônicas (NFS-e) diretamente da API REST do Emissor Nacional, sem intermediários.

Este módulo incorpora uma postura minimalista de oferecer 80% das funcionalidades com 20% do código, de modo a ser fácil de carregar e utilizar em programas já existentes.

ATENÇÃO: Este módulo emite somente notas de serviço (NFSe). Não é possível utilizá-lo para emitir notas fiscais de produto (NFe).

CONSTRUTOR

new( %args )

Instancia um novo objeto Business::BR::NFSe. Aceita os seguintes argumentos:

cert_pem_path, key_pem_path

Caminhos para o certificado A1/A3 do ICP-Brasil e para a chave privada, ambos em formato PEM. O certificado deve conter somente o bloco PEM puro, sem os cabeçalhos de atributos do OpenSSL.

Obrigatório para emissão de notas de serviço.

cnpj_prestador

CNPJ da empresa prestadora dos serviços, utilize caso seu programa emita de apenas um CNPJ. Somente dígitos, sem pontuação.

ibge_cidade

Código de cidade do IBGE da empresa prestadora do serviço. 7 digitos. Veja IBGE::Municipios para uma interface de consulta.

op_simples_nacional

Indicador do status da prestadora no Simples Nacional 1=Não Optante, 2=MEI, 3=ME/EPP. Padrão: 3.

reg_ap_trib_sn

Regime de apuração para os optantes do Simples Nacional:

1=federal+municipal no Simples, 2=federal no Simples, ISSQN fora do Simples. Padrão: 1.

regime_especial

Código do regime especial. Padrão é 0 (nenhum).

p_tot_trib_sn

Valor aproximado do percentual de taxa do Simples Nacional (Lei 12.741/2012). Padrão: '17.99'. Verifique o percentual da empresa prestadora pela alíquota do DAS.

ambiente

1=Produção, 2=Homologação. Padrão: 1.

Emissão de Notas de Serviço Eletrônicas (NFS-e)

emitir( %dados )

Utilize esse método para emitir notas. Ele aceita os mesmos argumentos descritos no construtor, de modo que você possa emitir notas de diferentes prestadores de serviço com o mesmo objeto.

Além disso, é obrigatório especificar os dados do tomador do serviço, preenchendo uma (e somente uma) das opções abaixo:

cpf_tomador — CPF, somente dígitos

ou

cnpj_tomador — CNPJ, somente dígitos

ou

nao_nif_tomador — '1' (dispensado) ou '2' (não exigência), para estrangeiros.

Outras propriedades obrigatórias na emissão da nota de serviço:

serie - o número da série DPS

n_dps - o número sequencial do DPS (precisa ser único e incremental)

data_emissao - data da emissão em formato ISO8601, ex: '2026-03-04T12:59:00-03:00'

nome_tomador - nome completo (ou razão social) do tomador do serviço

cod_tributacao_nacional - código de 6 dígitos do serviço prestado (ex: '100201')

cod_tributacao_municipal - código do serviço municipal, ex: '001'

descricao_servico - texto livre para descrever o serviço (máx: 2000 caracteres)

valor_servico - valor do serviço prestado em reais (BRL), ex: '3869.49'

Este método devolve um hashref com a resposta do HTTP::Tiny, com informações a respeito da emissão (ou do erro gerado). Em caso de sucesso, um dos elementos retornados será a chave de acesso da NFSe.

Obtendo o DANFSe (PDF da Nota de Serviço)

danfse( $chave )

Recebe uma chave de acesso (retornada ao chamar emitir()) e retorna o pdf da DANFSe em bytes, pronto para ser gravado em arquivo ou servido na sua aplicação.

LICENÇA / LICENSE

As mesmas do Perl. Same terms as Perl itself.