README

用于与 FsDelivery 软件系统集成的 SDK。

API 文档。

内容

变更日志
 安装
 调试
 计算运费
 获取配送服务列表
 获取配送模式列表
 获取运费列表
 获取可能的订单状态列表
 获取国家列表
 获取城市列表
 获取城市自动完成列表
 获取订单提取点列表
 按 NP 注册簿详细情况
 NP 注册簿的可能状态
 NP 注册簿列表
 获取用户信息
 获取订单状态
 获取订单信息

变更日志

0.6.1 - 添加了对 Guzzle 7.* 的支持
0.6.0 - 详细信息请查看此处;
0.5.0 - SDK 的第一个版本，实现了 FsDelivery API 的方法。

安装

可以使用 Composer 包管理器进行安装

composer require fsdelivery/fsdelivery-php-sdk

如果不存在，则可以使用内置的 autoload.php。
然后 SDK 的连接将如下所示

require_once __DIR__.'/autoload.php';

// Если нужно логирование
$logger = new \FsDeliverySdk\Log\Logger();
$logger->setFilePath('/path/to/log.txt');

$Client = new \FsDeliverySdk\Client('eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9');
$Client->setLogger($logger); // Подключение логгера

如果您的系统已安装 Http 客户端 Guzzle，则将使用它进行 API 请求。
如果没有安装，则将使用内置的 HttpClient。

调试

用于请求和响应的日志记录使用 PSR-3 日志记录器标准。下面是使用 Monolog 进行日志记录的示例。

<?php
    use Monolog\Logger;
    use Monolog\Handler\StreamHandler;
    
    $log = new Logger('name');
    $log->pushHandler(new StreamHandler('/path/to/log.txt', Logger::INFO));

    $Client = new \FsDeliverySdk\Client('eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9');
    $Client->setLogger($log);

或者可以使用 SDK 内置的 Logger，它可以写入文本文件。

<?php
    $log = new \FsDeliverySdk\Log\Logger();
    $log->setFilePath('/path/to/log.txt');

    $Client = new \FsDeliverySdk\Client('eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9');
    $Client->setLogger($log);

在 log.txt 中的日志如下

