README

为 ShopAPI.cz 提供简单连接产品供应商产品流的客户端。

API 详细文档在 docs/api.md。

ShopAPI/Client 的优势

服务器要求低，性能高

• 下载馈电使用压缩，因此速度快，不会占用数据限额。
• 处理是流式的，因此即使是 5GB 的馈电也只需几 MB 的内存（@todo 基准测试）

简单连接

使用客户端时，您完全脱离了 XML，并直接与简单对象工作。因此，稍后从 XML 馈电切换到 REST API（过滤器等）而不必更改连接代码是完全可行的。

安装

composer require shopapicz/client
composer require composer/ca-bundle       # nepovinné, doporučené

如果您的服务器没有最新的证书，我们建议安装 composer/ca-bundle。

使用

<?php
use ShopAPI\Client\XmlReader;

$reader = new XmlReader();
/*
 * URL XML feedu je https://shopapi.cz/feed/97ef49da-4169-412f-8a76-cd4c501303c2
 */
foreach ($reader->readFromUrl('97ef49da-4169-412f-8a76-cd4c501303c2') as $product) {
    echo $product->getName();
}

代码

UID 标识符是唯一的，并且始终可用。 它在 ShopAPI 中分配，并建议您使用它进行配对。但是，它不适用于与供应商的通信，因为供应商有自己的代码来管理商品。因此，如果可能的话，我们建议同时保存 code 和 EAN。

我们建议仅在应用程序内部使用 UID，并绝对不要向客户或用户显示它。

图片

图片以最大可能分辨率提供，没有额外的压缩，就像从供应商那里获取的一样。因此，它们完全不适用于直接在网店中使用，需要进一步处理。

图片存储在 CDN 上，可以轻松并行下载。但是，图片 URL 可能会随后更改，因此不建议长期依赖。

商品可用性

商品可用性以多种方式提供。对于不同的商品，这些可能以不同的组合出现

• code - 可用性代码（in_stock, out_of_stock, unknown, pre_order, unavailable）
• hours - 小时数（168 = 一周）
• quantity - 库存中的数量
• text - 文字描述（库存，最后一件，不会有的，...）

在连接时，我们建议使用 code - 它始终可用，并且具有明确的格式。相反，text 无法保证，仅适用于信息性显示。

<?php
use \ShopAPI\Client\Entity\Availability;

if($product->getAvailability()->getCode() === Availability::IN_STOCK){
    echo 'skladem!';
}
// nebo zkráceně:
if($product->getAvailability()->isInStock()){
    echo 'skladem!';
}

注意事项

每个供应商提供的数据范围不同，数据范围可能随后会更改。例如，曾经为所有产品提供品牌的供应商可能后来会将没有指定品牌的产品添加到产品中。在连接时必须考虑到这种情况。

<?php
// ŠPATNĚ
echo $product->getBrand()->getName(); 

// SPRÁVNĚ
if($product->getBrand()) {
    echo $product->getBrand()->getName(); 
}

示例

<?php
use ShopAPI\Client\XmlReader;

$reader = new XmlReader();
/*
 * URL XML feedu je https://shopapi.cz/feed/97ef49da-4169-412f-8a76-cd4c501303c2
 */
foreach ($reader->readFromUrl('97ef49da-4169-412f-8a76-cd4c501303c2') as $product) {
    echo '<h1>' . $product->getName() . '</h1>';
    
    foreach($product->getImages() as $image) {
        echo '<img src="' . $image->getUrl() . '">';
    }
    
    if(count($product->getVariants())) {
        echo '<h2>Dostupné varianty:</h2>';
        echo '<ul>';
        foreach($product->getVariants() as $variant) {
            if($variant->getAvailability()->isInStock()) {
                echo '<li style="color:green">';
            } else {
                echo '<li style="color:red">';
            }
            echo $variant->getName();
            echo ' - ';
            echo $variant->getAvailability()->getText();
            echo  '</li>';
        }
        echo '</ul>';
    }
}

API

除了 XML，还可以使用 REST API。API 数据由 ShopAPI.cz 为每个导出单独生成。

<?php
use ShopAPI\Client\Api\ApiClient;
use ShopAPI\Client\Api\ApiConfig;

$client = new ApiClient(new ApiConfig('username', 'password'));

交付方式列表

<?php
use ShopAPI\Client\Api\ApiClient;
use ShopAPI\Client\Api\ApiConfig;
use ShopAPI\Client\FieldList\DeliveryFields;

$client = new ApiClient(new ApiConfig('username', 'password'));
$returnFields = (new DeliveryFields())->addName();
foreach($client->getDeliveries($returnFields) as $delivery) {
    echo $delivery->getName() . "\n";
}

发送新订单

<?php
use ShopAPI\Client\Api\ApiClient;
use ShopAPI\Client\Api\ApiConfig;
use ShopAPI\Client\Api\OrderRequest\OrderRequest;
use ShopAPI\Client\Entity\Address;

$orderRequest = new OrderRequest();
$orderRequest
    ->setNote('Please hurry!')
    ->setDeliveryByUid('ogd9d5d44h')
    ->addItemByUid('w5d5v5vd5f', 2)
    ->setDeliveryAddress((new Address())
        ->setFirstName('John')
        ->setLastName('Smith')
        ->setStreet('Main Street')
        ->setHouseNumber('10a')
        ->setCity('Prague')
        ->setCountry('CZ')
    );

$client = new ApiClient(new ApiConfig('username', 'password'));
$orderResponse = $client->createOrder($orderRequest);

echo $orderResponse->getCode(); // order code
echo $orderResponse->getMessage();