focus_nfe 1.0.0

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    module Concerns
+      # Comportamento de Carta de Correção Eletrônica (CC-e) do CT-e/CT-e OS: +POST
+      # /<base>/<ref>/carta_correcao+ com a correção _por campo_ no corpo — diferente
+      # da CC-e de texto livre da NF-e ({Corrigivel}). Devolve o {Modelos::Documento}
+      # com o estado fiscal da CC-e.
+      module CorrigivelCte
+        # Emite uma Carta de Correção Eletrônica corrigindo um campo do documento.
+        #
+        # São aceitas até 20 correções por documento, cada uma em uma requisição; vale
+        # apenas a última correção enviada. Variáveis tributárias, dados de remetente/
+        # destinatário e datas de emissão/saída não podem ser corrigidos.
+        #
+        # @param ref [String] referência do documento
+        # @param campo_corrigido [String] nome do campo a corrigir
+        # @param valor_corrigido [String] novo valor do campo
+        # @param grupo_corrigido [String, nil] grupo que contém o campo (ex.: +"cargas"+)
+        # @param numero_item_grupo_corrigido [String, nil] índice do item, quando o campo está numa lista (inicia em 1)
+        # @param campo_api [Integer, String, nil] +1+ para nomes de campo da API (padrão), +0+ para tags XML
+        # @return [FocusNfe::Modelos::Documento]
+        # @raise [ArgumentError] se a +ref+, +campo_corrigido+ ou +valor_corrigido+ forem inválidos
+        # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+        def corrigir(ref, campo_corrigido:, valor_corrigido:, grupo_corrigido: nil,
+                     numero_item_grupo_corrigido: nil, campo_api: nil)
+          validar_referencia!(ref)
+          validar_campos_correcao!(campo_corrigido, valor_corrigido)
+
+          body = {
+            campo_corrigido: campo_corrigido, valor_corrigido: valor_corrigido,
+            grupo_corrigido: grupo_corrigido, numero_item_grupo_corrigido: numero_item_grupo_corrigido,
+            campo_api: campo_api
+          }.compact
+          response = connection.post("#{caminho_referencia(ref)}/carta_correcao", body: body)
+          Modelos::Documento.from_response(response, ref: ref)
+        end
+
+        private
+
+        # @param campo_corrigido [String] campo informado
+        # @param valor_corrigido [String] valor informado
+        # @return [void]
+        # @raise [ArgumentError] se algum deles não for uma String não-vazia
+        def validar_campos_correcao!(campo_corrigido, valor_corrigido)
+          return if string_preenchida?(campo_corrigido) && string_preenchida?(valor_corrigido)
+
+          raise ArgumentError, "correção inválida: campo_corrigido e valor_corrigido são obrigatórios"
+        end
+
+        # @param valor [Object] valor a checar
+        # @return [Boolean] true se for uma String com conteúdo não em branco
+        def string_preenchida?(valor)
+          valor.is_a?(String) && !valor.strip.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    module Concerns
+      # Comportamento de emissão (+POST /<base>?ref=+). Devolve o {Modelos::Documento}
+      # com o estado fiscal inicial (em geral assíncrono: +processando_autorizacao+).
+      module Emitivel
+        # Emite um documento fiscal.
+        #
+        # @param ref [String] referência única do documento na sua aplicação
+        # @param dados [Hash] payload de emissão (campos do schema, validados server-side)
+        # @param validar [Boolean] se +true+, valida +dados+ contra o schema empacotado
+        #   antes do envio (documentos sem schema próprio são emitidos sem validar)
+        # @param opcoes [Hash] parâmetros de query adicionais (ex.: emissão síncrona)
+        # @return [FocusNfe::Modelos::Documento]
+        # @raise [ArgumentError] se a +ref+ for inválida
+        # @raise [FocusNfe::Esquemas::ErroDeValidacao] se +validar+ e +dados+ violarem o schema
+        # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+        def emitir(ref:, dados:, validar: false, **opcoes)
+          validar_referencia!(ref)
+          validar_dados!(dados) if validar
+
+          response = connection.post(caminho_base, params: { ref: ref, **opcoes }, body: dados)
+          Modelos::Documento.from_response(response, ref: ref)
+        end
+
+        private
+
+        # @param dados [Hash] payload de emissão a validar contra o schema
+        # @return [void]
+        # @raise [FocusNfe::Esquemas::ErroDeValidacao] se houver campo inválido/ausente
+        def validar_dados!(dados)
+          esquema = Esquemas::Esquema.carregar(caminho_base)
+          return unless esquema
+
+          normalizados = dados.transform_keys(&:to_s)
+          aninhados = carregar_aninhados(normalizados)
+          erros = Esquemas::Validador.new(esquema, aninhados: aninhados).validar(normalizados)
+          raise Esquemas::ErroDeValidacao, erros unless erros.empty?
+        end
+
+        # @param dados [Hash] payload normalizado (chaves String)
+        # @return [Hash{String => FocusNfe::Esquemas::Esquema}] sub-esquemas por chave aninhada
+        def carregar_aninhados(dados)
+          esquemas_extras(dados).transform_values { |nome| Esquemas::Esquema.carregar(nome) }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    module Concerns
+      # Comportamento de reenvio do documento por e-mail (+POST
+      # /<base>/<ref>/email+ com a lista de destinatários no corpo). Devolve o
+      # corpo cru da resposta.
+      module Enviavel
+        # @return [Integer] número máximo de destinatários aceito pela API
+        MAX_EMAILS = 10
+
+        # Reenvia o documento por e-mail para os destinatários informados.
+        #
+        # @param ref [String] referência do documento
+        # @param emails [Array<String>] destinatários (1 a 10)
+        # @return [Hash, Array, nil] corpo cru da resposta
+        # @raise [ArgumentError] se a +ref+ ou a lista de +emails+ forem inválidas
+        # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+        def enviar_email(ref, emails:)
+          validar_referencia!(ref)
+          validar_emails!(emails)
+
+          connection.post("#{caminho_referencia(ref)}/email", body: { emails: emails }).body
+        end
+
+        private
+
+        # @param emails [Array<String>] lista informada
+        # @return [void]
+        # @raise [ArgumentError] se não for Array de 1 a 10 elementos
+        def validar_emails!(emails)
+          return if emails.is_a?(Array) && (1..MAX_EMAILS).cover?(emails.size)
+
+          raise ArgumentError, "emails inválidos: esperado Array com 1 a #{MAX_EMAILS} destinatários"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    module Concerns
+      # Transporte de eventos fiscais sobre um documento (+POST+/+DELETE+ num
+      # sub-caminho da referência). Cada recurso expõe seus eventos por cima
+      # destes helpers — o MDF-e com nomes próprios (+encerrar+, +incluir_condutor+,
+      # +incluir_dfe+) e as notas recebidas com +emitir_evento+/+cancelar_evento+.
+      # Devolve o {Modelos::Documento} com o estado fiscal resultante do evento.
+      module Eventavel
+        private
+
+        # Emite um evento sobre o documento (+POST /<base>/<ref>/<caminho>+).
+        #
+        # @param ref [String] referência do documento
+        # @param caminho [String] sub-caminho do evento (ex.: +encerrar+)
+        # @param dados [Hash] campos do corpo 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_em(ref, caminho:, **dados)
+          validar_referencia!(ref)
+
+          response = connection.post("#{caminho_referencia(ref)}/#{caminho}", body: dados)
+          Modelos::Documento.from_response(response, ref: ref)
+        end
+
+        # Cancela um evento do documento (+DELETE /<base>/<ref>/<caminho>+).
+        #
+        # @param ref [String] referência do documento
+        # @param caminho [String] sub-caminho do evento (ex.: +evento+)
+        # @param dados [Hash] campos do corpo do cancelamento; omitidos não enviam corpo
+        # @return [FocusNfe::Modelos::Documento]
+        # @raise [ArgumentError] se a +ref+ for inválida
+        # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+        def cancelar_evento_em(ref, caminho:, **dados)
+          validar_referencia!(ref)
+
+          response = connection.delete("#{caminho_referencia(ref)}/#{caminho}", body: dados.empty? ? nil : dados)
+          Modelos::Documento.from_response(response, ref: ref)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    module Concerns
+      # Comportamento de inutilização de numeração: criação (+POST
+      # /<base>/inutilizacao+, devolvendo um {Modelos::Inutilizacao}) e consulta
+      # das já criadas (+GET /<base>/inutilizacoes+, devolvendo uma lista de
+      # {Modelos::Inutilizacao}). É uma operação de coleção — sem +ref+ por
+      # documento.
+      module Inutilizavel
+        # @return [String] segmento do caminho de criação (singular)
+        CAMINHO_INUTILIZACAO = "inutilizacao"
+
+        # @return [String] segmento do caminho de consulta (plural)
+        CAMINHO_INUTILIZACOES = "inutilizacoes"
+
+        # @return [Integer] tamanho mínimo da justificativa exigido pela SEFAZ
+        JUSTIFICATIVA_MINIMA = 15
+
+        # Inutiliza uma faixa de numeração não utilizada.
+        #
+        # @param cnpj [String] CNPJ do emitente
+        # @param serie [String, Integer] série da numeração
+        # @param numero_inicial [String, Integer] número inicial da faixa
+        # @param numero_final [String, Integer] número final da faixa
+        # @param justificativa [String] motivo da inutilização (mínimo 15 caracteres)
+        # @return [FocusNfe::Modelos::Inutilizacao]
+        # @raise [ArgumentError] se a +justificativa+ for inválida
+        # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+        def inutilizar(cnpj:, serie:, numero_inicial:, numero_final:, justificativa:)
+          validar_justificativa!(justificativa)
+          validar_faixa!(numero_inicial, numero_final)
+
+          body = { cnpj: cnpj, serie: serie, numero_inicial: numero_inicial,
+                   numero_final: numero_final, justificativa: justificativa }
+          response = connection.post("#{caminho_base}/#{CAMINHO_INUTILIZACAO}", body: body)
+          Modelos::Inutilizacao.from_response(response)
+        end
+
+        # Consulta as inutilizações já registradas, aplicando os filtros como query string.
+        #
+        # @param filtros [Hash] filtros aceitos pela API (ex.: +cnpj:+, +cpf:+, +numero_inicial:+)
+        # @return [Array<FocusNfe::Modelos::Inutilizacao>]
+        # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+        def consultar_inutilizacoes(**filtros)
+          response = connection.get("#{caminho_base}/#{CAMINHO_INUTILIZACOES}", params: filtros)
+          itens = response.body.is_a?(Array) ? response.body : []
+          itens.map { |item| Modelos::Inutilizacao.from_item(item) }
+        end
+
+        private
+
+        # @param justificativa [String] justificativa informada
+        # @return [void]
+        # @raise [ArgumentError] se não for String ou tiver menos de 15 caracteres
+        def validar_justificativa!(justificativa)
+          return if justificativa.is_a?(String) && justificativa.length >= JUSTIFICATIVA_MINIMA
+
+          raise ArgumentError,
+                "justificativa inválida: esperado String com ao menos #{JUSTIFICATIVA_MINIMA} caracteres"
+        end
+
+        # Valida a faixa de numeração: ambos os números presentes, inteiros, e
+        # +numero_inicial+ não maior que +numero_final+ (faixa de um único número
+        # é permitida).
+        #
+        # @param numero_inicial [String, Integer] número inicial informado
+        # @param numero_final [String, Integer] número final informado
+        # @return [void]
+        # @raise [ArgumentError] se algum número for ausente/não inteiro ou se inicial > final
+        def validar_faixa!(numero_inicial, numero_final)
+          inicial = numero_para_inteiro(numero_inicial)
+          final = numero_para_inteiro(numero_final)
+
+          if inicial.nil? || final.nil?
+            raise ArgumentError, "numeração inválida: numero_inicial e numero_final devem ser inteiros"
+          end
+
+          return if inicial <= final
+
+          raise ArgumentError, "numeração inválida: numero_inicial (#{inicial}) maior que numero_final (#{final})"
+        end
+
+        # @param valor [Object] valor informado
+        # @return [Integer, nil] o valor como inteiro (base 10) ou +nil+ se não for conversível
+        def numero_para_inteiro(valor)
+          case valor
+          when Integer then valor
+          when String then Integer(valor, 10, exception: false)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    module Concerns
+      # Comportamento de listagem (+GET /<base>+). Os filtros viram query string e
+      # a resposta — corpo + cabeçalhos de paginação — é encapsulada numa
+      # {Modelos::Pagina}.
+      module Listavel
+        # Lista os registros do recurso, aplicando os filtros como query string.
+        #
+        # @param filtros [Hash] filtros e paginação aceitos pelo recurso (ex.: +cnpj:+, +versao:+, +offset:+)
+        # @return [FocusNfe::Modelos::Pagina]
+        # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+        def listar(**filtros)
+          response = connection.get(caminho_base, params: filtros)
+          Modelos::Pagina.from_response(response)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    module Concerns
+      # Comportamento de consulta por identificador (+GET /<base>/<identificador>+),
+      # para recursos de leitura e referência. Devolve o corpo cru da resposta
+      # (Hash) — sem validação fiscal de +ref+, pois o identificador é um código,
+      # chave ou CNPJ.
+      module Localizavel
+        # Consulta um registro pelo seu identificador.
+        #
+        # @param identificador [String] código/chave/CNPJ do registro
+        # @return [Hash, Array, nil] corpo cru da resposta
+        # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+        def consultar(identificador)
+          connection.get(caminho_referencia(identificador)).body
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    module Concerns
+      # Comportamento de reenvio de notificação (+POST /<base>/<identificador>/hook+),
+      # disparando de novo o webhook do documento.
+      module Notificavel
+        # Reenvia a notificação (webhook) do documento.
+        #
+        # @param identificador [String] chave ou referência do documento
+        # @return [Hash, Array, nil] corpo cru da resposta
+        # @raise [ArgumentError] se o +identificador+ for inválido
+        # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+        def reenviar_hook(identificador)
+          validar_referencia!(identificador)
+
+          connection.post("#{caminho_referencia(identificador)}/hook").body
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    module Concerns
+      # Comportamento de exclusão por identificador (+DELETE /<base>/<identificador>+),
+      # para recursos de gestão (CRUD).
+      module Removivel
+        # Exclui um registro pelo seu identificador.
+        #
+        # @param identificador [String] id do registro
+        # @return [Hash, Array, nil] corpo cru da resposta
+        # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+        def excluir(identificador)
+          connection.delete(caminho_referencia(identificador)).body
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    module Concerns
+      # Comportamento de prévia/visualização (+POST /<base_previa>+ com o payload
+      # no corpo). Gera o PDF apenas para conferência visual — sem valor fiscal e
+      # sem emitir o documento. O caminho é declarado por
+      # {Base.caminho_base_previa} em cada recurso (ex.: +"nfe/danfe"+), para que
+      # outros documentos com prévia o adotem sem alterar o mixin. A validação
+      # opt-in reaproveita o schema via {Concerns::Emitivel}.
+      module Visualizavel
+        # Gera a prévia do documento a partir do payload, devolvendo os bytes do PDF.
+        #
+        # @param dados [Hash] payload do documento (mesmos campos da emissão)
+        # @param validar [Boolean] se +true+, valida +dados+ contra o schema empacotado antes do envio
+        # @return [String, nil] bytes crus do PDF da prévia
+        # @raise [FocusNfe::Esquemas::ErroDeValidacao] se +validar+ e +dados+ violarem o schema
+        # @raise [FocusNfe::Errors::HttpError] em respostas não-2xx
+        def previa(dados:, validar: false)
+          validar_dados!(dados) if validar
+
+          connection.post(caminho_base_previa, body: dados).raw_body
+        end
+      end
+    end
+  end
+end

