focus_nfe 1.0.0

data/lib/focus_nfe/recursos/mdfe.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Recurso de Manifesto Eletrônico de Documentos Fiscais (MDF-e). Emissão
+    # assíncrona com consulta de estado, cancelamento e eventos próprios:
+    # encerramento, inclusão de condutor e inclusão de DF-e.
+    class Mdfe < Base
+      include Concerns::Emitivel
+      include Concerns::Consultavel
+      include Concerns::Cancelavel
+      include Concerns::Notificavel
+      include Concerns::Eventavel
+
+      caminho_base "mdfe"
+
+      # @return [Hash{String=>String}] chave +modal_<tipo>+ no payload => nome do sub-esquema
+      MODAIS = {
+        "modal_rodoviario" => "mdfe_transporte_rodoviario",
+        "modal_aereo" => "mdfe_transporte_aereo",
+        "modal_aquaviario" => "mdfe_transporte_aquaviario",
+        "modal_ferroviario" => "mdfe_transporte_ferroviario"
+      }.freeze
+
+      # Encerra o MDF-e ao fim da operação de transporte.
+      #
+      # @param ref [String] referência do manifesto
+      # @param data [String] data do encerramento (ISO 8601)
+      # @param sigla_uf [String] UF do município de encerramento
+      # @param nome_municipio [String] nome do município de encerramento
+      # @return [FocusNfe::Modelos::Documento]
+      # @raise [ArgumentError] se a +ref+ for inválida
+      # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+      def encerrar(ref, data:, sigla_uf:, nome_municipio:)
+        emitir_evento_em(ref, caminho: "encerrar", data: data, sigla_uf: sigla_uf, nome_municipio: nome_municipio)
+      end
+
+      # Inclui um condutor no MDF-e autorizado.
+      #
+      # @param ref [String] referência do manifesto
+      # @param nome [String] nome completo do condutor
+      # @param cpf [String] CPF do condutor
+      # @return [FocusNfe::Modelos::Documento]
+      # @raise [ArgumentError] se a +ref+ for inválida
+      # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+      def incluir_condutor(ref, nome:, cpf:)
+        emitir_evento_em(ref, caminho: "inclusao_condutor", nome: nome, cpf: cpf)
+      end
+
+      # Inclui documentos fiscais (DF-e) vinculados ao MDF-e autorizado.
+      #
+      # @param ref [String] referência do manifesto
+      # @param protocolo [String] protocolo de autorização do MDF-e
+      # @param codigo_municipio_carregamento [String] código do município de carregamento
+      # @param documentos [Array<Hash>] documentos com +chave_nfe+ e +codigo_municipio_descarregamento+
+      # @param nome_municipio_carregamento [String, nil] nome do município de carregamento
+      # @return [FocusNfe::Modelos::Documento]
+      # @raise [ArgumentError] se a +ref+ for inválida
+      # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+      def incluir_dfe(ref, protocolo:, codigo_municipio_carregamento:, documentos:, nome_municipio_carregamento: nil)
+        dados = { protocolo: protocolo, codigo_municipio_carregamento: codigo_municipio_carregamento,
+                  documentos: documentos }
+        dados[:nome_municipio_carregamento] = nome_municipio_carregamento if nome_municipio_carregamento
+        emitir_evento_em(ref, caminho: "inclusao_dfe", **dados)
+      end
+
+      private
+
+      # A MDFe não possui campo +modal+: o modal é deduzido pela chave
+      # +modal_<tipo>+ presente no payload.
+      #
+      # @see FocusNfe::Recursos::Base#esquemas_extras
+      def esquemas_extras(dados)
+        MODAIS.select { |chave, _| dados.key?(chave) }
+      end
+    end
+  end
+end