[2021-12-18T16:55:44.886552+00:00] name.INFO: FsDelivery API POST request /1.0/tariff/calculation: {"tariff_id_list":[136,137,233,234,4000,4001,4003],"delivery_company_id":[1,55],"sender_city_id":44,"reciver_city_index":630001,"packages":[{"length":10,"height":10,"width":10,"weight":0.5}],"items":[{"insurance":1000,"payment_sum":1000}]} [] []
[2021-12-18T16:55:45.971776+00:00] name.INFO: FsDelivery API response /1.0/tariff/calculation: {"request_id":"dc97011a-20f5-45a4-9200-40ee7e174122","tariffs":{"1":{"136":{"tariff_id":136,"min_day":3,"max_day":5,"sum":649,"total_sum":690.25,"services":[{"id":2,"name":"\u0421\u0442\u0440\u0430\u0445\u043e\u0432\u0430\u043d\u0438\u0435","sum":7.5,"rate":0.75},{"id":19,"name":"\u0410\u0433\u0435\u043d\u0442\u0441\u043a\u043e\u0435 \u0432\u043e\u0437\u043d\u0430\u0433\u0440\u0430\u0436\u0434\u0435\u043d\u0438\u0435","sum":30,"rate":3}],"tariff_name":"\u041f\u043e\u0441\u044b\u043b\u043a\u0430 \u0441\u043a\u043b\u0430\u0434-\u0441\u043a\u043b\u0430\u0434"},"137":{"tariff_id":137,"min_day":3,"max_day":5,"sum":803,"total_sum":844.25,"services":[{"id":2,"name":"\u0421\u0442\u0440\u0430\u0445\u043e\u0432\u0430\u043d\u0438\u0435","sum":7.5,"rate":0.75},{"id":19,"name":"\u0410\u0433\u0435\u043d\u0442\u0441\u043a\u043e\u0435 \u0432\u043e\u0437\u043d\u0430\u0433\u0440\u0430\u0436\u0434\u0435\u043d\u0438\u0435","sum":30,"rate":3}],"tariff_name":"\u041f\u043e\u0441\u044b\u043b\u043a\u0430 \u0441\u043a\u043b\u0430\u0434-\u0434\u0432\u0435\u0440\u044c"},"233":{"tariff_id":233,"min_day":4,"max_day":5,"sum":385,"total_sum":426.25,"services":[{"id":2,"name":"\u0421\u0442\u0440\u0430\u0445\u043e\u0432\u0430\u043d\u0438\u0435","sum":7.5,"rate":0.75},{"id":19,"name":"\u0410\u0433\u0435\u043d\u0442\u0441\u043a\u043e\u0435 \u0432\u043e\u0437\u043d\u0430\u0433\u0440\u0430\u0436\u0434\u0435\u043d\u0438\u0435","sum":30,"rate":3}],"tariff_name":"\u042d\u043a\u043e\u043d\u043e\u043c\u0438\u0447\u043d\u0430\u044f \u043f\u043e\u0441\u044b\u043b\u043a\u0430 \u0441\u043a\u043b\u0430\u0434-\u0434\u0432\u0435\u0440\u044c"},"234":{"tariff_id":234,"min_day":4,"max_day":5,"sum":253,"total_sum":294.25,"services":[{"id":2,"name":"\u0421\u0442\u0440\u0430\u0445\u043e\u0432\u0430\u043d\u0438\u0435","sum":7.5,"rate":0.75},{"id":19,"name":"\u0410\u0433\u0435\u043d\u0442\u0441\u043a\u043e\u0435 \u0432\u043e\u0437\u043d\u0430\u0433\u0440\u0430\u0436\u0434\u0435\u043d\u0438\u0435","sum":30,"rate":3}],"tariff_name":"\u042d\u043a\u043e\u043d\u043e\u043c\u0438\u0447\u043d\u0430\u044f \u043f\u043e\u0441\u044b\u043b\u043a\u0430 \u0441\u043a\u043b\u0430\u0434-\u0441\u043a\u043b\u0430\u0434"},"delivery_company_id":1,"delivery_company_name":"Cdek"},"55":{"4000":{"tariff_id":"4000","min_day":3,"max_day":5,"sum":295.54,"total_sum":325.54,"services":[{"id":2,"name":"\u0421\u0442\u0440\u0430\u0445\u043e\u0432\u0430\u043d\u0438\u0435","sum":0,"rate":0.75},{"id":19,"name":"\u0410\u0433\u0435\u043d\u0442\u0441\u043a\u043e\u0435 \u0432\u043e\u0437\u043d\u0430\u0433\u0440\u0430\u0436\u0434\u0435\u043d\u0438\u0435","sum":30,"rate":3}],"tariff_name":"\u041f\u043e\u0441\u044b\u043b\u043a\u0430"},"4001":{"tariff_id":"4001","min_day":3,"max_day":5,"sum":276.96,"total_sum":306.96,"services":[{"id":2,"name":"\u0421\u0442\u0440\u0430\u0445\u043e\u0432\u0430\u043d\u0438\u0435","sum":0,"rate":0.75},{"id":19,"name":"\u0410\u0433\u0435\u043d\u0442\u0441\u043a\u043e\u0435 \u0432\u043e\u0437\u043d\u0430\u0433\u0440\u0430\u0436\u0434\u0435\u043d\u0438\u0435","sum":30,"rate":3}],"tariff_name":"\u041f\u043e\u0441\u044b\u043b\u043a\u0430 \u043e\u043d\u043b\u0430\u0439\u043d"},"4003":{"tariff_id":"4003","min_day":2,"max_day":4,"sum":400.04,"total_sum":430.04,"services":[{"id":2,"name":"\u0421\u0442\u0440\u0430\u0445\u043e\u0432\u0430\u043d\u0438\u0435","sum":0,"rate":0.75},{"id":19,"name":"\u0410\u0433\u0435\u043d\u0442\u0441\u043a\u043e\u0435 \u0432\u043e\u0437\u043d\u0430\u0433\u0440\u0430\u0436\u0434\u0435\u043d\u0438\u0435","sum":30,"rate":3}],"tariff_name":"\u041f\u043e\u0441\u044b\u043b\u043a\u0430 1 \u043a\u043b\u0430\u0441\u0441"},"delivery_company_id":55,"delivery_company_name":"RussianPost"}}} {"Server":["nginx/1.18.0 (Ubuntu)"],"Content-Type":["application/json"],"Transfer-Encoding":["chunked"],"Connection":["keep-alive"],"Set-Cookie":["PHPSESSID=1pdul37glve4qbenqq0ash9t0n; path=/; HttpOnly; SameSite=lax"],"Cache-Control":["max-age=0, must-revalidate, private"],"Date":["Sat, 18 Dec 2021 16:55:45 GMT"],"X-Robots-Tag":["noindex"],"Expires":["Sat, 18 Dec 2021 16:55:45 GMT"],"http_status":200} []

