correios-cep - Gem para consulta de endereços por CEP

As soluções atuais disponíveis para consulta de endereços por CEP utilizam um formulário HTML existente no site dos Correios para realizar essa consulta, e não uma API verdadeira dos Correios.

Isso é feito com uma requisição HTTP para o formulário, seguida de um parser da página HTML de resultado. O grande problema aqui é que se o pessoal dos Correios decidir alterar algum elemento HTML nessa página de resultado, até mesmo uma mudança de layout, irá quebrar a lógica de parser do resultado da consulta.

A gem correios-cep resolve esse problema, fazendo a consulta direta na base de endereços dos Correios, sem fazer parser de HTML.


Instalando

Gemfile:
gem 'correios-cep'

Instalação direta:
$ gem install correios-cep

Usando

require 'correios-cep'

# Com o método de instância "get"
finder = Correios::CEP::AddressFinder.new
address = finder.get "54250610"

# Com o método de class "get"
address = Correios::CEP::AddressFinder.get "54250610"

address # =>
{
  :address => "Rua Fernando Amorim",
  :neighborhood => "Cavaleiro",
  :city => "Jaboatão dos Guararapes",
  :state => "PE",
  :zipcode => "54250610",
  :complement => ""
}

Configurações

Timeout

Por padrão, o tempo de espera de resposta (timeout) para o serviços Web dos Correios é de 5 segundos. Após isso, se o serviço não responder, uma exceção do tipo Timeout::Error será lançada.

Você pode configurar esse tempo de espera usando o módulo Correios::CEP.

Correios::CEP.configure do |config|
  config.request_timeout = 3  # Configura o tempo de espera para 3 segundos
end
Log

Por padrão, cada chamada ao serviço Web dos Correios é logada em STDOUT, com nível de log :info, usando a gem LogMe.

Exemplo de log:

I, [2014-02-14T00:10:12.718413 #76361]  INFO -- : [Correios::CEP] Request:
POST http://200.252.60.209/SigepCliente/AtendeClienteService
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:cli="http://cliente.bean.master.sigep.bsb.correios.com.br/">
  <soapenv:Header />
  <soapenv:Body>
    <cli:consultaCEP>
      <cep>54250610</cep>
    </cli:consultaCEP>
  </soapenv:Body>
</soapenv:Envelope>

I, [2014-02-14T00:10:12.969937 #76361]  INFO -- : [Correios::CEP] Response:
HTTP/1.1 200 OK
<?xml version='1.0' encoding='UTF-8'?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:consultaCEPResponse xmlns:ns2="http://cliente.bean.master.sigep.bsb.correios.com.br/">
      <return>
        <bairro>Cavaleiro</bairro>
        <cep>54250610</cep>
        <cidade>Jaboatão dos Guararapes</cidade>
        <complemento></complemento>
        <complemento2></complemento2>
        <end>Rua Fernando Amorim</end>
        <id>0</id>
        <uf>PE</uf>
      </return>
    </ns2:consultaCEPResponse>
  </S:Body>
</S:Envelope>

Para desabilitar o log e configurar um outro mecanismo de log, use o módulo Correios::CEP.

Correios::CEP.configure do |config|
  config.log_enabled = false   # Desabilita o log
  config.logger = Rails.logger # Usa o logger do Rails
end
Exemplo de configuração
Correios::CEP.configure do |config|
  config.logger = Rails.logger
  config.request_timeout = 3
end
Código no Github

https://github.com/prodis/correios-cep

Gem no RubyGems.org

https://rubygems.org/gems/correios-cep

  1. 19, maio, 2014 em 09:57 | #1

    E aí Prodis!

    Nossa, valew por esse post, pra mim essa gem é de grande valia para o pessoal que deseja consultar endereços de forma fácil e rápida. Com certeza essa gem foi um grande norte para a equipe do http://www.consultaenderecos.com.br

    Valew!

  2. Rodrigo
    13, junho, 2014 em 11:09 | #2

    Após instlar a gem ta dando um erro assim:

    cannot load such file — correios-cep

  3. 27, junho, 2014 em 07:20 | #3

    @Rodrigo
    Você instalou de que forma, via gem install?

  4. Fabiano
    17, dezembro, 2014 em 14:49 | #4

    Olá, estava com a gem funcionando até ontem, hoje ele está retornando os seguinte erro:

    Errno::ECONNRESET: Connection reset by peer

    Aconteceu alguma coisa o o webservice?!

    Abraços!

  5. rodrigo brancher
    25, março, 2015 em 17:00 | #5

    opa
    bacana a gem!
    agora, fiquei com uma questão… essa API dos correios é pública, sem necessidade de contrato com SIGEP/ e-DNE?
    abraços,
    rodrigo

  6. 25, março, 2015 em 23:22 | #6
  7. 25, março, 2015 em 23:23 | #7

    @Fabiano
    Provavelmente algum problema com o Web Service.

  8. Maury
    18, abril, 2015 em 18:32 | #8

    Muito útil e prático.
    Obrigado por compartilhar.

  9. Sandro
    22, dezembro, 2015 em 22:33 | #9

    Pessoal, sou novo na programação WEB e estou tentando implementar um formulário de cadastro de pessoas e consequentemente usando a gem correios-cep.

    Alguém poderia me enviar um exemplo de implementação funcionando?

  1. Nenhum trackback ainda.