BrNfe

Gem para emissão de notas fiscais eletrônicas.

Motivação

Devido a falta de padronização dos parâmetros e a forma de envio e resposta na transmissão de Notas Fiscais de Serviços (NFS-e), esta gem vem com o objetivo de obter uma forma padronizada dessa tarefa, e assim, facilitando a vida de muitos desenvolvedores.

A Nota Fiscal eletrônica de produto está em desenvolvimento e pode ser acompanhada através da issue #4

O que essa gem faz?

• Assina digitalmente a nota fiscal eletrônica.
• Envia os parâmetros com a formatação adequada conforme documentação de cada web service desenvolvido.
• Formata em um padrão único a resposta de cada web service.
• Valida (opcionalmente) a obrigatoriedade de cada informação a ser enviada.

Instalação

Manualmente

gem install br_nfe

Gemfile

 gem 'br_nfe'

Introdução

Com o objetivo de padronizar os valores, foi criado algumas classes auxiliares para montar e organizar os dados para a emissão das notas fiscais, dentre eles estão:

• BrNfe::Endereco -- Tem o objetivo de padronizar os dados de endereço para o emitente e destinatário.

Específico para NFS-e:

• BrNfe::Service::Emitente -- Classe para instanciar o emitente da nota fiscal de serviço (NFS-e). -- Contém as validações e regras para o mesmo. -- Contém uma "Associação" com BrNfe::Endereco

• BrNfe::Service::Destinatario -- Classe para instanciar o destinatário da nota fiscal de serviço (NFS-e). -- Contém as validações e regras para o mesmo. -- Contém uma "Associação" com BrNfe::Endereco

• BrNfe::Service::Intermediario -- Classe para instanciar o intermediário na nota fiscal de serviço (NFS-e). -- Contém as validações e regras para o mesmo.

• BrNfe::Service::Item -- Item da nota fiscal de serviço; -- Alguns órgãos emissores permitem adicionar vários itens de serviço na NFS. -- Ainda, para alguns emissores é obrigatório a definição de itens de serviço, porém para outros esse item não é necessário.

• BrNfe::Service::Rps -- Classe para instanciar o RPS (Recibo Provisório de Serviço). -- Contém as validações e regras para o mesmo. -- Contém "Associação" com BrNfe::Service::Destinatario e BrNfe::Service::Intermediario -- Contém vários BrNfe::Service::Item através do atributo items

Como citado anteriormente, essas são classes para objetos auxiliares, e serão utilizados para manter uma melhor organização da gem.

Entendendo a organização da gem

Primeiramente é necessário ter conhecimento das operações disponíveis para cada tipo de Nota Fiscal. Vamos a elas:

Notas Fiscais de Serviço (NFS)

Existe uma certa "padronização" das operações desenvolvidas pelos Órgãos Emissores¹. São elas:

• Cancelamento de NFS (Utilizado para cancelar uma NFS)
• Consulta do Lote RPS (Utilizado para consultar um lote de RPS)
• Consulta de NFS por RPS (Utilizado para consultar uma NFS através dos dados do RPS)
• Consulta NFS (Utilizado para consultar uma ou várias NFS através do número e/ou data)
• Consulta Situação do lote RPS (Utilizado para consultar a situação de um lote de RPS para verificar se foi processado e se foi processado com sucesso ou erro)
• Recepção do lote RPS (Utilizado enviar RPS's para emissão de NFS)

Através destas operações, serão instanciados os objetos para realizar as funcionalidades para cada atividade.

Cada cidade contrata um órgão emissor para o processamento das notas (ou pode ser que a própria prefeitura desenvolva), então para realizar as operações para cada cidade, você deverá saber qual a empresa contratada para esse fim, e então instanciar o objeto de acordo com sua necessidade. A seguir segue o padrão para instanciar os objetos para cada operação:

• Para Cancelamento de NFS:

  BrNfe::Service::ORGAO_EMISSOR::VERSAO_DO_XML::CancelaNfse.new(...)

• Para Consulta do Lote RPS:

  BrNfe::Service::ORGAO_EMISSOR::VERSAO_DO_XML::ConsultaLoteRps.new(...)

• Para Consulta de NFS por RPS:

  BrNfe::Service::ORGAO_EMISSOR::VERSAO_DO_XML::ConsultaNfsPorRps.new(...)

• Para Consulta NFS:

  BrNfe::Service::ORGAO_EMISSOR::VERSAO_DO_XML::ConsultaNfse.new(...)

• Para Consulta Situação do lote RPS:

  BrNfe::Service::ORGAO_EMISSOR::VERSAO_DO_XML::ConsultaSituacaoLoteRps.new(...)

• Para Recepção do lote RPS:

  BrNfe::Service::ORGAO_EMISSOR::VERSAO_DO_XML::RecepcaoLoteRps.new(...)

Para enviar os dados para processamento deve ser chamado o método request, no qual será enviado os dados via XML para o órgão emissor correspondente.

Se desejar, antes de enviar os dados, o objeto poderá ser validado, EX:

@ws = BrNfe::Service::ORGAO_EMISSOR::V1::ConsultaLoteRps.new(...)
if @ws.valid?
    @ws.request
    @response = @ws.response
else
    # Tratamento da validação
end

O resultado obtido na variável @response é um objeto com os dados pertinentes e derivados de cada operação, por exemplo, se eu utilizar a operação de RecepcaoLoteRps, então a resposta será um objeto da classe BrNfe::Service::Response::RecepcaoLoteRps, na qual tem as informações obtidas pela resposta dessa operação. Já para a operação ConsultaLoteRps a resposta é um objeto da classe BrNfe::Service::Response::ConsultaLoteRps, e assim segue para cada operação. (para ver exemplos das respostas obtidas a cada operação, consulte a wiki).

Se desejar, é possível obter a resposta original (do savon) de cada órgão emissor através do método original_response.

Instanciando e manipulando objetos

Em todas as classes desenvolvidas é possível instanciar objetos em forma de Hash ou Block. Veja:

# Hash
@endereco = BrNfe::Endereco.new({
    logradouro: "RUA FERNANDO MACHADO",
    numero: 369,
    complemento: "E",
    # ...
})

# Block
@endereco = BrNfe::Endereco.new do |endereco|
    endereco.logradouro = "RUA FERNANDO MACHADO"
    endereco.numero = 369
    endereco.complemento = "E"
    # ...
})

