focus_nfe 1.0.0

data/lib/focus_nfe/client.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  # Raiz de acesso à API. Cada cliente carrega sua própria {Configuration} e
+  # mantém duas {HTTP::Connection} memoizadas, uma por token: a de empresa
+  # (emissão/consulta de documentos) e a de conta (consultas auxiliares e gestão
+  # de empresas). Permite coexistência de várias empresas no mesmo processo sem
+  # estado compartilhado. Expõe os recursos da API instanciados preguiçosamente.
+  class Client
+    # @return [FocusNfe::Configuration] configuração validada deste cliente
+    attr_reader :configuration
+
+    # @overload initialize(configuration)
+    #   @param configuration [FocusNfe::Configuration] configuração já montada
+    # @overload initialize(token_empresa:, token_conta:, environment:, **options)
+    #   @param token_empresa [String] token da empresa (emissão/consulta de documentos)
+    #   @param token_conta [String] token da conta (consultas auxiliares e gestão de empresas)
+    #   @param environment [Symbol] :producao ou :homologacao
+    #   @param options [Hash] demais opções da {Configuration} (timeout, headers, …)
+    # @raise [FocusNfe::Errors::ConfigurationError] se a configuração for inválida
+    def initialize(configuration = nil, **)
+      @configuration = (configuration || Configuration.new(**)).tap(&:validate!)
+    end
+
+    # @return [FocusNfe::HTTP::Connection] conexão da empresa, memoizada
+    # @raise [FocusNfe::Errors::ConfigurationError] se +token_empresa+ estiver ausente
+    def connection
+      @connection ||= build_connection(:empresa)
+    end
+
+    # @return [FocusNfe::HTTP::Connection] conexão da conta, memoizada
+    # @raise [FocusNfe::Errors::ConfigurationError] se +token_conta+ estiver ausente
+    def connection_conta
+      @connection_conta ||= build_connection(:conta)
+    end
+
+    # @return [FocusNfe::Recursos::Nfe] recurso de NF-e, memoizado
+    def nfe
+      @nfe ||= Recursos::Nfe.new(connection)
+    end
+
+    # @return [FocusNfe::Recursos::Nfce] recurso de NFC-e, memoizado
+    def nfce
+      @nfce ||= Recursos::Nfce.new(connection)
+    end
+
+    # @return [FocusNfe::Recursos::Nfse] recurso de NFS-e, memoizado
+    def nfse
+      @nfse ||= Recursos::Nfse.new(connection)
+    end
+
+    # @return [FocusNfe::Recursos::NfseNacional] recurso de NFS-e nacional, memoizado
+    def nfse_nacional
+      @nfse_nacional ||= Recursos::NfseNacional.new(connection)
+    end
+
+    # @return [FocusNfe::Recursos::Cte] recurso de CT-e, memoizado
+    def cte
+      @cte ||= Recursos::Cte.new(connection)
+    end
+
+    # @return [FocusNfe::Recursos::CteOs] recurso de CT-e OS, memoizado
+    def cte_os
+      @cte_os ||= Recursos::CteOs.new(connection)
+    end
+
+    # @return [FocusNfe::Recursos::Mdfe] recurso de MDF-e, memoizado
+    def mdfe
+      @mdfe ||= Recursos::Mdfe.new(connection)
+    end
+
+    # @return [FocusNfe::Recursos::Nfcom] recurso de NFCom, memoizado
+    def nfcom
+      @nfcom ||= Recursos::Nfcom.new(connection)
+    end
+
+    # @return [FocusNfe::Recursos::Dce] recurso de DC-e, memoizado
+    def dce
+      @dce ||= Recursos::Dce.new(connection)
+    end
+
+    # @return [FocusNfe::Recursos::Nfgas] recurso de NFGas, memoizado
+    def nfgas
+      @nfgas ||= Recursos::Nfgas.new(connection)
+    end
+
+    # @return [FocusNfe::Recursos::NfesRecebidas] recurso de NF-e recebidas, memoizado
+    def nfes_recebidas
+      @nfes_recebidas ||= Recursos::NfesRecebidas.new(connection)
+    end
+
+    # @return [FocusNfe::Recursos::CtesRecebidas] recurso de CT-e recebidos, memoizado
+    def ctes_recebidas
+      @ctes_recebidas ||= Recursos::CtesRecebidas.new(connection)
+    end
+
+    # @return [FocusNfe::Recursos::NfsesNacionaisRecebidas] recurso de NFS-e nacionais recebidas, memoizado
+    def nfses_nacionais_recebidas
+      @nfses_nacionais_recebidas ||= Recursos::NfsesNacionaisRecebidas.new(connection)
+    end
+
+    # @return [FocusNfe::Recursos::Ceps] recurso de consulta de CEP, memoizado
+    def ceps
+      @ceps ||= Recursos::Ceps.new(connection_conta)
+    end
+
+    # @return [FocusNfe::Recursos::Municipios] recurso de consulta de municípios, memoizado
+    def municipios
+      @municipios ||= Recursos::Municipios.new(connection_conta)
+    end
+
+    # @return [FocusNfe::Recursos::Cfops] recurso de consulta de CFOP, memoizado
+    def cfops
+      @cfops ||= Recursos::Cfops.new(connection_conta)
+    end
+
+    # @return [FocusNfe::Recursos::Cnaes] recurso de consulta de CNAE, memoizado
+    def cnaes
+      @cnaes ||= Recursos::Cnaes.new(connection_conta)
+    end
+
+    # @return [FocusNfe::Recursos::Ncms] recurso de consulta de NCM, memoizado
+    def ncms
+      @ncms ||= Recursos::Ncms.new(connection_conta)
+    end
+
+    # @return [FocusNfe::Recursos::Cnpjs] recurso de consulta de CNPJ, memoizado
+    def cnpjs
+      @cnpjs ||= Recursos::Cnpjs.new(connection_conta)
+    end
+
+    # @return [FocusNfe::Recursos::Empresas] recurso de gestão de empresas, memoizado
+    def empresas
+      @empresas ||= Recursos::Empresas.new(connection_conta)
+    end
+
+    # @return [FocusNfe::Recursos::Webhooks] recurso de gestão de webhooks, memoizado
+    def webhooks
+      @webhooks ||= Recursos::Webhooks.new(connection)
+    end
+
+    # @return [FocusNfe::Recursos::EmailsBloqueados] recurso de e-mails bloqueados, memoizado
+    def emails_bloqueados
+      @emails_bloqueados ||= Recursos::EmailsBloqueados.new(connection)
+    end
+
+    # @return [FocusNfe::Recursos::Backups] recurso de backups de XML, memoizado
+    def backups
+      @backups ||= Recursos::Backups.new(connection)
+    end
+
+    private
+
+    # @param escopo [Symbol] :empresa ou :conta
+    # @return [FocusNfe::HTTP::Connection] conexão autenticada com o token do escopo
+    # @raise [FocusNfe::Errors::ConfigurationError] se o token do escopo estiver ausente
+    def build_connection(escopo)
+      configuration.validate_token!(escopo)
+      HTTP::Connection.new(configuration, token: configuration.token_de(escopo).to_s)
+    end
+  end
+end

