module CorreiosToolkit

This module's static methods are the entry point for using CorreiosToolkit.

This class concentrate the basic information to retrieve data from the web service. This class is intended to be inherited by all other classes.

This class is intended to get the full address information for a given zip code. In order to do that, this class receives the zip code value with its 8 digits, normalizes it by removing dots, hyphens and the like, then, requests the information about it from the brazilian post office (Correios) and returns a hash with the corresponding information.

Constants

VERSION

Public Class Methods

consulta_cep(cep) click to toggle source

Get address' information by zip code

Example:

# Valid zip code (without dots, hyphens and the like)
>> CorreiosToolkit.consulta_cep('01310000')
=> { "bairro"=>"Bela Vista", "cep"=>"01310000", "cidade"=>"São Paulo", "complemento2"=>"- até 610 - lado par", "end"=>"Avenida Paulista", "uf"=>"SP" }

# Valid zip code (with dots, hyphens and the like)
>> CorreiosToolkit.consulta_cep('01310-000')
=> { "bairro"=>"Bela Vista", "cep"=>"01310000", "cidade"=>"São Paulo", "complemento2"=>"- até 610 - lado par", "end"=>"Avenida Paulista", "uf"=>"SP" }

# Invalid zip code (less/more than 8 numbers)
>> CorreiosToolkit.consulta_cep('01310000000')
=> CorreiosToolkit::Base::LengthError (Wrong CEP format, expected CEP to have 8 numbers but 11 was found.)

# Invalid zip code (nonexistent zip code - zip code not found)
>> CorreiosToolkit.consulta_cep('01310005')
=> CorreiosToolkit::Base::GatewayError (CEP NAO ENCONTRADO)

Param:

<tt>:cep</tt> [String] - The zip code to verify, it must have 8 number

Return:

# Hash object with indifferent access attributes
# => Hash attributes:
# <tt>:bairro</tt>       - The neighborhood name
# <tt>:cep</tt>          - The requested zip code
# <tt>:cidade</tt>       - The city name
# <tt>:complemento2</tt> - The complement when available
# <tt>:end</tt>          - The street name
# <tt>:uf</tt>           - The state abbreviation

# File lib/correios_toolkit.rb, line 40
def self.consulta_cep(cep)
  CorreiosToolkit::ConsultaCep.request_data_for(cep: cep)
end