focus_nfe 1.0.0

data/lib/focus_nfe/modelos/documento.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Modelos
+    # Objeto de valor imutável que representa o estado fiscal de um documento.
+    # Encapsula o corpo (Hash) das respostas de emissão e consulta — que
+    # compartilham o mesmo schema — expondo os campos comuns e predicados de
+    # status. Campos não mapeados continuam acessíveis via {#[]}/{#dados}.
+    class Documento
+      # @return [FocusNfe::HTTP::Response, nil] resposta original que originou o documento (nil em webhooks inbound)
+      attr_reader :response
+
+      # @return [String, nil] referência informada na chamada (nem sempre presente no corpo)
+      attr_reader :ref
+
+      # @return [Hash] corpo cru da resposta
+      attr_reader :dados
+
+      # @return [String, nil] status do documento na Focus NFe (ex.: +autorizado+)
+      def status = dados["status"]
+
+      # @return [String, nil] código de status retornado pela SEFAZ
+      def status_sefaz = dados["status_sefaz"]
+
+      # @return [String, nil] mensagem descritiva retornada pela SEFAZ
+      def mensagem_sefaz = dados["mensagem_sefaz"]
+
+      # @return [String, nil] chave de acesso do documento autorizado
+      def chave_nfe = dados["chave_nfe"]
+
+      # @return [String, nil] número do documento fiscal
+      def numero = dados["numero"]
+
+      # @return [String, nil] série do documento fiscal
+      def serie = dados["serie"]
+
+      # @return [String, nil] caminho relativo do XML da nota na Focus NFe
+      def caminho_xml_nota_fiscal = dados["caminho_xml_nota_fiscal"]
+
+      # @return [String, nil] caminho relativo do PDF (DANFe/DACTe/DANFSe) na Focus NFe
+      def caminho_danfe = dados["caminho_danfe"]
+
+      # @return [String, nil] caminho relativo do XML da carta de correção na Focus NFe
+      def caminho_xml_carta_correcao = dados["caminho_xml_carta_correcao"]
+
+      # @return [String, nil] caminho relativo do PDF da carta de correção na Focus NFe
+      def caminho_pdf_carta_correcao = dados["caminho_pdf_carta_correcao"]
+
+      # @return [String, nil] número sequencial da carta de correção emitida
+      def numero_carta_correcao = dados["numero_carta_correcao"]
+
+      # Constrói um {Documento} a partir de uma {HTTP::Response}.
+      #
+      # @param response [FocusNfe::HTTP::Response] resposta de emissão/consulta
+      # @param ref [String, nil] referência conhecida pela chamada, injetada quando ausente do corpo
+      # @return [FocusNfe::Modelos::Documento]
+      def self.from_response(response, ref: nil)
+        new(dados: response.body, ref: ref, response: response)
+      end
+
+      # Constrói um {Documento} a partir do corpo já parseado de um webhook
+      # inbound — sem {HTTP::Response} associada.
+      #
+      # @param corpo [Hash] corpo do webhook, com o mesmo schema das respostas
+      # @param ref [String, nil] referência conhecida, injetada quando ausente do corpo
+      # @return [FocusNfe::Modelos::Documento]
+      def self.from_payload(corpo, ref: nil)
+        new(dados: corpo, ref: ref)
+      end
+
+      # @param dados [Object] corpo da resposta/webhook (usa {} quando não é Hash)
+      # @param ref [String, nil] referência conhecida pela chamada
+      # @param response [FocusNfe::HTTP::Response, nil] resposta original, quando houver
+      def initialize(dados:, ref: nil, response: nil)
+        @response = response
+        @dados = dados.is_a?(Hash) ? dados : {}
+        @ref = ref || @dados["ref"]
+        freeze
+      end
+
+      # @param chave [String] nome do campo no corpo da resposta
+      # @return [Object, nil] valor do campo cru
+      def [](chave)
+        dados[chave]
+      end
+
+      # @return [Boolean]
+      def autorizado?
+        status == "autorizado"
+      end
+
+      # @return [Boolean]
+      def cancelado?
+        status == "cancelado"
+      end
+
+      # @return [Boolean]
+      def processando?
+        status == "processando_autorizacao"
+      end
+
+      # @return [Boolean]
+      def erro?
+        status.to_s.start_with?("erro")
+      end
+
+      # @return [Boolean]
+      def denegado?
+        status == "denegado"
+      end
+    end
+  end
+end

