The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WWW-Correios-SIGEP-0.03
River stage zero No dependents
++
/ WWW::Correios::SIGEP::LogisticaReversa

NAME

WWW::Correios::SIGEP::LogisticaReversa - API de Logística Reversa dos Correios (SIGEP WEB)

SYNOPSIS

usando diretamente:

    use WWW::Correios::SIGEP::LogisticaReversa;

    my $correios = WWW::Correios::SIGEP::LogisticaReversa->new({
        usuario => ...,
        senha   => ...,
    });

    my $res = $correios->solicitar_postagem_reversa( {...} );

    my $pedido = $res->{resultado_solicitacao}[0];
    die $pedido->{descricao_erro} if $pedido->{codigo_erro};

    say 'postagem reversa código ' . $pedido->{numero_coleta}
      . ' com validade até ' . $pedido->{prazo};

você também pode acessar esse módulo dinamicamente através do WWW::Correios::SIGEP:

    use WWW::Correios::SIGEP;

    my $correios = WWW::Correios::SIGEP->new( {...} );
    $correios->logistica_reversa->solicitar_postagem_reversa( {...} );

IMPORTANTE: NECESSITA DE CONTRATO COM OS CORREIOS

Este módulo funciona como interface para o Web Service de Logística Reversa dos Correios, usado essencialmente para solicitar postagens reversas (devoluções de produtos) pagas pela empresa solicitante. Para que isso faça sentido, você precisa ter um contrato de prestação de serviços dos Correios.

Caso não tenha, entre em contato com os Correios para obter seu cartão de parceria empresarial ANTES de tentar usar esse módulo.

MÉTODOS

new( \%opcoes )

Cria o objeto cliente das requisições para o Web Service de Logística Reversa. Aceita os seguintes parâmetros (parâmetros obrigatórios estão demarcados):

  • usuario [OBRIGATÓRIO] Seu nome de usuário para o Web Service, conforme contrato com os Correios. Se você não passar esse campo durante a inicialização do objeto, precisará passar como valor em cada requisição (pode ser útil para gerir chamadas com vários contratos diferentes a partir do mesmo objeto).

  • senha [OBRIGATÓRIO] Sua senha para o Web Service, conforme contrato com os Correios. Se você não passar esse campo durante a inicialização do objeto, precisará passar como valor em cada requisição (pode ser útil para gerir chamadas com vários contratos diferentes a partir do mesmo objeto).

  • sandbox Se verdadeiro, utiliza os endpoints de sandbox dos Correios para todas as chamadas. Utilize esse modo para testar chamadas e valores de resposta da API sem gastar dinheiro ou consumir códigos reais. Note que você ainda precisará passar todos os parâmetros (e eles serão validados da mesma forma). Em teoria, após concluir sua homologação, basta remover essa flag e todas as chamadas continuarão rigorosamente iguais - só que agora custando/valendo de verdade.

  • debug Se verdadeiro, imprime no terminal detalhes do request, response e eventuais erros associados ao envio/recebimento do envelope SOAP. Utilize essa flag para depurar suas chamadas caso acredite que há algum problema na composição do request ou na interpretação da resposta.

  • timeout Timeout em segundos para as requisições à API dos Correios. Padrão 180 segundos (2 minutos).

  • precompile por padrão, as chamadas a este módulo são todas preguiçosas, ou seja, cada operação é compilada na primeira vez em que é utilizada. Escolhemos essa abordagem para evitar um tempo alto de inicialização (e maior quantidade de memória utilizada) caso apenas uma ou outra operação seja de fato utilizada. Se preferir, pode passar uma lista de operações nesse parâmetro para pré-compilar. Assim, a inicialização do objeto demora um pouco mais, mas não há penalidade durante a primeira execução da operação. Note que você precisará utilizar o nome da operação em camelCase conforme a documentação dos Correios:

       precompile => [ 'solicitarPostagemReversa' ]

solicitar_postagem_reversa( \%opcoes )

Este método processa o pedido de autorização de postagem ou coleta nos Correios. Poderá ser efetuado até 50 solicitações simultâneas em uma única chamada, sendo uma lista de coletas_solicitadas.

Consulte a documentação dos Correios para uma descrição de cada parâmetro, e se são obrigatórios ou opcionais.