data/lib/focus_nfe/recursos/cte.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Recurso de Conhecimento de Transporte eletrônico (CT-e). Emissão
+    # assíncrona (síncrona opcional) com consulta de estado, cancelamento e
+    # Carta de Correção Eletrônica (CC-e) por campo.
+    class Cte < Base
+      include Concerns::Emitivel
+      include Concerns::Consultavel
+      include Concerns::Cancelavel
+      include Concerns::CorrigivelCte
+      include Concerns::Notificavel
+
+      caminho_base "cte"
+
+      # @return [Hash{String=>Hash{String=>String}}] código do modal => chave do payload => nome do sub-esquema
+      MODAIS = {
+        "01" => { "modal_rodoviario" => "cte_transporte_rodoviario" },
+        "02" => { "modal_aereo" => "cte_transporte_aereo" },
+        "03" => { "modal_aquaviario" => "cte_transporte_aquaviario" },
+        "04" => { "modal_ferroviario" => "cte_transporte_ferroviario" },
+        "05" => { "modal_dutoviario" => "cte_transporte_dutoviario" },
+        "06" => { "modal_multimodal" => "cte_transporte_multimodal" }
+      }.freeze
+
+      private
+
+      # @see FocusNfe::Recursos::Base#esquemas_extras
+      def esquemas_extras(dados)
+        MODAIS.fetch(dados["modal"], {})
+      end
+    end
+  end
+end