data/lib/focus_nfe/modelos/inutilizacao.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Modelos
+    # Objeto de valor imutável que representa o resultado de uma inutilização de
+    # numeração. Encapsula o corpo (Hash) da resposta — tanto da criação
+    # (+POST+) quanto de cada item da consulta (+GET+) — expondo os campos comuns
+    # e o predicado de status. Campos não mapeados continuam acessíveis via
+    # {#[]}/{#dados}. Diferente de {Documento}, não carrega +ref+: a inutilização
+    # é uma operação de coleção, sem referência por documento.
+    class Inutilizacao
+      # @return [FocusNfe::HTTP::Response, nil] resposta original; +nil+ para itens de uma consulta
+      attr_reader :response
+
+      # @return [Hash] corpo cru da resposta (ou do item)
+      attr_reader :dados
+
+      # @return [String, nil] status da inutilização na SEFAZ (ex.: +autorizado+)
+      def status = dados["status"]
+
+      # @return [String, nil] código de status retornado pela SEFAZ
+      def status_sefaz = dados["status_sefaz"]
+
+      # @return [String, nil] mensagem descritiva retornada pela SEFAZ
+      def mensagem_sefaz = dados["mensagem_sefaz"]
+
+      # @return [String, nil] protocolo de autorização da SEFAZ (campo +protocolo_sefaz+)
+      def protocolo = dados["protocolo_sefaz"]
+
+      # @return [String, nil] série da numeração inutilizada
+      def serie = dados["serie"]
+
+      # @return [String, nil] número inicial da faixa inutilizada
+      def numero_inicial = dados["numero_inicial"]
+
+      # @return [String, nil] número final da faixa inutilizada
+      def numero_final = dados["numero_final"]
+
+      # Constrói uma {Inutilizacao} a partir de uma {HTTP::Response} de criação.
+      #
+      # @param response [FocusNfe::HTTP::Response] resposta da inutilização
+      # @return [FocusNfe::Modelos::Inutilizacao]
+      def self.from_response(response)
+        new(dados: response.body.is_a?(Hash) ? response.body : {}, response: response)
+      end
+
+      # Constrói uma {Inutilizacao} a partir de um item cru de uma consulta.
+      #
+      # @param item [Hash] item da resposta de consulta
+      # @return [FocusNfe::Modelos::Inutilizacao]
+      def self.from_item(item)
+        new(dados: item.is_a?(Hash) ? item : {})
+      end
+
+      # @param dados [Hash] corpo cru da resposta (ou do item)
+      # @param response [FocusNfe::HTTP::Response, nil] resposta original, quando houver
+      def initialize(dados:, response: nil)
+        @dados = dados
+        @response = response
+        freeze
+      end
+
+      # @param chave [String] nome do campo no corpo da resposta
+      # @return [Object, nil] valor do campo cru
+      def [](chave)
+        dados[chave]
+      end
+
+      # @return [Boolean]
+      def autorizado?
+        status == "autorizado"
+      end
+    end
+  end
+end