data/lib/focus_nfe/configuration.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  # Guarda as opções de uso da gem: os dois tokens da Focus NFe (+token_empresa+,
+  # que identifica a empresa emitente/consultada, e +token_conta+, usado nas
+  # consultas auxiliares e na gestão de empresas), o ambiente (que resolve a URL
+  # base), timeouts, logger, adaptador HTTP e cabeçalhos extras. Serve tanto ao
+  # modo global (FocusNfe.configure) quanto ao Client explícito (multi-empresa).
+  class Configuration
+    # @return [Hash{Symbol=>String}] ambiente => URL base da API (sem o prefixo /v2)
+    BASE_URLS = {
+      producao: "https://api.focusnfe.com.br",
+      homologacao: "https://homologacao.focusnfe.com.br"
+    }.freeze
+
+    # @return [Hash{Symbol=>Symbol}] escopo => atributo de token correspondente
+    ESCOPOS_TOKEN = { empresa: :token_empresa, conta: :token_conta }.freeze
+
+    # @return [Symbol] ambiente padrão quando nenhum é informado
+    DEFAULT_ENVIRONMENT = :homologacao
+    # @return [Integer] timeout de leitura padrão, em segundos
+    DEFAULT_TIMEOUT = 30
+    # @return [Integer] timeout de conexão padrão, em segundos
+    DEFAULT_OPEN_TIMEOUT = 10
+
+    attr_accessor :token_empresa, :token_conta, :environment, :timeout,
+                  :open_timeout, :logger, :http_adapter, :headers
+
+    # @param token_empresa [String, nil] token da empresa (emissão/consulta de documentos)
+    # @param token_conta [String, nil] token da conta (consultas auxiliares e gestão de empresas)
+    # @param environment [Symbol] :producao ou :homologacao
+    # @param timeout [Integer] timeout de leitura, em segundos
+    # @param open_timeout [Integer] timeout de conexão, em segundos
+    # @param logger [_Logger, nil] logger plugável usado pela {HTTP::Connection}; deve responder a
+    #   +debug+/+info+/+warn+/+error+ (compatível com o +Logger+ da stdlib, +Rails.logger+ etc.).
+    #   +nil+ (padrão) desliga o logging. O +Authorization+ é sempre redigido — ver {HTTP::Logging}.
+    # @param http_adapter [FocusNfe::HTTP::Adapter, nil] instância pronta (nil => Connection cria a default)
+    # @param headers [Hash] cabeçalhos extras enviados em toda requisição
+    def initialize(token_empresa: nil, token_conta: nil, environment: DEFAULT_ENVIRONMENT,
+                   timeout: DEFAULT_TIMEOUT, open_timeout: DEFAULT_OPEN_TIMEOUT,
+                   logger: nil, http_adapter: nil, headers: {})
+      @token_empresa = token_empresa
+      @token_conta = token_conta
+      @environment = environment
+      @timeout = timeout
+      @open_timeout = open_timeout
+      @logger = logger
+      @http_adapter = http_adapter
+      @headers = headers
+    end
+
+    # @return [String] URL base correspondente ao ambiente atual
+    # @raise [FocusNfe::Errors::ConfigurationError] se o ambiente for desconhecido
+    def base_url
+      validate_environment!
+      BASE_URLS.fetch(environment)
+    end
+
+    # @param escopo [Symbol] :empresa ou :conta
+    # @return [String, nil] token correspondente ao escopo
+    def token_de(escopo)
+      public_send(ESCOPOS_TOKEN.fetch(escopo))
+    end
+
+    # Valida o ambiente e a presença de ao menos um token, falhando cedo quando a
+    # configuração é inutilizável em qualquer escopo.
+    #
+    # @return [self]
+    # @raise [FocusNfe::Errors::ConfigurationError] ambiente inválido ou nenhum token presente
+    def validate!
+      validate_environment!
+      return self if ESCOPOS_TOKEN.keys.any? { |escopo| token_presente?(escopo) }
+
+      raise Errors::ConfigurationError, "informe token_empresa e/ou token_conta"
+    end
+
+    # Valida o ambiente e a presença do token de um escopo específico, no momento
+    # em que um recurso daquele escopo é efetivamente usado.
+    #
+    # @param escopo [Symbol] :empresa ou :conta
+    # @return [self]
+    # @raise [FocusNfe::Errors::ConfigurationError] ambiente inválido ou token do escopo ausente
+    def validate_token!(escopo)
+      validate_environment!
+      return self if token_presente?(escopo)
+
+      raise Errors::ConfigurationError, "#{ESCOPOS_TOKEN.fetch(escopo)} é obrigatório para esta operação"
+    end
+
+    private
+
+    # @raise [FocusNfe::Errors::ConfigurationError] se o ambiente não for reconhecido
+    def validate_environment!
+      return if BASE_URLS.key?(environment)
+
+      raise Errors::ConfigurationError,
+            "ambiente inválido: #{environment.inspect} (use :producao ou :homologacao)"
+    end
+
+    def token_presente?(escopo)
+      !token_de(escopo).to_s.strip.empty?
+    end
+  end
+end

