NAME
Net::Correios - acesse a API REST dos Correios
SYNOPSIS
my $correios = Net::Correios->new(
username => 'seu usuario',
password => 'sua chave de API',
contrato => 'seu número de contrato',
cartao => 'numero do seu cartao de postagem',
);
# Busca de CEP
my $cep = $correios->cep->enderecos( cep => '01310-200' );
say $cep->{logradouro}; # "Avenida Paulista"
# Preços e Prazos
my $params = {
codigo => '03220,03298', # SEDEX e PAC
cep_origem => '01310-200', # . e - ignorados
cep_destino => '20021-140', # . e - ignorados
tipo => 'caixa', # caixa, rolo ou envelope
largura => 16, # cm
altura => 16, # cm
comprimento => 16, # cm
peso => 300, # em gramas
valor_declarado => 100, # (opcional) em BRL (reais)
aviso_recebimento => true, # booleano. padrão é falso.
};
my $fretes = $correios->preco->nacional($params);
foreach my $frete (@$frete) {
say $frete->{codigo} . ' custa R$' . $frete->{preco};
}
# você pode usar a mesma estrutura para preço e prazo (de nada):
my $prazos = $correios->prazo->nacional($params);
foreach my $prazo ($@prazos) {
say "$prazo->{codigo} deve chegar até dia $prazo->{data_maxima}"
. "($prazo->{dias} dias)";
}
# Rastreio de Objetos
my $rastreio = $correios->sro->busca( 'YJ460348417BR', 'QP302718234BR' );
say $rastreio->{YJ460348417BR}{situacao};
foreach my $evento ($rastreio->{YJ460348417BR}{eventos}->@*) {
say $evento->{descricao};
}DESCRIPTION
This module provides a way to query the Brazilian Postal Office (Correios) via its REST API, regarding fees, estimated delivery times, etc. Since the main audience for this module are Brazilian developers, the documentation is provided in portuguese only. If you need help with this module but don't speak portuguese, please contact the author.
DESCRIÇÃO
Este módulo oferece acesso à API REST dos Correios - também conhecida como Correios Web Services ou CWS, ou mesmo "Correios API" - para consulta de preços e prazos, CEPs, rastreamento de objetos, etc.
Requisitos
Para acessar a API REST dos Correios, você precisa:
1. Ter um contrato comercial ativo com os Correios; 2. Ter um cadastro no Meu Correios; 3. Acessar o site do Correios Web Services em https://cws.correios.com.br, fazer o login, clicar em "Gestão de Acesso a APIs" e depois em "Regerar Código". Isso vai te dar uma chave/código de API para usar com este módulo.
Para usar esse módulo no ambiente de testes dos Correios, repita o passo 3 no site de homologação do CWS: https://cwshom.correios.com.br.
Procure seu contato nos Correios caso tenha dificuldade com qualquer um desses passos.
CONSTRUTOR
new( %args )
my $correios = Net::Correios->new(
username => 'seu usuario',
password => 'sua chave de API',
contrato => 'seu número de contrato',
cartao => 'seu cartao de postagem',
);Cria um novo objeto para se comunicar com a API dos Correios. Este objeto pode ser reaproveitado em todos os endpoints que seu programa usar, já que ele faz automaticamente a gestão dos tokens de acesso à API.
Depurando requisições à API
Muitas vezes, para depuração, pode ser interessante observar exatamente como está sendo feita a chamada. Este módulo possui uma opção "debug" que você pode passar ao construtor com um valor verdadeiro. Nesse caso, junto com a requisição, o módulo vai imprimir no STDERR o comando 'curl' equivalente da sua requisição, assim como a resposta tal como ela veio dos servidores dos Correios.
Utilize para enviar ao suporte dos Correios sempre que achar algo errado, eles podem usar esse formato para identificar e resolver problemas (relacionado ao seu uso incorreto ou a algum outro problema.
ATRIBUTOS
is_sandbox
Retorna verdadeiro se o objeto está acessando o ambiente de sandbox/homologação dos Correios, falso se estiver acessando o ambiente de produção.
access_token( $tipo )
Retorna o token de acesso atual para o tipo solicitado. Você provavelmente não precisa se preocupar com isso já que a criação e renovação dos tokens de acesso são feitas automaticamente por este módulo e seus submódulos.
debug( $bool )
Ativa/desativa o modo de depuração. Ver "Depurando requisições à API" acima.
MÉTODOS
cep
Retorna um objeto Net::Correios::CEP para busca de CEP e endereços.
sro
Retorna um objeto Net::Correios::SRO para consulta de códigos de rastreio e comprovantes de entrega de pacotes dos Correios.
preco
Retorna um objeto Net::Correios::Preco para consulta de preços (tarifas) para envios de encomendas/pacotes/postagens em diferentes tamanhos e formatos.
prazo
Retorna um objeto Net::Correios::Prazo para consulta de prazos de entrega para envios de encomendas.
token
Retorna um objeto Net::Correios::Token para autenticação com a API. Note que a autenticação e renovação de chaves é feita automaticamente por este módulo, de modo que você provavelmente não precisará usar este método diretamente.
empresas
Retorna um objeto Net::Correios::Empresas para consulta de contratos e serviços disponíveis.
prepostagens
Retorna um objeto Net::Correios::Prepostagens para consulta e criação de PLP/PPN (Pré-Postagens), emissão de rótulos (etiquetas) e geração de Declaração de Conteúdo Eletrônica (DCe).
manifestacao
Retorna um objeto Net::Correios::Manifestacao para cadastro/registro de manifestações nos Correios em caso de pedidos violados, devolvidos, não entregues, atrasados, etc.
faturas
TBD
agencias
TBD
VEJA TAMBÉM
Correios Web Services (link externo oficial)