data/lib/focus_nfe/modelos/pagina.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Modelos
+    # Coleção paginada de uma resposta de listagem. Encapsula o corpo (Array de
+    # Hashes crus) e os cabeçalhos de sincronização incremental, expondo os itens
+    # de forma enumerável. Itens permanecem como Hash — modelos leves nas
+    # auxiliares/recebidas, conforme a arquitetura.
+    class Pagina
+      include Enumerable
+
+      # @return [FocusNfe::HTTP::Response] resposta original da listagem
+      attr_reader :response
+
+      # @return [Array] itens da página (corpo cru da resposta)
+      attr_reader :itens
+
+      # @return [Integer, nil] total de registros disponíveis (cabeçalho +X-Total-Count+)
+      attr_reader :total
+
+      # @return [Integer, nil] maior versão presente (cabeçalho +X-Max-Version+), para sincronização incremental
+      attr_reader :versao_maxima
+
+      # Constrói uma {Pagina} a partir de uma {HTTP::Response} de listagem.
+      #
+      # @param response [FocusNfe::HTTP::Response] resposta de uma listagem
+      # @return [FocusNfe::Modelos::Pagina]
+      def self.from_response(response)
+        new(response: response)
+      end
+
+      # @param response [FocusNfe::HTTP::Response] resposta de uma listagem
+      def initialize(response:)
+        @response = response
+        @itens = response.body.is_a?(Array) ? response.body : []
+        @total = response.headers["X-Total-Count"]&.to_i
+        @versao_maxima = response.headers["X-Max-Version"]&.to_i
+        freeze
+      end
+
+      # Itera os itens da página.
+      #
+      # @yieldparam item [Object] item cru da listagem
+      # @return [self, Enumerator] +self+ quando há bloco; um Enumerator caso contrário
+      def each(&)
+        return to_enum(:each) unless block_given?
+
+        itens.each(&)
+        self
+      end
+      alias cada each
+    end
+  end
+end

data/lib/focus_nfe/recursos/backups.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Consulta de backups mensais de XML/DANFE por CNPJ. O recurso responde em
+    # +GET /backups/{cnpj}.json+ com as URLs dos pacotes ZIP por mês.
+    class Backups < Base
+      caminho_base "backups"
+
+      # @param cnpj [String] CNPJ da empresa (14 dígitos)
+      # @return [Array<Hash>] lista de backups mensais (+mes+, +danfes+, +xmls+)
+      def consultar(cnpj)
+        connection.get("#{caminho_referencia(cnpj)}.json").body
+      end
+    end
+  end
+end

data/lib/focus_nfe/recursos/base.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module FocusNfe
+  module Recursos
+    # Base dos recursos da API. Guarda a {HTTP::Connection} e o +caminho_base+
+    # declarado por cada recurso, e oferece os utilitários compartilhados pelos
+    # mixins de comportamento ({Concerns::Emitivel}, {Concerns::Consultavel}, {Concerns::Cancelavel}, …):
+    # montagem do caminho por referência e validação client-side da +ref+.
+    class Base
+      # @return [Regexp] formato aceito para a +ref+ (alfanumérico, hífen ou underscore)
+      REFERENCIA = /\A[\w-]+\z/
+
+      class << self
+        # Declara (ou lê) o caminho base do recurso, sem o prefixo +/v2+.
+        #
+        # @param valor [String, nil] caminho a declarar; omitido apenas lê o atual
+        # @return [String, nil] caminho base efetivo da classe
+        def caminho_base(valor = nil)
+          @caminho_base = valor unless valor.nil?
+          @caminho_base
+        end
+
+        # Declara (ou lê) o caminho da prévia do recurso, sem o prefixo +/v2+.
+        # Usado por {Concerns::Visualizavel}; cada documento com prévia o declara
+        # (ex.: +"nfe/danfe"+).
+        #
+        # @param valor [String, nil] caminho a declarar; omitido apenas lê o atual
+        # @return [String, nil] caminho de prévia efetivo da classe
+        def caminho_base_previa(valor = nil)
+          @caminho_base_previa = valor unless valor.nil?
+          @caminho_base_previa
+        end
+      end
+
+      # @param connection [FocusNfe::HTTP::Connection] conexão do cliente
+      def initialize(connection)
+        @connection = connection
+      end
+
+      # @return [String, nil] caminho base declarado pela classe do recurso
+      def caminho_base
+        self.class.caminho_base
+      end
+
+      # @return [String, nil] caminho de prévia declarado pela classe do recurso
+      def caminho_base_previa
+        self.class.caminho_base_previa
+      end
+
+      private
+
+      attr_reader :connection
+
+      # Monta o caminho do recurso escapando o segmento dinâmico, para que um
+      # identificador com +/+, +?+, +#+ ou +..+ não sequestre o path nem injete
+      # query na requisição autenticada (identificadores comuns — dígitos, hífen,
+      # underscore, ponto — passam intactos).
+      #
+      # @param ref [String] referência/identificador do documento
+      # @return [String] caminho do recurso para a referência (ex.: "nfe/pedido-42")
+      def caminho_referencia(ref)
+        "#{caminho_base}/#{URI.encode_www_form_component(ref)}"
+      end
+
+      # Valida a +ref+ client-side antes de qualquer requisição, evitando uma ida
+      # à API por um erro trivial de formato.
+      #
+      # @param ref [String] referência informada
+      # @return [void]
+      # @raise [ArgumentError] se a +ref+ não for alfanumérica (hífen/underscore permitidos)
+      def validar_referencia!(ref)
+        return if ref.is_a?(String) && ref.match?(REFERENCIA)
+
+        raise ArgumentError, "referência inválida: #{ref.inspect} (esperado alfanumérico, hífen ou underscore)"
+      end
+
+      # Esquemas extras a validar além do esquema de topo, dependentes do payload.
+      # Cada par associa a chave de um objeto aninhado no payload ao nome do
+      # esquema que o valida. Recursos com esquema dinâmico (CTe, CTe OS, MDFe)
+      # sobrescrevem este método para, conforme os +dados+, escolher o sub-esquema.
+      #
+      # @param _dados [Hash] payload de emissão (chaves String)
+      # @return [Hash{String => String}] chave aninhada no payload => nome do esquema
+      def esquemas_extras(_dados)
+        {}
+      end
+    end
+  end
+end

