nfcom 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f32a81ac2b024665327e6649dd7ce8003210074349a587ac94e59da097292304
+  data.tar.gz: 382c3ef2e2932b82bff36c7523e7612408ef728839f003944cd7e291ea944ffa
+SHA512:
+  metadata.gz: cbab82c83610bcd0bf2cd28dade2fb53cacce091120eb2c6d7c9ac38908d6969fa7f2ebbe4a02a11eebc87936ab98e9b41cd584d33351c9f97332e0ddee5b48d
+  data.tar.gz: 139211d3998a511a8a32e6ee49d688846b1ff79bd2cdfe0b103fbfc83e7beae9aac94633c51c23cc80508db4c31db45ea8b8e2491f00f9cc83bfbc337c7b9c95

data/.rubocop.yml

@@ -0,0 +1,115 @@
+require:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 2.7
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+    - 'node_modules/**/*'
+    - 'bin/**/*'
+
+# Configurações de estilo
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: single_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+# Métricas
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - 'examples/**/*'
+
+Metrics/MethodLength:
+  Max: 25
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/nfcom/builder/**/*'  # Builders naturalmente têm métodos longos para gerar XML
+
+Metrics/ClassLength:
+  Max: 150
+  Exclude:
+    - 'lib/nfcom/builder/**/*'  # Builders podem ser mais longos
+
+Metrics/ModuleLength:
+  Max: 150
+
+Metrics/AbcSize:
+  Max: 25  # Aumentado para permitir validações complexas
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/nfcom/builder/**/*'  # Builders têm alta complexidade por gerarem XML
+  AllowedMethods:
+    - erros          # Métodos de validação naturalmente complexos
+    - initialize     # Construtores podem ser complexos
+
+Metrics/CyclomaticComplexity:
+  Max: 10  # Validações têm muitas condições
+  AllowedMethods:
+    - erros
+    - initialize
+
+Metrics/PerceivedComplexity:
+  Max: 10  # Validações têm muitas condições
+  AllowedMethods:
+    - erros
+    - initialize
+
+# Layout
+
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - 'spec/**/*'
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+# Naming
+
+Naming/VariableNumber:
+  Enabled: false
+
+Naming/MethodParameterName:
+  MinNameLength: 2
+
+# Lint
+
+Lint/MissingSuper:
+  Enabled: false
+
+# RSpec
+
+RSpec/ExampleLength:
+  Max: 20
+
+RSpec/MultipleExpectations:
+  Max: 5
+
+RSpec/NestedGroups:
+  Max: 5
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+
+# Suporte para contextos em português
+RSpec/ContextWording:
+  Prefixes:
+    - when
+    - with
+    - without
+    - com      # "com" = "with" em português
+    - quando   # "quando" = "when" em português
+    - sem      # "sem" = "without" em português
+    - para     # "para" = "for" em português
+    - dado     # "dado" = "given" em português

data/.ruby-version

@@ -0,0 +1 @@
+3.3.4