data/lib/focus_nfe/errors.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  # Raiz de toda a hierarquia de exceções da gem. Permite ao integrador capturar
+  # qualquer falha do `focus_nfe` com um único `rescue FocusNfe::Error`.
+  class Error < StandardError; end
+
+  # Exceções tipadas: falhas HTTP (por faixa de status), de configuração
+  # (client-side) e de conexão (transporte). Reúne também o mapeamento
+  # status → classe e a construção da exceção a partir de uma `Response`.
+  module Errors
+    # Falha HTTP retornada pela API, carregando o status, o corpo parseado com
+    # as mensagens de erro da API e a {FocusNfe::HTTP::Response} original.
+    class HttpError < Error
+      # @return [Integer, nil] código de status HTTP da resposta
+      attr_reader :status
+
+      # @return [Object, nil] corpo parseado com as mensagens de erro da API
+      attr_reader :body
+
+      # @return [FocusNfe::HTTP::Response, nil] resposta original que originou o erro
+      attr_reader :response
+
+      # @param message [String, nil] mensagem da exceção
+      # @param status [Integer, nil] código de status HTTP
+      # @param body [Object, nil] corpo parseado da resposta
+      # @param response [FocusNfe::HTTP::Response, nil] resposta original
+      def initialize(message = nil, status: nil, body: nil, response: nil)
+        @status = status
+        @body = body
+        @response = response
+        super(message)
+      end
+
+      # @return [String, nil] código de erro da API, quando o corpo é estruturado
+      def codigo
+        body["codigo"] if body.is_a?(Hash)
+      end
+
+      # @return [Array<Hash>] erros no formato +{ "campo" => String?, "mensagem" => String }+;
+      #   vazio quando o corpo não traz erros estruturados
+      def erros
+        return [] unless body.is_a?(Hash)
+        return body["erros"] if body["erros"].is_a?(Array)
+
+        body["mensagem"] ? [{ "campo" => nil, "mensagem" => body["mensagem"] }] : []
+      end
+    end
+
+    # 400 — requisição malformada.
+    class BadRequest < HttpError; end
+
+    # 401 — token ausente ou inválido.
+    class Unauthorized < HttpError; end
+
+    # 403 — autenticado, porém sem permissão para o recurso.
+    class Forbidden < HttpError; end
+
+    # 404 — recurso inexistente.
+    class NotFound < HttpError; end
+
+    # 409 — conflito de estado (ex.: `ref` já utilizada).
+    class Conflict < HttpError; end
+
+    # 422 — erro de validação dos campos enviados.
+    class ValidationError < HttpError; end
+
+    # 429 — limite de requisições excedido.
+    class RateLimited < HttpError; end
+
+    # 5xx — erro interno do servidor da Focus NFe.
+    class ServerError < HttpError; end
+
+    # Status não-2xx sem mapeamento específico (ex.: 418, 451).
+    class UnexpectedResponse < HttpError; end
+
+    # Erro client-side de configuração (token ausente, ambiente inválido) —
+    # não envolve resposta HTTP.
+    class ConfigurationError < Error; end
+
+    # Falha de transporte (timeout, conexão recusada, excesso de redirects).
+    class ConnectionError < Error; end
+
+    # Falha ao processar um webhook inbound (corpo malformado) — client-side,
+    # não envolve resposta HTTP.
+    class WebhookError < Error; end
+
+    # @return [Hash{Integer=>Class}] status HTTP específico => classe de exceção
+    BY_STATUS = {
+      400 => BadRequest,
+      401 => Unauthorized,
+      403 => Forbidden,
+      404 => NotFound,
+      409 => Conflict,
+      422 => ValidationError,
+      429 => RateLimited
+    }.freeze
+
+    module_function
+
+    # Resolve a classe de exceção correspondente a um status HTTP.
+    #
+    # @param status [Integer] código de status HTTP não-2xx
+    # @return [Class] subclasse de {HttpError}; qualquer 5xx vira {ServerError}
+    #   e qualquer status sem mapeamento específico vira {UnexpectedResponse}
+    def class_for(status)
+      BY_STATUS[status] || (status.between?(500, 599) ? ServerError : UnexpectedResponse)
+    end
+
+    # Constrói a exceção tipada já preenchida a partir de uma resposta.
+    #
+    # @param response [FocusNfe::HTTP::Response] resposta não-2xx recebida
+    # @return [HttpError] instância da classe certa com status/corpo/resposta
+    def from_response(response)
+      class_for(response.status).new(
+        "requisição falhou com status #{response.status}",
+        status: response.status,
+        body: response.body,
+        response: response
+      )
+    end
+  end
+end