data/lib/focus_nfe/recursos/ceps.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Consulta de CEPs. +consultar(cep)+ devolve o endereço de um CEP; +buscar+
+    # filtra endereços por UF/logradouro/localidade/código IBGE.
+    class Ceps < Base
+      include Concerns::Localizavel
+      include Concerns::Listavel
+
+      caminho_base "ceps"
+
+      alias buscar listar
+    end
+  end
+end

data/lib/focus_nfe/recursos/cfops.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Consulta de CFOPs (Código Fiscal de Operações e Prestações).
+    # +consultar(codigo)+ busca um CFOP; +buscar+ filtra por código/descrição.
+    class Cfops < Base
+      include Concerns::Localizavel
+      include Concerns::Listavel
+
+      caminho_base "cfops"
+
+      alias buscar listar
+    end
+  end
+end

data/lib/focus_nfe/recursos/cnaes.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Consulta de códigos CNAE. +consultar(codigo)+ busca um CNAE; +buscar+ filtra
+    # por código/descrição. O caminho da API é +codigos_cnae+.
+    class Cnaes < Base
+      include Concerns::Localizavel
+      include Concerns::Listavel
+
+      caminho_base "codigos_cnae"
+
+      alias buscar listar
+    end
+  end
+end

data/lib/focus_nfe/recursos/cnpjs.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Consulta de CNPJ. +consultar(cnpj)+ devolve os dados cadastrais da empresa
+    # com o endereço aninhado.
+    class Cnpjs < Base
+      include Concerns::Localizavel
+
+      caminho_base "cnpjs"
+    end
+  end
+end

data/lib/focus_nfe/recursos/concerns/baixavel.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    module Concerns
+      # Comportamento de download (+GET /<base>/<identificador>.<formato>+). Devolve
+      # os bytes crus da resposta (+raw_body+); o eventual +302+ para URL pré-assinada
+      # (PDFs) é seguido pelo adaptador sem reenviar a autenticação.
+      module Baixavel
+        # Baixa o documento no formato indicado, devolvendo os bytes crus.
+        #
+        # @param identificador [String] chave ou referência do documento
+        # @param formato [String, Symbol] extensão desejada (+json+, +xml+, +pdf+, +html+)
+        # @return [String] corpo cru da resposta (bytes)
+        # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+        def download(identificador, formato:)
+          response = connection.get("#{caminho_referencia(identificador)}.#{URI.encode_www_form_component(formato)}")
+          response.raw_body
+        end
+
+        # @param identificador [String] chave ou referência do documento
+        # @return [String] JSON cru do documento
+        def download_json(identificador)
+          download(identificador, formato: :json)
+        end
+
+        # @param identificador [String] chave ou referência do documento
+        # @return [String] XML cru do documento
+        def download_xml(identificador)
+          download(identificador, formato: :xml)
+        end
+
+        # @param identificador [String] chave ou referência do documento
+        # @return [String] PDF (DANFe/DACTe/DANFSe) cru do documento
+        def download_pdf(identificador)
+          download(identificador, formato: :pdf)
+        end
+      end
+    end
+  end
+end

