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.

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.

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

TBD

prepostagens

TBD

faturas

TBD

agencias

TBD

VEJA TAMBÉM

Correios Web Services (link externo oficial)

cpanm Net::Correios

perl -MCPAN -e shell
install Net::Correios