Um exemplo de requisição válida (que pode ser testada na sandbox):

    my $res = $correios->solicitar_postagem_reversa({
        usuario           => '60618043',
        senha             => '8o8otn',
        codAdministrativo => '08082650',
        contrato          => '9912208555',
        codigo_servico    => '41076',
        cartao            => '0057018901',
        destinatario      => {
            nome        => 'Fulano',
            logradouro  => 'Qd 301',
            numero      => '10',
            complemento => 'Residencial Central',
            bairro      => 'Centro',
            cep         => '70002900',
            cidade      => 'Brasília',
            uf          => 'DF',
            referencia  => '',
            ddd         => '61',
            telefone    => '6133331234',
            email       => 'sigepdestinatario@mailinator.com',
        },
        coletas_solicitadas => {
            id_cliente => '102030',
            remetente => {
                nome          => 'Ciclano',
                logradouro    => 'Rua João Negrão',
                numero        => '1251',
                complemento   => 'Bloco II',
                bairro        => 'Centro',
                cep           => '80002900',
                cidade        => 'Curitiba',
                uf            => 'PR',
                # email com número de postagem será enviado pelos Correios para:
                email         => 'sigepremetente@mailinator.com',,
            },
            tipo            => 'A', # (A)utorização, (C)oleta, ou (CA) para ambos
            valor_declarado => '399.00',
            ag              => '10',
            ar              => 0,
            obj_col         => { item => 1 },
        }
    });

O valor de retorno, nesse caso, conterá uma estrutura na forma:

    $res = {
        cod_erro              => "00",
        data_processamento    => "20/10/2016",
        hora_processamento    => "17:41",
        msg_erro              => "",
        resultado_solicitacao => [
            {
                codigo_erro      => 0,
                data_solicitacao => "20/10/2016",
                descricao_erro   => "",
                hora_solicitacao => "17:41",
                id_cliente       => 1,
                numero_coleta    => "225319229",
                numero_etiqueta  => "",
                prazo            => "30/10/2016",
                status_objeto    => "01",
                tipo             => "A"
            }
        ]
    };

cancelar_pedido( \%opcoes )

Cancela um número de autorização de postagem que ainda não tenha sido utilizado. Como exemplo, para cancelar o número solicitado no exemplo de solicitar_postagem_reversa(), faríamos algo como:

    my $res = $correios->cancelar_pedido({
        usuario           => '60618043',
        senha             => '8o8otn',
        codAdministrativo => '08082650',
        numeroPedido      => '225319229',
        tipo              => 'A',
    });

e a resposta seria na forma:

    $res = {
        codigo_administrativo => "8082650",
        objeto_postal         => {
            datahora_cancelamento => "22/10/2016 12:26",
            numero_pedido         => "225319229",
            status_pedido         => "Desistência do Cliente ECT"
        }
    }

acompanhar_pedido( \%opcoes )

Quando houver a postagem em uma unidade dos Correios, este método retornará o número da etiqueta de registro através da chave numero_etiqueta. Utilize esse número para acompanhar o rastreamento do objeto. Exemplo:

    my $res = $correios->acompanhar_pedido({
        usuario           => '60618043',
        senha             => '8o8otn',
        codAdministrativo => '08082650',
        numeroPedido      => '225319229',
        tipoBusca         => 'H', # (H => todos, U => última)
        tipoSolicitacao   => 'A', # (A => autorização, C => coleta, L => domiciliar)
    });

Como neste exemplo passamos "H" como tipo de busca, a resposta inclui todo o histórico da solicitação, bem como o último status:

    $res = {
        codigo_administrativo => "8082650",
        coleta => [
            {
                controle_cliente => 1,
                historico        => [
                    {
                        data_atualizacao => "20-10-2016",
                        descricao_status => "Aguardando Objeto na Ag�ncia",
                        hora_atualizacao => "17:41:03",
                        observacao       => "",
                        status           => "55",
                    },
                    {
                        data_atualizacao => "22-10-2016",
                        descricao_status => "Desist�ncia do Cliente ECT",
                        hora_atualizacao => "12:26:31",
                        observacao       => "",
                        status           => 9
                    }
                ],
                numero_pedido => "225319229",
                objeto        => [
                    {
                        controle_objeto_cliente => "",
                        data_ultima_atualizacao => "20-10-2016",
                        descricao_status        => "Aguardando Objeto na Ag�ncia",
                        hora_ultima_atualizacao => "17:41:03",
                        numero_etiqueta         => "",
                        ultimo_status           => "55"
                    }
                ]
            }
        ],
        tipo_solicitacao => "A"
    }

Nota do autor: Repare que na resposta acima os dados na chave historico estão mais atualizados do que os dados na chave objeto. Pode ser apenas uma questão do ambiente de homologação dos Correios. Por garantia, minha sugestão é usar o tipoBusca como "U" e pegar o status da (única) ocorrência retornada no historico.

AGRADECIMENTOS

Este módulo não existiria sem a interface SIGEP WEB disponibilizada pelos Correios.

AUTOR

Breno G. de Oliveira <garu@cpan.org>

LICENÇA E COPYRIGHT

Copyright (c) 2016, Breno G. de Oliveira. Todos os direitos reservados.

Este módulo é software livre; você pode redistribuí-lo e/ou modificá-lo sob os mesmos termos que o Perl. Veja perlartistic.

Este módulo não vem com nenhuma garantia. Use sob sua própria conta e risco.

VEJA TAMBÉM

WWW::Correios::SIGEP