计算运费

要计算运费，请使用 calculateTariff 方法。

输入参数

$calcParams - FsDeliverySdk\ValueObject\CalculateParams 对象

输出参数

array - 根据计算参数列表的运费

调用示例

获取配送服务列表

要获取可用配送服务，请使用 getDeliveryList 方法。

输入参数: 无

输出参数

array - 配送服务列表

调用示例

获取配送模式列表

要获取配送模式列表，请使用 getDeliveryTypes 方法。

输入参数

int $type_id - FsDelivery 数据库中的配送模式 ID（非必需参数）

输出参数

array - 配送模式列表

调用示例

<?php
    try {
        $client = new \FsDeliverySdk\Client('api-token');
        $client->setLogger($log);
        $result = $client->getDeliveryTypes(4);

        /*
         Array
        (
            [request_id] => a3e7cca7-a3cf-4d7a-b15e-26fcd691d21f
            [types] => Array
                (
                    [0] => Array
                        (
                            [delivery_company_id] => 50
                            [delivery_company_name] => FSDelivery
                            [type_id] => 4
                            [name] => Дверь-Дверь
                        )
        
                    [1] => Array
                        (
                            [delivery_company_id] => 1
                            [delivery_company_name] => Cdek
                            [type_id] => 4
                            [name] => Дверь-Дверь
                        )
        
                )
        
        )
         */
    }
    
    catch (\InvalidArgumentException $e) {
        // Обработка неверного заполнения параметров
        // $e->getMessage(); // Текст ошибки 
    }

    catch (\FsDeliverySdk\Exception\FsDeliveryException $e) {
        // Обработка ошибки вызова API FsDelivery
        // $e->getMessage(); // Текст ошибки 
        // $e->getCode(); // Код ошибки
        // $e->getRawResponse(); // Ответ сервера FsDelivery как есть (http request body)
    }

    catch (\Exception $e) {
        // Обработка исключения
    }

获取运费列表

要计算运费，请使用 calculateTariff 方法。

输入参数: int $delivery_id - FsDelivery 数据库中的配送服务 ID（非必需参数） int $type_id - FsDelivery 数据库中的配送模式 ID（非必需参数）

输出参数

array - 运费列表

调用示例

<?php
    try {
        $client = new \FsDeliverySdk\Client('api-token');
        $client->setLogger($log);
        $result = $client->getDeliveryTariffs(2);

        /*
         Array
        (
            [request_id] => e4271d3c-dc32-4592-b8bc-7e32a7b57821
            [tariffs] => Array
                (
                    [0] => Array
                        (
                            [id] => 1001
                            [name] => Boxberry склад-склад
                            [delivery_company_id] => 2
                            [delivery_company_name] => Boxberry
                            [type_id] => 1
                        )
        
                )
        
        )
         */
    }
    
    catch (\InvalidArgumentException $e) {
        // Обработка неверного заполнения параметров
        // $e->getMessage(); // Текст ошибки 
    }

    catch (\FsDeliverySdk\Exception\FsDeliveryException $e) {
        // Обработка ошибки вызова API FsDelivery
        // $e->getMessage(); // Текст ошибки 
        // $e->getCode(); // Код ошибки
        // $e->getRawResponse(); // Ответ сервера FsDelivery как есть (http request body)
    }

    catch (\Exception $e) {
        // Обработка исключения
    }

获取可能的订单状态列表

要获取所有可能的订单状态列表，请使用 getDeliveryStatuses 方法。

输入参数: 无

输出参数

array - 包含配送服务拆分的状态列表

调用示例

获取国家列表

要获取国家列表，请使用 getReferenceCountries 方法。

输入参数

