NAME
WWW::Correios::SRO - Serviço de Rastreamento de Objetos (Brazilian Postal Object Tracking Service)
BILINGUAL MODULE
This module provides APIs in english and portuguese. Documentation is also shown in both languages.
Este módulo oferece APIs em inglês e português. Documentação também é mostrada em ambos os idiomas.
SYNOPSIS
API em português:
use WWW::Correios::SRO qw( sro sro_ok );
my $codigo = 'SS123456789BR'; # insira seu código de rastreamento aqui
return 'SRO inválido' unless sro_ok( $codigo );
my $prefixo = sro_sigla( $codigo ); # retorna "SEDEX FISICO";
my @historico_completo = sro( $codigo );
my $ultimo = sro( $codigo );
# $ultimo terá uma estrutura como:
{
cidade => "BELO HORIZONTE",
codigo => 31276970,
data => "19/03/2018",
descricao => "Objeto encaminhado",
destino => {
bairro => "Parque Novo Mundo",
cidade => "Sao Paulo",
codigo => "02170975",
local => "CTE VILA MARIA",
uf => "SP"
},
hora => "22:19",
local => "CTE BELO HORIZONTE",
status => "01",
tipo => "DO",
uf => "MG"
}
if (status_da_entrega($ultimo) eq 'entregue') {
say "Yay! Pedido entregue!";
}English API:
use WWW::Correios::SRO qw( sro_en sro_ok );
my $code = 'SS123456789BR'; # insert tracking code here
return 'invalid SRO' unless sro_ok( $code );
my $prefix = sro_sigla( $code ); # returns "SEDEX";
my @full_history = sro_en( $code );
my $last = sro_en( $code );Note: All messages are created by the brazilian post office website. Some messages might not be translated.
Note #2: the sro_en() function is experimental, and could be removed in future versions with no prior notice. If you care, or have any comments/suggestions on how to improve this, please let me know.
DESCRIPTION
Este módulo oferece uma interface com o serviço de rastreamento de objetos dos Correios. Até a data de publicação deste módulo não há uma API pública dos Correios para isso, então este módulo consulta o site dos Correios diretamente e faz parsing dos resultados. Sim, isso significa que mudanças no layout do site dos Correios podem afetar o funcionamento deste módulo. Até os Correios lançarem o serviço via API, isso é o que temos.
This module provides an interface to the Brazilian Postal (Correios) object tracking service. Until the date of release of this module there was no public API to achieve this, so this module queries the Correios website directly and parses its results. Yup, this means any layout changes on their website could affect the correctness of this module. Until Correios releases an API for this service, that's all we can do.
EXPORTS
Este módulo não exporta nada por padrão. Você precisa explicitar 'sro' (para mensagens em português) ou 'sro_en' (para mensagens em inglês).
This module exports nothing by default. You have to explicitly ask for 'sro' (for the portuguese messages) or 'sro_en' (for the english messages).
sro
Recebe o código identificador do objeto.
Em contexto escalar, retorna retorna um hashref contendo a entrada mais recente no registro dos Correios. Em contexto de lista, retorna um array de hashrefs, da entrada mais recente à mais antiga. Em caso de falha, retorna undef. As mensagens do objeto retornado estarão em português.
Seu segundo parâmetro (opcional) é um hashref com dados extras:
sro( 'SS123456789BR', {
ua => LWP::UserAgent->new,
timeout => 5,
username => 'meu_usuario',
password => 'minha_senha',
verifica_prefixo => 1,
multiple => 1,
});ua - user agent que fará a requisição. Precisa implementar o método
post()com a mesma interface do LWP::UserAgent.timeout - se o user agent não for especificado, esse parâmetro ajusta o timeout do user agent padrão.
username - usuário disponibilizado pelos Correios para o seu contrato de acesso ao webservice de SRO.
password - senha disponibilizada pelos Correios para o seu contrato de acesso ao webservice de SRO.
verifica_prefixo - se verdadeiro, pesquisará apenas códigos com prefixo disponibilizado pelos Correios.
multiple - permite passar vários códigos de rastreamento concatenados (e.g. 'SS123456789BRJR123456789BR').
Se você passar mais de um código de rastreamento concatenado e o parâmetro 'multiple', o resultado será um hash onde cada chave é um dos códigos passados. O valor será o mesmo de antes, por chave (i.e. ou um hashref com os dados ou um array de hashrefs, dependendo se você chamou a função em contexto escalar ou de lista). Em outras palavras:
my $ultimos_status = sro( 'SS123456789BRJR123456789BR', { multiple => 1 } );
say $ultimos_status->{'SS123456789BR'}{status};
my %todos_os_status = sro( 'SS123456789BRJR123456789BR', { multiple => 1 } );
foreach my $entrada ( @{$todos_os_status{'SS123456789BR'}} ) {
say $entrada->{status};
}--
Receives the item identification code.
In scalar context, returns a hashref containing the most recent log entry in the Postal service. In list context, returns a list of hashrefs, from the most recent entry to the oldest. Returns undef upon failure. Messages on the returned object will be in portuguese.
Its second (optional) parameter is a hashref with extra data:
sro( 'SS123456789BR', {
ua => LWP::UserAgent->new,
timeout => 5,
username => 'my_user',
password => 'my_password',
verifica_prefixo => 1,
multiple => 1,
});ua - user agent that will make the request. Must implement the
post()method with the same API as LWP::UserAgent.timeout - if no user agent is specified, this parameter will adjust the timeout of the default one.
username - user provided by Correios for your webservice contract.
password - password provided by Correios for your webservice contract.
verifica_prefixo - if given a true value, determines whether we query just the codes with valid prefixes.
multiple - lets you pass several concatenated codes (e.g. 'SS123456789BRJR123456789BR').
If you pass more than one concatenated code with the 'multiple' parameter, the result will be a hash where each key is one of the given codes. The value is the same as before, per key (i.e. either a hashref of data or an array of hashrefs, depending on scalar or list context). In other words:
my $last_statuses = sro( 'SS123456789BRJR123456789BR', { multiple => 1 } );
say $last_statuses->{'SS123456789BR'}{status};
my %all_statuses = sro( 'SS123456789BRJR123456789BR', { multiple => 1 } );
foreach my $entry ( @{$all_statuses{'SS123456789BR'}} ) {
say $entry->{status};
}sro_en
O mesmo que sro(), mas com mensagens em inglês.
Same as sro(), but with messages in english.
sro_ok
Retorna verdadeiro se o código de rastreamento passado é válido, caso contrário retorna falso. Essa função é chamada automaticamente pelas funções sro e sro_en, então você não precisa se preocupar em chamá-la diretamente. Ela deve ser usada quando você quer apenas saber se o código é válido ou não, sem precisar fazer uma consulta HTTP ao site dos correios. Essa função não elimina espaços da string, você deve fazer sua própria higienização.
--
Returns true if the given tracking code is valid, false otherwise. This function is automatically called by the sro and sro_en functions, so you don't have to worry about calling it directly. It should be used when you just want to know whether the tracking code is valid or not, without the need to make an HTTP request to the postal office website. This function does not trim whitespaces from the given string, you have to sanitize it by yourself.
sro_sigla
Retorna uma string com o significado do prefixo do código que foi passado. Retorna undef caso a string não seja conhecida.
--
Returns a string with the meaning of the code's prefix. Returns undef if we don't know the meaning.
status_da_entrega( $dados_retornados )
Esta função recebe os dados retornados por uma consulta via sro() em formato arrayref ou hashref, e retorna uma string no seguinte formato:
- 'entregue' - entrega concluida, nada mais a ser feito.
- 'erro' - acionar Correios (objetos perdidos, extraviado, etc).
- 'retirar' - pacote na agência, aguardando retirada pelo interessado.
- 'incompleto' - pacote retornado ao remetente.
- 'acompanhar' - pacote em trânsito.
DADOS RETORNADOS/RETURNED DATA (BREAKING CHANGES)
Em versões anteriores à 0.11, este módulo retornava um objeto (ou uma lista de objetos). A API dos Correios mudou em meados de 2016, e agora a consulta retorna dados diferentes. Para dar mais flexibilidade, optamos por um hashref livre de estrutura.
Algumas informações ainda são pertinentes:
- a data/hora retornada indica o momento em que os dados de entrega foram recebidos pelo sistema, exceto no 'SEDEX 10' e no 'SEDEX Hoje', em que representa o horário real da entrega. Informação sobre onde encontrar o código para rastreamento estão disponíveis (em português) no link: http://www.correios.com.br/servicos/rastreamento/como_loc_objeto.cfm
- the returned date/time refer to the moment in which the delivery data got into the system, except on 'SEDEX 10' and 'SEDEX Hoje', where it corresponds to the actual delivery date. Information on how to find the tracking code is available in the link: http://www.correios.com.br/servicos/rastreamento/como_loc_objeto.cfm (follow the "English version" link on that page).
- o campo de "local" contém o local em que o evento ocorreu. A string retornada é prefixada por uma sigla, como ACF (Agência de Correios Franqueada), CTE (Centro de Tratamento de Encomendas), CTCE (Centro de Tratamento de Cartas e Encomendas), CTCI (Centro de Tratamento de Correio Internacional), CDD (Centro de Distribuição Domiciliária), CEE (Centro de Entrega de Encomendas).
- the "location" field contains the location where the event ocurred. The returned string is prefixed by an acronym like ACF (Franchised Postal Agency), CTE (Center for Item Assessment), CTCE (Center for Item and Mail Assessment), CTCI (Center for International Postal Assessment), CDD (Center for Domiciliary Distribution), CEE (Center for Item Delivery).
AUTHOR
Breno G. de Oliveira, <garu at cpan.org>
BUGS
Por favor envie bugs ou pedidos para bug-www-correios-sro at rt.cpan.org, ou pela interface web em http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Correios-SRO. Eu serei notificado, e então você será automaticamente notificado sobre qualquer progresso na questão.
Please report any bugs or feature requests to bug-www-correios-sro at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Correios-SRO. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
AGRADECIMENTOS/ACKNOWLEDGEMENTS
Este módulo não existiria sem o serviço gratuito de rastreamento online dos Correios.
http://www.correios.com.br/servicos/rastreamento/
LICENSE AND COPYRIGHT
Copyright 2010-2017 Breno G. de Oliveira.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.