data/lib/focus_nfe/recursos/municipios.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Consulta de municípios e seus sub-recursos de NFS-e (códigos tributários e
+    # itens da lista de serviço). +consultar(codigo)+ usa o código IBGE.
+    class Municipios < Base
+      include Concerns::Localizavel
+      include Concerns::Listavel
+
+      caminho_base "municipios"
+
+      # @param codigo_municipio [String] código IBGE do município
+      # @param filtros [Hash] filtros/paginação (+codigo:+, +descricao:+, +offset:+, +limit:+)
+      # @return [FocusNfe::Modelos::Pagina]
+      def listar_codigos_tributarios(codigo_municipio, **filtros)
+        sub_listagem(codigo_municipio, "codigos_tributarios_municipio", filtros)
+      end
+
+      # @param codigo_municipio [String] código IBGE do município
+      # @param filtros [Hash] filtros/paginação (+codigo:+, +descricao:+, +offset:+, +limit:+)
+      # @return [FocusNfe::Modelos::Pagina]
+      def listar_itens_lista_servico(codigo_municipio, **filtros)
+        sub_listagem(codigo_municipio, "itens_lista_servico", filtros)
+      end
+
+      # @param codigo_municipio [String] código IBGE do município
+      # @param codigo [String] código do tributo municipal
+      # @return [Hash] corpo cru da resposta
+      def consultar_codigo_tributario(codigo_municipio, codigo)
+        sub_consulta(codigo_municipio, "codigos_tributarios_municipio", codigo)
+      end
+
+      # @param codigo_municipio [String] código IBGE do município
+      # @param codigo [String] código do item na lista de serviço (ex. +"1.06"+)
+      # @return [Hash] corpo cru da resposta
+      def consultar_item_lista_servico(codigo_municipio, codigo)
+        sub_consulta(codigo_municipio, "itens_lista_servico", codigo)
+      end
+
+      # @param codigo_municipio [String] código IBGE do município
+      # @return [Hash] JSON de exemplo de NFS-e do município
+      def consultar_json(codigo_municipio)
+        connection.get("#{caminho_referencia(codigo_municipio)}/json").body
+      end
+
+      private
+
+      def sub_listagem(codigo_municipio, sufixo, filtros)
+        response = connection.get("#{caminho_referencia(codigo_municipio)}/#{sufixo}", params: filtros)
+        Modelos::Pagina.from_response(response)
+      end
+
+      def sub_consulta(codigo_municipio, sufixo, codigo)
+        segmento = URI.encode_www_form_component(codigo)
+        connection.get("#{caminho_referencia(codigo_municipio)}/#{sufixo}/#{segmento}").body
+      end
+    end
+  end
+end

data/lib/focus_nfe/recursos/ncms.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Consulta de NCMs (Nomenclatura Comum do Mercosul). +consultar(codigo)+ busca
+    # um NCM; +buscar+ filtra por código/descrição e componentes.
+    class Ncms < Base
+      include Concerns::Localizavel
+      include Concerns::Listavel
+
+      caminho_base "ncms"
+
+      alias buscar listar
+    end
+  end
+end

data/lib/focus_nfe/recursos/nfce.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Recurso de Nota Fiscal de Consumidor eletrônica (NFC-e). Emissão síncrona
+    # com consulta de estado, cancelamento, inutilização de numeração, envio por
+    # e-mail e conciliação financeira (ECONF). A NFC-e não admite Carta de Correção.
+    class Nfce < Base
+      include Concerns::Emitivel
+      include Concerns::Consultavel
+      include Concerns::Cancelavel
+      include Concerns::Inutilizavel
+      include Concerns::Enviavel
+      include Concerns::Conciliavel
+
+      caminho_base "nfce"
+    end
+  end
+end

data/lib/focus_nfe/recursos/nfcom.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Recurso de Nota Fiscal Fatura de Serviço de Comunicação eletrônica
+    # (NFCom). Emissão assíncrona com consulta de estado e cancelamento.
+    class Nfcom < Base
+      include Concerns::Emitivel
+      include Concerns::Consultavel
+      include Concerns::Cancelavel
+      include Concerns::Notificavel
+
+      caminho_base "nfcom"
+    end
+  end
+end

data/lib/focus_nfe/recursos/nfe.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Recurso de Nota Fiscal eletrônica (NF-e). Emissão assíncrona com consulta
+    # de estado, cancelamento, Carta de Correção Eletrônica (CC-e), inutilização
+    # de numeração, prévia da DANFe, envio por e-mail e importação a partir do XML.
+    class Nfe < Base
+      include Concerns::Emitivel
+      include Concerns::Consultavel
+      include Concerns::Cancelavel
+      include Concerns::Corrigivel
+      include Concerns::Inutilizavel
+      include Concerns::Visualizavel
+      include Concerns::Notificavel
+      include Concerns::Enviavel
+      include Concerns::Eventavel
+      include Concerns::Conciliavel
+
+      caminho_base "nfe"
+      caminho_base_previa "nfe/danfe"
+
+      # Importa uma NF-e a partir do seu XML autorizado.
+      #
+      # @param xml [String] XML da NF-e (enviado como +application/xml+)
+      # @param ref [String, nil] referência a atribuir; omitida usa a chave da nota
+      # @return [FocusNfe::Modelos::Documento]
+      # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+      def importar(xml, ref: nil)
+        params = ref ? { ref: ref } : {}
+        response = connection.post("#{caminho_base}/importacao",
+                                   params: params, body: xml,
+                                   headers: { "Content-Type" => "application/xml" })
+        Modelos::Documento.from_response(response, ref: ref)
+      end
+
+      # Emite um evento genérico sobre a NF-e (+POST /nfe/:ref/evento+).
+      #
+      # @param ref [String] referência da nota
+      # @param tipo_evento [String] tipo do evento suportado pela API
+      # @param dados [Hash] campos adicionais específicos do evento
+      # @return [FocusNfe::Modelos::Documento]
+      # @raise [ArgumentError] se a +ref+ for inválida
+      # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+      def emitir_evento(ref, tipo_evento:, **dados)
+        emitir_evento_em(ref, caminho: "evento", tipo_evento: tipo_evento, **dados)
+      end
+
+      # Cancela um evento da NF-e (+DELETE /nfe/:ref/evento+ com +tipo_evento+ no corpo).
+      #
+      # @param ref [String] referência da nota
+      # @param tipo_evento [String] tipo do evento a cancelar
+      # @return [FocusNfe::Modelos::Documento]
+      # @raise [ArgumentError] se a +ref+ for inválida
+      # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+      def cancelar_evento(ref, tipo_evento:)
+        cancelar_evento_em(ref, caminho: "evento", tipo_evento: tipo_evento)
+      end
+
+      # Registra o Ator Interessado da NF-e (+POST /nfe/:ref/ator_interessado+),
+      # autorizando um terceiro a acessar o XML. Informe +cpf+ ou +cnpj+.
+      #
+      # @param ref [String] referência da nota
+      # @param permite_autorizacao_terceiros [Boolean] libera o acesso ao terceiro
+      # @param cpf [String, nil] CPF do ator interessado
+      # @param cnpj [String, nil] CNPJ do ator interessado
+      # @return [FocusNfe::Modelos::Documento]
+      # @raise [ArgumentError] se a +ref+ for inválida
+      # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+      def registrar_ator_interessado(ref, permite_autorizacao_terceiros:, cpf: nil, cnpj: nil)
+        dados = { permite_autorizacao_terceiros: permite_autorizacao_terceiros }
+        dados[:cpf] = cpf if cpf
+        dados[:cnpj] = cnpj if cnpj
+        emitir_evento_em(ref, caminho: "ator_interessado", **dados)
+      end
+
+      # Registra o evento de Insucesso na Entrega (+POST /nfe/:ref/insucesso_entrega+).
+      # Quando +motivo_insucesso+ for 4, a API exige +justificativa_insucesso+.
+      #
+      # @param ref [String] referência da nota
+      # @param data_tentativa_entrega [String] data/hora da tentativa (ISO 8601)
+      # @param motivo_insucesso [Integer] código do motivo (1 a 4)
+      # @param hash_tentativa_entrega [String] hash SHA-1 em Base64 da tentativa
+      # @param dados [Hash] campos opcionais (+numero_tentativas+, +justificativa_insucesso+, …)
+      # @return [FocusNfe::Modelos::Documento]
+      # @raise [ArgumentError] se a +ref+ for inválida
+      # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+      def registrar_insucesso_entrega(ref, data_tentativa_entrega:, motivo_insucesso:, hash_tentativa_entrega:, **dados)
+        emitir_evento_em(ref, caminho: "insucesso_entrega",
+                              data_tentativa_entrega: data_tentativa_entrega,
+                              motivo_insucesso: motivo_insucesso,
+                              hash_tentativa_entrega: hash_tentativa_entrega, **dados)
+      end
+
+      # Cancela o evento de Insucesso na Entrega (+DELETE /nfe/:ref/insucesso_entrega+).
+      #
+      # @param ref [String] referência da nota
+      # @return [FocusNfe::Modelos::Documento]
+      # @raise [ArgumentError] se a +ref+ for inválida
+      # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+      def cancelar_insucesso_entrega(ref)
+        cancelar_evento_em(ref, caminho: "insucesso_entrega")
+      end
+    end
+  end
+end

data/lib/focus_nfe/recursos/nfes_recebidas.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Notas fiscais (NF-e) recebidas contra um CNPJ. Listagem com sincronização
+    # incremental, consulta por chave, downloads, manifestação do destinatário e
+    # eventos.
+    class NfesRecebidas < Base
+      include Concerns::Listavel
+      include Concerns::Baixavel
+      include Concerns::BaixavelEventos
+      include Concerns::Notificavel
+      include Concerns::Eventavel
+
+      caminho_base "nfes_recebidas"
+
+      # @param chave [String] chave de acesso da NF-e
+      # @param completa [Boolean] quando +true+, pede a resposta completa (+completa=1+)
+      # @return [Hash] corpo cru da resposta
+      def consultar(chave, completa: false)
+        params = completa ? { completa: 1 } : {}
+        connection.get(caminho_referencia(chave), params: params).body
+      end
+
+      # Registra a manifestação do destinatário.
+      #
+      # @param chave [String] chave de acesso da NF-e
+      # @param tipo [String] +ciencia+/+confirmacao+/+desconhecimento+/+nao_realizada+
+      # @param justificativa [String, nil] obrigatória apenas para +nao_realizada+
+      # @return [Hash] corpo cru da resposta
+      def manifestar(chave, tipo:, justificativa: nil)
+        corpo = { tipo: tipo }
+        corpo[:justificativa] = justificativa unless justificativa.nil?
+        connection.post("#{caminho_referencia(chave)}/manifesto", body: corpo).body
+      end
+
+      # Emite um evento sobre a NF-e recebida.
+      #
+      # @param chave [String] chave de acesso da NF-e
+      # @param tipo_evento [String] tipo do evento suportado pela API
+      # @param dados [Hash] campos adicionais do evento
+      # @return [FocusNfe::Modelos::Documento]
+      def emitir_evento(chave, tipo_evento:, **dados)
+        emitir_evento_em(chave, caminho: "evento", tipo_evento: tipo_evento, **dados)
+      end
+
+      # Cancela o último evento emitido para a NF-e recebida.
+      #
+      # @param chave [String] chave de acesso da NF-e
+      # @return [FocusNfe::Modelos::Documento]
+      def cancelar_evento(chave)
+        cancelar_evento_em(chave, caminho: "evento")
+      end
+    end
+  end
+end

data/lib/focus_nfe/recursos/nfgas.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Recurso de Nota Fiscal de Gás eletrônica (NFGas, em beta). Emissão
+    # assíncrona com consulta de estado e cancelamento.
+    class Nfgas < Base
+      include Concerns::Emitivel
+      include Concerns::Consultavel
+      include Concerns::Cancelavel
+      include Concerns::Notificavel
+
+      caminho_base "nfgas"
+    end
+  end
+end

data/lib/focus_nfe/recursos/nfse.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Recurso de Nota Fiscal de Serviço eletrônica (NFS-e). Pré-validação
+    # síncrona seguida de autorização assíncrona; o cancelamento fica sujeito às
+    # regras da prefeitura. Suporta reenvio da nota por e-mail.
+    class Nfse < Base
+      include Concerns::Emitivel
+      include Concerns::Consultavel
+      include Concerns::Cancelavel
+      include Concerns::Notificavel
+      include Concerns::Enviavel
+
+      caminho_base "nfse"
+    end
+  end
+end

data/lib/focus_nfe/recursos/nfse_nacional.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Recurso de NFS-e padrão nacional (DPS). Emissão assíncrona com consulta de
+    # estado e cancelamento.
+    class NfseNacional < Base
+      include Concerns::Emitivel
+      include Concerns::Consultavel
+      include Concerns::Cancelavel
+      include Concerns::Notificavel
+
+      caminho_base "nfse_nacional"
+    end
+  end
+end

data/lib/focus_nfe/recursos/nfses_nacionais_recebidas.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # NFS-e de padrão nacional recebidas contra um CNPJ. Listagem com
+    # sincronização incremental e downloads (incluindo o DANFSe em HTML).
+    class NfsesNacionaisRecebidas < Base
+      include Concerns::Listavel
+      include Concerns::Baixavel
+      include Concerns::Notificavel
+
+      caminho_base "nfsens_recebidas"
+
+      # @param chave [String] chave de acesso da NFS-e
+      # @return [String] DANFSe em HTML cru
+      def download_html(chave)
+        download(chave, formato: :html)
+      end
+    end
+  end
+end

data/lib/focus_nfe/recursos/webhooks.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Gestão de webhooks (gatilhos de notificação). O caminho da API é +hooks+.
+    class Webhooks < Base
+      include Concerns::Listavel
+      include Concerns::Localizavel
+      include Concerns::Removivel
+
+      caminho_base "hooks"
+
+      # Cria um webhook.
+      #
+      # @param dados [Hash] dados do gatilho (+event+, +url+, +cnpj+, …)
+      # @return [Hash] corpo cru da resposta
+      def criar(dados:)
+        connection.post(caminho_base, body: dados).body
+      end
+    end
+  end
+end

data/lib/focus_nfe/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  # @return [String] versão da gem
+  VERSION = "1.0.0"
+end

data/lib/focus_nfe/webhook.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+
+module FocusNfe
+  # Recebimento de webhooks inbound: quando a Focus NFe chama a URL da aplicação
+  # ao mudar o status de um documento. Fachada stateless (sem token, sem HTTP) —
+  # apenas transforma o corpo cru recebido e autentica a chamada.
+  #
+  # @see FocusNfe::Recursos::Webhooks gestão dos gatilhos (lado saída)
+  module Webhook
+    module_function
+
+    # Converte o corpo cru de um webhook inbound em um {Modelos::Documento}, o
+    # mesmo objeto devolvido por emissão/consulta.
+    #
+    # @param raw_body [String, Hash] corpo recebido (JSON cru ou já parseado)
+    # @param ref [String, nil] referência conhecida, injetada quando ausente do corpo
+    # @return [FocusNfe::Modelos::Documento]
+    # @raise [FocusNfe::Errors::WebhookError] quando o corpo é uma String que não é JSON válido
+    def parse(raw_body, ref: nil)
+      dados = raw_body.is_a?(String) ? JSON.parse(raw_body) : raw_body
+      Modelos::Documento.from_payload(dados, ref: ref)
+    rescue JSON::ParserError => e
+      raise Errors::WebhookError, "corpo do webhook não é JSON válido: #{e.message}"
+    end
+
+    # Verifica se a chamada é autêntica comparando o header recebido com o
+    # +authorization+ configurado na criação do gatilho. A comparação é feita em
+    # tempo constante para não vazar o segredo por timing.
+    #
+    # @param headers [#[]] cabeçalhos da requisição recebida (ex.: +request.headers+ do Rails)
+    # @param authorization [String] valor esperado, igual ao informado em {Recursos::Webhooks#criar}
+    # @param authorization_header [String] nome do header onde a Focus envia o valor
+    # @return [Boolean] +true+ somente quando o header existe e bate com o esperado
+    def autenticado?(headers:, authorization:, authorization_header:)
+      recebido = valor_do_header(headers, authorization_header)
+      !recebido.nil? && comparacao_segura?(recebido.to_s, authorization.to_s)
+    end
+
+    # @param headers [#[]] cabeçalhos da requisição
+    # @param nome [String] nome do header procurado
+    # @return [Object, nil] valor do header, com fallback case-insensitive em Hash
+    def valor_do_header(headers, nome)
+      direto = headers[nome]
+      return direto unless direto.nil?
+      return nil unless headers.respond_to?(:each)
+
+      alvo = nome.to_s.downcase
+      headers.each { |chave, valor| return valor if chave.to_s.downcase == alvo }
+      nil
+    end
+
+    # @param esquerda [String]
+    # @param direita [String]
+    # @return [Boolean] comparação de strings resistente a timing attack
+    def comparacao_segura?(esquerda, direita)
+      return false unless esquerda.bytesize == direita.bytesize
+
+      bytes_direita = direita.bytes
+      diferenca = 0
+      esquerda.bytes.each_with_index { |byte, i| diferenca |= byte ^ bytes_direita[i].to_i }
+      diferenca.zero?
+    end
+
+    private_class_method :valor_do_header, :comparacao_segura?
+  end
+end

data/lib/focus_nfe.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "focus_nfe/version"
+require_relative "focus_nfe/errors"
+require_relative "focus_nfe/configuration"
+require_relative "focus_nfe/http/authentication"
+require_relative "focus_nfe/http/response"
+require_relative "focus_nfe/http/adapter"
+require_relative "focus_nfe/http/adapters/net_http"
+require_relative "focus_nfe/http/logging"
+require_relative "focus_nfe/http/connection"
+require_relative "focus_nfe/esquemas/catalogo"
+require_relative "focus_nfe/client"
+
+# Ponto de entrada da gem e fachada da configuração global (modo de empresa
+# única): {configure}/{configuration}/{client}/{reset_configuration!} operam
+# sobre uma {Configuration} memoizada no nível do módulo. Para multi-empresa,
+# instancie {Client} explicitamente.
+#
+# Apenas o núcleo (configuração, HTTP, cliente) é carregado no +require+. Os
+# recursos de documento, os modelos e a camada de esquemas são registrados via
+# +autoload+ e carregados sob demanda — quem só emite um tipo de documento não
+# paga o custo de carregar os demais.
+module FocusNfe
+  # Recebimento de webhooks inbound (parse + autenticação da chamada).
+  autoload :Webhook, "focus_nfe/webhook"
+
+  # Modelos de resposta da API (documento fiscal, página de listagem).
+  module Modelos
+    autoload :Documento, "focus_nfe/modelos/documento"
+    autoload :Inutilizacao, "focus_nfe/modelos/inutilizacao"
+    autoload :Pagina, "focus_nfe/modelos/pagina"
+  end
+
+  # Camada opcional de esquemas: introspecção pública dos campos e validação
+  # client-side opt-in. Ver {Esquemas.descrever} e {Validador}.
+  module Esquemas
+    autoload :Esquema, "focus_nfe/esquemas/esquema"
+    autoload :ErroDeValidacao, "focus_nfe/esquemas/esquema"
+    autoload :Campo, "focus_nfe/esquemas/campo"
+    autoload :Decimal, "focus_nfe/esquemas/decimal"
+    autoload :Validador, "focus_nfe/esquemas/validador"
+  end
+
+  # Recursos da API, um por tipo de documento ou consulta. Cada um deriva de
+  # {Recursos::Base} e compõe seu comportamento com os mixins de {Concerns}.
+  module Recursos
+    autoload :Base, "focus_nfe/recursos/base"
+
+    # Mixins de comportamento compartilhados pelos recursos (emissão, consulta,
+    # cancelamento, listagem, …).
+    module Concerns
+      autoload :Emitivel, "focus_nfe/recursos/concerns/emitivel"
+      autoload :Consultavel, "focus_nfe/recursos/concerns/consultavel"
+      autoload :Cancelavel, "focus_nfe/recursos/concerns/cancelavel"
+      autoload :Eventavel, "focus_nfe/recursos/concerns/eventavel"
+      autoload :Corrigivel, "focus_nfe/recursos/concerns/corrigivel"
+      autoload :CorrigivelCte, "focus_nfe/recursos/concerns/corrigivel_cte"
+      autoload :Inutilizavel, "focus_nfe/recursos/concerns/inutilizavel"
+      autoload :Listavel, "focus_nfe/recursos/concerns/listavel"
+      autoload :Baixavel, "focus_nfe/recursos/concerns/baixavel"
+      autoload :BaixavelEventos, "focus_nfe/recursos/concerns/baixavel_eventos"
+      autoload :Localizavel, "focus_nfe/recursos/concerns/localizavel"
+      autoload :Notificavel, "focus_nfe/recursos/concerns/notificavel"
+      autoload :Enviavel, "focus_nfe/recursos/concerns/enviavel"
+      autoload :Conciliavel, "focus_nfe/recursos/concerns/conciliavel"
+      autoload :Removivel, "focus_nfe/recursos/concerns/removivel"
+      autoload :Visualizavel, "focus_nfe/recursos/concerns/visualizavel"
+    end
+
+    autoload :Nfe, "focus_nfe/recursos/nfe"
+    autoload :Nfce, "focus_nfe/recursos/nfce"
+    autoload :Nfse, "focus_nfe/recursos/nfse"
+    autoload :NfseNacional, "focus_nfe/recursos/nfse_nacional"
+    autoload :Cte, "focus_nfe/recursos/cte"
+    autoload :CteOs, "focus_nfe/recursos/cte_os"
+    autoload :Mdfe, "focus_nfe/recursos/mdfe"
+    autoload :Nfcom, "focus_nfe/recursos/nfcom"
+    autoload :Dce, "focus_nfe/recursos/dce"
+    autoload :Nfgas, "focus_nfe/recursos/nfgas"
+    autoload :NfesRecebidas, "focus_nfe/recursos/nfes_recebidas"
+    autoload :CtesRecebidas, "focus_nfe/recursos/ctes_recebidas"
+    autoload :NfsesNacionaisRecebidas, "focus_nfe/recursos/nfses_nacionais_recebidas"
+    autoload :Ceps, "focus_nfe/recursos/ceps"
+    autoload :Municipios, "focus_nfe/recursos/municipios"
+    autoload :Cfops, "focus_nfe/recursos/cfops"
+    autoload :Cnaes, "focus_nfe/recursos/cnaes"
+    autoload :Ncms, "focus_nfe/recursos/ncms"
+    autoload :Cnpjs, "focus_nfe/recursos/cnpjs"
+    autoload :Empresas, "focus_nfe/recursos/empresas"
+    autoload :Webhooks, "focus_nfe/recursos/webhooks"
+    autoload :EmailsBloqueados, "focus_nfe/recursos/emails_bloqueados"
+    autoload :Backups, "focus_nfe/recursos/backups"
+  end
+
+  class << self
+    # Cede a configuração global ao bloco para ajuste, memoizando-a.
+    #
+    # @yieldparam configuration [FocusNfe::Configuration]
+    # @return [FocusNfe::Configuration] a configuração global
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    # @return [FocusNfe::Configuration] a configuração global, criada como default na primeira chamada
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # @return [FocusNfe::Client] cliente construído a partir da config global
+    # @raise [FocusNfe::Errors::ConfigurationError] se a config global não tiver ao menos um token e ambiente válido
+    def client
+      Client.new(configuration)
+    end
+
+    # Limpa a configuração global memoizada.
+    #
+    # @return [void]
+    def reset_configuration!
+      @configuration = nil
+    end
+  end
+end