As associações também podem ser instanciadas em forma de Hash ou Block, e ainda pode ser setado o objeto diretamente. Exemplo:

# Hash
@emitente = BrNfe::Service::Emitente.new({
    cnpj: '11.111.111/1111-00',
    ...
    endereco: {
        logradouro: "RUA FERNANDO MACHADO",
        numero: 369,
        complemento: "E",
        ...
    }
})
# Block
@emitente = BrNfe::Service::Emitente.new do |emitente|
    emitente.cnpj = '11.111.111/1111-00'
    ...
    emitente.endereco do |address|
        address.logradouro  = "RUA FERNANDO ...",
        address.numero      = 369,
        address.complemento = "E",
        ...
    end
    # OU
    # emitente.endereco = {
    #   logradouro: "RUA FERNANDO ...",
    #   numero: 369,
    #   complemento: "E",
    #   ...
    # }
end

# Setando o objeto
@endereco = BrNfe::Endereco.new(rua: "RUA DOS PRAZERES",...)
@emitente = BrNfe::Service::Emitente.new(razao_social: 'Emitente LTDA', endereco: @endereco)

Também é possível fazer o merge dos atributos através do método assign_attributes, por exemplo:

@endereco = BrNfe::Endereco.new({
    logradouro: "RUA 1",
    numero: 100,
    uf: 'SC'
})
@endereco.logradouro
# => "RUA 1"
@endereco.numero
# => 100
@endereco.uf
# => "SC"

@endereco.assign_attributes(numero: 200, uf: 'RS')
@endereco.logradouro
# => "RUA 1"
@endereco.numero
# => 200
@endereco.uf
# => "RS"

Exemplo para Recepção de um Lote RPS:

Endereço:

@endereco = BrNfe::Endereco.new({
    logradouro: "RUA FERNANDO MACHADO",
    numero: 369,
    complemento: "E",
    bairro: "CENTRO",
    nome_municipio: "CHAPECÓ",
    codigo_municipio: 4204202,
    uf: "SC",
    cep: "89665-000",
    # codigo_pais: 1058, <- Default
    # nome_pais: 'BRASIL', <- Default
})

Emitente:

@emitente = BrNfe::Service::Emitente.new({
    cnpj: '11.111.111/1111-00',
    inscricao_municipal: '66165-4',
    razao_social: 'RAZÃO SOCIAL',
    natureza_operacao: '1',
    nome_fantasia: 'NOME FANTASIA',
    telefone: '4933665577',
    email: 'emitente@mail.com',
    regime_especial_tributacao: '1',
    codigo_regime_tributario: '1', # 1: Simples Nacional, 2: Simples Nacional(sublimite), 3: Reg. Normal
    incentivo_fiscal: false,
    endereco: @endereco
})

Lembrando que por padrão, sempre que for chamar @emitente.endereco irá retornar um objeto da class BrNfe::Endereco, mesmo que não seja setado valor algum, ex:

@emitente = BrNfe::Service::Emitente.new
@emitente.endereco
# => #<BrNfe::Endereco:0x000000022669a0 @codigo_pais="1058",  ....>

Destinatário

@destinatario = BrNfe::Service::Destinatario.new({
    cpf_cnpj: "111.111.111-00",
    inscricao_municipal: "",
    inscricao_estadual:  "",
    inscricao_suframa:   "",
    razao_social: "NOME DA PESSOA OU EMPRESA",
    nome_fantasia: "",
    telefone: "3365478",
    email: "destinatario@mail.com",
    endereco: {
        logradouro: "RUA AUGUSTO VILA LOBO",
    numero: 45,
    complemento: "E",
    bairro: "CENTRO",
    nome_municipio: "FLORIANÓPOLIS",
    codigo_municipio: '4205407',
    uf: "SC",
    cep: "89665-000",
    }
})

