PHPackages fagner/laravel-shipping-gateway - 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. [Utility & Helpers](/categories/utility) 4. / 5. fagner/laravel-shipping-gateway ActiveLibrary[Utility & Helpers](/categories/utility) fagner/laravel-shipping-gateway =============================== Gateway unificado de fretes para MelhorEnvio (logística e transporte) v1.0.1(6mo ago)123MITPHPPHP >=8.3 Since Nov 7Pushed 6mo agoCompare [ Source](https://github.com/joaofagner0/laravel-shipping-gateway)[ Packagist](https://packagist.org/packages/fagner/laravel-shipping-gateway)[ RSS](/packages/fagner-laravel-shipping-gateway/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (5)Versions (5)Used By (0) Laravel Shipping Gateway ======================== [](#laravel-shipping-gateway) Gateway unificado para Melhor Envio e Correios com foco em integrações Laravel. A biblioteca expõe uma API simples em português para consultar preços, gerar e imprimir etiquetas, além de oferecer suporte nativo ao ambiente sandbox do Melhor Envio. Índice ------ [](#índice) - [Instalação](#instala%C3%A7%C3%A3o) - [Configuração](#configura%C3%A7%C3%A3o) - [Uso básico](#uso-b%C3%A1sico) - [Melhor Envio - Fluxo Completo](#melhor-envio---fluxo-completo) - [Sandbox do Melhor Envio](#sandbox-do-melhor-envio) - [Logs e observabilidade](#logs-e-observabilidade) - [Testes](#testes) - [Contribuindo](#contribuindo) Instalação ---------- [](#instalação) Adicione o pacote ao seu projeto Laravel via Composer: ``` composer require fagner/laravel-shipping-gateway ``` Configuração ------------ [](#configuração) 1. Registre o `ShippingServiceProvider` na sua aplicação Laravel: - **Laravel <= 10**: adicione `Fagner\LaravelShippingGateway\Providers\ShippingServiceProvider::class` ao array `providers` em `config/app.php`. - **Laravel 11+**: edite `bootstrap/app.php` e inclua o provider dentro de `withProviders`, por exemplo: ``` use Fagner\LaravelShippingGateway\Providers\ShippingServiceProvider; return Application::configure(basePath: dirname(__DIR__)) // ... ->withProviders([ ShippingServiceProvider::class, ]) ->create(); ``` 2. Publique o arquivo de configuração (opcional): ``` php artisan vendor:publish --tag=shipping-config ``` 3. (Opcional) Publique e personalize o arquivo de configuração: ``` php artisan vendor:publish --tag=shipping-config # ou php artisan vendor:publish --tag=laravel-shipping-gateway-config ``` Caso não publique, a lib usa os valores padrão do pacote. 4. Defina as variáveis de ambiente necessárias no `.env` do projeto que consome a lib: ``` SHIPPING_DEFAULT=melhor_envio MELHOR_ENVIO_TOKEN="seu-token" MELHOR_ENVIO_USE_SANDBOX=false MELHOR_ENVIO_BASE_URI=https://www.melhorenvio.com.br/api/v2/ MELHOR_ENVIO_SANDBOX_BASE_URI=https://sandbox.melhorenvio.com.br/api/v2/ CORREIOS_TOKEN=null CORREIOS_BASE_URI=https://api.correios.com.br/ CORREIOS_TIMEOUT=10 ``` 5. Limpe ou recrie o cache de configuração se necessário: ``` php artisan config:clear # ou php artisan config:cache ``` Uso básico ---------- [](#uso-básico) Injete o `ShippingManager` onde precisar e monte um `ShipmentRequest` com os dados do frete. ``` use Fagner\LaravelShippingGateway\DTOs\ShipmentRequest; use Fagner\LaravelShippingGateway\Manager\ShippingManager; class CheckoutController { public function cotar(ShippingManager $shippingManager) { $solicitacao = new ShipmentRequest( cepOrigem: '01001-000', cepDestino: '20040-010', pesoKg: 1.2, comprimentoCm: 20, larguraCm: 15, alturaCm: 10, valor: 100, opcoes: [ 'service_id' => 123, // ID do serviço retornado pela API 'from' => ['zip_code' => '01001-000'], 'to' => ['zip_code' => '20040-010'], // 'products' => [...], // opcional // 'volumes' => [...], // opcional: será gerado automaticamente se omitido ], ); // Cotação individual do provedor configurado como padrão $cotacoes = $shippingManager->driver()->consultarPrecos($solicitacao); // Gerar etiqueta e recuperar PDF em base64 $etiqueta = $shippingManager->driver()->gerarEtiqueta($solicitacao); // Quando precisar reaproveitar o mesmo payload para impressão $etiquetaImpressa = $shippingManager->driver()->imprimirEtiqueta($solicitacao); return response()->json([ 'cotacoes' => $cotacoes, 'etiqueta' => [ 'codigo_rastreio' => $etiqueta->codigoRastreio, 'pdf_base64' => $etiqueta->etiquetaBase64, ], ]); } } ``` ### Consultar preços de todos os provedores [](#consultar-preços-de-todos-os-provedores) ``` $todas = $shippingManager->getRatesFromAllProviders($solicitacao); ``` Melhor Envio - Fluxo Completo ----------------------------- [](#melhor-envio---fluxo-completo) O `MelhorEnvioAdapter` implementa **corretamente** o fluxo oficial da API do Melhor Envio, que consiste em 4 etapas automáticas: 1. **Adicionar ao Carrinho** → `POST /api/v2/me/cart` 2. **Finalizar Compra (Checkout)** → `POST /api/v2/me/shipment/checkout` 3. **Gerar Etiqueta** → `POST /api/v2/me/shipment/generate` 4. **Imprimir Etiqueta** → `POST /api/v2/me/shipment/print` Quando você chama `gerarEtiqueta()` ou `imprimirEtiqueta()`, todas essas etapas são executadas automaticamente. **📚 Para exemplos completos e detalhados de uso do Melhor Envio, consulte:** 👉 **[EXEMPLO\_MELHOR\_ENVIO.md](EXEMPLO_MELHOR_ENVIO.md)** O documento inclui exemplos de: - Consulta de preços e obtenção do `service_id` - Geração de etiquetas com todos os campos obrigatórios - Múltiplos volumes e produtos - Opções de seguro, AR, mão própria - Tratamento de erros - E muito mais! Sandbox do Melhor Envio ----------------------- [](#sandbox-do-melhor-envio) Ative o sandbox definindo `MELHOR_ENVIO_USE_SANDBOX=true` e forneça o endpoint/token apropriado. Consulte a [documentação oficial do Sandbox do Melhor Envio](https://docs.melhorenvio.com.br/docs/sandbox) para gerar credenciais, entender as limitações e simular fluxos com segurança. Logs e observabilidade ---------------------- [](#logs-e-observabilidade) Os adapters emitem logs através de PSR-3 (`psr/log`). Em um projeto Laravel, o logger padrão do framework é detectado automaticamente. Eventos como falhas de requisição, respostas inesperadas ou etiquetas geradas sem conteúdo são registrados com níveis `error`/`warning`, enquanto operações bem-sucedidas de geração de etiqueta são registradas em `info`. Se quiser inspecionar ou customizar os registros, ajuste o canal de log da aplicação ou injete um logger próprio ao resolver o `ShippingManager`. Testes ------ [](#testes) ``` composer install ./vendor/bin/phpunit ``` Os testes utilizam `orchestra/testbench` com mocks do Guzzle, garantindo que as integrações com o Melhor Envio não dependem de chamadas reais. Contribuindo ------------ [](#contribuindo) 1. Faça um fork e crie sua branch (`git checkout -b feature/minha-feature`). 2. Garanta que os testes continuam verdes (`./vendor/bin/phpunit`). 3. Envie um pull request descrevendo suas mudanças. Bug reports e sugestões são bem-vindos! ### Health Score 36 — LowBetter than 82% of packages Maintenance69 Regular maintenance activity Popularity8 Limited adoption so far Community6 Small or concentrated contributor base Maturity53 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 Every ~1 days Total 4 Last Release 182d ago Major Versions v0.2.2 → v1.0.02025-11-11 ### Community Maintainers ![](https://www.gravatar.com/avatar/4f2072951b3282d5d541695c79c3c8864d4f0a6654c515680e988ac08ad5a8c4?d=identicon)[joaofagner0](/maintainers/joaofagner0) --- Top Contributors [![joaofagner0](https://avatars.githubusercontent.com/u/111348255?v=4)](https://github.com/joaofagner0 "joaofagner0 (17 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/fagner-laravel-shipping-gateway/health.svg) ``` [![Health](https://phpackages.com/badges/fagner-laravel-shipping-gateway/health.svg)](https://phpackages.com/packages/fagner-laravel-shipping-gateway) ``` ### Alternatives [illuminate/broadcasting The Illuminate Broadcasting package. 7126.5M178](/packages/illuminate-broadcasting)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 245.2k](/packages/aedart-athenaeum)[nativephp/mobile NativePHP for Mobile 82724.0k43](/packages/nativephp-mobile)[bensampo/laravel-embed Painless responsive embeds for videos, slideshows and more. 142146.8k](/packages/bensampo-laravel-embed)[glhd/conveyor-belt 14797.0k](/packages/glhd-conveyor-belt)[ankurk91/laravel-ses-webhooks Handle AWS SES webhooks in Laravel php framework 2534.2k](/packages/ankurk91-laravel-ses-webhooks) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)