data/lib/focus_nfe/esquemas/campo.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "date"
+
+module FocusNfe
+  module Esquemas
+    # Um campo de um {Esquema} de emissão, derivado das definições de
+    # +campos.focusnfe.com.br+. Conhece o nome do campo, sua obrigatoriedade e
+    # sabe parsear o tipo fiscal (+String[1-60]+, +Integer[1-9]+, +Decimal[13.2]+,
+    # +Date+, +DateTime+, enum, coleção) em restrições aplicáveis a um valor.
+    class Campo
+      # @return [Regexp] captura base e tamanho de um escalar de comprimento (ex.: +String[1-60]+)
+      ESCALAR = /\A(?<base>String|Integer)\[(?<inicio>\d+)(?:-(?<fim>\d+))?\]/
+
+      # @return [Regexp] captura os códigos declarados em um enum (+* +0+: …+ ou +*+0+: …+)
+      CODIGO_ENUM = /\*\s*\+([^+]+)\+/
+
+      # @param definicao [Hash] entrada do schema ({ "name", "type", "required", "collection", … })
+      def initialize(definicao)
+        @definicao = definicao
+        parsear_tipo
+      end
+
+      # @return [String] nome do campo no payload de emissão
+      def nome = @definicao["name"]
+
+      # @return [String, nil] descrição do campo conforme +campos.focusnfe.com.br+
+      def descricao = @definicao["description"]
+
+      # @return [String, nil] tipo bruto como documentado (ex.: +"String[1-60]"+)
+      def tipo_bruto = @definicao["type"]
+
+      # @return [String, nil] enumeração dos valores aceitos, como documentada
+      def enum = @definicao["enum"]
+
+      # @return [Array<String>] códigos aceitos extraídos do {#enum} (vazio se não houver)
+      def valores_enum
+        @valores_enum ||= enum.to_s.scan(CODIGO_ENUM).flatten
+      end
+
+      # @return [Boolean] se o campo declara um conjunto de valores aceitos
+      def enum? = !valores_enum.empty?
+
+      # @return [String, nil] tag XML subjacente do campo
+      def tag = @definicao["tag"]
+
+      # Representação serializável do campo, para introspecção externa (devs e
+      # ferramentas automatizadas). Coleções aninham a descrição dos subcampos em
+      # +:colecao+, em profundidade arbitrária; campos escalares têm +:colecao+ nil.
+      #
+      # @return [Hash] descrição estruturada do campo
+      def to_h
+        {
+          nome: nome, descricao: descricao, tipo: tipo, tipo_bruto: tipo_bruto,
+          obrigatorio: obrigatorio?, tamanho_minimo: tamanho_minimo, tamanho_maximo: tamanho_maximo,
+          decimal: decimal&.to_h, enum: enum, tag: tag, colecao: esquema_colecao&.descrever
+        }
+      end
+
+      # @return [Boolean] se o campo é obrigatório na emissão
+      def obrigatorio? = @definicao["required"] == true
+
+      # @return [Boolean] se o campo é uma coleção de subitens
+      def colecao? = tipo == :colecao
+
+      # @return [Symbol] tipo parseado (+:string+, +:integer+, +:decimal+, +:date+,
+      #   +:datetime+, +:enum+, +:colecao+ ou +:desconhecido+)
+      attr_reader :tipo
+
+      # @return [Esquema, nil] esquema dos subcampos da coleção, ou +nil+ se o campo
+      #   não for coleção ou não declarar +object_attributes+
+      def esquema_colecao
+        return unless colecao?
+
+        @esquema_colecao ||= (atributos = @definicao.dig("collection", "object_attributes")) && Esquema.new(atributos)
+      end
+
+      # @return [Integer, nil] tamanho/quantidade de dígitos mínimo (escalares)
+      attr_reader :tamanho_minimo
+
+      # @return [Integer, nil] tamanho/quantidade de dígitos máximo (escalares)
+      attr_reader :tamanho_maximo
+
+      # @return [Decimal, nil] especificação decimal do campo, ou +nil+ se não for decimal
+      attr_reader :decimal
+
+      # Valida um valor contra o tipo/tamanho e o conjunto de enum do campo.
+      # Coleções e tipos desconhecidos não restringem nesta etapa.
+      #
+      # @param valor [Object] valor informado para o campo
+      # @return [String, nil] mensagem de erro ou +nil+ se válido
+      def validar_valor(valor)
+        erro = validar_tipo(valor)
+        return erro if erro
+
+        validar_enum(valor) if enum?
+      end
+
+      private
+
+      def parsear_tipo
+        bruto = @definicao["type"]
+        escalar = bruto && ESCALAR.match(bruto)
+        return parsear_escalar(escalar) if escalar
+
+        @decimal = Decimal.parsear(bruto)
+        return @tipo = :decimal if @decimal
+
+        @tipo = tipo_nao_escalar(bruto)
+      end
+
+      def tipo_nao_escalar(bruto)
+        return :colecao if @definicao.key?("collection") || bruto.to_s.start_with?("Coleção")
+        return @definicao["enum"] ? :enum : :desconhecido if bruto.nil?
+        return :datetime if bruto.start_with?("DateTime")
+        return :date if bruto.start_with?("Date")
+
+        :desconhecido
+      end
+
+      def parsear_escalar(match)
+        @tipo = { "String" => :string, "Integer" => :integer }[match[:base].to_s]
+        @tamanho_minimo = Integer(match[:inicio])
+        @tamanho_maximo = match[:fim] ? Integer(match[:fim]) : @tamanho_minimo
+      end
+
+      def validar_tipo(valor)
+        case tipo
+        when :string then validar_string(valor)
+        when :integer then validar_integer(valor)
+        when :decimal then validar_decimal(valor)
+        when :date then validar_data(valor, Date)
+        when :datetime then validar_data(valor, DateTime)
+        end
+      end
+
+      def validar_string(valor)
+        comprimento = valor.to_s.length
+        return if comprimento.between?(tamanho_minimo, tamanho_maximo)
+
+        "#{nome}: tamanho #{comprimento} fora do intervalo #{tamanho_minimo}-#{tamanho_maximo}"
+      end
+
+      def validar_integer(valor)
+        digitos = valor.to_s
+        return "#{nome}: deve conter apenas dígitos" unless digitos.match?(/\A\d+\z/)
+        return if digitos.length.between?(tamanho_minimo, tamanho_maximo)
+
+        "#{nome}: #{digitos.length} dígitos fora do intervalo #{tamanho_minimo}-#{tamanho_maximo}"
+      end
+
+      def validar_decimal(valor)
+        mensagem = decimal&.validar(valor)
+        "#{nome}: #{mensagem}" if mensagem
+      end
+
+      def validar_data(valor, classe)
+        classe.iso8601(valor.to_s)
+        nil
+      rescue ArgumentError, TypeError
+        "#{nome}: data inválida (esperado ISO 8601)"
+      end
+
+      def validar_enum(valor)
+        return if valores_enum.include?(valor.to_s)
+
+        "#{nome}: valor #{valor.inspect} fora do conjunto permitido (#{valores_enum.join(", ")})"
+      end
+    end
+  end
+end

