EnotasApi

enotas_api é um cliente ruby para a API do e-notas.

EnotasApi é uma gem não oficial porém com design simples, livre de dependências

Criada e mantida com carinho por @bempapp.

English Readers

enotas_api is a ruby api client for e-notas API.

EnotasApi its a non oficial, but well with simple design an dependency free

Created and supported with love by @bempapp.

PS: Because e-notas api is entire in portuguese, the code and documentation from here will also be. Sorry about that. :D

Dependencias

EnotasApi não depende de nenhuma Gem externa para executar, (aloha dependency hell). Porém implementamos com a versão de ruby >= ruby 3.1 que é compatível com a versão que temos em produção, ~> ruby 3.2.2. Se tiver interesse em fazer backport para versões anteriores, não deixe de fazer seu comentário ou abrir um PR.

Instalação

Adicione ao seu Gemfile

gem 'enotas_api'

E então execute:

$ bundle install

Ou instale você mesmo com:

$ gem install enotas_api

Utilização

Primeiro é necessário configurar o EnotasApi

EnotasApi::Configuration.configure(api_key: '<sua api key>')

Você pode ver como conseguir sua API-KEY na documentação do e-notas.

Conceitos

Enotas-API é dividida da mesma forma como os endpoints do e-notas para facilitar o uso e o entendimento da relação de nossa implementação com os endpoints documentos. Portanto para cada endpoint disponíveis há um objeto em EnotasApi para.

Alguns exemplos:

Este é um exemplo de uma consulta simples

result = EnotasApi::V1::ConsultarCaracteristicasPrefeitura.new(codigo_ibge_cidade).call
result # é um objeto com todos os atributos retornados pela api do e-notas
result.tipoAutenticacao # = 1
result.helpTipoAutenticacao.certificadoDigital # = "Sua prefeitura exige a utilização de certificado digital, portanto, inclua aqui o arquivo de seu certificado A1."

Um exemplo um pouco mais complexo onde se pode utilizar os recursos de filtro, ordenação e paginação suportados pela API.

result = EnotasApi::V1::ListarEmpresas.new.search_by_nome_fantasia('nome_fantasia').sort_by_cidade.page(number: 10, size: 30).call
result.totalRecords # = 10
result.data.first.razaoSocial # = "Razão Social"

Todos os objetos lhe permitem também saber a URL e o json retornado pela API

instance = EnotasApi::V1::ConsultarCaracteristicasPrefeitura.new(123)
instance.to_url # = "https://api.enotasgw.com.br/v1/estados/cidades/123/provedor"
result = instance.call
result.to_json # = <JSON retornado pela API do e-notas>

Endpoints suportados (marcados com X) e em desenvolvimento (sem marcação)

Atualmente EnotasApi suporta por complexo a API V1 do enotas (NFS-e) O suporte as novas APIs (V2) com suporte a NFC-e e NF-e estarão disponíveis em breve.

• NFS-e (V1)
  • Empresa
    • Consultar Empresa - EnotasApi::V1::ConsultarEmpresa
    • Listar Empresas - EnotasApi::V1::ListarEmpresas
    • Incluir / Atualizar Empresa - EnotasApi::V1::IncluirAtualizarEmpresa
    • Vincular Certificado - EnotasApi::V1::VincularCertificado
    • Vincular Logotipo - EnotasApi::V1::VincularLogotipo
    • Desabilitar Empresa - EnotasApi::V1::DesabilitarEmpresa
    • Habilitar Empresa - EnotasApi::V1::HabilitarEmpresa
  • Nota Fiscal eletrônica de serviço (NFS-e)
    • Listar Notas Fiscais - EnotasApi::V1::ListarNotasFiscais
    • Consultar pelo ID do Gateway - EnotasApi::V1::ConsultarNotaFiscal
    • Consultar pelo Id Externo - EnotasApi::V1::ConsultarNotaFiscalIdExterno
    • Download XML - EnotasApi::V1::BaixarXmlNfs
    • Download XML (IdExterno) - EnotasApi::V1::BaixarXmlNfsIdExterno
    • Download PDF - EnotasApi::V1::BaixarPdfNfs
    • Download PDF (IdExterno) - EnotasApi::V1::BaixarPdfNfsIdExterno
    • Emissão de Nota Fiscal - EnotasApi::V1::EmitirNfs
    • Cancelar - EnotasApi::V1::CancelarNfs
    • Cancelar (IdExterno) - EnotasApi::V1::CancelarNfsIdExterno
  • API Complementar
    • Serviços Municipais da Cidade - EnotasApi::V1::ConsultarServicosMunicipais
    • Características da Prefeitura - EnotasApi::V1::ConsultarCaracteristicasPrefeitura
    • Cidades com Serviço Municipal Unificado - EnotasApi::V1::ConsultarCidadesServicoMunicipalUnificado
• NF-e & NFC-e (v2)
  • Empresa
    • Incluir/Alterar Empresa
    • Vincular Certificado
    • Vincular Logotipo
    • Consultar Empresa
    • Listar Empresas
  • Nota Fiscal eletrônica de consumidor (NFC-e)
    • Emitir Nota Fiscal
    • Consultar Nota Fiscal
    • Cancelar Nota Fiscal
    • Consultar XML
    • Consultar XML de Envio do Cancelamento
    • Consultar XML de Retorno do Cancelamento
    • Inutilizar Numeração
    • Consultar Inutilização de Número da Nota Fiscal
    • Consultar XML de Inutilização
  • Nota fiscal eletrônica de produto (NF-e)
    • Emitir Nota Fiscal
    • Consultar Nota Fiscal
    • Cancelar Nota Fiscal
    • Consultar XML de Cancelamento
    • Emitir Carta de Correção pela Chave da NF-e
    • Consultar Carta de Correção
    • Consultar XML da Carta de Correção
    • Inutilizar Numeração
    • Consultar Inutilização de Número da Nota Fiscal
    • Consultar XML de Inutilização
  • S@T - SÃO PAULO
    • Download EXE customizado do S@T
  • Consulta de nota prestada (emitida)
    • NFS-e - Consulta de Nota Prestada (Emitida)
  • Consulta de nota tomada (recebida)
    • NF-e - Consulta de Nota Tomada (Recebida)
    • NF-e - Consulta de Nota Tomada sem manifestação
    • NFS-e - Consulta de Nota Tomada (Recebida)
  • Manifestação de destinatário NF-e
    • Manifestação de Destinatário (NF-e)

Como liberar uma nova versão

1. Garantir cobertura de teste em 100% (para rodar os testes: rake check)
2. Atualizar o CHANGELOG
3. Atualizar a versão em version.rb
4. Realizar o commit
5. Enviar ao repositório git push origin main
6. Criar uma tag git tag <VERSAO> && git push origin <VERSAO>
7. Gerar uma nova versão da gem gem build enotas_api
8. Publicar a gem gem push enotas_api-<VERSAO>.gem

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/bempapp/enotas_api. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the EnotasApi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.