Module: Nfe::IdValidator

Defined in:
lib/nfe/id_validator.rb,
sig/nfe/id_validator.rbs

Overview

Client-side validators for identifiers and document numbers. Each method runs before any HTTP request is issued (fail-fast) and raises InvalidRequestError with a Portuguese-language message naming the offending argument.

Normalizing validators (+access_key+, cnpj, cpf, cep, state) return a normalized String; CNPJ/CPF/CEP are NEVER coerced to Integer, so future alphanumeric CNPJ (v3) input is preserved.

Constant Summary collapse

UF =

The 27 Brazilian UFs plus EX (foreign) and NA (not applicable).

Returns:

  • (Array[String]) 
%w[
  AC AL AP AM BA CE DF ES GO MA MT MS MG PA PB PR PE PI RJ RN RS RO RR SC SP SE TO
  EX NA
].freeze

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.access_key(value) ⇒ String

Strips non-digits, validates the 44-digit length, returns the normalized digits-only string.

Returns:

  • (String) 


45
46
47
48
49
50
51
52
 
# File 'lib/nfe/id_validator.rb', line 45

def access_key(value)
  digits = digits_only(value)
  unless /\A\d{44}\z/.match?(digits)
    raise Nfe::InvalidRequestError, "chave de acesso (access_key) deve conter 44 dígitos"
  end

  digits
end

.cep(value) ⇒ String

Returns the 8-digit CEP.

Returns:

  • (String) —

    the 8-digit CEP.

Raises:



74
75
76
77
78
79
 
# File 'lib/nfe/id_validator.rb', line 74

def cep(value)
  digits = digits_only(value)
  raise Nfe::InvalidRequestError, "CEP (cep) deve conter 8 dígitos" unless digits.length == 8

  digits
end

.cnpj(value) ⇒ String

Normalizes to 14 digits without coercing to Integer (preserves future alphanumeric CNPJ v3).

Returns:

  • (String)

Raises:



58
59
60
61
62
63
 
# File 'lib/nfe/id_validator.rb', line 58

def cnpj(value)
  normalized = strip_separators(value)
  raise Nfe::InvalidRequestError, "CNPJ (cnpj) deve conter 14 caracteres" unless normalized.length == 14

  normalized
end

.company_id(value) ⇒ String

Returns the non-empty company id.

Returns:

  • (String) —

    the non-empty company id.



22
23
24
 
# File 'lib/nfe/id_validator.rb', line 22

def company_id(value)
  presence!(value, "company_id")
end

.cpf(value) ⇒ String

Returns the 11-digit CPF.

Returns:

  • (String) —

    the 11-digit CPF.

Raises:



66
67
68
69
70
71
 
# File 'lib/nfe/id_validator.rb', line 66

def cpf(value)
  digits = digits_only(value)
  raise Nfe::InvalidRequestError, "CPF (cpf) deve conter 11 dígitos" unless digits.length == 11

  digits
end

.digits_only(value) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



98
99
100
 
# File 'lib/nfe/id_validator.rb', line 98

def digits_only(value)
  value.to_s.gsub(/\D/, "")
end

.event_key(value) ⇒ String

Returns the non-empty event key.

Returns:

  • (String) —

    the non-empty event key.



37
38
39
 
# File 'lib/nfe/id_validator.rb', line 37

def event_key(value)
  presence!(value, "event_key")
end

.invoice_id(value) ⇒ String

Returns the non-empty invoice id.

Returns:

  • (String) —

    the non-empty invoice id.



27
28
29
 
# File 'lib/nfe/id_validator.rb', line 27

def invoice_id(value)
  presence!(value, "invoice_id")
end

.presence!(value, name) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Raises:



90
91
92
93
94
95
 
# File 'lib/nfe/id_validator.rb', line 90

def presence!(value, name)
  string = value.to_s
  raise Nfe::InvalidRequestError, "#{name} não pode ser vazio" if string.strip.empty?

  value
end

.state(value) ⇒ String

Returns the validated, uppercased UF.

Returns:

  • (String) —

    the validated, uppercased UF.

Raises:



82
83
84
85
86
87
 
# File 'lib/nfe/id_validator.rb', line 82

def state(value)
  normalized = value.to_s.strip.upcase
  raise Nfe::InvalidRequestError, "estado (state) inválido: #{value.inspect}" unless UF.include?(normalized)

  normalized
end

.state_tax_id(value) ⇒ String

Returns the non-empty state-tax id.

Returns:

  • (String) —

    the non-empty state-tax id.



32
33
34
 
# File 'lib/nfe/id_validator.rb', line 32

def state_tax_id(value)
  presence!(value, "state_tax_id")
end

.strip_separators(value) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



103
104
105
 
# File 'lib/nfe/id_validator.rb', line 103

def strip_separators(value)
  value.to_s.gsub(/[^0-9A-Za-z]/, "")
end

Instance Method Details

#self?.access_key ⇒ String

Parameters:

  • value (Object)

Returns:

  • (String) 


9
 
# File 'sig/nfe/id_validator.rbs', line 9

def self?.access_key: (untyped value) -> String

#self?.cep ⇒ String

Parameters:

  • value (Object)

Returns:

  • (String) 


12
 
# File 'sig/nfe/id_validator.rbs', line 12

def self?.cep: (untyped value) -> String

#self?.cnpj ⇒ String

Parameters:

  • value (Object)

Returns:

  • (String) 


10
 
# File 'sig/nfe/id_validator.rbs', line 10

def self?.cnpj: (untyped value) -> String

#self?.company_id ⇒ Object

Parameters:

  • value (Object)

Returns:

  • (Object) 


5
 
# File 'sig/nfe/id_validator.rbs', line 5

def self?.company_id: (untyped value) -> untyped

#self?.cpf ⇒ String

Parameters:

  • value (Object)

Returns:

  • (String) 


11
 
# File 'sig/nfe/id_validator.rbs', line 11

def self?.cpf: (untyped value) -> String

#self?.digits_only ⇒ String

Parameters:

  • value (Object)

Returns:

  • (String) 


15
 
# File 'sig/nfe/id_validator.rbs', line 15

def self?.digits_only: (untyped value) -> String

#self?.event_key ⇒ Object

Parameters:

  • value (Object)

Returns:

  • (Object) 


8
 
# File 'sig/nfe/id_validator.rbs', line 8

def self?.event_key: (untyped value) -> untyped

#self?.invoice_id ⇒ Object

Parameters:

  • value (Object)

Returns:

  • (Object) 


6
 
# File 'sig/nfe/id_validator.rbs', line 6

def self?.invoice_id: (untyped value) -> untyped

#self?.presence! ⇒ Object

Parameters:

  • value (Object)
  • name (String)

Returns:

  • (Object) 


14
 
# File 'sig/nfe/id_validator.rbs', line 14

def self?.presence!: (untyped value, String name) -> untyped

#self?.state ⇒ String

Parameters:

  • value (Object)

Returns:

  • (String) 


13
 
# File 'sig/nfe/id_validator.rbs', line 13

def self?.state: (untyped value) -> String

#self?.state_tax_id ⇒ Object

Parameters:

  • value (Object)

Returns:

  • (Object) 


7
 
# File 'sig/nfe/id_validator.rbs', line 7

def self?.state_tax_id: (untyped value) -> untyped

#self?.strip_separators ⇒ String

Parameters:

  • value (Object)

Returns:

  • (String) 


16
 
# File 'sig/nfe/id_validator.rbs', line 16

def self?.strip_separators: (untyped value) -> String