PHPackages lucasbrito-wdt/correios - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [HTTP & Networking](/categories/http) 4. / 5. lucasbrito-wdt/correios ActiveLibrary[HTTP & Networking](/categories/http) lucasbrito-wdt/correios ======================= Pacote Laravel para integração com as APIs do CWS (Correios Web Services) — Token, CEP, Preço, Prazo, Rastro e Pré-Postagem. v1.0.0(1mo ago)04MITPHPPHP ^8.2 Since May 2Pushed 1mo agoCompare [ Source](https://github.com/lucasbrito-wdt/correios)[ Packagist](https://packagist.org/packages/lucasbrito-wdt/correios)[ RSS](/packages/lucasbrito-wdt-correios/feed)WikiDiscussions master Synced 1w ago READMEChangelog (1)Dependencies (6)Versions (2)Used By (0) Laravel Correios — Pacote de integração com o CWS ================================================= [](#laravel-correios--pacote-de-integração-com-o-cws) Pacote Laravel para integrar com as APIs do CWS (Correios Web Services): Token, CEP, Preço, Prazo, Rastro e Pré-Postagem. Arquitetura limpa com **classe abstrata base**, **services especializados**, **DTOs**, **Form Requests para validação**, **token JWT cacheado no Redis** e **retry automático em 401**. Requisitos ---------- [](#requisitos) - PHP 8.2+ - Laravel 11 ou 12 - Contrato ativo com os Correios + cartão de postagem - Credenciais geradas no portal `cws.correios.com.br` Instalação ---------- [](#instalação) ``` composer require codifytech/laravel-correios ``` Publique a config: ``` php artisan vendor:publish --tag=correios-config ``` Configuração ------------ [](#configuração) Adicione no `.env`: ``` CORREIOS_AMBIENTE=homologacao # ou 'producao' CORREIOS_USUARIO=seu_id_correios CORREIOS_CODIGO_ACESSO=seu_codigo_gerado_no_cws CORREIOS_CARTAO_POSTAGEM=0070123456 CORREIOS_CONTRATO=9912345678 CORREIOS_TIPO_AUTH=cartao_postagem # ou 'contrato' / 'usuario' CORREIOS_CACHE_STORE=redis ``` Estrutura do pacote ------------------- [](#estrutura-do-pacote) ``` src/ ├── Contracts/ # Interfaces (DTO, TokenManager) ├── DTOs/ # Data Transfer Objects por domínio │ ├── Cep/EnderecoDTO.php │ ├── Preco/CotacaoPrecoRequestDTO.php │ ├── Preco/CotacaoPrecoResponseDTO.php │ ├── Prazo/PrazoResponseDTO.php │ ├── Rastro/EventoRastroDTO.php │ ├── Rastro/ObjetoRastreadoDTO.php │ └── PrePostagem/... ├── Exceptions/ # CorreiosException, Autenticacao, Request, Validacao ├── Facades/Correios.php # Facade Laravel ├── Http/ │ ├── Client/ │ │ ├── TokenManager.php # Gerencia JWT (cache + renovação) │ │ └── CorreiosHttpClient.php # Wrapper Http::baseUrl + auth + retry │ └── Requests/ # Form Requests para validação │ ├── AbstractCorreiosRequest.php │ ├── CotacaoPrecoRequest.php │ ├── CotacaoPrazoRequest.php │ ├── ConsultaCepRequest.php │ ├── PrePostagemRequest.php │ └── RastreioRequest.php ├── Services/ │ ├── AbstractCorreiosService.php # 🟢 Classe abstrata base │ ├── CepService.php │ ├── PrecoService.php │ ├── PrazoService.php │ ├── RastroService.php │ ├── PrePostagemService.php │ └── CorreiosManager.php # Fachada agregadora ├── Support/LogHelper.php # Logging com mascaramento de credenciais └── Providers/CorreiosServiceProvider.php ``` Fluxo de autenticação (resumo) ------------------------------ [](#fluxo-de-autenticação-resumo) 1. `TokenManager` checa o Redis pela chave `correios:token` 2. Se não existir, faz `POST /token/v1/autentica/cartaopostagem` com Basic Auth 3. Cacheia o JWT por 23h (1h de margem antes do vencimento real de 24h) 4. Toda chamada subsequente injeta `Authorization: Bearer {jwt}` automaticamente 5. Se algum endpoint devolver `401`, o cache é invalidado e o token regenerado em retry Como usar --------- [](#como-usar) ### Via Facade [](#via-facade) ``` use Correios\Facades\Correios; use Correios\DTOs\Preco\CotacaoPrecoRequestDTO; // CEP $endereco = Correios::cep()->consultar('58015-430'); echo $endereco->logradouro; // Cotação de frete $cotacao = Correios::preco()->cotar( CotacaoPrecoRequestDTO::fromArray([ 'coProduto' => '03220', // SEDEX 'cepOrigem' => '58015430', 'cepDestino' => '01001000', 'psObjeto' => 1500, // gramas 'comprimento'=> 30, 'largura' => 20, 'altura' => 10, ]) ); echo "Frete: R$ {$cotacao->pcFinal}"; // Prazo $prazo = Correios::prazo()->calcular('03220', '58015430', '01001000'); echo "Prazo: {$prazo->prazoEntrega} dias úteis"; // Rastreio $objeto = Correios::rastro()->rastrear('BR123456789BR'); echo $objeto->ultimoEvento()->descricao; echo $objeto->foiEntregue() ? 'Entregue!' : 'Em trânsito'; ``` ### Via injeção de dependência (recomendado) [](#via-injeção-de-dependência-recomendado) ``` use Correios\Services\PrecoService; class CalcularFreteAction { public function __construct( private readonly PrecoService $precoService, ) {} public function __invoke(CotacaoPrecoRequest $request): CotacaoPrecoResponseDTO { $dto = CotacaoPrecoRequestDTO::fromArray($request->validated()); return $this->precoService->cotar($dto); } } ``` ### Cotação em lote (até 100) [](#cotação-em-lote-até-100) ``` $resultados = Correios::preco()->cotarLote([ CotacaoPrecoRequestDTO::fromArray([...]), CotacaoPrecoRequestDTO::fromArray([...]), // ... ]); ``` ### Pré-Postagem (gerar etiqueta) [](#pré-postagem-gerar-etiqueta) ``` use Correios\DTOs\PrePostagem\PrePostagemRequestDTO; $pre = Correios::prePostagem()->criar( PrePostagemRequestDTO::fromArray([ 'codigoServico' => '03220', 'pesoGramas' => 1500, 'dimensoes' => ['altura' => 10, 'largura' => 20, 'comprimento' => 30], 'remetente' => [...], 'destinatario' => [...], 'itens' => [ ['descricao' => 'Camiseta personalizada', 'quantidade' => 1, 'valor' => 89.90], ], 'numeroNotaFiscal' => '12345', 'chaveNotaFiscal' => '35200114200166000187550010000000071123456789', ]) ); echo "Código: {$pre->codigoObjeto}"; // Gerar PDF da etiqueta $rotulo = Correios::prePostagem()->gerarRotulo($pre->id); ``` Pontos de extensão ------------------ [](#pontos-de-extensão) ### Criando um service novo [](#criando-um-service-novo) Estenda `AbstractCorreiosService`: ``` namespace App\Correios; use Correios\Services\AbstractCorreiosService; class MeuServiceCustom extends AbstractCorreiosService { protected function basePath(): string { return '/meu-endpoint/v1'; } public function minhaOperacao(array $payload): array { return $this->post('/operacao', $payload); } } ``` Registre no seu `AppServiceProvider`: ``` $this->app->singleton(MeuServiceCustom::class, fn ($app) => new MeuServiceCustom( $app->make(\Correios\Http\Client\CorreiosHttpClient::class) )); ``` Pronto — autenticação, retry, logging e tratamento de erros já vêm de graça. Testes ------ [](#testes) ``` composer install vendor/bin/phpunit ``` Use `Http::fake()` pra simular as respostas do CWS. Boas práticas ------------- [](#boas-práticas) - **Sempre comece em homologação** (`apihom.correios.com.br`) antes de mudar pra produção - **Cacheie cotações de frete por CEP+peso** — os Correios cobram por consulta em alguns contratos - **Use jobs em fila pro polling de rastreio** — não consulte sob demanda do usuário - **Faça webhook ou polling agendado** — armazene histórico no seu banco pra timeline rica no painel - **Monitore o status code 401** — se aparecer com frequência, sua chave de acesso pode ter sido revogada (validade de 180 dias para subdelegações) Códigos de serviço comuns ------------------------- [](#códigos-de-serviço-comuns) CódigoServiço03220SEDEX (contrato)03298PAC (contrato)04162SEDEX (varejo)04510PAC (varejo)04669SEDEX 1204227SEDEX 10Códigos de eventos de rastreio mais relevantes ---------------------------------------------- [](#códigos-de-eventos-de-rastreio-mais-relevantes) CódigoSignificadoBDE/BDI/BDRObjeto entregueOECSaiu para entregaLDIAguardando retiradaROEncaminhadoPOPostadoLicença ------- [](#licença) MIT ### Health Score 39 — LowBetter than 84% of packages Maintenance92 Actively maintained with recent releases Popularity5 Limited adoption so far Community6 Small or concentrated contributor base Maturity46 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 38d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/f7804accedd190804443c7150e8f0185530d3db578825b437e4e59010aae1d6c?d=identicon)[lucasbrito-wdt](/maintainers/lucasbrito-wdt) --- Top Contributors [![lucasbrito-wdt](https://avatars.githubusercontent.com/u/30214900?v=4)](https://github.com/lucasbrito-wdt "lucasbrito-wdt (2 commits)") --- Tags laravelcorreiosfreterastreiocwsetiquetapre-postagem ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/lucasbrito-wdt-correios/health.svg) ``` [![Health](https://phpackages.com/badges/lucasbrito-wdt-correios/health.svg)](https://phpackages.com/packages/lucasbrito-wdt-correios) ``` ### Alternatives [spatie/laravel-responsecache Speed up a Laravel application by caching the entire response 2.8k8.7M64](/packages/spatie-laravel-responsecache)[laravel/mcp Rapidly build MCP servers for your Laravel applications. 76318.2M110](/packages/laravel-mcp)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9732.3M121](/packages/roots-acorn)[propaganistas/laravel-disposable-email Disposable email validator 6012.9M7](/packages/propaganistas-laravel-disposable-email)[psalm/plugin-laravel Psalm plugin for Laravel 3325.1M337](/packages/psalm-plugin-laravel)[api-platform/laravel API Platform support for Laravel 59156.3k10](/packages/api-platform-laravel) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)