WWW::Correios::SRO(3)

NAME
WWW::Correios::SRO - Servico 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 modulo oferece APIs em ingles e portugues. Documentaca~o tambem e mostrada em ambos os idiomas.

SYNOPSIS
API em portugues:

    use WWW::Correios::SRO qw( sro sro_ok );

    my $codigo = 'SS123456789BR';  # insira seu codigo de rastreamento aqui

    return 'SRO invalido' unless sro_ok( $codigo );

    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;  # 'Destinatario ausente'
    $ultimo->extra;   # 'Sera 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 @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 modulo na~o exporta nada por padra~o. Voce precisa explicitar 'sro' (para mensagens em portugues) ou 'sro_en' (para mensagens em ingles).

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 codigo identificador do objeto.

Em contexto escalar, retorna retorna um objeto WWW::Correios::SRO::Item contento 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 a mais antiga. Em caso de falha, retorna undef. As mensagens do objeto retornado estara~o em portugues.

--

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.

  sro_en
O mesmo que "sro()", mas com mensagens em ingles.

Same as "sro()", but with messages in english.

  sro_ok
Retorna verdadeiro se o codigo de rastreamento passado e valido, caso contrario retorna falso. Essa funca~o e chamada automaticamente pelas funco~es "sro" e "sro_en", enta~o voce na~o precisa se preocupar em chama-la diretamente. Ela deve ser usada quando voce quer apenas saber se o codigo e valido ou na~o, sem precisar fazer uma consulta HTTP ao site dos correios. Essa funca~o na~o elimina espacos da string, voce deve fazer sua propria higienizaca~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.

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 horario real da entrega. Informaca~o sobre onde encontrar o codigo para rastreamento esta~o disponiveis (em portugues) 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 e prefixada por uma sigla, como ACF (Agencia 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 Distribuica~o Domiciliaria), 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 situaca~o registrada para o evento (postado, encaminhado, destinatario ausente, etc)

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

  extra
Contem informaco~es adicionais a respeito do evento, ou undef. Exemplo: 'Sera 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 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Correios-SRO>. Eu serei notificado, e enta~o voce sera automaticamente notificado sobre qualquer progresso na questa~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 <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:

•   RT: CPAN's request tracker

    http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Correios-SRO <http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Correios-SRO>

•   AnnoCPAN: Annotated CPAN documentation

    http://annocpan.org/dist/WWW-Correios-SRO <http://annocpan.org/dist/WWW-Correios-SRO>

•   CPAN Ratings

    http://cpanratings.perl.org/d/WWW-Correios-SRO <http://cpanratings.perl.org/d/WWW-Correios-SRO>

•   Search CPAN

    http://search.cpan.org/dist/WWW-Correios-SRO/ <http://search.cpan.org/dist/WWW-Correios-SRO/>

AGRADECIMENTOS/ACKNOWLEDGEMENTS
Este modulo na~o existiria sem o servico 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.