correios-frete - Gem para cálculo de frete dos Correios

Os Correios disponbilizam um Web Service para cálculo de frete de serviços como SEDEX e PAC. Muitas lojas virtuais no Brasil consomem esse Web Service em seus carrinhos de compra, como por exemplo a WebStore Locaweb.

Procurei alguma RubyGem existente que fizessse esse cálculo, mas as opções que encontrei (Correios, frete_correios e Mooamba) não me agradaram muito, tanto na forma de uso, quanto no código.

Então criei a gem correios-frete, com o intuito de deixar a tarefa do cálculo de frete algo simples de ser executado.

Os serviços de frete suportados são PAC, SEDEX, SEDEX a Cobrar (necessário informar o valor declarado), SEDEX 10, SEDEX Hoje e e-SEDEX. Para os serviços com contrato é necessário informar código de empresa e senha.

Optei por deixar toda a interface pública das classes em português para facilitar o uso, pois se trata de algo totalmente localizado no Brasil. Mas também criei alias em inglês para alguns métodos.


Instalando

Gemfile:
gem 'correios-frete'

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

Usando

require 'correios-frete'

frete = Correios::Frete::Calculador.new :cep_origem => "04094-050",
                                          :cep_destino => "90619-900",
                                          :peso => 0.3,
                                          :comprimento => 30,
                                          :largura => 15,
                                          :altura => 2

Cálculo de vários serviços ao mesmo tempo:

servicos = frete.calcular :sedex, :pac

servicos[:sedex].nome          # => "SEDEX"
servicos[:sedex].descricao     # => "SEDEX sem contrato"
servicos[:sedex].valor         # => 26.2
servicos[:sedex].prazo_entrega # => 1

servicos[:pac].nome          # => "PAC"
servicos[:pac].descricao     # => "PAC sem contrato"
servicos[:pac].valor         # => 10.0
servicos[:pac].prazo_entrega # => 5

Cálculo de um serviço de frete passando o serviço para parâmetro:

servico = frete.calcular :sedex
servico.nome          # => "SEDEX"
servico.descricao     # => "SEDEX sem contrato"
servico.valor         # => 26.2
servico.prazo_entrega # => 1

servico = frete.calcular :pac
servico.nome          # => "PAC"
servico.descricao     # => "PAC sem contrato"
servico.valor         # => 10.0
servico.prazo_entrega # => 5

Cálculo de um serviço de frete chamando o método direto do serviço:

servico = frete.calcular_sedex
servico.nome          # => "SEDEX"
servico.descricao     # => "SEDEX sem contrato"
servico.valor         # => 26.2
servico.prazo_entrega # => 1

servico = frete.calcular_pac
servico.nome          # => "PAC"
servico.descricao     # => "PAC sem contrato"
servico.valor         # => 10.0
servico.prazo_entrega # => 5

Verificação de sucesso e erro:

frete.altura = 100

servico = frete.calcular_sedex
servico.sucesso? # => false
servico.erro?    # => true
servico.msg_erro # => "A altura nao pode ser maior que 90 cm."

Usando a interface pública em inglês:

servicos = frete.calculate :sedex, :pac

servico = frete.calculate_sedex
servico.success? # => true
servico.error?   # => false
Usando pacotes

Você pode “montar” um pacote com vários itens. Com o cálculo do volume dos itens adicionados, o pacote único será gerado em formato de cubo.

item1 = Correios::Frete::PacoteItem.new :peso => 0.3,
                                          :comprimento => 30,
                                          :largura => 15,
                                          :altura => 2

item2 = Correios::Frete::PacoteItem.new :peso => 0.7,
                                          :comprimento => 70,
                                          :largura => 25,
                                          :altura => 3

pacote = Correios::Frete::Pacote.new
pacote.adicionar_item(item1)
pacote.adicionar_item(item2)

pacote.peso        # => 1.0
pacote.comprimento # => 18.32138799447962
pacote.largura     # => 18.32138799447962
pacote.altura      # => 18.32138799447962
pacote.volume      # => 6150.0
pacote.formato     # => :caixa_pacote
pacote.itens.size  # => 2

Caso alguma dimensão do pacote montado seja menor que o tamanho mínimo exigido pelos Correios, o valor mínimo será atribuído à dimensão.

item1 = Correios::Frete::PacoteItem.new :peso => 0.3,
                                          :comprimento => 30,
                                          :largura => 15,
                                          :altura => 2

item2 = Correios::Frete::PacoteItem.new :peso => 0.7,
                                          :comprimento => 40,
                                          :largura => 10,
                                          :altura => 3