data/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-12-30
+
+### Added
+- Estrutura inicial da gem
+- Configuração básica via `Nfcom.configure`
+- Modelos: Nota, Emitente, Destinatario, Item, Total, Endereco
+- Builder de XML conforme layout NF-COM 1.00
+- Assinatura digital com certificado A1/A3
+- Validação de CNPJ, CPF e CEP
+- Webservices SOAP para:
+  - Autorização de notas
+  - Consulta de notas
+  - Status do serviço
+  - Inutilização de numeração
+- Parser de respostas da SEFAZ
+- Validador de XML
+- Validador de regras de negócio
+- Geração de chave de acesso
+- Geração de URL para QR Code
+- Retry automático em caso de falhas
+- Tratamento de erros específicos
+- Helper utilities
+- Gerenciador de certificado digital
+- Suporte a ambiente de homologação e produção
+- Suporte inicial para PE (Pernambuco)
+- Documentação completa
+- Exemplos de uso
+- Testes RSpec (estrutura)
+
+### Notes
+- Versão inicial (MVP)
+- Suporte apenas para Pernambuco no momento
+- Validação XSD será implementada em versão futura
+- Contingência (FS-DA) será implementada em versão futura
+- Cancelamento será implementado em versão futura
+
+## [0.1.1] - 2026-01-15
+
+### Added
+- Gerador de DANFE-COM em PDF via Prawn (`Nfcom::DanfeCom`)
+  - Layout completo: cabeçalho, emitente, destinatário, itens, totais, fatura
+  - Exibição do período de uso do serviço (`dPerUsoIni` / `dPerUsoFim`)
+  - Banner do Simples Nacional quando `CRT = 1`
+  - Suporte a logotipo (PNG e SVG via prawn-svg)
+  - Formatação de código de barras e exibição de QR Code
+  - Layout dinâmico adaptável ao conteúdo
+- Gerador de código de barras (`Nfcom::Models::Fatura::CodigoDeBarras`)
+- Modelo `Formato44` para representação da linha digitável
+
+## [0.1.2] - 2026-03-31
+
+### Added
+- Suporte a notas de substituição (`finalidade: :substituicao`)
+  - Atributos `chave_nfcom_substituida` e `motivo_substituicao` no modelo `Nota`
+  - Geração do grupo `gSub` no XML (`chNFCom` + `motSub`) conforme schema NFCom v1.00
+  - Validação de presença e formato da chave substituída (44 dígitos) e do motivo (D26)
+  - Todos os 5 motivos de substituição suportados: erro de preço, erro cadastral, decisão judicial, erro de tributação e descontinuidade do serviço

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Keith Yoder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,280 @@
+# Nfcom Ruby
+
+[![CI](https://github.com/keithyoder/nfcom-ruby/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/keithyoder/nfcom-ruby/actions/workflows/ci.yml)
+[![Security](https://github.com/keithyoder/nfcom-ruby/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/keithyoder/nfcom-ruby/actions/workflows/security.yml)
+[![Gem Version](https://badge.fury.io/rb/nfcom.svg)](https://badge.fury.io/rb/nfcom)
+
+Biblioteca Ruby para emissão de NF-COM (Nota Fiscal de Comunicação) modelo 62, desenvolvida especialmente para provedores de internet e empresas de telecomunicação.
+
+## Características
+
+- ✅ Emissão de NF-COM modelo 62
+- ✅ Assinatura digital com certificado A1/A3
+- ✅ Integração com SEFAZ via webservices SOAP
+- ✅ Validação de XML e regras de negócio
+- ✅ Suporte a ambiente de homologação e produção
+- ✅ Retry automático em caso de falhas
+- ✅ Geração de QR Code para consulta
+- ✅ Consulta de notas autorizadas
+- ✅ Verificação de status da SEFAZ
+- ✅ Inutilização de numeração
+
+## Instalação
+
+Adicione ao seu Gemfile:
+
+```ruby
+gem 'nfcom'
+```
+
+Ou instale diretamente:
+
+```bash
+gem install nfcom
+```
+
+## Configuração
+
+```ruby
+require 'nfcom'
+
+Nfcom.configure do |config|
+  # Ambiente
+  config.ambiente = :homologacao  # ou :producao
+  config.estado = 'PE'
+  
+  # Certificado digital
+  config.certificado_path = '/path/to/certificado.pfx'
+  config.certificado_senha = 'senha_do_certificado'
+    
+  # Dados do emitente
+  config.cnpj = '12345678000100'
+  config.razao_social = 'Minha Empresa LTDA'
+  config.inscricao_estadual = '0123456789'
+  config.regime_tributario = :simples_nacional
+  
+  # Configurações opcionais
+  config.serie_padrao = 1
+  config.timeout = 30
+  config.max_tentativas = 3
+  config.log_level = :info
+end
+```
+
+## Uso Básico
+
+### Emitir uma Nota
+
+```ruby
+# 1. Criar a nota
+nota = Nfcom::Models::Nota.new do |n|
+  n.serie = 1
+  n.numero = 1
+  
+  # Emitente
+  n.emitente = Nfcom::Models::Emitente.new(
+    cnpj: '12345678000100',
+    razao_social: 'Provedor Internet LTDA',
+    nome_fantasia: 'Meu Provedor',
+    inscricao_estadual: '0123456789',
+    endereco: {
+      logradouro: 'Rua das Flores',
+      numero: '123',
+      bairro: 'Centro',
+      codigo_municipio: '2611606',
+      municipio: 'Recife',
+      uf: 'PE',
+      cep: '50000-000'
+    }
+  )
+  
+  # Destinatário (cliente)
+  n.destinatario = Nfcom::Models::Destinatario.new(
+    cpf: '12345678900',
+    razao_social: 'Cliente Pessoa Física',
+    tipo_assinante: :residencial,
+    email: 'cliente@email.com',
+    endereco: {
+      logradouro: 'Av. Principal',
+      numero: '456',
+      bairro: 'Jardins',
+      codigo_municipio: '2611606',
+      municipio: 'Recife',
+      uf: 'PE',
+      cep: '51000-000'
+    }
+  )
+  
+  # Fatura
+  n.fatura = Nfcom::Models::Fatura.new(
+    competencia: '202601',                    # AAAAMM
+    data_vencimento: '2026-02-15',            # YYYY-MM-DD
+    codigo_barras: '23793381286000000099901234567890123456789012',
+    valor_fatura: 99.90
+  )
+  
+  # Adicionar serviço (item)
+  n.add_item(
+    codigo_servico: '0303',                   # Internet
+    descricao: 'Plano Fibra 100MB',
+    classe_consumo: :nao_medido_internet,     # Usar símbolo do enum
+    cfop: '5307',                             # Prestação de serviço de comunicação
+    unidade: :un,                             # Usar símbolo
+    quantidade: 1,
+    valor_unitario: 99.90
+  )
+end
+
+# 2. Enviar para SEFAZ
+client = Nfcom::Client.new
+resultado = client.autorizar(nota)
+
+if resultado[:autorizada]
+  puts "✓ Nota autorizada!"
+  puts "Chave: #{nota.chave_acesso}"
+  puts "Protocolo: #{nota.protocolo}"
+  puts "Data: #{nota.data_autorizacao}"
+  
+  # Salvar XML autorizado completo (nfcomProc)
+  # Este XML contém a NFCom assinada + protocolo de autorização
+  xml_completo = nota.xml_autorizado
+  File.write("nfcom_#{nota.numero}_#{nota.protocolo}.xml", xml_completo)
+  
+  # Ou salvar com formatação bonita
+  doc = Nokogiri::XML(xml_completo)
+  File.write("nfcom_#{nota.numero}.xml", doc.to_xml(indent: 2))
+  
+  puts "✓ XML salvo com sucesso"
+else
+  puts "✗ Erro na autorização"
+  puts "Código: #{resultado[:codigo]}"
+  puts "Motivo: #{resultado[:motivo]}"
+end
+```
+
+### O que é armazenado após autorização
+
+Após a autorização bem-sucedida, o objeto `nota` é atualizado com:
+
+```ruby
+nota.chave_acesso        # "26260107159053000107620010000081661049503004"
+nota.protocolo           # "3262600000362421"
+nota.data_autorizacao    # "2026-01-16T06:29:46-03:00"
+nota.xml_autorizado      # XML completo (nfcomProc)
+```
+
+O `nota.xml_autorizado` contém o documento completo no formato `nfcomProc`:
+- A NFCom original assinada (`<NFCom>` com `<Signature>`)
+- O protocolo de autorização da SEFAZ (`<protNFCom>`)
+
+Este é o XML legalmente válido que deve ser armazenado e fornecido ao cliente.
+
+### Consultando uma Nota
+
+```ruby
+client = Nfcom::Client.new
+
+resultado = client.consultar_nota(
+  chave: '26220512345678000100620010000000011234567890'
+)
+
+puts "Situação: #{resultado[:situacao]}"
+puts "Protocolo: #{resultado[:protocolo]}"
+```
+
+### Verificando Status da SEFAZ
+
+```ruby
+client = Nfcom::Client.new
+status = client.status_servico
+
+if status[:online]
+  puts "✓ SEFAZ online"
+  puts "Tempo médio de resposta: #{status[:tempo_medio]}ms"
+else
+  puts "✗ SEFAZ offline: #{status[:motivo]}"
+end
+```
+
+### Inutilizando Numeração
+
+```ruby
+client = Nfcom::Client.new
+
+resultado = client.inutilizar(
+  serie: 1,
+  numero_inicial: 10,
+  numero_final: 15,
+  justificativa: 'Inutilização de numeração por erro no sistema'
+)
+
+if resultado[:inutilizada]
+  puts "✓ Numeração inutilizada"
+  puts "Protocolo: #{resultado[:protocolo]}"
+end
+```
+
+## Ambiente de Homologação
+
+Durante o desenvolvimento, sempre use o ambiente de homologação:
+
+```ruby
+Nfcom.configure do |config|
+  config.ambiente = :homologacao
+  # ... outras configurações
+end
+```
+
+## Desenvolvimento
+
+```bash
+# Instalar dependências
+bundle install
+
+# Rodar testes
+bundle exec rspec
+
+# Rodar linter
+bundle exec rubocop
+
+# Console interativo
+bundle exec irb -r ./lib/nfcom
+```
+
+## Contribuindo
+
+1. Fork o projeto
+2. Crie uma branch para sua feature (`git checkout -b feature/nova-funcionalidade`)
+3. Commit suas mudanças (`git commit -am 'Adiciona nova funcionalidade'`)
+4. Push para a branch (`git push origin feature/nova-funcionalidade`)
+5. Crie um Pull Request
+
+## Licença
+
+MIT License - veja [LICENSE](LICENSE) para detalhes.
+
+## Suporte
+
+- GitHub Issues: https://github.com/keithyoder/nfcom-ruby/issues
+- Documentação SEFAZ: http://www.nfcom.fazenda.gov.br/
+- Manual NFCom: [Portal da Nota Fiscal](http://www.nfcom.fazenda.gov.br/)
+
+## Roadmap
+
+- [x] Emissão de NFCom
+- [x] Assinatura digital
+- [x] Integração SEFAZ
+- [x] Consulta de notas
+- [x] Validações completas
+- [ ] Geração de DANFE-COM (PDF)
+- [ ] Suporte a mais estados (atualmente PE)
+- [ ] Contingência (FS-DA)
+- [ ] Cancelamento de notas
+- [ ] Carta de correção
+- [ ] Validação contra schemas XSD
+- [ ] Cache de consultas
+- [ ] Webhook para eventos
+
+## Autores
+
+- Keith Yoder - Desenvolvedor inicial

data/Rakefile

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+# Bundler Audit task
+desc 'Run bundler-audit to check for vulnerable dependencies'
+task :audit do
+  require 'bundler/audit/cli'
+  Bundler::Audit::CLI.start(['check', '--update'])
+rescue LoadError
+  warn 'bundler-audit not available. Install it with: gem install bundler-audit'
+end
+
+task default: %i[spec rubocop]
+task ci: %i[spec rubocop audit]

data/examples/.env.example

@@ -0,0 +1,41 @@
+# ============================================
+# CONFIGURAÇÃO NFCOM - Nota Fiscal de Comunicação
+# ============================================
+# Copie este arquivo para .env e preencha com seus dados reais
+# NUNCA commite o arquivo .env no Git!
+
+# ============================================
+# CERTIFICADO DIGITAL (OBRIGATÓRIO)
+# ============================================
+# Caminho completo para o arquivo .pfx ou .p12
+NFCOM_CERTIFICADO_PATH=/caminho/completo/para/certificado.pfx
+
+# Senha do certificado digital
+NFCOM_CERTIFICADO_SENHA=senha_do_certificado
+
+# ============================================
+# DADOS DO EMITENTE (OBRIGATÓRIO)
+# ============================================
+# Seus dados cadastrais como provedor de internet
+NFCOM_CNPJ=12345678000100
+NFCOM_RAZAO_SOCIAL=Minha Empresa LTDA
+NFCOM_INSCRICAO_ESTADUAL=0123456789
+
+# Regime Tributário
+# 1 = Simples Nacional (padrão)
+# 3 = Regime Normal
+NFCOM_REGIME_TRIBUTARIO=1
+
+# ============================================
+# CONFIGURAÇÕES OPCIONAIS
+# ============================================
+# Série da nota fiscal (padrão: 1)
+NFCOM_SERIE_PADRAO=1
+
+# ============================================
+# NOTAS IMPORTANTES
+# ============================================
+# 1. Este arquivo deve estar em .gitignore
+# 2. NUNCA commite certificados ou senhas
+# 3. Para produção, use variáveis de ambiente do servidor
+# 4. Sempre teste em homologação primeiro

data/examples/emitir_nota.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'nfcom'
+
+# Configuração
+Nfcom.configure do |config|
+  config.ambiente = :homologacao
+  config.estado = 'PE'
+  config.certificado_path = 'caminho/para/certificado.pfx'
+  config.certificado_senha = 'senha'
+  config.cnpj = '12345678000100'
+  config.razao_social = 'Provedor Internet LTDA'
+  config.inscricao_estadual = '0123456789'
+end
+
+# Criar nota
+nota = Nfcom::Models::Nota.new do |n|
+  n.serie = 1
+  n.numero = 1
+
+  # Emitente
+  n.emitente = Nfcom::Models::Emitente.new(
+    cnpj: '12345678000100',
+    razao_social: 'Provedor Internet LTDA',
+    nome_fantasia: 'Meu Provedor',
+    inscricao_estadual: '0123456789',
+    endereco: {
+      logradouro: 'Rua das Flores',
+      numero: '123',
+      bairro: 'Centro',
+      codigo_municipio: '2611606',
+      municipio: 'Recife',
+      uf: 'PE',
+      cep: '50000-000'
+    }
+  )
+
+  # Destinatário
+  n.destinatario = Nfcom::Models::Destinatario.new(
+    cpf: '12345678900',
+    razao_social: 'Cliente Teste',
+    tipo_assinante: :residencial,
+    email: 'cliente@teste.com',
+    endereco: {
+      logradouro: 'Av. Principal',
+      numero: '456',
+      bairro: 'Jardins',
+      codigo_municipio: '2611606',
+      municipio: 'Recife',
+      uf: 'PE',
+      cep: '51000-000'
+    }
+  )
+
+  # Adicionar item
+  n.add_item(
+    codigo_servico: '0303',
+    descricao: 'Plano Fibra 100MB',
+    classe_consumo: '0303',
+    cfop: '5307',
+    quantidade: 1,
+    valor_unitario: 99.90
+  )
+end
+
+# Validar nota
+if nota.valida?
+  puts '✓ Nota válida'
+
+  # Emitir nota
+  begin
+    client = Nfcom::Client.new
+    resultado = client.autorizar(nota)
+
+    if resultado[:autorizada]
+      puts '✓ Nota autorizada!'
+      puts "  Chave: #{resultado[:chave]}"
+      puts "  Protocolo: #{resultado[:protocolo]}"
+      puts "  Data: #{resultado[:data_autorizacao]}"
+    end
+  rescue Nfcom::Errors::NotaRejeitada => e
+    puts "✗ Nota rejeitada [#{e.codigo}]: #{e.motivo}"
+  rescue Nfcom::Errors::SefazIndisponivel
+    puts '✗ SEFAZ temporariamente indisponível'
+  rescue StandardError => e
+    puts "✗ Erro: #{e.message}"
+  end
+else
+  puts '✗ Nota inválida:'
+  nota.erros.each { |erro| puts "  - #{erro}" }
+end