README

该库提供了与Rodium批发API集成的官方工具

目录

要求

安装

使用

分类API

产品API

订单API

供应商API：分类

供应商API：产品

要求

• PHP >= 7.2
• php-json扩展

安装

使用Composer工具安装

composer require rodium/rodium-sdk

使用

创建ApiFactory对象。需要API地址（baseUrl）和密钥（apiKey）。请联系Rodium批发API以获取它们。

use Rodium\Sdk\Client\ApiFactory;
use Rodium\Sdk\Client\ApiKey;

$apiFactory = new ApiFactory("https://base-url", new ApiKey("twój-klucz-api"));

ApiFactory允许创建单个API

$categoriesApi = $apiFactory->categoriesApi(); // CategoriesApi
$itemsApi = $apiFactory->itemsApi(); // ItemsApi
$ordersApi = $apiFactory->ordersApi(); // OrdersApi

$supplierCategoriesApi = $apiFactory->supplierCategoriesApi(); // SupplierCategoriesApi
$supplierItemsApi = $apiFactory->supplierItemsApi(); // SupplierItemsApi  

分类API：CategoriesApi

分类API允许获取目录中分类的信息

按ID获取分类

$category = $categoriesApi->categoryOfId(123);

获取所有分类的扁平列表

$categories = $categoriesApi->all();

获取完整分类树

$category = $categoriesApi->tree();

获取所选分类的树

$category = $categoriesApi->tree(123);

获取所选分类的孩子

$categories = $categoriesApi->children(123);

产品API：ItemsApi

产品API允许获取产品及其变体的信息

按ID获取产品

注意：API中的产品标识符与Rodium批发API中的产品标识符不相同

$item = $itemsApi->itemOfId(123);

获取产品列表

use Rodium\Sdk\Page\PageRequest;

$pageRequest = new PageRequest(1, 25); // numer strony, liczba produktów na stronę
// lub
$pageRequest = PageRequest::defaultPageRequest();
$page = $itemsApi->items($pageRequest);

获取按分类过滤的产品列表

$pageRequest = PageRequest::defaultPageRequest();
$categoryId = 123;

$page = $itemsApi->items($pageRequest, $categoryId);

获取产品变体

注意：API中的变体标识符与Rodium批发API中的产品标识符不相同。Variant对象具有专用的rodiumId字段。

$variants = $itemsApi->variantsOfItem(123);

订单API：OrdersApi

订单API允许获取已提交的订单信息以及提交新订单

创建API

如果客户只有一个分支机构

/** @var OrdersApi $ordersApi */
$ordersApi = $apiFactory->ordersApi();

如果客户有多个分支机构，则需要指定要创建API的分支机构的ID

/** @var OrdersApi $ordersApi */
$ordersApi = $apiFactory->ordersApi(123);

获取订单列表

use Rodium\Sdk\Page\PageRequest;

$orders = $ordersApi->orders();
// lub
$pageRequest = PageRequest::pageRequest(1, 30);
$orders = $ordersApi->orders($pageRequest);

按ID获取订单

注意：API中的订单标识符是UUID（通过Order::id()读取），而不是用户界面中可见的连续编号。

$order = $ordersApi->orderOfId("id-zamówienia");

提交订单

注意：如果发票数据未设置，将使用最后订单的数据。

use Rodium\Sdk\Order\Order;
use Rodium\Sdk\Order\InvoiceData;

// Dane fakturowe
$invoiceData = new InvoiceData(
    "Nazwa firmy",
    "1234567890", // NIP
    "ul. Mokra 2",
    "32-020",
    "Wieliczka"
); // opcjonalnie

$order = Order::newOrder($invoiceData);
$order = $order
    ->withVariant(123, 2)
    ->withVariant(234, 1)
    // ...
    ->withVariant(5431, 2)
    ->withNotes("Proszę o szybką realizację");

$placedOrder = $ordersApi->place($order);

错误处理

如果失败，API会抛出AbstractApiException类的异常，因此每个操作都应该在try/catch块中调用。

如果API返回了正确的JSON响应，可以使用AbstractApiException::error()方法访问它。

use Rodium\Sdk\Client\AbstractApiException;
use Rodium\Sdk\Error\ValidationError;

