Brval

This is a gem to validate many Brazilian codes. Because it's common to use many gems, libs and even copy and paste methods found around the internet to do that.

So the idea of Brval gem is: reunite all those validations methods in one single gem, making our lives even "easier" to develop Ruby apps.

Link para ler as instruções em português (link to read the instructions in portuguese)

NPM package for JS projects coming soon!

Add this line to your Gemfile

gem 'brval'

Or run it direct on terminal:

$ gem install brval

To use Brval gem is quite simple, just call the module Brval with the validation you wish. Examples:

# CPF valid
Brval.cpf_valid?('79411449050') # => true

# CPF invalid
Brval.cpf_valid?('79411400000') # => false

# CNH valid
Brval.cnh_valid?('30142868570') # => true

# Título de eleitor valid
Brval.te_valid?('264632480167') # => true

# Cep valid
Brval.cep_valid?('70297-400') # => true

Above is the list with all the functions and validations avaible on Brval gem.

Brazilian postal code, CEP, doesn't has any formula or calculation to check if some CEP is valid or not, the only way to know that is searching in a database with all CEP's in Brazil

Apparently Correios doesn't provides any database with all CEP's of Brazil, so some devs developer their own services to search for a CEP info, some of those services are public API's and anyone can use it.

Considering this, Brval does the CEP validation following this flow:

• Brval.cep_valid?('00000000')
• The gem does a first query at Via Cep API
• If the CEP is not found, the gem does a second query at WideNet API
• If again, the CEP is not found the gem does third query to search the CEP at Postmon API
• And finally, if the CEP is not found in any of these three API's the gem Brval will say that this CEP doesn't exists.

The gem uses the same procedure to get the info of some CEP with the function: Brval.cep_info(00000000)

OBS: the gem "only" search in three API's, if a CEP exists but any of these API's doesn't have it, the gem will return a false negative.

If you miss any validation, create an Issue explaining about it, if possible, leave some links with the calculation or any formula example about the validation. I will be happy trying to implement that to help you.

If you want to contribute with some code create an issue so we can discuss about, if everyone agree with your idea, create a fork, create your branch and send your pull request explaining the details about your PR.

Don't forget the tests, Brval use Rspec to test. Update the README with the new info. Also, try to follow the gem pattern to implement your contribution.

You can run the gem with: rake console

And before send your PR make a simulation installing the gem locally with your changes, just run the ./build.sh script.

chmod +x build.sh
./build.sh

Thanks!

The gem is available as open source under the terms of the MIT License.