data/lib/focus_nfe/esquemas/catalogo.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  # Introspecção pública dos esquemas empacotados: lista os documentos com schema
+  # e descreve seus campos como dado serializável, para devs e ferramentas
+  # automatizadas — sem token nem conexão.
+  module Esquemas
+    # @return [String] glob dos arquivos de schema empacotados em +data/schemas/+
+    GLOB_SCHEMAS = "schema_*.json"
+
+    class << self
+      # Nomes dos documentos com schema empacotado, ordenados. Inclui os
+      # sub-schemas auxiliares (ex.: +"nfe_item"+, +"cte_transporte_aereo"+), pois
+      # também são introspectáveis via {descrever}.
+      #
+      # @return [Array<String>] nomes de documento aceitos por {descrever}
+      def disponiveis
+        Dir.glob(File.join(Esquema::DIRETORIO, GLOB_SCHEMAS))
+           .map { |caminho| File.basename(caminho, ".json").delete_prefix("schema_") }
+           .sort
+      end
+
+      # Descrição estruturada dos campos de um documento, para devs e ferramentas
+      # automatizadas conhecerem nomes, tipos e obrigatoriedade sem token nem
+      # conexão. Coleções aninham seus subcampos (ver {Campo#to_h}).
+      #
+      # @param nome [String] nome do documento (ver {disponiveis})
+      # @return [Array<Hash>, nil] descrição de cada campo, ou +nil+ se não houver schema
+      def descrever(nome)
+        Esquema.carregar(nome)&.descrever
+      end
+    end
+  end
+end

