README

注意：这个库是由社区构建的，如果您想使用由Mercado Livre维护的官方库 - 点击这里

功能

• 身份验证和授权
• 查询用户数据
• 查询类别
• 查询货币
• 查询和发布广告
• 查询订单
• 查询支付
• 向客户发送售后消息
• 对订单发表反馈

要求

• PHP 5.6+ 或 PHP 7+
• 与PSR-4兼容的Autoloader

依赖关系

• Guzzle
• JMS Serializer
• Doctrine Collections
• Doctrine Cache

安装

要安装此库，只需通过composer添加它即可

PHP 5.6+（版本 1.）

composer require dsc/mercado-livre 1.*

或者 composer.json

{
    "dsc/mercado-livre": "1.*"
}

PHP 7+（版本 2.）

composer require dsc/mercado-livre 2.*

或者 composer.json

{
    "dsc/mercado-livre": "2.*"
}

测试

我们可以使用composer来运行测试

composer test

或使用 .phar

php composer.phar test

使用方法

要使用此库，首先您必须在Mercado Livre上配置一个应用程序。如果您不熟悉这些功能，您可以在开发者的入门指南中查看。

创建应用程序后，您将获得由Mercado Livre提供的 App ID (client-id) 和 Secret Key (client-secret) 信息。这些信息将在您访问需要授权的资源时使用。

目前Mercado Livre没有提供用于测试的 Sandbox 环境。所有发布都将按照手册中描述的方式在您的实际账户上执行。

如果您需要，还可以创建一个测试用户。创建测试用户后，您可以配置另一个应用程序并获取测试用户的 App ID (client-id) 和 Secret Key (client-secret)。请记住，即使有测试用户，数据也会显示在Mercado Livre的 生产 环境中。

身份验证和授权示例

在开发手册中，您可以找到有关Mercado Livre 身份验证和授权的更多详细信息。

以下是一个使用OAuth和此库进行身份验证的简单示例。

<?php
// Consideramos que já existe um autoloader compatível com a PSR-4 registrado

use Dsc\MercadoLivre\Meli;
use Dsc\MercadoLivre\Resources\Authorization\AuthorizationService;

$meli = new Meli('APP-ID', 'SECRET-ID');
$service = new AuthorizationService($meli);

if(isset($_GET['code'])) {
   $service->authorize($_GET['code'], 'https://your-domain.com/login.php');
   header('Location: https://your-domain.com');
}

echo '<br><br><a href="' . $service->getOAuthUrl('https://your-domain/login.php') . '">Login using MercadoLibre oAuth 2.0</a>';

如果您想发送state参数，也可以这样做，例如

echo '<br><br><a href="' . $service->getOAuthUrl('https://your-domain/login.php', 'your-state-value') . '">Login using MercadoLibre oAuth 2.0</a>';

服务器端身份验证示例

另一种获取AccessToken的方法是通过client_credentials进行查询。这种方法适用于通过cron或其他计划任务自动运行的脚本。 注意：要使用此方法，您需要在您的应用程序中配置 Scope offline access。

<?php
// Consideramos que já existe um autoloader compatível com a PSR-4 registrado
use Dsc\MercadoLivre\Meli;
use Dsc\MercadoLivre\Resources\Authorization\AuthorizationService;

// seu script background

$meli = new Meli('APP-ID', 'SECRET-ID');
$service = new AuthorizationService($meli);

$token = $service->getAccessToken();

// seu script background

重要：该库将存储access_token和refresh_token，用于需要身份验证的请求。也就是说，当access_token过期时，它将由库自动更新，使用refresh_token。

用户认证完成后，我们可以发布我们的第一条广告。

发布广告

配置应用并完成用户认证后，您可以在Mercado Livre发布广告，因此您需要拥有在应用中创建的 App ID 和 Secret Key。

<?php
// Consideramos que já existe um autoloader compatível com a PSR-4 registrado

use Dsc\MercadoLivre\Meli;
use Dsc\MercadoLivre\Announcement\Item;
use Dsc\MercadoLivre\Announcement\Picture;
use Dsc\MercadoLivre\Announcement;

// E NECESSARIO ESTAR AUTENTICADO...

$meli = new Meli('APP-ID', 'SECRET-ID');

$item = new Item();
$item->setTitle('Test item - no offer')
     ->setCategoryId('MLB46585')
     ->setPrice(100)
     ->setCurrencyId('BRL')
     ->setAvailableQuantity(10)
     ->setBuyingMode('buy_it_now')
     ->setListingTypeId('gold_especial')
     ->setCondition('new')
     ->setDescription('Test item - no offer')
     ->setWarranty('12 months');