data/lib/focus_nfe/recursos/cte_os.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Recurso de CT-e Outros Serviços (CT-e OS). Emissão síncrona com consulta
+    # de estado e cancelamento.
+    class CteOs < Base
+      include Concerns::Emitivel
+      include Concerns::Consultavel
+      include Concerns::Cancelavel
+      include Concerns::CorrigivelCte
+      include Concerns::Notificavel
+
+      caminho_base "cte_os"
+
+      # @return [Hash{String=>Hash{String=>String}}] código do modal => chave do payload => nome do sub-esquema
+      MODAIS = {
+        "01" => { "modal_rodoviario" => "cte_os_transporte_rodoviario" }
+      }.freeze
+
+      private
+
+      # @see FocusNfe::Recursos::Base#esquemas_extras
+      def esquemas_extras(dados)
+        MODAIS.fetch(dados["modal"], {})
+      end
+    end
+  end
+end

data/lib/focus_nfe/recursos/ctes_recebidas.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Conhecimentos de transporte (CT-e) recebidos contra um CNPJ. Listagem com
+    # sincronização incremental, consulta por chave, downloads e prestação de
+    # desacordo de serviço.
+    class CtesRecebidas < Base
+      include Concerns::Listavel
+      include Concerns::Baixavel
+      include Concerns::BaixavelEventos
+      include Concerns::Notificavel
+
+      caminho_base "ctes_recebidas"
+
+      # @param chave [String] chave de acesso do CT-e
+      # @return [Hash] corpo cru da resposta
+      def consultar(chave)
+        connection.get(caminho_referencia(chave)).body
+      end
+
+      # Registra a prestação de desacordo do serviço de transporte.
+      #
+      # @param chave [String] chave de acesso do CT-e
+      # @param observacoes [String] motivo do desacordo (15 a 255 caracteres)
+      # @return [Hash] corpo cru da resposta
+      def desacordo(chave, observacoes:)
+        connection.post("#{caminho_referencia(chave)}/desacordo", body: { observacoes: observacoes }).body
+      end
+
+      # @param chave [String] chave de acesso do CT-e
+      # @return [Hash] corpo cru da resposta com o desacordo registrado
+      def consultar_desacordo(chave)
+        connection.get("#{caminho_referencia(chave)}/desacordo").body
+      end
+    end
+  end
+end