data/lib/focus_nfe/esquemas/decimal.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Esquemas
+    # Especificação decimal de um {Campo} (ex.: +Decimal[13.2]+, +Decimal[13.2-4]+):
+    # até +inteiros+ dígitos inteiros e de +casas_minimas+ a +casas_maximas+ casas
+    # decimais. Sabe validar um valor informado contra esses limites.
+    class Decimal
+      # @return [Regexp] captura inteiros e a faixa de casas (ex.: +Decimal[13.2-4]+)
+      ESPEC = /\ADecimal\[(?<inteiros>\d+)(?:\.(?<casas_min>\d*)(?:-(?<casas_max>\d+))?)?\]/
+
+      # @return [Regexp] decompõe um valor em parte inteira e fracionária
+      VALOR = /\A-?(?<inteira>\d+)(?:[.,](?<fracionaria>\d+))?\z/
+
+      # @param bruto [String, nil] tipo bruto do campo
+      # @return [Decimal, nil] a especificação parseada, ou +nil+ se +bruto+ não for decimal
+      def self.parsear(bruto)
+        match = bruto && ESPEC.match(bruto)
+        match && new(match)
+      end
+
+      # @return [Integer] quantidade máxima de dígitos inteiros
+      attr_reader :inteiros
+
+      # @return [Integer] quantidade mínima de casas decimais
+      attr_reader :casas_minimas
+
+      # @return [Integer] quantidade máxima de casas decimais
+      attr_reader :casas_maximas
+
+      # @param match [MatchData] captura de {ESPEC}
+      def initialize(match)
+        @inteiros = Integer(match[:inteiros])
+        @casas_minimas = match[:casas_min].to_s.empty? ? 0 : Integer(match[:casas_min])
+        @casas_maximas = match[:casas_max] ? Integer(match[:casas_max]) : @casas_minimas
+      end
+
+      # Valida um valor decimal. Lenient: aceita menos casas que o mínimo (zeros à
+      # direita são equivalentes) — rejeita apenas o claramente inválido.
+      #
+      # @param valor [Object] valor informado
+      # @return [String, nil] mensagem de erro (sem o nome do campo) ou +nil+ se válido
+      def validar(valor)
+        match = VALOR.match(valor.to_s.strip)
+        return "valor decimal inválido" unless match
+
+        erro_de_tamanho(match[:inteira].to_s, match[:fracionaria])
+      end
+
+      # @return [Hash] descrição serializável da especificação
+      def to_h
+        { inteiros: inteiros, casas_minimas: casas_minimas, casas_maximas: casas_maximas }
+      end
+
+      private
+
+      def erro_de_tamanho(inteira, fracionaria)
+        digitos = inteira.sub(/\A0+(?=\d)/, "").length
+        casas = fracionaria&.length || 0
+        return "#{digitos} dígitos inteiros excedem o máximo de #{inteiros}" if digitos > inteiros
+
+        "#{casas} casas decimais excedem o máximo de #{casas_maximas}" if casas > casas_maximas
+      end
+    end
+  end
+end