README

A modern Laravel package for integrating with the Mercado Libre API. Provides a clean interface using Laravel's native features with comprehensive marketplace functionality.

Features

🚀 Complete API Coverage: Full support for all major Mercado Libre API endpoints
🎯 Laravel Integration: Built specifically for Laravel with Facades and Service Providers
🔧 Modern PHP: PHP 8.1+ with type hints and modern syntax
📦 Service-Based Architecture: Organized services for different API domains
🛡️ Type Safety: Full PHPDoc coverage and type declarations
🔄 HTTP Client: Built on Laravel's HTTP client with automatic error handling
🌍 Multi-Region: Support for all Latin American marketplaces

Requirements

PHP 8.1+
Laravel 9.0+

Installation

Install the package via Composer:

composer require zdearo/meli-php

The package will be auto-discovered by Laravel.

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=meli-config

Configure your environment variables in .env:

MELI_BASE_URL="https://api.mercadolibre.com/"
MELI_REGION=BRASIL
MELI_API_TOKEN=your-api-token
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

Quick Start

Basic Usage with Facade

use Zdearo\Meli\Facades\Meli;

// Get product information
$product = Meli::products()->get('MLB123456789');

// Search products
$results = Meli::searchItem()->byQuery('smartphone samsung');

// Get user information
$user = Meli::users()->get(123456789);

// Get orders
$orders = Meli::orders()->getBySeller(123456789);

Authentication Flow

use Zdearo\Meli\Facades\Meli;

// Generate authorization URL
$authUrl = Meli::getAuthUrl('your-state-parameter');

// Exchange code for access token
$token = Meli::auth()->getToken($authorizationCode);

// Refresh token
$newToken = Meli::auth()->refreshToken($refreshToken);

Working with Products

// Create a new product
$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 product status
Meli::products()->changeStatus('MLB123456789', 'paused');

Available Services

This package provides comprehensive services for all major Mercado Libre API endpoints:

AuthService: OAuth authentication and token management
ProductService: Product CRUD operations and status management
SearchItemService: Product search and discovery
UserService: User information and account management
CategoryService: Categories, attributes, and marketplace structure
OrderService: Order management and sales tracking
QuestionService: Q&A system for products
PaymentService: Payment information and transaction details
NotificationService: Webhook notifications and missed feeds
VisitsService: Analytics and visit tracking

For detailed documentation of all services and methods, see SERVICES.md.

Example Controller

use Zdearo\Meli\Facades\Meli;
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 (Exception $e) {
            return response()->json(['error' => 'Product not found'], 404);
        }
    }

    public function search(Request $request)
    {
        $results = Meli::searchItem()->byQuery($request->input('q'));
        return view('products.search', compact('results'));
    }

    public function orders()
    {
        $orders = Meli::orders()->getBySeller(auth()->user()->meli_user_id);
        return view('orders.index', compact('orders'));
    }
}

Error Handling

The package uses Laravel's HTTP client, which throws Illuminate\Http\Client\RequestException for API errors:

use Illuminate\Http\Client\RequestException;
use Zdearo\Meli\Facades\Meli;

try {
    $product = Meli::products()->get('MLB123456789');
} catch (RequestException $e) {
    Log::error('Mercado Libre API Error: ' . $e->getMessage());
    
    // Get response details
    $status = $e->response->status();
    $body = $e->response->body();
}

Testing

./vendor/bin/pest

Code Style

./vendor/bin/pint

Contributing

Please see CONTRIBUTING.md for details on how to contribute.

License

MIT License. See LICENSE for more details.

Credits

Built for the Mercado Libre API
Developed with Laravel best practices
Inspired by the Laravel ecosystem

zdearo / meli-php

Maintainers

Details