README

PHP SDK for outofbox.ru platform websites and online stores

• 安装
• 使用
• 方法
  • 授权令牌
  • 目录位置列表
  • 查看目录位置
  • 商品类别列表
  • 分店列表
  • 订单/申请
    • 创建订单/申请
    • 订单/申请信息
• 错误处理
• 配置 HTTP 客户端
• 日志记录
• 测试

安装

composer require justcommunication-ru/outofbox-ru-api-php-sdk

使用

$client = new OutofboxAPIClient('https://domain.ru', 'email', 'token');

https://domain.ru – 您在 outofbox.ru 平台上的网站域名

email — 用户名或邮箱。账户访问级别不得低于 员工

token — 授权令牌

方法

授权令牌

此方法可帮助根据用户密码获取授权令牌。令牌无时间限制，仅当用户更改密码时才会更改。

$client = new OutofboxAPIClient('https://domain.ru', 'username', ''); // обязательно передать пустой token

$token = $client->getAuthToken($password);

var_dump($token);

$password – 用户密码

注意！此方法不适用于生产环境！假设您不知道用户令牌，则需要请求令牌并随后仅使用授权令牌进行操作。不要将用户密码存储在公开资源中！

如果存在令牌泄露的风险，建议更改用户密码并重新请求令牌。

目录位置列表

$request = new ProductsListRequest();

$request
    ->setImagesSizes([
        'thumbnail' => [
            'fs' => 'ofb-320-240'
        ]
    ])
;

$response = $client->sendProductsListRequest($request);

foreach ($response->getProducts() as $product) {
    echo $product->getTitle() . ' ' . $product->getFieldValue('Марка') . ' ' . $product->getFieldValue('Модель') . "\n";
    if ($product->withImages()) {
        echo $product-getImages()[0]->getUrl('thumbnail') . "\n";
    }
}

库存情况（如果连接了 Outofbox.Склад）

$request = new ProductsListRequest();
$request
    ->setInStock(true) // только в наличии на любом складе
    ->setInStock(false) // только НЕ в наличии на любом складе
    
    ->setStock(5643) // только в наличии в филиале с номером 5643
    ->setStocks([ 5643, 5644 ]) // только если позиция есть в наличии в филиалах 5643 или 5644
;

查看目录位置

$request = ProductViewRequest::withProductID($id);
$request
    ->addImageSize('medium', [
        'fs' => 'ofb-640'
    ])
;

$response = $client->sendProductViewRequest($request);
$product = $response->getProduct();

echo $product->getTitle() . ' ' . $product->getFieldValue('Марка') . ' ' . $product->getFieldValue('Модель') . "\n";
if ($product->withImages()) {
    echo $product-getImages()[0]->getUrl('medium') . "\n";
}

商品类别列表

顶级类别

$request = new CategoriesListRequest();
$response = $client->sendCategoriesListRequest($request);

foreach ($response->getCategories() as $category) {
    echo $category->getFullTitle(' > ') . "\n";
}

子类别

$request = new CategoriesListRequest(123); // список категорий для подкатегории с идентификатором 123

或

$request = new CategoriesListRequest();
$request->setParentId(123);

$response = $client->sendCategoriesListRequest($request);

foreach ($response->getCategories() as $category) {
    echo $category->getFullTitle(' > ') . "\n";
}

重要！此方法不适用于通过递归调用选择整个子类别树！相反，应使用能够立即返回整个树的方法（@todo）

分店列表

$request = new StoresListRequest();
$response = $client->sendStoresListRequest($request);

foreach ($response->getStores() as $store) {
    echo $store->getName() . ' (№' . $store->getId() . ')' . "\n";
}

订单/申请

• 创建订单/申请
• 订单/申请信息

创建订单/申请

$request = new CreateShopOrderRequest();

$request
    ->setPhoneNumber('89688888888') // номер телефона
    ->setStoreId(123) // идентификатор филиала/склада
    // состав заказа
    ->setProducts([
        ProductShopOrderItem::create(1271231, 1), // Позиция с id = 1271231, 1 шт.
        ProductShopOrderItem::create(1271232, 2)  // Позиция с id = 1271232, 2 шт.
    ])
;

// Можно добавить еще один товар в список
$request->addProduct(ProductShopOrderItem::create(1271233, 3));

$response = $client->sendCreateShopOrderRequest($request);

echo 'Заказ создан, его номер: ' . $response->getShopOrder()->getNumber();

@todo：描述所有可用的订单字段（收货地址、客户信息等）

订单/申请信息

use Outofbox\OutofboxSDK\API\ShopOrders\GetShopOrderRequest;
use Outofbox\OutofboxSDK\OutofboxAPIClient;

$client = new OutofboxAPIClient($domain, $username, $api_token);

// через объект запроса
$request = new GetShopOrderRequest();
$request->setOrderNumber('8189-071122');

$response = $client->sendGetShopOrderRequest($request);

$shopOrder = $response->getShopOrder();

// либо короче
$shopOrder = $client->getShopOrder('8189-071122');

$shopOrder->number; // номер заказа
$shopOrder->delivery_price; // стоимость доставки

if ($shopOrder->status) {
    $shopOrder->status->id; // идентификатор статуса заказа
    $shopOrder->status->value; // наименование статуса заказа
} else {
    // статус "Новый"
}

if ($shopOrder->deliveryMethod) {
    $shopOrder->deliveryMethod->id; // идентификатор способа доставки
    $shopOrder->deliveryMethod->value; // наименование способа доставки
}

if ($shopOrder->paymentMethod) {
    $shopOrder->paymentMethod->id; // идентификатор способа оплаты
    $shopOrder->paymentMethod->value; // наименование способа оплаты
}

// позиции заказа
foreach ($shopOrder->items as $shopOrderItem) {
    $shopOrderItem->id; // идентификатор позиции
    $shopOrderItem->title; // наименование позиции
    $shopOrderItem->price; // стоимость единицы позиции
    $shopOrderItem->quantity; // количество
    $shopOrderItem->amount; // общая стоимость
    $shopOrderItem->item_weight; // вес одной позиции
}

错误处理

出错时将生成 OutofboxAPIException 异常

try {
    $client->sendProductViewRequest(ProductViewRequest::withProductID($id));
} catch (OutofboxAPIException $e) {
    $logger->error('Outofbox ERROR: ' . $e->getMessage());
}

配置 HTTP 客户端

方法 No.1：传递参数数组

$client = new OutofboxAPIClient('https://domain.ru', 'email', 'token', [
    'proxy' => 'tcp://:8125',
    'timeout' => 6,
    'connect_timeout' => 4
]);

可用的参数列表： https://docs.guzzlephp.org/en/stable/request-options.html

方法 No.2：传递自己的 \GuzzleHttp\Client

配置自己的 http 客户端

// Http клиент с логгированием всех запросов

$stack = HandlerStack::create();
$stack->push(Middleware::log($logger, new MessageFormatter(MessageFormatter::DEBUG)));

$httpClient = new \GuzzleHttp\Client([
    'handler' => $stack,
    'timeout' => 6
]);

并将其作为构造函数参数或设置器传递

$client = new OutofboxAPIClient('https://domain.ru', 'email', 'token', $httpClient);

或者

$client = new OutofboxAPIClient('https://domain.ru', 'email', 'token');
$client->setHttpClient($httpClient);

日志记录

在 $client 中可以传递自己的 Psr\Logger。

$client->setLogger($someLogger);

默认情况下，日志记录是关闭的。