NAME

Net::Correios::SRO - consulte o rastreio de pacotes dos Correios

SINOPSYS

    my $correios = Net::Correios->new( %credenciais );

    my $rastreio = $correios->sro->busca( 'TF884516597BR', 'YJ460348417BR' );

DESCRIÇÃO

Este módulo oferece uma interface para consulta ao Serviço de Rastreamento de Objetos (SRO) dos Correios.

MÉTODOS

busca( @codigos )

busca( $tipo, @codigos )

    # busca pelo rastreio de 1 código:
    $sro = $correios->sro->busca( 'YJ460348417BR' );

    # busca pelo rastreio de N códigos:
    $sro = $correios->sro->busca( 'YJ460348417BR', 'QP302718234BR' );

    # o primeiro parâmetro pode explicitar o tipo (padrão é 'T'):
    $sro = $correios->sro->busca( 'U', 'QP302718234BR' );

    say $sro->{'QP302718234BR'}{'peso'};
    say $sro->{'QP302718234BR'}{'eventos'}[0]{descricao};

O método busca() é uma versão incrementada do método objetos() abaixo e foi criado como seu substituto.

Ele recebe um ou mais códigos de rastreio de objetos dos Correios e retorna um hashref em que cada chave é um desses códigos. Por padrão a lista de eventos de rastreio inclui todos os eventos, mas você pode passar o tipo explicitamente como primeiro parâmetro ('P' para primeiro evento, 'U' para último, ou 'T' para todos).

O conteúdo (valor) de cada chave é um hashref com as mesmas informações obtidas pela consulta a objetos(). Se o tipo de evento for 'T' (padrão) ou 'U', a estrutura será acrescida do campo situacao que pode conter os seguintes valores:

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

objetos( objetos => \@codigos, resultado => $tipo )

    my $sro = $correios->sro->objetos(
        objetos   => ['QP302718234BR', 'YJ460348417BR'],
        resultado => 'U',
    );

    foreach my $obj ($sro->{objetos}->@*) {
        say $obj->{codObjeto};
        say $obj->{peso};
        say $obj->{eventos}[0]{descricao};
    }

Interface direta para a chamada ao endpoint "objetos" da API dos Correios. Recebe uma lista de objetos e um tipo de resultado para os eventos ('U' para só retornar o último evento registrado, 'T' para todos os eventos e 'P' para retornar apenas o primeiro evento registrado). Retorna uma estrutura que lista os objetos dentro da chave 'objetos', em nenhuma ordem garantida.

Para simplificar a consulta e acesso aos dados de rastreio, recomendamos o uso do método buscar em vez deste.

sro_ok( $codigo )

    say "código inválido!"
        unless $correios->sro->sro_ok( 'QP302718234BR' );

Retorna verdadeiro se o código de rastreamento passado é válido, caso contrário retorna falso. 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.

Note que essa função não elimina espaços da string, você deve fazer sua própria higienização antes de testar valores, ou ela pode retornar falso-negativos.

nome_do_evento( $codigo_do_evento, $tipo_do_evento )

Recebe o código e o tipo de um evento retornado pelos Correios e traduz para um nome de fácil compreensão ('acompanhar', 'entregue', 'erro', 'retirar' ou 'incompleto'). Esse método é usado internamente pelo método busca() para traduzir a situação do último evento de um rastreio. (veja a documentação do busca() para mais detalhes).

VEJA TAMBÉM

Net::Correios