try {
    $placedOrder = $ordersApi->place($order);
} catch (AbstractApiException $e) {
    $request = $e->request(); // żądanie wysłane do API
    $response = $e->response(); // surowa odpowiedź z API

    $error = $e->error(); // przetworzona odpowiedź z błędem
    $errorMessage = $error->message(); // informacja o błędzie
    
    // jeśli błąd walidacji danych wejściowych
    if ($error instanceof ValidationError) {
        $violations = $error->violations(); // lista błędów walidacji
    }
}

供应商分类API

供应商分类API允许检查供应商可以访问哪些分类

创建API

要创建产品API，请使用以下代码

use Rodium\Sdk\Catalog\Categories\SupplierCategoriesApi;

/** @var SupplierCategoriesApi $supplierApi */
$supplierApi = $apiFactory->supplierCategoriesApi();

通过树形结构检查可用分类

use Rodium\Sdk\Catalog\Categories\SupplierCategoriesApi;

$rootCategory = $supplierApi->tree();
$rootCategory->isHasSupplierAccess(); // sprawdza, czy dostawca ma dostęp do tej kategorii

foreach ($rootCategory->children() as $child) {
    $child->isHasSupplierAccess();
    foreach ($child->children() as $child2) {
        $child2->isHasSupplierAccess();
        // ...
    }
}

通过扁平列表检查可用分类

$categories = $supplierApi->all(); // zwraca płaską listę kategorii (liści), do których dostawca ma dostęp

供应商产品API

供应商API允许在分配的分类中管理产品及其变体（添加、编辑、删除）

创建API

要创建产品API，请使用以下代码

use Rodium\Sdk\Catalog\Items\SupplierItemsApi;

/** @var SupplierItemsApi $supplierApi */
$supplierApi = $apiFactory->supplierItemsApi();

添加新产品和变体

添加新产品

use Rodium\Sdk\Catalog\Items\SupplierItemsApi;
use Rodium\Sdk\Catalog\Items\Item;
/** @var SupplierItemsApi $supplierApi */

$item = Item::forCategory(
    123, // ID Kategorii
    "Produkt-123" // Symbol produktu nie może zawierać spacji
);

$createdItem = $supplierApi->createItem($item);
$createdItem->id();

向现有产品添加变体

use Rodium\Sdk\Catalog\Items\SupplierItemsApi;
use Rodium\Sdk\Catalog\Items\Variant;
use Rodium\Sdk\Catalog\Items\Pricing;
use Rodium\Sdk\Catalog\Items\Dimensions;
use Rodium\Sdk\Catalog\Items\Diamonds;
use Rodium\Sdk\Catalog\Items\Other;

/** @var SupplierItemsApi $supplierApi */

$variant = Variant::forItem(
    123, // ID Produktu
    "321", // ID Produktu w systemie dostawcy
    Pricing::forSupplierPrice(1234.23), // cena netto dostawcy
    1, // stan magazynowy (ilościowy)
    new Dimensions(
        2.43,
        10
    ), // wymiary (masa, średnica, ...)
    new Diamonds(
        "brylantowy", // szlif
        "biały", // barwa
        1, // liczba brylantów
        0.32 // masa brylantów
    ), // informacje o brynalcie
    new Other(
        "Pięny pierścionek", // dodatkowy opis słowny
        null, // kolor złota
        null, // opis innych kamieni szlachetnych
        "PL" // kraj producenta
    ), // inne informacje
    null // EAN
);

$createdVariant = $supplierApi->createVariant($variant);
$createdItem->id();

仅添加一个变体的新产品

use Rodium\Sdk\Catalog\Items\SupplierItemsApi;
use Rodium\Sdk\Catalog\Items\Variant;
use Rodium\Sdk\Catalog\Items\Pricing;
use Rodium\Sdk\Catalog\Items\Dimensions;
use Rodium\Sdk\Catalog\Items\Diamonds;
use Rodium\Sdk\Catalog\Items\Other;

/** @var SupplierItemsApi $supplierApi */

