PHPackages zdearo/meli-php - 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. [API Development](/categories/api) 4. / 5. zdearo/meli-php ActiveLibrary[API Development](/categories/api) zdearo/meli-php =============== A Laravel-focused PHP SDK for integrating with the Mercado Libre API. Provides modern Laravel features like Facades, Service Providers, and HTTP Client integration. 2.0.0(2mo ago)4611MITPHPPHP ^8.3 Since Aug 26Pushed 2mo ago1 watchersCompare [ Source](https://github.com/zdearo/meli-php)[ Packagist](https://packagist.org/packages/zdearo/meli-php)[ RSS](/packages/zdearo-meli-php/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (8)Dependencies (12)Versions (10)Used By (0) Mercado Libre PHP SDK ===================== [](#mercado-libre-php-sdk) A modern Laravel package for integrating with the Mercado Libre API. Provides typed DTOs, custom exceptions, automatic pagination, optional retry, and a clean Facade interface. Features -------- [](#features) - **Complete API Coverage**: 11 services covering all major Mercado Libre API endpoints - **Typed DTOs**: Readonly data objects with IDE autocomplete (`Product`, `Order`, `User`, `Payment`, `Question`, `Category`, `AuthToken`) - **Custom Exceptions**: Typed exceptions for every API error (`MeliNotFoundException`, `MeliValidationException`, `MeliAuthException`, etc.) - **Lazy Pagination**: Automatic page-by-page iteration via `LazyCollection` - **Optional Retry**: Configurable retry with backoff for rate limits (429) and server errors (5xx) - **Multi-Tenancy**: Per-request token resolution with `withToken()` and `forConnection()` - **Multi-Region**: Support for all 19 Latin American marketplaces - **Laravel Boost**: Includes AI guidelines and skills for AI-assisted development - **Modern PHP**: PHP 8.3+ with readonly classes, enums, and named arguments Requirements ------------ [](#requirements) - PHP 8.3+ - Laravel 9.0+ Installation ------------ [](#installation) ``` composer require zdearo/meli-php ``` The package will be auto-discovered by Laravel. Configuration ------------- [](#configuration) Publish the configuration file: ``` php artisan vendor:publish --tag=meli-config ``` Configure your environment variables in `.env`: ``` MELI_REGION=BRASIL MELI_CLIENT_ID=your-client-id MELI_CLIENT_SECRET=your-client-secret MELI_REDIRECT_URI=https://your-app.com/callback MELI_AUTH_DOMAIN=mercadolibre.com.br MELI_API_TOKEN=your-api-token # Optional: retry on rate limit / server errors (disabled by default) MELI_RETRY_TIMES=0 MELI_RETRY_SLEEP_MS=500 ``` Quick Start ----------- [](#quick-start) ### Basic Usage [](#basic-usage) ``` use Zdearo\Meli\Facades\Meli; // Get a product — returns Product DTO $product = Meli::products()->get('MLB123456789'); $product->title; // string $product->price; // float $product->status; // string // Search products — returns SearchResult DTO $results = Meli::searchItem()->byQuery('smartphone samsung'); $results->results; // array $results->total; // int // Get user — returns User DTO $user = Meli::users()->me(); $user->nickname; // string // Get orders — returns SearchResult with Order DTOs $orders = Meli::orders()->getBySeller(123456789); $orders->results; // array ``` ### Authentication (OAuth 2.0) [](#authentication-oauth-20) ``` use Zdearo\Meli\Facades\Meli; // Generate authorization URL $authUrl = Meli::getAuthUrl('your-state-parameter'); // Exchange code for token — returns AuthToken DTO $token = Meli::auth()->getToken($code); $token->accessToken; // string $token->refreshToken; // string $token->expiresIn; // int // Refresh token $newToken = Meli::auth()->refreshToken($token->refreshToken); ``` ### Multi-Tenancy [](#multi-tenancy) ``` // Per-request token $user = Meli::withToken($accessToken)->users()->me(); // Via connection object $orders = Meli::forConnection($meliConnection)->orders()->getBySeller($sellerId); // Via resolver in config config(['meli.access_token_resolver' => function ($connectionId = null) { if ($connectionId) { return MeliConnection::find($connectionId)?->access_token; } return auth()->user()?->meli_access_token; }]); ``` ### Working with Products [](#working-with-products) ``` // Create $product = Meli::products()->create([ 'title' => 'Amazing Product', 'category_id' => 'MLB1055', 'price' => 99.99, 'currency_id' => 'BRL', 'available_quantity' => 10, 'condition' => 'new', ]); // Update $product = Meli::products()->update('MLB123456789', [ 'price' => 89.99, 'available_quantity' => 5, ]); // Change status $product = Meli::products()->changeStatus('MLB123456789', 'paused'); ``` Available Services ------------------ [](#available-services) AccessorServiceReturns`Meli::auth()`AuthService`AuthToken``Meli::products()`ProductService`Product``Meli::orders()`OrderService`Order`, `SearchResult``Meli::users()`UserService`User``Meli::payments()`PaymentService`Payment`, `SearchResult``Meli::questions()`QuestionService`Question`, `SearchResult``Meli::categories()`CategoryService`Category``Meli::searchItem()`SearchItemService`SearchResult``Meli::visits()`VisitsService`Response``Meli::notifications()`NotificationService`SearchResult``Meli::documentation()`DocumentationService`array`For detailed documentation of all services and methods, see [SERVICES.md](SERVICES.md). Error Handling -------------- [](#error-handling) The package throws typed exceptions for all API errors: ``` use Zdearo\Meli\Exceptions\MeliNotFoundException; use Zdearo\Meli\Exceptions\MeliValidationException; use Zdearo\Meli\Exceptions\MeliRateLimitException; use Zdearo\Meli\Exceptions\MeliException; try { $product = Meli::products()->get('MLB123456789'); } catch (MeliNotFoundException $e) { // 404 — resource not found $e->statusCode; // 404 $e->errorCode; // "not_found" $e->context; // full response body as array } catch (MeliValidationException $e) { // 400 — validation errors $e->causes; // array of validation errors from ML } catch (MeliRateLimitException $e) { // 429 — too many requests } catch (MeliException $e) { // Catch-all for any API error Log::error("Meli [{$e->statusCode}]: {$e->getMessage()}", $e->context); } ``` ExceptionHTTP Status`MeliAuthException`401`MeliForbiddenException`403`MeliNotFoundException`404`MeliValidationException`400`MeliRateLimitException`429`MeliServerException`500+`MeliException`Any otherLazy Pagination --------------- [](#lazy-pagination) Search methods return `SearchResult` DTOs with pagination metadata. Use `searchAll()` to iterate lazily: ``` // Memory-efficient — fetches pages on demand Meli::orders() ->searchAll(['seller' => $sellerId]) ->cursor() ->each(function (\Zdearo\Meli\DTO\Order $order) { // Process each order }); // Collect all into a Collection $allOrders = Meli::orders()->searchAll(['seller' => $sellerId])->all(); ``` Available on: `OrderService`, `QuestionService`, `PaymentService`, `NotificationService`, `SearchItemService`. Retry Configuration ------------------- [](#retry-configuration) Retry is **disabled by default**. To enable automatic retry on rate limit (429) and server errors (5xx): ``` MELI_RETRY_TIMES=3 MELI_RETRY_SLEEP_MS=500 ``` Example Controller ------------------ [](#example-controller) ``` use Zdearo\Meli\Facades\Meli; use Zdearo\Meli\Exceptions\MeliNotFoundException; use Illuminate\Http\Request; class ProductController extends Controller { public function show(string $itemId) { try { $product = Meli::products()->get($itemId); return view('products.show', compact('product')); } catch (MeliNotFoundException) { abort(404); } } public function search(Request $request) { $results = Meli::searchItem()->byQuery($request->input('q')); return view('products.search', ['results' => $results->results, 'total' => $results->total]); } public function orders() { $orders = Meli::orders()->getBySeller(auth()->user()->meli_user_id); return view('orders.index', ['orders' => $orders->results]); } } ``` Documentation Service (MCP) --------------------------- [](#documentation-service-mcp) Access Mercado Libre's technical documentation programmatically via the MCP server: ``` $results = Meli::documentation()->search('items', 'pt_BR'); $page = Meli::documentation()->getPage('/pt_br/product-search', 'pt_BR'); ``` Laravel Boost Support --------------------- [](#laravel-boost-support) This package includes AI guidelines and skills for [Laravel Boost](https://github.com/laravel/boost). When installed alongside Boost, running `php artisan boost:install` will automatically include Meli SDK guidelines and the `meli-development` skill. Testing ------- [](#testing) ``` ./vendor/bin/pest ``` Code Style ---------- [](#code-style) ``` ./vendor/bin/pint ``` License ------- [](#license) MIT License. See [LICENSE](LICENSE) for more details. ### Health Score 45 — FairBetter than 92% of packages Maintenance87 Actively maintained with recent releases Popularity18 Limited adoption so far Community8 Small or concentrated contributor base Maturity56 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 ~28 days Recently: every ~41 days Total 8 Last Release 66d ago Major Versions 0.0.1 → 1.0.02025-08-26 1.2.0 → 2.0.02026-03-10 PHP version history (2 changes)0.0.1PHP ^8.1 1.2.0PHP ^8.3 ### Community Maintainers ![](https://www.gravatar.com/avatar/a022e60a18a9aacbd3cf4d4352ae3fdbde08b7b7dbc7c76aae008990ec8cdb43?d=identicon)[zdearo](/maintainers/zdearo) --- Top Contributors [![zdearo](https://avatars.githubusercontent.com/u/110416695?v=4)](https://github.com/zdearo "zdearo (66 commits)") ### Code Quality TestsPest Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/zdearo-meli-php/health.svg) ``` [![Health](https://phpackages.com/badges/zdearo-meli-php/health.svg)](https://phpackages.com/packages/zdearo-meli-php) ``` ### Alternatives [spatie/laravel-query-builder Easily build Eloquent queries from API requests 4.4k26.9M220](/packages/spatie-laravel-query-builder)[essa/api-tool-kit set of tools to build an api with laravel 52680.5k](/packages/essa-api-tool-kit)[esign/laravel-conversions-api A laravel wrapper package around the Facebook Conversions API 69145.4k](/packages/esign-laravel-conversions-api)[surface/laravel-webfinger A Laravel package to create an ActivityPub webfinger. 113.8k](/packages/surface-laravel-webfinger) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)