WWW::Correios::SIGEP::LogisticaReversa - API de Logística Reversa dos Correios (SIGEP WEB)
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( {...} );
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.
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).
usuario
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).
senha
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.
sandbox
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.
debug
timeout Timeout em segundos para as requisições à API dos Correios. Padrão 180 segundos (2 minutos).
timeout
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
precompile => [ 'solicitarPostagemReversa' ]
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" } ] };
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:
solicitar_postagem_reversa()
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" } }
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:
numero_etiqueta
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:
"H"
$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.
historico
objeto
tipoBusca
"U"
Este módulo não existiria sem a interface SIGEP WEB disponibilizada pelos Correios.
Breno G. de Oliveira <garu@cpan.org>
<garu@cpan.org>
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.
WWW::Correios::SIGEP
To install WWW::Correios::SIGEP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WWW::Correios::SIGEP
CPAN shell
perl -MCPAN -e shell install WWW::Correios::SIGEP
For more information on module installation, please visit the detailed CPAN module installation guide.