int $country_id - FsDelivery 数据库中的国家 ID
string $country_code - 国家代码（ISO 3166-1 2 个字母）
string $country_name - 国家确切名称（例如俄罗斯），不区分大小写搜索

输出参数

array - 国家列表

调用示例

<?php
    try {
        $client = new \FsDeliverySdk\Client('api-token');
        $client->setLogger($log);
        $result = $client->getReferenceCountries(null, 'RU');
        
        /*
        Array
        (
            [request_id] => 3af5a29f-b2a5-4f24-8d51-61db501fb7b2
            [country_list] => Array
                (
                    [0] => Array
                        (
                            [id] => 1
                            [name] => Россия
                            [name_eng] => Russia
                            [code] => RU
                        )
        
                )
        )
        */
    }
    
    catch (\InvalidArgumentException $e) {
        // Обработка неверного заполнения параметров
        // $e->getMessage(); // Текст ошибки 
    }

    catch (\FsDeliverySdk\Exception\FsDeliveryException $e) {
        // Обработка ошибки вызова API FsDelivery
        // $e->getMessage(); // Текст ошибки 
        // $e->getCode(); // Код ошибки
        // $e->getRawResponse(); // Ответ сервера FsDelivery как есть (http request body)
    }

    catch (\Exception $e) {
        // Обработка исключения
    }

获取城市列表

要获取城市列表，请使用方法 getReferenceCities。

输入参数

CitiesFilter $searchFilter - 对象-过滤器
int $page_number - 用于选择的页面编号
int $page_size - 每页结果数量

输出参数

array - 城市列表

调用示例

<?php
    try {
        $client = new \FsDeliverySdk\Client('api-token');
        $client->setLogger($log);
        $citiesFilter = new \FsDeliverySdk\ValueObject\CitiesFilter();
        $citiesFilter->setKladrId('0100400000200');
        $result = $client->getReferenceCities($citiesFilter);
        
        /*
        Array
        (
            [request_id] => 1a100d01-0535-409c-a9ec-ea553ae01695
            [city_list] => Array
                (
                    [0] => Array
                        (
                            [id] => 16418
                            [kladr_id] => 0100400000200
                            [fias_id] => a11b882d-79ab-4087-9d2d-8effea6d066c
                            [postal_code] => 
                            [name] => Абадзехская, Адыгея респ.
                            [name_only] => Абадзехская
                            [fullname] => 
                            [name_eng] => 
                            [region] => Адыгея респ.
                            [country_iso] => RU
                            [country_id] => 1
                            [country_name] => Россия
                            [country_name_eng] => Russia
                            [last_date_update] => 2021-03-21
                        )
        
                )
        
            [page_number] => 1
            [page_size] => 100
        )
         */
    }
    
    catch (\InvalidArgumentException $e) {
        // Обработка неверного заполнения параметров
        // $e->getMessage(); // Текст ошибки 
    }

    catch (\FsDeliverySdk\Exception\FsDeliveryException $e) {
        // Обработка ошибки вызова API FsDelivery
        // $e->getMessage(); // Текст ошибки 
        // $e->getCode(); // Код ошибки
        // $e->getRawResponse(); // Ответ сервера FsDelivery как есть (http request body)
    }

    catch (\Exception $e) {
        // Обработка исключения
    }

获取城市自动完成列表

要获取用于自动完成的 cities 列表，请使用方法 getReferenceCitiesAutocomplete。

输入参数

string $char_city_name - 根据城市名称进行搜索的字符串（至少两个字符）
int|null $fsdelivery_country_id - FSDelivery 基础上的国家 ID

输出参数

array - 城市列表

调用示例

获取订单提取点列表

要获取订单提取点（PВЗ）列表，请使用方法 getDeliveryPoints。

输入参数

PvzFilter $pvzFilter - 对象-过滤器

输出参数

array - PВЗ列表

调用示例

按 NP 名录细化

要获取 NP 名录的详细信息，请使用方法 getReestrWaybills。

输入参数

int $reestr_number - 预付费订单注册号（/1.0/reestr/list 方法中的 number 字段）

输出参数

array - 数据列表

调用示例

NP 注册簿的可能状态

要获取可能的 NP 注册状态，请使用方法 getReestrStatuses。

输入参数: 无

输出参数

array - 状态列表

