O Sistema de Rastreamento de Objetos dos Correios (SRO) possibilita o acompanhamento dos objetos postados sob registro, incluindo portanto todas as encomendas SEDEX, e-SEDEX e PAC.
Os Correios disponibilizam um Web Service para consultar o progresso na entrega das mercadorias. O SRO XML permite a consulta de até 50 encomendas simultaneamente.
A gem correios-sro-xml utiliza o SRO XML dos Correios facilitando o uso desse recurso em aplicações Ruby.
Para usar o SRO XML em ambiente de produção, é necessário solicitar dados de acesso (usuário e senha) junto aos Correios, conforme descrito no blog dos Correios.
Para o ambiente de desenvolvimento, você pode usar os seguintes dados:
Instalando
Gemfile:
gem 'correios-sro-xml'
Instalação direta:
$ gem install correios-sro-xml
Usando
require 'correios-sro-xml'
sro = Correios::SRO::Tracker.new(:user => "ECT", :password => "SRO")
Rastreamento de um objeto:
object = sro.get("SI047624825BR")
object.number # => "SI047624825BR"
object.events.first.date # => "26/12/2011"
object.events.first.hour # => "15:22"
object.events.first.place # => "AC CENTRAL DE SAO PAULO"
object.events.first.description # => "Entregue"
Rastreamento de vários objetos:
objects = sro.get("SI047624825BR", "SX104110463BR")
objects["SI047624825BR"].number # => "SI047624825BR"
objects["SI047624825BR"].events.first.date # => "26/12/2011"
objects["SI047624825BR"].events.first.hour # => "15:22"
objects["SI047624825BR"].events.first.place # => "AC CENTRAL DE SAO PAULO"
objects["SI047624825BR"].events.first.description # => "Entregue"
objects["SX104110463BR"].number # => "SX104110463BR"
objects["SX104110463BR"].events.first.date # => "08/12/2011"
objects["SX104110463BR"].events.first.hour # => "09:30"
objects["SX104110463BR"].events.first.place # => "CEE JUNDIAI"
objects["SX104110463BR"].events.first.description # => "Entregue"
Modo de resultado (result mode)
Um objeto pode ter um ou mais eventos. Por padrão, o modo de resultado do rastreador irá retornar o último evento do objeto.
sro.result_mode # => :last
object = sro.get("SI047624825BR")
object.events.size # => 1
Você pode configurar para o retorno ser todos os eventos do objeto.
sro.result_mode = :all
object = sro.get("SI047624825BR")
object.events.size # => 5
Tipo de consulta (query type)
Existem duas maneiras para consultar objetos no rastreador:
Lista de objetos
Onde todos os números de objetos serão consultados (o padrão).
sro.query_type # => :list
objects = sro.get("PB996681660BR", "PB996681700BR")
objects.keys # => ["PB996681660BR", "PB996681700BR"]
Intervalo de objetos
No qual você fornece primeiro e último números de objetos de um intervalo.
sro.query_type = :range
objects = sro.get("PB996681660BR", "PB996681700BR")
objects.keys # => ["PB996681660BR", "PB996681673BR", "PB996681687BR", "PB996681695BR", "PB996681700BR"]
Configurações
Timeout
Por padrão, o tempo de espera de resposta (timeout) para uma requisição ao SRO XML é de 5 segundos. Após isso, se o SRO XML 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::SRO.
Correios::SRO.configure do |config|
config.request_timeout = 3 # Configura o tempo de espera para 3 segundos
end
Log
Por padrão, cada chamada ao SRO XML é logada em STDOUT, com nível de log :info, usando a gem LogMe.
Exemplo de log:
I, [2012-08-17T00:55:10.531780 #22692] INFO -- : Correios-SRO-XML Request:
POST http://websro.correios.com.br/sro_bin/sroii_xml.eventos
Usuario=ECT&Senha=SRO&Tipo=L&Resultado=U&Objetos=PB996681660BR
I, [2012-08-17T00:55:10.750308 #22692] INFO -- : Correios-SRO-XML Response:
HTTP/1.1 200 OK
<?xml version="1.0" encoding="iso-8859-1" ?>
<sroxml>
<versao>1.0</versao>
<qtd>1</qtd>
<TipoPesquisa>Lista de Objetos</TipoPesquisa>
<TipoResultado>Último evento</TipoResultado>
<objeto>
<numero>PB996681660BR</numero>
<evento>
<tipo>BDE</tipo>
<status>01</status>
<data>05/07/2012</data>
<hora>21:11</hora>
<descricao>Entregue</descricao>
<recebedor> </recebedor>
<documento> </documento>
<comentario> </comentario>
<local>CDD VILA ANDRADE</local>
<codigo>05724970</codigo>
<cidade>SAO PAULO</cidade>
<uf>SP</uf>
<sto>72824000</sto>
</evento>
</objeto>
</sroxml>
Se você configurar o nível de log como :debug, serão logados também todos os cabeçalhos HTTP da requisição e da resposta:
D, [2012-08-17T00:58:56.226742 #22692] DEBUG -- : Correios-SRO-XML Request:
POST http://websro.correios.com.br/sro_bin/sroii_xml.eventos
accept: */*
user-agent: Ruby
content-type: application/x-www-form-urlencoded
Usuario=ECT&Senha=SRO&Tipo=L&Resultado=U&Objetos=PB996681660BR
D, [2012-08-17T00:58:56.495131 #22692] DEBUG -- : Correios-SRO-XML Response:
HTTP/1.1 200 OK
date: Fri, 17 Aug 2012 03:58:56 GMT
server: Oracle-Application-Server-10g/10.1.2.0.2 Oracle-HTTP-Server
content-length: 855
content-type: text/html; charset=ISO-8859-1
x-cache: MISS from 127.0.0.1
connection: close
<?xml version="1.0" encoding="iso-8859-1" ?>
<sroxml>
<versao>1.0</versao>
<qtd>1</qtd>
<TipoPesquisa>Lista de Objetos</TipoPesquisa>
<TipoResultado>?ltimo evento</TipoResultado>
<objeto>
<numero>PB996681660BR</numero>
<evento>
<tipo>BDE</tipo>
<status>01</status>
<data>05/07/2012</data>
<hora>21:11</hora>
<descricao>Entregue</descricao>
<recebedor> </recebedor>
<documento> </documento>
<comentario> </comentario>
<local>CDD VILA ANDRADE</local>
<codigo>05724970</codigo>
<cidade>SAO PAULO</cidade>
<uf>SP</uf>
<sto>72824000</sto>
</evento>
</objeto>
</sroxml>
Para desabilitar o log, mudar o nível do log ou configurar um outro mecanismo de log, use o módulo Correios::SRO.
Correios::SRO.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::SRO.configure do |config|
config.log_level = :debug
config.logger = Rails.logger
config.request_timeout = 3
end
Código no Github
https://github.com/prodis/correios-sro-xml
Gem no RubyGems.org
https://rubygems.org/gems/correios-sro-xml
Ruby Correios, correios-sro-xml, Gem, Rastreamento, Ruby
Comentários