pacote = Correios::Frete::Pacote.new
pacote.adicionar_item(item1)
pacote.adicionar_item(item2)

pacote.comprimento # => 16.0
pacote.largura     # => 12.80579164987494
pacote.altura      # => 12.80579164987494

Montado o pacote, basta passá-lo pelo parâmetro encomenda no construtor de Correios::Frete::Calculador.

frete = Correios::Frete::Calculador.new :cep_origem => "04094-050",
                                          :cep_destino => "90619-900",
                                          :encomenda => pacote

servicos = frete.calcular :sedex, :pac

servicos[:sedex].valor         # => 29.2
servicos[:sedex].prazo_entrega # => 1

servicos[:pac].valor         # => 13.3
servicos[:pac].prazo_entrega # => 5

Observação: Quando uma encomenda é fornecida ao calculador de frete, os parâmetros peso, comprimento, largura, altura e formato serão ignorados, sendo utilizados os valores da encomenda.

Usando a interface pública em inglês:

item1 = Correios::Frete::PacoteItem.new :peso => 0.3,
                                          :comprimento => 30,
                                          :largura => 15,
                                          :altura => 2

item2 = Correios::Frete::PacoteItem.new :peso => 0.7,
                                          :comprimento => 70,
                                          :largura => 25,
                                          :altura => 3

pacote = Correios::Frete::Pacote.new
pacote.add_item(item1)
pacote.add_item(item2)
pacote.items.size # => 2

Configurações

Timeout

Por padrão, o tempo de espera de resposta (timeout) para uma requisição ao Web Service dos Correios é de 10 segundos. Após isso, se o Web Service dos Correios 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::Frete.

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

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