调用示例

<?php
    try {
        $client = new \FsDeliverySdk\Client('api-token');
        $client->setLogger($log);
        $result = $client->getReestrStatuses();
        
        /*
        Array
        (
            [request_id] => 93b4a90f-24b4-4ab1-892c-208aef3cb18f
            [status_list] => Array
                (
                    [0] => Array
                        (
                            [name] => Готовится
                            [id] => 0
                        )
        
                    [1] => Array
                        (
                            [name] => К оплате
                            [id] => 1
                        )
        
                    [2] => Array
                        (
                            [name] => В графике
                            [id] => 2
                        )
        
                    [3] => Array
                        (
                            [name] => Оплачен
                            [id] => 3
                        )
        
                    [4] => Array
                        (
                            [name] => Удален
                            [id] => 4
                        )
        
                )
        
        )
         */
    }
    
    catch (\InvalidArgumentException $e) {
        // Обработка неверного заполнения параметров
        // $e->getMessage(); // Текст ошибки 
    }

    catch (\FsDeliverySdk\Exception\FsDeliveryException $e) {
        // Обработка ошибки вызова API FsDelivery
        // $e->getMessage(); // Текст ошибки 
        // $e->getCode(); // Код ошибки
        // $e->getRawResponse(); // Ответ сервера FsDelivery как есть (http request body)
    }

    catch (\Exception $e) {
        // Обработка исключения
    }

NP 注册簿列表

要获取 NP 注册列表，请使用方法 getReestrList。

输入参数

ReestrFilter $reestrFilter - 对象-过滤器

输出参数

array - 注册列表

调用示例

获取用户信息

要获取用户信息，请使用方法 getUserInfo。

输入参数: 无

输出参数

array - 用户信息

调用示例

获取订单状态

要获取订单状态，请使用方法 $orderStatusFilter。

输入参数

OrderStatusFilter $orderStatusFilter - 对象-过滤器

输出参数

array - 状态列表

调用示例

<?php
    try {
        $client = new \FsDeliverySdk\Client('api-token');
        $client->setLogger($log);
        $result = $client->getOrderStatuses((new \FsDeliverySdk\ValueObject\OrderFilter())->setOrderId(358)); // последний статус
        $result = $client->getOrderStatuses((new \FsDeliverySdk\ValueObject\OrderFilter())->setOrderId([358, 382])->setShowHistory(1)); // с историей статусов
        /*
        Array
        (
            [request_id] => cb1dbcb7-eb7d-46d3-9f80-0c60c9ae27cc
            [orders] => Array
                (
                    [0] => Array
                        (
                            [order_id] => 358
                            [order_number] => 
                            [order_dispacher_number] => 1108697266
                            [order_delivery_copmany_id] => 1
                            [order_delivery_copmany_name] => Cdek
                            [city_name] => Москва
                            [delivery_status_id] => 4
                            [delivery_status_date] => 2019-02-07 18:12:24
                            [delivery_status_name] => Вручен
                            [delivery_status_description] => 
                        )
        
                )
        
        )
         */
    }
    
    catch (\InvalidArgumentException $e) {
        // Обработка неверного заполнения параметров
        // $e->getMessage(); // Текст ошибки 
    }

    catch (\FsDeliverySdk\Exception\FsDeliveryException $e) {
        // Обработка ошибки вызова API FsDelivery
        // $e->getMessage(); // Текст ошибки 
        // $e->getCode(); // Код ошибки
        // $e->getRawResponse(); // Ответ сервера FsDelivery как есть (http request body)
    }

    catch (\Exception $e) {
        // Обработка исключения
    }

获取订单信息

要获取订单信息，请使用方法 ****。

输入参数

OrderFilter $orderFilter - 对象-过滤器

输出参数

array - 订单列表

调用示例

fsdelivery / fsdelivery-php-sdk

维护者

详细信息

README

用于与 FsDelivery 软件系统集成的 SDK。

内容

变更日志

安装

调试

计算运费

获取配送服务列表

获取配送模式列表

获取运费列表

获取可能的订单状态列表

获取国家列表

获取城市列表

获取城市自动完成列表

获取订单提取点列表

按 NP 名录细化

NP 注册簿的可能状态

NP 注册簿列表

获取用户信息

获取订单状态

获取订单信息