$variant = Variant::forCategory(
    123, // ID Kategorii
    "Produkt-321",
    "321", // ID Produktu w systemie dostawcy
    Pricing::forSupplierPrice(1234.23), // cena netto dostawcy
    1, // stan magazynowy (ilościowy)
    new Dimensions(
        2.43,
        10
    ), // wymiary (masa, średnica, ...)
    new Diamonds(
        "brylantowy", // szlif
        "biały", // barwa
        1, // liczba brylantów
        0.32 // masa brylantów
    ), // informacje o brynalcie
    new Other(
        "Pięny pierścionek", // dodatkowy opis słowny
        null, // kolor złota
        null, // opis innych kamieni szlachetnych
        "PL" // kraj producenta
    ), // inne informacje,
    null // EAN
);

$createdVariant = $supplierApi->createVariant($variant);
$createdItem->id();

管理变体图片

添加图片

use Rodium\Sdk\Catalog\Items\SupplierItemsApi;
use Rodium\Sdk\Catalog\Items\ImageSource;

/** @var SupplierItemsApi $supplierApi */
$variant = $supplierApi->addVariantPhoto(
    321, // ID wariantu
    ImageSource::fromUrl("https://moj-sklep-jubilerski.pl/prodkuty/321-xxl.jpg")
);

$variant->images(); // list of images

替换图片

use Rodium\Sdk\Catalog\Items\SupplierItemsApi;
use Rodium\Sdk\Catalog\Items\ImageSource;

/** @var SupplierItemsApi $supplierApi */
$variant = $supplierApi->changeVariantPhoto(
    321, // ID wariantu
    ImageSource::fromUrl("https://moj-sklep-jubilerski.pl/prodkuty/321-xxl.jpg"),
    0 // numer zdjęcia do podmiany (indeksowane od zera),  
);

$variant->images(); // list of images

删除图片

use Rodium\Sdk\Catalog\Items\SupplierItemsApi;

/** @var SupplierItemsApi $supplierApi */
$variant = $supplierApi->removeVariantPhoto(
    321, // ID wariantu
    0 // numer zdjęcia do usunięcia (indeksowane od zera)
);

$variant->images(); // list of images

编辑变体

以下代码将覆盖特定变体的所有参数。无法单独编辑单个参数。

use Rodium\Sdk\Catalog\Items\SupplierItemsApi;

/** @var SupplierItemsApi $supplierApi */
$upatedVariant = $supplierApi->updateVariant(
    321, // ID wariantu
    $variant // zobacz Variant::forItem
);

更改变体库存状态

要更改变体库存状态，请使用以下代码

use Rodium\Sdk\Catalog\Items\SupplierItemsApi;

/** @var SupplierItemsApi $supplierApi */
$upatedVariant = $supplierApi->updateVariantStock(
    321, // ID wariantu
    5 // liczba dostępnych sztuk
);

删除产品和变体

要删除现有的变体，请使用以下代码

use Rodium\Sdk\Catalog\Items\SupplierItemsApi;

/** @var SupplierItemsApi $supplierApi */
$supplierApi->removeVariant(321);

要删除现有的产品（及其变体），请使用以下代码

use Rodium\Sdk\Catalog\Items\SupplierItemsApi;

/** @var SupplierItemsApi $supplierApi */
$supplierApi->removeItem(123);

列出产品和变体

获取供应商产品列表

use Rodium\Sdk\Catalog\Items\SupplierItemsApi;
use Rodium\Sdk\Page\PageRequest;

/** @var SupplierItemsApi $supplierApi */
$page = $supplierApi->items(
    PageRequest::pageRequest(1, 25)
);

/** @var \Rodium\Sdk\Catalog\Items\Item $item */
foreach ($page->elements() as $item) {
    $item->id();
}

获取特定产品的变体

use Rodium\Sdk\Catalog\Items\SupplierItemsApi;
use Rodium\Sdk\Page\PageRequest;

/** @var SupplierItemsApi $supplierApi */
$variants = $supplierApi->variantsOfItem(
    123 // ID Produktu
);

foreach ($variants as $variant) {
    $variant->id();
}

获取所选变体

use Rodium\Sdk\Catalog\Items\SupplierItemsApi;
use Rodium\Sdk\Page\PageRequest;

/** @var SupplierItemsApi $supplierApi */
$variant = $supplierApi->variantOfId(
    123 // ID Wariantu
);

$variant->id();

结束

如有问题/疑问，请联系罗迪乌姆仓库工作人员 rodium@rodium.pl