Download the PHP package eberfreitas/correios without Composer

Correios

Um pacote para interagir com serviços dos Correios.

Recursos

• Encontra endereço a partir de um CEP;
• Pega dados de rastreio de pacotes;
• Calcula preços e prazos de entrega.

Acha que está faltando algo? Abra um issue!

Por quê?

Já existem diversos pacotes que trabalham com os serviços dos Correios, mas sempre existia algo que me impedia de usar algum deles, seja porque ele havia sido feito especificamente para algum software ou framework, ou porque ele não tinha todos os recursos que eu precisava, etc. A ideia então foi tentar um novo pacote com os seguintes objetivos:

• Stand-alone: para ser usado em qualquer projeto/framework com o mínimo de dependências extras possível;
• Feature complete: tentar cobrir o máximo de recursos que os Correios oferecem através de APIs oficiais ou não;
• PSR compliant: O autoload é compatível com PSR-4 e a formatação PSR-2;
• Testes: Tentar testar a biblioteca o máximo possível.

Instalação

Pelo Composer:

Como usar

Para usar a biblioteca, antes de tudo, você precisa criar uma instância:

Isto já deve ser suficiente para começar a utilizar a biblioteca. Opcionalmente você pode configurar a sua instância de forma diferente. O construtor da classe aceita um array com as seguintes chaves:

Exemplo:

Embora você tenha a opção de providenciar um adaptador, se você não indicar nenhum, a biblioteca irá utilizar o Guzzle por padrão.

Encontrando um endereço via CEP

Para encontrar um endereço a partir de um CEP, basta usar o método endereco:

Que resulta neste output:

No caso de falha na consulta serão emitidos exceptions. Fique atento para pegá-los quando necessário. Na dúvida, verifique o código-fonte. Ele é bem documentado e deve te ajudar a entender cada método corretamente.

Rastreando um pacote

Para rastrear um pacote basta utilizar o método rastreamento:

Que resulta neste output:

Como você pode ver, temos um array associativo com diversos dados referentes a cada evento relativo ao pacote sendo consultado. Cada entrada diz respeito a um evento e possui as seguintes chaves:

Uma nota sobre a consulta de pacotes: Os Correios fornecem um webservice específico para a consulta de pacotes, porém este webservice é reservado a clientes que possuem contrato. Sendo assim, a biblioteca realiza um processo de "web scraping" para extrair os dados de páginas comuns de consulta. Embora a página sendo utilizada já tenha demonstrado uma estabilidade de anos no que diz respeito à sua estrutura, qualquer alteração no HTML desta página pode fazer este método falhar.

Calculando valor de frete e prazo de entrega

Para calcular o valor de uma entrega e seu prazo, basta utilizar o método calculaFrete:

Diferente dos outros métodos, este método recebe um array com um bocado de opções para que o cálculo seja realizado. Vamos dar uma olhada no que eles são:

Os valores não obrigatórios serão preenchidos por valores padrão minimamente sãos. Fique de olho para garantir que o valor calculado esteja de acordo com as reais condições de envio.

A chamada acima vai produzir o seguinte output:

Veja que temos o retorno de um array cujos elementos são instâncias da classe Correios\Calculo. Esta é uma classe simples que de dá acesso aos dados do resultado da consulta como um array ou um objeto:

Os dados disponíveis são os seguintes:

Calculando uma data de entrega

Lembra que o resultado da consulta traz um objeto? Ele tem alguns métodos interessantes que podem te ajudar a manipular melhor os dados de retorno da consulta de preço e prazo. Um destes métodos é o calculaEntrega. Com ele a gente consegue ter uma data de estimativa de entrega. Veja:

Que resulta neste output:

Veja que o método recebe um objeto DateTime e retorna um objeto DateTime representando a data de entrega. O método vai levar em consideração se, a partir da data de envio, a soma do prazo cai em algum dia do fim de semana, e ajusta a data para o próximo dia útil seguinte, a não ser que a entrega caia num sábado e o endereço de entrega possua o valor da chave entrega_sabado como true.

Formatando valores

Você também pode retornar facilmente os valores de envio já formatados. Veja:

Que resulta neste output:

O valor será formatado de acordo com o padrão monetário brasileiro. Se você quiser, pode omitir o prefixo "R$" passando false no segundo argumento:

Você pode realizar esta formatação para qualquer chave de valor suprida pela consulta.

Ajuste inteligente de pacotes

Nenhum dos valores de dimensões dos pacotes é obrigatório de ser preenchido. Desta forma a biblioteca usa padrões que fazem sentido pra maioria dos envios e deve retornar valores adequados. Se você quiser personalizar os valores das dimensões, a biblioteca automaticamente ajusta estes valores caso eles estejam fora dos padrões definidos pelos Correios. Existem diversas regras que definem quais são as dimensões permitidas, inclusive para cada tipo de formato diferente.

Sendo assim, a biblioteca vai verificar qual o formato definido, as regras para este formato e vai tentar ajustar as dimensões para que o cálculo aconteça sem errors.

Se você desejar que a biblioteca não faça este ajuste automaticamente, basta chamar o método da seguinte forma:

Tabela de serviços

Aqui estão alguns dos códigos e suas respectivas descrições para consulta:

Usando um http adapter diferente

Por padrão a biblioteca irá usar o Guzzle para realizar as requisições http aos endpoints dos webservices e páginas usados pela biblioteca. Se você quiser, poderá utilizar outro pacote no lugar do Guzzle fornecendo um novo objeto na hora de instanciar a classe dos Correios.

Para isto você deve criar uma classe intermediária que implemente a interface Correios\Adapters\AdapterInterface que possui apenas dois métodos: get e post.

Ambos os métodos devem retornar uma string representando o corpo da resposta da requisição e qualquer erro no processo de requisição deve ser indicado através da utilização de exceptions.

Veja uma implementação exemplo aqui.

Créditos

• Criado por Éber F. Dias
• Com o auxilio de Tiago Correa
• Patrocinado por Tanlup