Exemplo de log:
I, [2011-10-01T00:26:16.864990 #5631] INFO — : Correios-Frete Request:
http://ws.correios.com.br/calculador/CalcPrecoPrazo.aspx?sCepOrigem=04094-050&sCepDestino=90619-900&nVlPeso=0.3&nVlComprimento=30&nVlAltura=2&nVlLargura=15&nVlDiametro=0.0&nCdFormato=1&sCdMaoPropria=N&sCdAvisoRecebimento=N&nVlValorDeclarado=0.00&nCdServico=41106&nCdEmpresa=&sDsSenha=&StrRetorno=xml

I, [2011-10-01T00:26:17.121822 #5631] INFO — : Correios-Frete Response:
HTTP/1.1 200 OK
<?xml version=”1.0″ encoding=”ISO-8859-1″ ?>
<Servicos><cServico><Codigo>41106</Codigo><Valor>10,00</Valor><PrazoEntrega>5</PrazoEntrega><ValorMaoPropria>0,00</ValorMaoPropria><ValorAvisoRecebimento>0,00</ValorAvisoRecebimento><ValorValorDeclarado>0,00</ValorValorDeclarado><EntregaDomiciliar>S</EntregaDomiciliar><EntregaSabado>N</EntregaSabado><Erro>0</Erro><MsgErro></MsgErro></cServico></Servicos>

Se você configurar o nível de log como :debug, serão logados também todos os cabeçalhos HTTP da resposta:
D, [2011-10-01T00:27:50.597961 #5631] DEBUG — : Correios-Frete Request:
http://ws.correios.com.br/calculador/CalcPrecoPrazo.aspx?sCepOrigem=04094-050&sCepDestino=90619-900&nVlPeso=0.3&nVlComprimento=30&nVlAltura=2&nVlLargura=15&nVlDiametro=0.0&nCdFormato=1&sCdMaoPropria=N&sCdAvisoRecebimento=N&nVlValorDeclarado=0.00&nCdServico=41106&nCdEmpresa=&sDsSenha=&StrRetorno=xml

D, [2011-10-01T00:27:50.812046 #5631] DEBUG — : Correios-Frete Response:
HTTP/1.1 200 OK
date: Sat, 01 Oct 2011 03:27:55 GMT
server: Microsoft-IIS/6.0
x-powered-by: ASP.NET
x-aspnet-version: 1.1.4322
set-cookie: ASP.NET_SessionId=cnoejn3dpioxapejc0c3np55; path=/
cache-control: private
expires: Sat, 01 Oct 2011 03:27:55 GMT
content-type: text/xml; charset=iso-8859-1
content-length: 401
<?xml version=”1.0″ encoding=”ISO-8859-1″ ?>
<Servicos><cServico><Codigo>41106</Codigo><Valor>10,00</Valor><PrazoEntrega>5</PrazoEntrega><ValorMaoPropria>0,00</ValorMaoPropria><ValorAvisoRecebimento>0,00</ValorAvisoRecebimento><ValorValorDeclarado>0,00</ValorValorDeclarado><EntregaDomiciliar>S</EntregaDomiciliar><EntregaSabado>N</EntregaSabado><Erro>0</Erro><MsgErro></MsgErro></cServico></Servicos>

Para desabilitar o log, mudar o nível do log ou configurar um outro mecanismo de log, use o módulo Correios::Frete.

Correios::Frete.configure do |config|
  config.log_enabled = false   # Desabilita o log
  config.log_level = :debug    # Altera o nível do log
  config.logger = Rails.logger # Usa o logger do Rails
end
Exemplo de configuração
Correios::Frete.configure do |config|
  config.log_level = :debug
  config.logger = Rails.logger
  config.request_timeout = 3
end

Informações adicionais

Serviços suportados
:pac                         # 41106 - PAC sem contrato
:pac_com_contrato            # 41068 - PAC com contrato
:pac_gf                      # 41300 - PAC para grandes formatos
:sedex                       # 40010 - SEDEX sem contrato
:sedex_a_cobrar              # 40045 - SEDEX a Cobrar, sem contrato
:sedex_a_cobrar_com_contrato # 40126 - SEDEX a Cobrar, com contrato
:sedex_10                    # 40215 - SEDEX 10, sem contrato
:sedex_hoje                  # 40290 - SEDEX Hoje, sem contrato
:sedex_com_contrato_1        # 40096 - SEDEX com contrato
:sedex_com_contrato_2        # 40436 - SEDEX com contrato
:sedex_com_contrato_3        # 40444 - SEDEX com contrato
:sedex_com_contrato_4        # 40568 - SEDEX com contrato
:sedex_com_contrato_5        # 40606 - SEDEX com contrato
:e_sedex                     # 81019 - e-SEDEX, com contrato
:e_sedex_prioritario         # 81027 - e-SEDEX Prioritário, com contrato
:e_sedex_express             # 81035 - e-SEDEX Express, com contrato
:e_sedex_grupo_1             # 81868 - (Grupo 1) e-SEDEX, com contrato
:e_sedex_grupo_2             # 81833 - (Grupo 2) e-SEDEX, com contrato
:e_sedex_grupo_3             # 81850 - (Grupo 3) e-SEDEX, com contrato
Maneiras de configurar atributos no construtor de Correios::Frete::Calculador

Com um hash:

frete = Correios::Frete::Calculador.new :cep_origem => "04094-050",
                                          :cep_destino => "90619-900",
                                          :peso => 0.3,
                                          :comprimento => 30,
                                          :largura => 15,
                                          :altura => 2

Com um bloco:

frete = Correios::Frete::Calculador.new do |f|
  f.cep_origem = "04094-050"
  f.cep_destino = "90619-900"
  f.peso = 0.3
  f.comprimento = 30
  f.largura = 15
  f.altura = 2
end
Maneiras de adicionar itens em Correios::Frete::Pacote

Pelo método adicionar_item passando instâncias de Correios::Frete::PacoteItem:

item1 = Correios::Frete::PacoteItem.new :peso => 0.3,
                                          :comprimento => 30,
                                          :largura => 15,
                                          :altura => 2

item2 = Correios::Frete::PacoteItem.new :peso => 0.7,
                                          :comprimento => 70,
                                          :largura => 25,
                                          :altura => 3

pacote = Correios::Frete::Pacote.new
pacote.adicionar_item(item1)
pacote.adicionar_item(item2)

Pelo construtor passando instâncias de Correios::Frete::PacoteItem:

pacote = Correios::Frete::Pacote.new [
  Correios::Frete::PacoteItem.new(:peso => 0.3,
                                   :comprimento => 30,
                                   :largura => 15,
                                   :altura => 2),
  Correios::Frete::PacoteItem.new(:peso => 0.3,
                                   :comprimento => 70,
                                   :largura => 25,
                                   :altura => 3)
]

Pelo método adicionar_item passando parâmetros dos itens:

pacote = Correios::Frete::Pacote.new
pacote.adicionar_item(:peso => 0.3, :comprimento => 30, :largura => 15, :altura => 2)
pacote.adicionar_item(:peso => 0.7, :comprimento => 70, :largura => 25, :altura => 3)

Pelo construtor passando parâmetros dos itens:

pacote = Correios::Frete::Pacote.new [
  { :peso => 0.3, :comprimento => 30, :largura => 15, :altura => 2 },
  { :peso => 0.7, :comprimento => 70, :largura => 25, :altura => 3 }
]
Atributos de Correios::Frete::Calculador
  • String: cep_origem, cep_destino, codigo_empresa, senha
  • Float: peso, comprimento, largura, altura, diametro, valor_declarado
  • Boolean: mao_propria, aviso_recebimento
  • Symbol: formato (:caixa_pacote, :rolo_prisma, :envelope)
Atributos de Correios::Frete::Pacote
  • Float: peso, comprimento, largura, altura, volume
  • Array de Correios::Frete::PacoteItem: itens
  • Symbol: formato (:caixa_pacote)
Atributos de Correios::Frete::PacoteItem
  • Float: peso, comprimento, largura, altura, volume
Atributos de Correios::Frete::Servico
  • String: codigo, erro, msg_erro, nome, descricao
  • Float: valor, valor_mao_propria, valor_aviso_recebimento, valor_valor_declarado
  • Fixnum: prazo_entrega
  • Boolean: entrega_domiciliar, entrega_sabado
  • Symbol: tipo (:pac, :pac_com_contrato, :pac_gf, :sedex, :sedex_a_cobrar, :sedex_a_cobrar_com_contrato, :sedex_10, :sedex_hoje, :sedex_com_contrato_1, :sedex_com_contrato_2, :sedex_com_contrato_3, :sedex_com_contrato_4, :sedex_com_contrato_5, :e_sedex, :e_sedex_prioritario, :e_sedex_express, :e_sedex_grupo_1, :e_sedex_grupo_2, :e_sedex_grupo_3)
Colaboradores
Código no Github

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

Gem no RubyGems.org

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

  1. Alan
    24, fevereiro, 2012 em 18:06 | #1

    Olá, boa noite.

    Primeiramente gostaria de parabenizá-los pelo trabalho.

    Estou procurando um módulo para calcular frete, e aqui foi um dos poucos lugares que encontrei.

    Ocorre que eu nunca tinha ouvido falar de Gem.. ruby… como faço para saber se meu servidor aceita instalar esse tipo de arquivo?

  2. 24, fevereiro, 2012 em 18:21 | #2

    Obrigado, Alan.

    Uma gem é como uma biblioteca ou componente que você referencia e usa na sua aplicação Ruby.

    Você precisa verificar junto ao seu provedor de hospedagem. Em geral as hospedagens Linux oferecerem suporte a Ruby on Rails, que é um framework em Ruby para aplicações Web.

  3. Stefano Diem Benatti
    6, março, 2012 em 12:04 | #3

    Sensacional!!! Eu estou construindo uma loja virtual usando o spree (http://spreecommerce.com), e estou criando uma extensão para que possa utilizar os correios como forma de entrega. Eu comecei a olhar a documentação para escrever uma gem dos correios (porque achei um lixo as já existentes), para depois criar a gem que faz a integração do spree com esta, mas depois de ver a existência da sua gem pretendo utilizá-la!

    Parabéns mesmo!

  4. 6, março, 2012 em 13:06 | #4

    Legal, Stefano!

    Na WebStore, loja virtual da Locaweb que é baseada em uma versão mais antiga do Spree, estamos utilizando a gem correios-frete.

    Quando você criar essa extensão para o Spree, me avise que eu ajudo a divulgar.

    Abraço.

  5. Leandro
    11, abril, 2012 em 00:40 | #5

    Legal, parabens!
    Só não entendo por que vocês desenvolveram com as classes e métodos em portugues… em projetos com desenvolvedores estrangeiros (como o que eu estou agora) fica simplesmente inviável utilizar a gem =/
    abs

  6. 11, abril, 2012 em 12:32 | #6

    Obrigado, @Leandro.

    Como mencionei, optei por deixar a interface pública em português por se tratar de algo totalmente localizado no Brasil.

    Se todos os atributos das classes Calculador, Pacote, PacoteItem e Servicos tivessem alias em inglês lhe ajudaria?

  7. 23, abril, 2012 em 22:11 | #7

    Vi que existem dois formatos (caixa_pacote e rolo_prisma). Pelo site dos correios (http://www.correios.com.br/encomendas/prazo/default.cfm) tem como fazer o cálculo pelo formato envelope também.
    Pela gem que você criou não é possível fazer o cálculo no formato ‘envelope’?

  8. 24, abril, 2012 em 12:25 | #8

    @Ranieri,

    A versão atual da gem correios-frete não tem suporte ao formato envelope, pois este formato ainda não estava disponível para cálculo através do Web Service dos Correios.

    Vi agora na documentação deles que foi implementado esse formato.

    Criei uma issue (https://github.com/prodis/correios-frete/issues/10) para isso. Você quer implementar?

  9. 9, agosto, 2012 em 10:27 | #9

    @Ranieri
    Implementei o suporte ao formato envelope. Está disponível na versão 1.8.0.

  10. 18, outubro, 2012 em 20:57 | #10

    Parabéns, muito boa a gem, me poupou horas de trabalho. valeu

  11. 20, outubro, 2012 em 18:00 | #11

    Obrigado, @Nando Sousa. Que bom que pude ajudar.

  12. Fábio
    20, novembro, 2012 em 20:53 | #12

    Parabéns pelo post, só estou com uma dúvida nos “pacotes” em que o código define as dimensões como “18.32138799447962″ após adicionar 2 produtos de pesos e dimensões diferentes. Não entendi como se chega a estes valores.
    Se alguém puder responder eu agradeço!

  13. 22, novembro, 2012 em 17:13 | #13

    Obrigado, @Fábio.

    Quando você monta um pacote com vários itens é feito o cálculo de volume de cada item adicionado, esses volumes são somados e o pacote único será gerado em formato de cubo com o volume total dos itens.

    A partir do volume total são extraídas as dimensões (comprimento, largura e altura).

  14. André
    22, janeiro, 2013 em 22:07 | #14

    @Stefano Diem Benatti, você criou a extensão para o spree para utilizar os correios como forma de entrega? Eu estou bastante interessado em usar/testar essa extensão. Estou tentando utilizar a https://github.com/angelim/spree-correios-shipping mas ainda não tive sucesso em configurá-la! Qualquer dica será muito bem vinda!

  15. edson
    15, abril, 2013 em 04:07 | #16

    Estou com duvida ao adicionar a gem como faço para integrar ela com o spree? ex: migration, estou muito confuso se alguém puder me ajudar?

  16. 22, abril, 2013 em 16:23 | #17

    @edson
    Dá uma olhada no documentação do Spree sobre extensões: http://guides.spreecommerce.com/extensions.html.

    Depois tenta instalar a extensão que o @Stefano Diem Benatti fez: https://github.com/heavenstudio/spree_correios
    https://rubygems.org/gems/spree_correios

  17. lucas
    4, maio, 2013 em 00:30 | #18

    @edson

    Algum sucesso com a integração? Sem sucesso aqui.

  18. Jonatas
    8, agosto, 2013 em 12:10 | #19

    Olá, Parabens ficou muito bom.

    Agora eu estou com uma dúvida.
    Como faço pra integrar isso com meu site em php?
    Tem como?

    Grato, Jonatas

  19. Thiago
    10, dezembro, 2013 em 17:31 | #20

    @Prodis
    Boa tarde,

    Gostaria de saber como você fez o cálculo para obter a altura x largura e comprimento a partir do volume total? Teria como me passar por e-mail?

    thi.fatec@gmail.com

    Obrigado desde já

  20. Felipe
    24, janeiro, 2014 em 14:49 | #21

    Parabéns pelo tutorial. Você tem algo semelhante desenvolvido em PHP? Eu não sei como aplicar essa lógica no meu site. Eu tenho 3 caixas definidas os tamanhos L/A/C e tenho vários produtos a serem vendidos e precisa descobrir em qual das caixas eu irei enviar os produtos comprados e com isso calcular o frete dos correios.

  21. 14, fevereiro, 2014 em 22:29 | #22

    @Felipe
    Não tenho um “port” da gem correios-frete em PHP. Quanto ao cálculo de volume, o que a gem correios-frete faz é encontrar as dimensões de um cubo originado a partir de todos os pacotes. Dá uma olhada no método “volume” da classe PacoteItem (https://github.com/prodis/correios-frete/blob/master/lib/correios/frete/pacote_item.rb) e no método “calcular_medidas” da classe Pacote (https://github.com/prodis/correios-frete/blob/master/lib/correios/frete/pacote.rb).

  22. 16, fevereiro, 2014 em 18:13 | #23

    @Jonatas
    A gem é um Ruby. Você vai ter que fazer uma biblioteca em PHP.

  23. Crato
    12, setembro, 2014 em 17:18 | #24

    Olá, se existir vários produtos cujo o Volume ultrapasse o COMPRIMENTO MAXIMO ou ALTURA MAXIMA OU LARGURA MAXIMA. Você gera outra pacote ? como é feito ?

  24. 8, dezembro, 2014 em 00:12 | #25

    @Crato
    O controle das medidas não é feito pela gem e se você não tratar as larguras máximas na sua aplicação, o cálculo do frete retornará um erro ao ser calculado.

  1. 28, janeiro, 2012 em 13:07 | #1