data/lib/focus_nfe/recursos/dce.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Recurso de Declaração de Conteúdo eletrônica (DC-e). Emissão assíncrona
+    # com consulta de estado e cancelamento.
+    class Dce < Base
+      include Concerns::Emitivel
+      include Concerns::Consultavel
+      include Concerns::Cancelavel
+      include Concerns::Notificavel
+
+      caminho_base "dce"
+    end
+  end
+end

data/lib/focus_nfe/recursos/emails_bloqueados.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Gestão de e-mails bloqueados (bounces/reclamações). O caminho da API é
+    # +blocked_emails+; o e-mail compõe o path e é escapado.
+    class EmailsBloqueados < Base
+      caminho_base "blocked_emails"
+
+      # @param email [String] e-mail a consultar
+      # @return [Hash] corpo cru da resposta com o motivo do bloqueio
+      def consultar(email)
+        connection.get(caminho_email(email)).body
+      end
+
+      # Solicita o desbloqueio (exclusão) de um e-mail.
+      #
+      # @param email [String] e-mail a desbloquear
+      # @return [Hash] corpo cru da resposta
+      def desbloquear(email)
+        connection.delete(caminho_email(email)).body
+      end
+
+      private
+
+      def caminho_email(email)
+        "#{caminho_base}/#{URI.encode_www_form_component(email)}"
+      end
+    end
+  end
+end

data/lib/focus_nfe/recursos/empresas.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module FocusNfe
+  module Recursos
+    # Gestão de empresas (CRUD). Disponível apenas em produção na Focus NFe; o
+    # certificado vai em base64 nos dados. A simulação (+dry_run+) valida o cadastro
+    # sem persistir.
+    class Empresas < Base
+      include Concerns::Listavel
+      include Concerns::Localizavel
+      include Concerns::Removivel
+
+      caminho_base "empresas"
+
+      # Cadastra uma empresa.
+      #
+      # @param dados [Hash] dados da empresa (certificado PFX em base64 quando aplicável)
+      # @param dry_run [Boolean] quando +true+, valida sem persistir (+dry_run=1+)
+      # @return [Hash] corpo cru da resposta
+      def criar(dados:, dry_run: false)
+        params = dry_run ? { dry_run: 1 } : {}
+        connection.post(caminho_base, params: params, body: dados).body
+      end
+
+      # Atualiza uma empresa existente.
+      #
+      # @param id [String, Integer] identificador da empresa
+      # @param dados [Hash] campos a atualizar
+      # @return [Hash] corpo cru da resposta
+      def atualizar(id, dados:)
+        connection.put(caminho_referencia(id), body: dados).body
+      end
+    end
+  end
+end