// Imagem do Produto        
$picture = new Picture();
$picture->setSource('http://mla-s2-p.mlstatic.com/968521-MLA20805195516_072016-O.jpg');
$item->addPicture($picture); // collection de imagens

$announcement = new Announcement($meli);
$response = $announcement->create($item);

// Link do produto publicado
echo $response->getPermalink();

发布带有变体的广告

更多详细信息请参阅：变体手册

<?php
// Consideramos que já existe um autoloader compatível com a PSR-4 registrado

use Dsc\MercadoLivre\Meli;
use Dsc\MercadoLivre\Requests\Category\CategoryService;
use Dsc\MercadoLivre\Environments\Site;
use Dsc\MercadoLivre\Announcement\Item;
use Dsc\MercadoLivre\Announcement\Picture;
use Dsc\MercadoLivre\Announcement;
use Dsc\MercadoLivre\Requests\Category\AttributeCombination;
use Dsc\MercadoLivre\Requests\Product\Variation;

// E NECESSARIO ESTAR AUTENTICADO...

$meli = new Meli('APP-ID', 'SECRET-ID');

$item = new Item();
$item->setTitle('Test item - no offer')
     ->setCategoryId('MLB46585')
     ->setCurrencyId('BRL')
     ->setAvailableQuantity(10)
     ->setBuyingMode('buy_it_now')
     ->setListingTypeId('gold_especial')
     ->setCondition('new')
     ->setDescription('Test item - no offer')
     ->setWarranty('12 months');

// Imagem do Produto        
$picture = new Picture();
$picture->setSource('http://mla-s2-p.mlstatic.com/968521-MLA20805195516_072016-O.jpg');
$item->addPicture($picture); // collection de imagens

// Consulta os atributos de uma determinada categoria
$service = new CategoryService();
$attributes = $service->findCategoryAttributes('MLB46585');

$attributeCombination = new AttributeCombination();
// E necessario selecionar os atributos da Categoria e setar no AttributeCombination

// Primeira variacao
$variation = new Variation();
$variation->setPrice(120);
$variation->setAvailableQuantity(10);
$variation->addAttributeCombination($attributeCombination);
$variation->setPictureIds([
    'http://mla-s2-p.mlstatic.com/968521-MLA20805195516_072016-O.jpg'
]);

$item->addVariation($variation);

// Criando um Anuncio...
$announcement = new Announcement($meli);
$response = $announcement->create($item);

// Link do produto publicado
echo $response->getPermalink();

发布带有属性的广告

更多详细信息请参阅：属性手册

<?php
// Consideramos que já existe um autoloader compatível com a PSR-4 registrado

use Dsc\MercadoLivre\Meli;
use Dsc\MercadoLivre\Requests\Category\CategoryService;
use Dsc\MercadoLivre\Environments\Site;
use Dsc\MercadoLivre\Announcement\Item;
use Dsc\MercadoLivre\Announcement\Picture;
use Dsc\MercadoLivre\Announcement;
use Dsc\MercadoLivre\Requests\Category\AttributeCombination;
use Dsc\MercadoLivre\Requests\Product\Variation;

// E NECESSARIO ESTAR AUTENTICADO...

$meli = new Meli('APP-ID', 'SECRET-ID');

$item = new Item();
$item->setTitle('Test item - no offer')
     ->setCategoryId('MLB46585')
     ->setCurrencyId('BRL')
     ->setAvailableQuantity(10)
     ->setBuyingMode('buy_it_now')
     ->setListingTypeId('gold_especial')
     ->setCondition('new')
     ->setDescription('Test item - no offer')
     ->setWarranty('12 months');

// Imagem do Produto
$picture = new Picture();
$picture->setSource('http://mla-s2-p.mlstatic.com/968521-MLA20805195516_072016-O.jpg');
$item->addPicture($picture); // collection de imagens

// Consulta os atributos de uma determinada categoria
$service = new CategoryService();
$attributes = $service->findCategoryAttributes('MLB46585');

$item->setAttributes($attributes);

// Criando um Anuncio...
$announcement = new Announcement($meli);
$response = $announcement->create($item);

// Link do produto publicado
echo $response->getPermalink();

修改广告

要修改您的广告...

这会根据产品是否已售出而有所不同。此外，请记住，要修改产品，它必须处于 活动状态。您可以更改以下值

• 标题
• 可用数量
• 价格
• 视频
• 图片
• 运输

请参阅以下链接：手册链接

<?php
// Consideramos que já existe um autoloader compatível com a PSR-4 registrado

use Dsc\MercadoLivre\Meli;
use Dsc\MercadoLivre\Announcement;

