/ 
WWW-Correios-SRO-0.10
River stage zero No dependents
/ WWW::Correios::SRO

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 FÍSICO";

my @historico_completo = sro( $codigo );

my $ultimo = sro( $codigo );

$ultimo->data;    # '22/05/2010 12:10'
$ultimo->local;   # 'CEE JACAREPAGUA - RIO DE JANEIRO/RJ'
$ultimo->status;  # 'Destinatário ausente'
$ultimo->extra;   # 'Será realizada uma nova tentativa de entrega'

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 FÍSICO";

my @full_history = sro_en( $code );

my $last = sro_en( $code );

$last->date;       # '22/05/2010 12:10'
$last->location;   # 'CEE JACAREPAGUA - RIO DE JANEIRO/RJ'
$last->status;     # 'No receiver at the address'
$last->extra;      # 'Delivery will be retried'

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

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 objeto WWW::Correios::SRO::Item contendo a entrada mais recente no registro dos Correios. Em contexto de lista, retorna um array de objetos WWW::Correios::SRO::Item, da entrada mais recente à mais antiga. Em caso de falha, retorna undef. As mensagens do objeto retornado estarão em português.

Seu terceiro parâmetro, verifica_prefixo, determina se pesquisaremos apenas os códigos com prefixos apresentados pelos Correios ($verifica_prefixo = 1) ou não. --

Receives the item identification code.

In scalar context, returns a WWW::Correios::SRO::Item object containing the most recent log entry in the Postal service. In list context, returns a list of WWW::Correios::SRO::Item objects, from the most recent entry to the oldest. Returns undef upon failure. Messages on the returned object will be in portuguese.

Its thirds parameter, verifica_prefixo, determines if we shall search only the codes with prefixes shown by Brazilian Post Office ($erifica_prefixo = 1) or not.

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.

OBJETO RETORNADO/RETURNED OBJECT

data

date (alias)

Retorna a data/hora 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

Returns the date/time 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).

local

location (alias)

Retorna 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).

Returns 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).

status

Retorna a situação registrada para o evento (postado, encaminhado, destinatário ausente, etc)

Returns the registered situation for the event (no receiver at the address, etc)

extra

Contém informações adicionais a respeito do evento, ou undef. Exemplo: 'Será realizada uma nova tentativa de entrega'.

Contains additional information about the event, or undef. E.g.: 'Delivery will be retried'

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.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc WWW::Correios::SRO

You can also look for information at:

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 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.