data/lib/focus_nfe/recursos/concerns/baixavel_eventos.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    module Concerns
+      # Download do XML de eventos fiscais de um documento
+      # (+GET /<base>/<chave>/<evento>.xml+). Devolve os bytes crus (+raw_body+).
+      # Opt-in: só recursos que expõem cancelamento e carta de correção — as notas
+      # (NF-e) e conhecimentos (CT-e) recebidos.
+      module BaixavelEventos
+        # @param chave [String] chave de acesso do documento
+        # @return [String, nil] XML do último cancelamento
+        def download_xml_cancelamento(chave)
+          download_xml_evento(chave, evento: "cancelamento")
+        end
+
+        # @param chave [String] chave de acesso do documento
+        # @return [String, nil] XML da última carta de correção
+        def download_xml_carta_correcao(chave)
+          download_xml_evento(chave, evento: "carta_correcao")
+        end
+
+        private
+
+        # @param chave [String] chave de acesso do documento
+        # @param evento [String] sub-caminho do evento (ex.: +cancelamento+)
+        # @return [String, nil] XML cru do evento
+        def download_xml_evento(chave, evento:)
+          connection.get("#{caminho_referencia(chave)}/#{evento}.xml").raw_body
+        end
+      end
+    end
+  end
+end

data/lib/focus_nfe/recursos/concerns/cancelavel.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    module Concerns
+      # Comportamento de cancelamento (+DELETE /<base>/<ref>+ com +justificativa+ no
+      # corpo). Devolve o {Modelos::Documento} com o estado fiscal resultante.
+      module Cancelavel
+        # Cancela um documento já emitido.
+        #
+        # @param ref [String] referência do documento
+        # @param justificativa [String] motivo do cancelamento exigido pela SEFAZ
+        # @return [FocusNfe::Modelos::Documento]
+        # @raise [ArgumentError] se a +ref+ for inválida
+        # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+        def cancelar(ref, justificativa:)
+          validar_referencia!(ref)
+
+          response = connection.delete(caminho_referencia(ref), body: { justificativa: justificativa })
+          Modelos::Documento.from_response(response, ref: ref)
+        end
+      end
+    end
+  end
+end

data/lib/focus_nfe/recursos/concerns/conciliavel.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    module Concerns
+      # Comportamento de Conciliação Financeira (ECONF): registro, consulta e
+      # cancelamento por número de protocolo num sub-caminho da referência
+      # (+/<base>/<ref>/econf+). Devolve o {Modelos::Documento} com o estado do
+      # evento. Uso compartilhado por NF-e e NFC-e.
+      module Conciliavel
+        # Registra um evento de conciliação financeira sobre o documento autorizado.
+        #
+        # @param ref [String] referência do documento
+        # @param detalhes_pagamento [Array<Hash>] pagamentos a conciliar (1 a 100)
+        # @return [FocusNfe::Modelos::Documento]
+        # @raise [ArgumentError] se a +ref+ for inválida
+        # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+        def registrar_econf(ref, detalhes_pagamento:)
+          validar_referencia!(ref)
+
+          response = connection.post("#{caminho_referencia(ref)}/econf",
+                                     body: { detalhes_pagamento: detalhes_pagamento })
+          Modelos::Documento.from_response(response, ref: ref)
+        end
+
+        # Consulta um evento de conciliação financeira pelo número de protocolo.
+        #
+        # @param ref [String] referência do documento
+        # @param numero_protocolo [String] protocolo devolvido no registro do ECONF
+        # @return [FocusNfe::Modelos::Documento]
+        # @raise [ArgumentError] se a +ref+ for inválida
+        # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+        def consultar_econf(ref, numero_protocolo)
+          validar_referencia!(ref)
+
+          response = connection.get(caminho_econf(ref, numero_protocolo))
+          Modelos::Documento.from_response(response, ref: ref)
+        end
+
+        # Cancela um evento de conciliação financeira pelo número de protocolo. Havendo
+        # mais de um ECONF na mesma nota, cancele do mais antigo ao mais recente.
+        #
+        # @param ref [String] referência do documento
+        # @param numero_protocolo [String] protocolo devolvido no registro do ECONF
+        # @return [FocusNfe::Modelos::Documento]
+        # @raise [ArgumentError] se a +ref+ for inválida
+        # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+        def cancelar_econf(ref, numero_protocolo)
+          validar_referencia!(ref)
+
+          response = connection.delete(caminho_econf(ref, numero_protocolo))
+          Modelos::Documento.from_response(response, ref: ref)
+        end
+
+        private
+
+        # @param ref [String] referência do documento
+        # @param numero_protocolo [String] protocolo do ECONF (escapado no caminho)
+        # @return [String] caminho do ECONF por protocolo
+        def caminho_econf(ref, numero_protocolo)
+          "#{caminho_referencia(ref)}/econf/#{URI.encode_www_form_component(numero_protocolo)}"
+        end
+      end
+    end
+  end
+end