Condição de pagamento

@condicao_pagamento = BrNfe::CondicaoPagamento.new do |cond|
    cond.condicao = 'A_PRAZO' # ou 'A_VISTA'
    cond.parcelas = [
        {valor: 50.33, vencimento: Date.today}, 
        {valor: '27.00', vencimento: 1.month.since}
    ]
end

Intermediário do serviço

@intermediario = BrNfe::Service::Intermediario.new({
    cpf_cnpj: '11.111.111/0001-36',
    inscricao_municipal: '3355-6',
    razao_social: "INTERMEDIÁRIO DO SERVIÇO"
})

RPS

@rps = BrNfe::Service::Rps.new do |rps|
    rps.destinatario  = @destinatario
    rps.intermediario = @intermediario
    rps.condicao_pagamento  =  @condicao_pagamento
    rps.numero                  = 5525
    rps.serie                   = "SN"
    rps.tipo                    = "1"
    rps.data_emissao            = DateTime.now
    rps.status                  = "1"
    rps.competencia             = DateTime.now
    rps.numero_substituicao     = "5524"
    rps.serie_substituicao      = "SN"
    rps.tipo_substituicao       = "1"
    rps.valor_servicos          = 100.00
    rps.valor_deducoes          = "0"
    rps.valor_pis               = "0"
    rps.valor_iss               = 2.0
    rps.aliquota                = 0.02 # = 2%
    rps.base_calculo            = "100.00"
    rps.item_lista_servico      = "1.07"
    rps.discriminacao           = "1 Configuração de servidor: R$ 500.00"
    rps.exigibilidade_iss       = "1"
    rps.codigo_municipio        = "4204202"
    rps.municipio_incidencia    = "4204202"
end

RecepcaoLoteRps (Com o órgão emissor Betha)

@recepcao = BrNfe::Service::Betha::V1::RecepcaoLoteRps.new do |ws|
    ws.emitente = @emitente
    ws.lote_rps = [@rps]
    ws.numero_lote_rps = 214
    ws.env = :production # OU :test
    ws.certificate_pkcs12_path  = '/path/to/certificate.pfx'
    wx.certificate_pkcs12_password = 'PASSWORD'
end

@recepcao.request
resp = @recepcao.response
#=> #<BrNfe::Service::Response::RecepcaoLoteRps:0x000016a9e28 ...>

resp.protocolo
#=> 'EX456156E'

resp.data_recebimento
#=> Fri, 23 Sep 2015 17:40:15 -0300

resp.numero_lote
#=> 214

Para demais operações consulte a WiKi.

Configurações

É possível customizar as classes auxiliares, por exemplo, se você quiser fazer alguma validação específica para o endereço, que contenha os mesmo atributos, você deve criar sua própria class e setar na configuração da gem qual será a classe que irá representar o endereço. Exemplo:

class MeuEndereco < BrNfe::Endereco
    validates :cep, length: { is: 8 }
end

emitente = BrNfe::Service::Emitente.new
emitente.endereco
#=> #<BrNfe::Endereco:0x000000016741d8 @codigo_pais="1058", @nome_pais="BRASIL">

BrNfe.endereco_class = MeuEndereco

emitente = BrNfe::Service::Emitente.new
emitente.endereco
#=> #<MeuEndereco:0x000000016741d8 @codigo_pais="1058", @nome_pais="BRASIL">

Segue as configurações possíveis

BrNfe.setup do |config|
    # Classe que representa o endereço
    config.endereco_class = BrNfe::Endereco

    # Classe que representa os emitentes para NFS
    config.emitente_service_class = BrNfe::Service::Emitente

    # Classe que representa o destinatário para NFS
    config.destinatario_service_class = BrNfe::Service::Destinatario

    # Classe que representa o intermediário da NFS
    config.intermediario_service_class = BrNfe::Service::Intermediario

    # Classe que representa a condição de pagamento da NFS
    config.condicao_pagamento_class = BrNfe::CondicaoPagamento

    # Classe que representa o RPS da NFS
    config.rps_class = BrNfe::Service::Rps

    # Classe que representa o item de uma NFS
    config.service_item_class = BrNfe::Service::Item

    # Se você quiser exibir em log a requisição SOAP, mude para true as opções a seguir
    config.client_wsdl_log = false
    config.client_wsdl_pretty_print_xml = false
end

Objetivos futuros

• Emitir notas fiscais de produtos (em andamento).
• Emitir notas fiscais de serviços para todas as cidades do Brasil.
• Emitir DANFE.
• Leitura de notas fiscais de produto e serviço

Contribuições

Seja um contribuidor. Você pode contribuir de várias formas:

• Desenvolver emissão de NFS-e para outras cidades.
• Desenvolver emissão de NF-e (produtos).
• Refatorando código.
• Fornecendo Feedback construtivo (Sempre bem vindo!).

Licença

• MIT
• Copyleft 2016 Bruno Mucelini Mergen

¹ Órgão Emissor: É a empresa contratada pela prefeitura com a finalidade de processar as notas fiscais. Exemplo: (Betha, Simpliss, Thema)