enel-ruby-sdk 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eab8ca3e3db55b2a8e37d6f16bdb0ddd5de50fc5df3cdebed3d5e50247544c7b
+  data.tar.gz: 3d8bde302a73e43bcc9d91a45c47306160b59136f6fb1f352a6ab56c6ce7b32b
+SHA512:
+  metadata.gz: 3d1780c7bbe75da24c66168e6f2eea77ed714ab85e724b6702bf24773795ecb3d1787ad6fed3b01fbece03e893152b9d00b70ec5a0e80c015bd8d04167c56844
+  data.tar.gz: 878bb7c511258e5aed6729fda3cc2c5c0c2d8ee3fb50f8df300a509615936e4192cfc6ce18cf85ad81b4d55a5d37ad6846cb8a64c6500e4af2a96d951984460f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danilo Josino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,128 @@
+# enel-ruby-sdk
+
+SDK Ruby não oficial para a API da Enel X (X-Customer, TPB). Sem dependências de runtime
+além da stdlib do Ruby. Requer Ruby 3.3 ou mais novo.
+
+Cobre os 10 endpoints do PDF `docs/enel_PTBR_v5.0.pdf` (X-Customer, TPB): Consulta Cliente,
+venda, alteração de valores, cancelamento e as cinco consultas de histórico.
+
+## Instalação
+
+Repositório privado, sem publicação no RubyGems por padrão: use a tag git no `Gemfile`.
+
+```ruby
+gem 'enel-ruby-sdk', require: 'enel_x', git: 'https://github.com/djosino/enel-ruby-sdk', tag: 'vX.Y.Z'
+```
+
+Troque `vX.Y.Z` pela [versão mais recente](https://github.com/djosino/enel-ruby-sdk/releases)
+e rode `bundle install`.
+
+## Configuração
+
+A autenticação é OAuth2 `client_credentials`: a Enel X fornece `client_id` e `client_secret`
+do parceiro, mais o valor de `ClientSystem`. Mantenha-os fora do código, em variáveis de
+ambiente ou no gerenciador de segredos do app. O PDF não traz o host: ele é configuração.
+
+```ruby
+require 'enel_x'
+
+client = EnelX::Client.new(
+  host: ENV.fetch('ENEL_HOST'),
+  client_id: ENV.fetch('ENEL_CLIENT_ID'),
+  client_secret: ENV.fetch('ENEL_CLIENT_SECRET'),
+  client_system: 'BRA-MEUPARCEIRO',
+  partner_code: 'PARC01',          # usado como empresaParc nas consultas
+  # cache: Rails.cache,            # opcional: read/write/delete; padrão em memória
+  # on_request: ->(entry) { ... }, # opcional: chamada já filtrada de segredos e PII
+)
+```
+
+Há um cliente por ambiente e nenhum estado global. O cliente não repete chamadas: a política
+de repetição é do app, guiada por `error.kind` (veja [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md)).
+
+## Exemplos
+
+Os campos usam os nomes do PDF, como Hash ou como argumentos nomeados. Toda validação roda
+antes da rede e levanta `EnelX::ValidationError` com `field` e `limit`.
+
+### Consulta Cliente (§5.2)
+
+```ruby
+contracts = client.contract(
+  legal_entity: 'EXBRA_SA_Fortaleza_CE', identity_number: '123.456.789-09', pos: '0001',
+)
+contract = contracts.first
+contract.customer_active?   # => true
+contract.customer_supplies? # => true
+```
+
+`EnelX::UcNotFound` indica cliente inexistente. A decisão de cobrar ou não é do app.
+
+### Venda (§5.3)
+
+```ruby
+result = client.order_sale(
+  'Nome' => 'John', 'Sobrenome' => 'Doe', 'Telefone' => '21987654321', 'Email' => '',
+  'Endereco' => 'Av Lucio Costa', 'EnderecoNumero' => '0123', 'Bairro' => 'Barra da Tijuca',
+  'Cidade' => 'Rio de Janeiro', 'CEP' => '22630-011', 'empresa' => '2005',
+  'numeroCliente' => '123456', 'CPF' => '12345678909', 'numParcelas' => 10,
+  'valorParcela' => BigDecimal('32.23'), 'codProduto' => '12342005',
+  'dataOcorrencia' => Date.today, 'numeroClienteEmpPar' => 'MD2026ABC',
+  'anexos' => [{ type: 'Termo de Adesão', filename: 'termo.pdf', bytes: File.binread('termo.pdf') }],
+  context: { subscription_id: 7 },
+)
+result.transaction_id
+```
+
+Sucesso significa só "recebido": a cobrança se confirma nas ocorrências 996 e 998. `Cidade`
+precisa ser o nome exato do IBGE e o SDK não consegue conferir. Para empresa, acrescente
+`'CNPJ'` e `'NomeEmpresa'`.
+
+### Alteração de valores (§5.4) e cancelamento (§5.5)
+
+```ruby
+client.order_change('Nome' => 'ALVARO', 'Sobrenome' => 'GOMES', 'empresa' => '2003',
+                    'numeroCliente' => '7331365', 'numParcelas' => 4, 'valorParcela' => '32.23',
+                    'codProduto' => '57062003', 'dataOcorrencia' => Date.today,
+                    'Endereco' => 'Rua A', 'EnderecoNumero' => '1', 'Bairro' => 'Centro',
+                    'Cidade' => 'Fortaleza', 'CEP' => '60000-000') # codOcorr padrão: "61"
+
+client.order_disconnect('Nome' => 'John', 'Sobrenome' => 'Doe', 'empresa' => '2005',
+                        'numeroCliente' => '000', 'valorParcela' => 0, 'codProduto' => '12',
+                        'codOcorr' => '26', 'dataOcorrencia' => Date.today,
+                        'Endereco' => 'Rua A', 'EnderecoNumero' => '20', 'Bairro' => 'Centro',
+                        'Cidade' => 'Rio de Janeiro', 'CEP' => '00000-000')
+```
+
+### Consultas de histórico (§5.6 a §5.10)
+
+A API não tem webhook: estas consultas são a única forma de saber o que houve com a venda.
+`dataOcorrencia` aceita `Date`, `Time` ou `YYYY-MM-DD`.
+
+```ruby
+client.subscription_history('empresa' => '2005', 'numeroCliente' => '123456', 'codProduto' => '12342005')
+client.subscription_history('empresa' => '2005', 'dataOcorrencia' => '2026-09-16', 'operacao' => 'C')
+
+item = client.request_history('empresa' => '2005', 'numeroCliente' => '123456').first
+item.occurrence.description # => "Cobrança Incluída para o Cliente"
+item.occurrence.ok?         # => true
+item.numeroclienteemppar    # chave de correlação com a venda
+
+client.invoice_history('empresa' => '2005', 'numeroCliente' => '123456').first.document_state # => :paid
+client.collections('empresa' => '2005', 'dataOcorrencia' => Date.today)
+client.movements('empresa' => '2005', 'numeroCliente' => '123456', 'codProduto' => '12342005')
+```
+
+Datas e números voltam como a API enviou; `null` e texto vazio viram `nil`.
+
+### Dados de referência
+
+`EnelX::Distributor`, `EnelX::Occurrence` (tabela 7.2, com `stage`), `EnelX::Reference::PartnerCode`
+(tabela 7.1) e `EnelX::DocumentState` (tabela 7.4).
+
+## Documentação
+
+- [Índice da documentação](docs/README.md)
+- [Contribuir](CONTRIBUTING.md) e [Segurança](SECURITY.md)
+- [Changelog](CHANGELOG.md)
+- Fonte única da API: [`docs/enel_PTBR_v5.0.pdf`](docs/enel_PTBR_v5.0.pdf)

data/REVISION

@@ -0,0 +1 @@
+0.1.2

data/lib/enel_x/attachment.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+require_relative 'validators'
+
+module EnelX
+  # Sale attachment (PDF 5.3.2 ANEXO). Pass either `content_base64:` (already encoded)
+  # or `bytes:` (raw, encoded here without line breaks).
+  class Attachment
+    TYPES = ['Documento', 'Termo de Adesão', 'Audio', 'Outros'].freeze
+    ADHESION = 'Termo de Adesão'
+    # [ASSUMPTION p.16] "8.5Mb" read as 8.5 MiB of decoded content.
+    MAX_BYTES = (8.5 * 1024 * 1024).to_i
+
+    attr_reader :type, :filename, :extension, :content_base64
+
+    def initialize(type:, filename:, content_base64: nil, bytes: nil, extension: nil)
+      @type = Validators.one_of('tipoAnexo', type, TYPES)
+      @filename = Validators.text('nomeArquivo', filename, max: 255)
+      @extension = check_extension(extension)
+      @content_base64 = check_content(content_base64, bytes)
+    end
+
+    def adhesion? = type == ADHESION
+
+    def to_h
+      {
+        'tipoAnexo' => type, 'conteudoBase64' => content_base64,
+        'nomeArquivo' => filename, 'extensao' => extension
+      }
+    end
+
+    PDF_KEYS = {
+      'tipoAnexo' => :type, 'nomeArquivo' => :filename,
+      'conteudoBase64' => :content_base64, 'extensao' => :extension
+    }.freeze
+
+    # Accepts an Attachment or a Hash named after #initialize or after the PDF keys.
+    def self.coerce(value)
+      return value if value.is_a?(self)
+
+      new(**value.to_h.transform_keys { |key| PDF_KEYS.fetch(key.to_s) { key.to_sym } })
+    end
+
+    private
+
+    def check_extension(given)
+      from_name = File.extname(filename).delete_prefix('.').downcase
+      Validators.invalid('nomeArquivo', 'must include the file extension', filename) if
+        from_name.empty?
+
+      given = given.nil? ? from_name : given.to_s.delete_prefix('.').downcase
+      unless given == from_name
+        Validators.invalid('extensao', "must match the file name (#{from_name})",
+          given)
+      end
+      given
+    end
+
+    def check_content(encoded, bytes)
+      if encoded.nil? == bytes.nil?
+        Validators.invalid('conteudoBase64',
+          'pass exactly one of content_base64 or bytes')
+      end
+      return check_size(encoded, strict_decode(encoded)) if encoded
+
+      check_size([bytes].pack('m0'), bytes.b)
+    end
+
+    def strict_decode(encoded)
+      encoded.to_s.unpack1('m0')
+    rescue ArgumentError
+      Validators.invalid('conteudoBase64', 'strict Base64 without line breaks')
+    end
+
+    def check_size(encoded, decoded)
+      Validators.invalid('conteudoBase64', 'file is empty') if decoded.empty?
+      if decoded.bytesize > MAX_BYTES
+        Validators.invalid('conteudoBase64', 'at most 8.5 MB after decoding')
+      end
+      encoded
+    end
+  end
+end

data/lib/enel_x/client.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+
+require_relative 'configuration'
+require_relative 'endpoint'
+require_relative 'endpoints/contract'
+require_relative 'filter'
+require_relative 'headers'
+require_relative 'http'
+require_relative 'endpoints/history'
+require_relative 'endpoints/order_change'
+require_relative 'endpoints/order_disconnect'
+require_relative 'endpoints/order_sale'
+require_relative 'response_parser'
+require_relative 'result'
+require_relative 'token_provider'
+
+module EnelX
+  # One client per environment; there is no global state to share between them.
+  class Client
+    attr_reader :configuration
+
+    def initialize(**)
+      @configuration = Configuration.new(**)
+      @http = Http.new(open_timeout: configuration.open_timeout,
+        read_timeout: configuration.read_timeout)
+      @tokens = TokenProvider.new(configuration, @http)
+    end
+
+    # Consulta Cliente (PDF 5.2); see EnelX::Endpoints::Contract#call.
+    def contract(**)
+      Endpoints::Contract.new(self).call(**)
+    end
+
+    # Venda (PDF 5.3), Alteração de Valores (5.4) and Cancelamento (5.5). Fields use the
+    # names of the PDF. A success only means "received"; see EnelX::Result.
+    def order_sale(fields = nil, context: nil, **rest)
+      Endpoints::OrderSale.new(self).call(merge_fields(fields, rest), context:)
+    end
+
+    def order_change(fields = nil, context: nil, **rest)
+      Endpoints::OrderChange.new(self).call(merge_fields(fields, rest), context:)
+    end
+
+    def order_disconnect(fields = nil, context: nil, **rest)
+      Endpoints::OrderDisconnect.new(self).call(merge_fields(fields, rest), context:)
+    end
+
+    # History queries (PDF 5.6 to 5.10): subscription_history, request_history,
+    # invoice_history, collections and movements. Each returns an Array of records.
+    Endpoints::History::QUERIES.each_key do |name|
+      define_method(name) do |fields = nil, context: nil, **rest|
+        Endpoints::History.new(self, name).call(merge_fields(fields, rest), context:)
+      end
+    end
+
+    # Runs one business call and returns an EnelX::Result. Never retries on its own,
+    # except the single renewal after a 401. The on_request hook sees every outcome.
+    def request(endpoint, payload: nil, context: nil)
+      headers = build_headers(endpoint)
+      id = headers['TransactionID']
+      base = base_entry(endpoint, id, payload, context)
+      response = error = nil
+      begin
+        response = call(endpoint.verb, target(endpoint, payload),
+          headers:, body: body_for(endpoint, payload))
+        Result.build(ResponseParser.parse(response, transaction_id: id), id)
+      rescue Error => e
+        error = e
+        raise
+      ensure
+        notify(base, response, error)
+      end
+    end
+
+    # Sends an authenticated request. A 401 renews the token and retries exactly once.
+    def call(method, path, headers: {}, body: nil)
+      response = authorized(method, path, headers, body)
+      return response unless response.status == 401
+
+      @tokens.invalidate
+      response = authorized(method, path, headers, body)
+      return response unless response.status == 401
+
+      raise ConfigurationError, 'API rejected a freshly issued token (HTTP 401)'
+    end
+
+    private
+
+    # Fields may come as one Hash or as plain keywords/string keys: both work.
+    def merge_fields(fields, rest)
+      return rest if fields.nil?
+      return fields if rest.empty? || !fields.respond_to?(:to_h)
+
+      fields.to_h.merge(rest)
+    end
+
+    def authorized(method, path, headers, body)
+      @http.request(
+        method, "#{configuration.host}#{path}",
+        headers: headers.merge('Authorization' => "Bearer #{@tokens.token}"), body:
+      )
+    end
+
+    def build_headers(endpoint)
+      Headers.build(
+        operation: endpoint.operation, functionality: endpoint.functionality,
+        client_system: endpoint.client_system || configuration.client_system,
+        server_system: endpoint.server_system
+      )
+    end
+
+    def get?(endpoint)
+      endpoint.verb.to_s.casecmp?('get')
+    end
+
+    def body_for(endpoint, payload)
+      JSON.generate(payload) if payload && !get?(endpoint)
+    end
+
+    def target(endpoint, payload)
+      return endpoint.path unless get?(endpoint) && payload && !payload.empty?
+
+      "#{endpoint.path}?#{URI.encode_www_form(payload)}"
+    end
+
+    def notify(base, response, error)
+      hook = configuration.on_request
+      return unless hook
+
+      hook.call(base.merge(response_status: response&.status,
+        response_body: filtered_body(response),
+        error_message: error&.message))
+    rescue StandardError => e
+      configuration.logger.warn("EnelX on_request hook failed: #{e.class}")
+    end
+
+    def base_entry(endpoint, id, payload, context)
+      {
+        service: endpoint.service, endpoint: endpoint.path, method: endpoint.verb,
+        transaction_id: id, request_payload: Filter.apply(payload), context:
+      }
+    end
+
+    def filtered_body(response)
+      return unless response
+
+      Filter.apply(JSON.parse(response.body.to_s))
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/enel_x/configuration.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+require_relative 'memory_cache'
+
+module EnelX
+  # Default logger. Logger is a bundled gem since Ruby 4.0: the SDK does not require it.
+  class NullLogger
+    def warn(*); end
+  end
+
+  class Configuration
+    REQUIRED = %i[host client_id client_secret].freeze
+    CACHE_METHODS = %i[read write delete].freeze
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_READ_TIMEOUT = 30
+
+    attr_reader :host, :client_id, :client_secret, :client_system, :partner_code,
+      :cache, :logger, :on_request, :open_timeout, :read_timeout
+
+    # rubocop:disable-next Metrics/ParameterLists
+    def initialize(host: nil, client_id: nil, client_secret: nil, client_system: nil,
+      partner_code: nil, cache: nil, logger: nil, on_request: nil,
+      open_timeout: DEFAULT_OPEN_TIMEOUT,
+      read_timeout: DEFAULT_READ_TIMEOUT)
+      @host = normalize_host(host)
+      @client_id = client_id.to_s
+      @client_secret = client_secret.to_s
+      @client_system = client_system
+      @partner_code = partner_code
+      @cache = cache || MemoryCache.new
+      @logger = logger || NullLogger.new
+      @on_request = on_request
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      validate!
+    end
+
+    # Never prints the secret: configurations end up in logs and error reports.
+    def inspect
+      "#<#{self.class.name} host=#{host.inspect} client_id=#{client_id.inspect}>"
+    end
+
+    private
+
+    def normalize_host(value)
+      text = value.to_s.strip
+      return text if text.empty?
+
+      text = "https://#{text}" unless text.match?(%r{\A[a-z][a-z0-9+.-]*://}i)
+      text.sub(%r{/+\z}, '')
+    end
+
+    def validate!
+      missing = REQUIRED.select { |name| public_send(name).empty? }
+      unless missing.empty?
+        raise ConfigurationError, "missing configuration: #{missing.join(', ')}"
+      end
+
+      return if CACHE_METHODS.all? { |name| cache.respond_to?(name) }
+
+      raise ConfigurationError, 'cache must respond to read, write and delete'
+    end
+  end
+end

data/lib/enel_x/contract.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative 'response_parser'
+
+module EnelX
+  # One entry of the Consulta Cliente answer (PDF 5.2.3). Read-only: whether the
+  # customer may be billed is a business decision that belongs to the consumer.
+  Contract = Data.define(
+    :address_data, :customer_name, :customer_identity_number, :customer_active,
+    :customer_supplies, :customer_bad_payer, :billing_address, :activation_date,
+    :deactivation_date, :business_partner_installation, :unpaid_invoices, :days_unpaid,
+    :invoice_installment, :nova_uc
+  )
+
+  class Contract
+    ATTRIBUTES = {
+      address_data: 'AddressData', customer_name: 'CommodityCustomerName',
+      customer_identity_number: 'CommodityIdentityNumber',
+      billing_address: 'ContractBillingAddress',
+      activation_date: 'ContractActivationDate',
+      deactivation_date: 'ContractDesactivationDate',
+      business_partner_installation: 'BusinessPartnerInstallation',
+      unpaid_invoices: 'NumberOfUnpaidInvoices', days_unpaid: 'NumberOfDaysUnpaid',
+      nova_uc: 'NovaUC'
+    }.freeze
+    INDICATORS = {
+      customer_active: 'IsCommodityCustomerActive',
+      customer_supplies: 'HasCommodityCustomerSupplies',
+      customer_bad_payer: 'IsCommodityCustomerBadPayer',
+      invoice_installment: 'HasInvoiceInstallment',
+    }.freeze
+
+    # Accepts "Contract" (any case) as an array or as a single object.
+    def self.list_from(body)
+      items = ResponseParser.fetch_ci(body, 'contract')
+      wrap(items).map { |item| from_hash(item) }
+    end
+
+    def self.wrap(items)
+      case items
+      when Array then items
+      when Hash then [items]
+      else []
+      end
+    end
+
+    def self.from_hash(hash)
+      texts = ATTRIBUTES.transform_values do |name|
+        text(ResponseParser.fetch_ci(hash, name))
+      end
+      flags = INDICATORS.transform_values do |name|
+        flag(ResponseParser.fetch_ci(hash, name))
+      end
+      new(**texts, **flags)
+    end
+
+    def self.text(value)
+      value.nil? || value.to_s.strip.empty? ? nil : value.to_s
+    end
+
+    def self.flag(value)
+      case value.to_s.strip.downcase
+      when 'true' then true
+      when 'false' then false
+      end
+    end
+
+    def customer_active? = customer_active
+    def customer_supplies? = customer_supplies
+    def customer_bad_payer? = customer_bad_payer
+    def invoice_installment? = invoice_installment
+  end
+end

data/lib/enel_x/endpoint.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module EnelX
+  # One row of the endpoint table (PDF 5.1): path, verb and the per-endpoint headers.
+  # A nil client_system means "use the one configured on the client".
+  Endpoint = Struct.new(
+    :service, :verb, :path, :operation, :functionality, :client_system, :server_system,
+    keyword_init: true
+  )
+end

data/lib/enel_x/endpoints/contract.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative '../contract'
+require_relative '../endpoint'
+require_relative '../errors'
+require_relative '../validators'
+
+module EnelX
+  module Endpoints
+    # Consulta Cliente (PDF 5.2): situation of the customer and supply at the distributor.
+    class Contract
+      # [ASSUMPTION p.12] table 5.1 and 5.2.2 disagree on ClientSystem; the specific
+      # section wins. This query has its own header values, not the configured ones.
+      ENDPOINT = Endpoint.new(
+        service: :contract, verb: :get, path: '/services/v1/contract',
+        operation: 'Read', functionality: 'getContract',
+        client_system: 'XCustomerB2CBR', server_system: 'CommodityBrazil'
+      )
+      LEGAL_ENTITIES = %w[
+        EXBRA_SA_Fortaleza_CE EXBRA_SA_Paulo_SP EXBRA_SA_Rio_de_Janeiro_RJ
+      ].freeze
+      IDENTITY_TYPES = %w[CPF CNPJ].freeze
+      CNPJ_DIGITS = 14
+
+      def initialize(client)
+        @client = client
+      end
+
+      # Returns an Array of EnelX::Contract. Raises EnelX::UcNotFound for an unknown UC.
+      def call(legal_entity:, identity_number: nil, pos: nil, identity_type: nil,
+        context: nil)
+        params = build_params(legal_entity, identity_number, pos, identity_type)
+        result = @client.request(ENDPOINT, payload: params, context:)
+        EnelX::Contract.list_from(result.body)
+      end
+
+      private
+
+      def build_params(legal_entity, identity_number, pos, identity_type)
+        number = digits(identity_number)
+        pos = pos.to_s.strip
+        type = identity_type(identity_type, number)
+        check_legal_entity(legal_entity)
+        check_identifiers(number, pos)
+
+        {
+          'IdentityType' => type, 'IdentityNumber' => number,
+          'POS' => (pos unless pos.empty?), 'LegalEntity' => legal_entity
+        }.compact
+      end
+
+      def digits(value)
+        return if value.nil? || value.to_s.strip.empty?
+
+        value.to_s.gsub(/\D/, '').tap do |number|
+          fail_field('IdentityNumber', value, 'digits only') if number.empty?
+        end
+      end
+
+      def identity_type(value, number)
+        type = value&.to_s&.upcase
+        if type && !IDENTITY_TYPES.include?(type)
+          fail_field('IdentityType', value, IDENTITY_TYPES.join(' or '))
+        end
+        if number&.length == CNPJ_DIGITS && type != 'CNPJ'
+          fail_field('IdentityType', value, 'CNPJ is required for a 14-digit document')
+        end
+        type
+      end
+
+      def check_legal_entity(value)
+        return if LEGAL_ENTITIES.include?(value)
+
+        fail_field('LegalEntity', value, LEGAL_ENTITIES.join(', '))
+      end
+
+      def check_identifiers(number, pos)
+        return if number || !pos.empty?
+
+        fail_field('IdentityNumber', nil, 'IdentityNumber or POS is required')
+      end
+
+      def fail_field(field, value, limit)
+        Validators.invalid(field, limit, value)
+      end
+    end
+  end
+end