$meli = new Meli('APP-ID', 'SECRET-ID');

$data = [
    'title' => 'New title',
    'available_quantity' => 10,
    'price' => 100
];

$announcement = new Announcement($meli);
$response = $announcement->update('ITEM-CODE', $data);

// Link do produto
echo $response->getPermalink();

添加或替换现有描述

产品的描述包含有关您正在销售的产品的一些自定义信息。您可以选择添加到产品描述中的信息量以及它们将如何显示。您可以选择简单的描述或无格式文本。描述中显示的信息应补充我们已在产品描述页面显示的产品属性。例如，您可以添加规格、图片、销售详情、促销广告以及您认为有助于买家选择产品并减少在出价前提出更多问题的任何有用和吸引人的内容。

应避免的元素

• Iframes
• 脚本
• 表单
• 输入
• 元数据
• 对象
• 嵌入

如果在发布产品时未在描述中发送任何内容，您可以使用以下教程稍后添加。请按照以下示例操作

<?php
// Consideramos que já existe um autoloader compatível com a PSR-4 registrado

use Dsc\MercadoLivre\Meli;
use Dsc\MercadoLivre\Announcement;

$meli = new Meli('APP-ID', 'SECRET-ID');

$description = '<p>New description item</p>';

$announcement = new Announcement($meli);
$response = $announcement->changeDescription('ITEM-CODE', $description);

echo $response->getPermalink();

修改广告状态

在Mercado Livre发布的任何产品都可以有不同的状态；以下是对每个状态的描述

• 已关闭：完成您的发布。一旦关闭，发布将无法再次激活，但可以重新发布。
• 暂停：暂停您的发布。一旦暂停，产品将无法被其他Mercado Livre用户查看，但不会关闭，以后可以重新激活。
• 活动：重新激活先前暂停的产品。

如果您需要修改产品状态，请将以下值之一发送到“status”字段。请记住，值区分大小写，并且应以小写字母发送。以下是一个暂停活动产品的示例

<?php
// Consideramos que já existe um autoloader compatível com a PSR-4 registrado

use Dsc\MercadoLivre\Meli;
use Dsc\MercadoLivre\Announcement;
use Dsc\MercadoLivre\Announcement\Status;

$meli = new Meli('APP-ID', 'SECRET-ID');

$announcement = new Announcement($meli);
$response = $announcement->changeStatus('ITEM-CODE', Status::PAUSED); // pausa o anúncio

echo $response->getPermalink();

删除广告

要删除，请提供产品代码。要执行此操作，广告必须处于 已完成 状态。

<?php
// Consideramos que já existe um autoloader compatível com a PSR-4 registrado

use Dsc\MercadoLivre\Meli;
use Dsc\MercadoLivre\Announcement;

$meli = new Meli('APP-ID', 'SECRET-ID');

$announcement = new Announcement($meli);
$announcement->delete('ITEM-CODE');

公共资源

Mercado Livre提供公共和私有资源。公共资源是任何人都可以访问的，即不需要通过 App-ID 和 Secret Key。例如，访问“sites”资源时，您将看到Mercado Livre运营的所有国家。

公共查询示例

• 查询类别

<?php
// Consideramos que já existe um autoloader compatível com a PSR-4 registrado

use Dsc\MercadoLivre\Requests\Category\CategoryService;
use Dsc\MercadoLivre\Environments\Site;

$service = new CategoryService();

// Consulta uma categoria específica
$category = $service->findCategory('MLA5725');

// Consulta a lista de categorias de uma determinada região (Site ID)
$categories = $service->findCategories(Site::BRASIL);

// Consulta a lista de categorias a partir do título de um produto
$categories = $service->findCategoryPredictor(Site::BRASIL, 'titulo-do-seu-produto');

// Consulta os atributos de uma determinada categoria
$attributes = $service->findCategoryAttributes('MLA5725');

• 查询货币

<?php
// Consideramos que já existe um autoloader compatível com a PSR-4 registrado

use Dsc\MercadoLivre\Requests\Currency\CurrencyService;

$service = new CurrencyService();

// Consulta uma moeda específica
$currency = $service->findCurrency('ARS');

// Consulta a lista de moedas e seus atributos
$currencies = $service->findCurrencies();

私有资源

私有资源只能通过授权访问，因此，要访问这些信息，用户需要在Mercado Livre上登录（或之前已经通过授权流程）。

• 登录用户数据

<?php
// Consideramos que já existe um autoloader compatível com a PSR-4 registrado

use Dsc\MercadoLivre\Meli;
use Dsc\MercadoLivre\Resources\User\UserService;

$meli = new Meli('APP-ID', 'SECRET-ID');