data/lib/focus_nfe/recursos/concerns/consultavel.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    module Concerns
+      # Comportamento de consulta (+GET /<base>/<ref>+). Devolve o {Modelos::Documento}
+      # com o estado fiscal atual do documento.
+      module Consultavel
+        # Consulta o estado de um documento já emitido.
+        #
+        # @param ref [String] referência do documento
+        # @param completa [Boolean] quando +true+, pede a resposta completa (+completa=1+)
+        # @return [FocusNfe::Modelos::Documento]
+        # @raise [ArgumentError] se a +ref+ for inválida
+        # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+        def consultar(ref, completa: false)
+          validar_referencia!(ref)
+
+          params = completa ? { completa: 1 } : {}
+          response = connection.get(caminho_referencia(ref), params: params)
+          Modelos::Documento.from_response(response, ref: ref)
+        end
+      end
+    end
+  end
+end

data/lib/focus_nfe/recursos/concerns/corrigivel.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    module Concerns
+      # Comportamento de Carta de Correção Eletrônica (CC-e): +POST
+      # /<base>/<ref>/carta_correcao+ com o texto da correção no corpo. Devolve o
+      # {Modelos::Documento} com o estado fiscal da CC-e.
+      module Corrigivel
+        # @return [Range] faixa de tamanho aceita para o texto da correção
+        TAMANHO_CORRECAO = (15..1000)
+
+        # Emite uma Carta de Correção Eletrônica sobre um documento autorizado.
+        #
+        # @param ref [String] referência do documento
+        # @param correcao [String] texto da correção (15 a 1000 caracteres)
+        # @param data_evento [String, nil] data/hora do evento em ISO 8601; omitida usa a data atual
+        # @return [FocusNfe::Modelos::Documento]
+        # @raise [ArgumentError] se a +ref+ ou a +correcao+ forem inválidas
+        # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+        def corrigir(ref, correcao:, data_evento: nil)
+          validar_referencia!(ref)
+          validar_correcao!(correcao)
+
+          body = { correcao: correcao }
+          body[:data_evento] = data_evento if data_evento
+          response = connection.post("#{caminho_referencia(ref)}/carta_correcao", body: body)
+          Modelos::Documento.from_response(response, ref: ref)
+        end
+
+        private
+
+        # @param correcao [String] texto informado
+        # @return [void]
+        # @raise [ArgumentError] se não for String ou estiver fora de 15..1000 caracteres
+        def validar_correcao!(correcao)
+          return if correcao.is_a?(String) && TAMANHO_CORRECAO.cover?(correcao.length)
+
+          raise ArgumentError,
+                "correção inválida: esperado String com #{TAMANHO_CORRECAO.min} a #{TAMANHO_CORRECAO.max} caracteres"
+        end
+      end
+    end
+  end
+end