Project

enotas_api

0.0
The project is in a healthy, maintained state
Non oficial, well supported, e-notas ruby api client
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
 Project Readme

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 @salaozen.

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 @salaozen.

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 utilizamos a versão que ruby que temos em produção atualmente que é ~> ruby 2.6.6. 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
      • Consultar XML
      • Cancelar Nota Fiscal
      • 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. Atualizar o CHANGELOG
  2. Atualizar a versão em version.rb
  3. Realizar o commit
  4. Enviar ao repositório git push origin main
  5. Criar uma tag git tag <VERSAO> && git push origin <VERSAO>
  6. Gerar uma nova versão da gem gem build enotas_api
  7. Publicar a gem gem push enotas_api-<VERSAO>.gem

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/salaozen/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.