README

SDK для интеграции с программным комплексом FsDelivery.

Документация к API.

Содержание

Changelog

0.6.1 - Добавляет поддержку Guzzle 7.*
0.6.0 - Подробное описание можно посмотреть здесь;
0.5.0 - Первая версия SDK реализующая методы API FsDelivery;

Установка

Для установки можно использовать менеджер пакетов 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 - ID режима доставки по базе FsDelivery (не обязательный параметр)

Выходные параметры:

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 - ID службы доставки по базе FsDelivery (не обязательный параметр) int $type_id - ID режима доставки по базе FsDelivery (не обязательный параметр)

Выходные параметры:

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 - ID страны по базе FsDelivery
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) {
        // Обработка исключения
    }

Получение списка городов для AUTOCOMPLETE

Для получение списка городов для AUTOCOMPLETE используйте метод getReferenceCitiesAutocomplete.

Входные параметры:

string $char_city_name - Строка поиска по названию города (от двух символов)
int|null $fsdelivery_country_id - ID страны по базе FSDelivery

Выходные параметры:

array - список городов

Примеры вызова:

Получение списка пунктов выдачи заказов (ПВЗ)

Для получение списка пунктов выдачи заказов (ПВЗ) используйте метод getDeliveryPoints.

Входные параметры:

PvzFilter $pvzFilter - объект-фильтр

Выходные параметры:

array - список ПВЗ

Примеры вызова:

ДЕТАЛИЗАЦИЯ ПО РЕЕСТРУ НП

Для получения детализации по реестру НП используйте метод getReestrWaybills.

Входные параметры:

int $reestr_number - Номер реестра наложенного платежа (поле number из метода /1.0/reestr/list)

Выходные параметры:

array - список данных

Примеры вызова:

Возможные статусы реестров НП

Для получения возможных статусов реестров НП используйте метод 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) {
        // Обработка исключения
    }

Список реестров НП

Для получения списка реестров НП используйте метод 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

Maintainers

Details

README

SDK для интеграции с программным комплексом FsDelivery.

Содержание

Changelog

Установка

Отладка

Расчет тарифа

Получение списка служб доставки

Получение списка режимов доставки

Получение списка тарифов

Получение списка возможных статусов заказа

Получение списка стран

Получение списка городов

Получение списка городов для AUTOCOMPLETE

Получение списка пунктов выдачи заказов (ПВЗ)

ДЕТАЛИЗАЦИЯ ПО РЕЕСТРУ НП

Возможные статусы реестров НП

Список реестров НП

Получение информации о пользователе

Получение статусов заказа

Получение информации по заказам