$service = new UserService($meli);

// Consulta dados do usuário
$information = $service->getInformationAuthenticatedUser();

• 订单查询

<?php
// Consideramos que já existe um autoloader compatível com a PSR-4 registrado

use Dsc\MercadoLivre\Meli;
use Dsc\MercadoLivre\Resources\Order\OrderService;

$meli = new Meli('APP-ID', 'SECRET-ID');

$service = new OrderService($meli);

// Consulta um pedido
$order = $service->findOrder('ORDER-ID');

• 多个订单查询

<?php
// Consideramos que já existe um autoloader compatível com a PSR-4 registrado

use Dsc\MercadoLivre\Meli;
use Dsc\MercadoLivre\Resources\Order\OrderService;

$meli = new Meli('APP-ID', 'SECRET-ID');

$service = new OrderService($meli);
// Consulta de pedidos de um vendedor
$orders = $service->findOrdersBySeller('SELLER-ID');
// Ou Consulta de pedidos de um comprador
$orders = $service->findOrdersByBuyer('BUYER-ID');

// Nesses métodos você tem a opção de passar alguns parâmetros adicionais
// para paginação ou ordenação
$limit = 50;
$offset = 0;
$sort = 'date_desc';
$orders = $service->findOrdersBySeller('SELLER-ID', $limit, $offset, $sort);

• 查询支付

<?php
// Consideramos que já existe um autoloader compatível com a PSR-4 registrado

use Dsc\MercadoLivre\Meli;
use Dsc\MercadoLivre\Resources\Payment\PaymentService;

$meli = new Meli('APP-ID', 'SECRET-ID');

$service = new PaymentService($meli);

// Consulta um pagamento
$payment = $service->findPayment('PAYMENT-ID');

// Consulta um pagamento de vendedor
$payment = $service->findPaymentOfSeller('PAYMENT-ID');

• 运输数据查询

<?php
// Consideramos que já existe um autoloader compatível com a PSR-4 registrado

use Dsc\MercadoLivre\Meli;
use Dsc\MercadoLivre\Resources\Shipment\ShipmentService;

$meli = new Meli('APP-ID', 'SECRET-ID');

$service = new ShipmentService($meli);

// Consulta um envio
$shipment = $service->findShipment('SHIPMENT-ID');

• 向客户发送售后消息

<?php
// Consideramos que já existe um autoloader compatível com a PSR-4 registrado

use Dsc\MercadoLivre\Meli;
use Dsc\MercadoLivre\Resources\Message\MessageService;
use Dsc\MercadoLivre\Resources\Message\From;
use Dsc\MercadoLivre\Resources\Message\Message;
use Dsc\MercadoLivre\Resources\Message\To;

$meli = new Meli('APP-ID', 'SECRET-ID');

$service = new MessageService($meli);

// identifica o vendedor
$from = new From();
$from->setUserId('SELLER-ID');

// identifica o cliente
$to = new To();
$to->setUserId('USER-ID');

$message = new Message();
$message->setFrom($from);
$message->setTo($to);
$message->setText("Text message");

// Enviando a mensagem
$messageResponse = $service->send($message, 'ORDER-ID', 'SELLER-ID');

• 对订单发表反馈

<?php
// Consideramos que já existe um autoloader compatível com a PSR-4 registrado

use Dsc\MercadoLivre\Meli;
use Dsc\MercadoLivre\Resources\Feedback\FeedbackPost;
use Dsc\MercadoLivre\Resources\Feedback\Rating;
use Dsc\MercadoLivre\Resources\Order\OrderService;

$meli = new Meli('APP-ID', 'SECRET-ID');

$service = new OrderService($meli);

// Criando o feedback a ser postado
$feedback = new FeedbackPost();
$feedback->setFulfilled(true);
$feedback->setMessage('Test');
$feedback->setRating(Rating::POSITIVE);

// Publicando o feedback
$feedbackResponse = $service->publishFeedback($feedback, 'ORDER-ID');

修改网站

默认情况下，该库配置为巴西应用程序，但如果需要，可以在提供凭据时更改此配置，如下所示

<?php
// Consideramos que já existe um autoloader compatível com a PSR-4 registrado

use Dsc\MercadoLivre\Meli;
use Dsc\MercadoLivre\Environments\Site;
use Dsc\MercadoLivre\Environments\Production;

// Acessando os recursos da Argentina
$meli = new Meli(
            'APP-ID', 
            'SECRET-ID',
            new Production(Site::ARGENTINA)
        );

在此链接中，您可以查看可用网站的列表。

贡献！

想贡献吗？点击这里

许可证

此库遵循Apache-2.0的使用条款