WT CDEK library

Описание

В составе пакета

• библиотека WT CDEK library
• плагин настроек для подключения к API CDEK System - WT Cdek
• официальный виджет выбора типа доставки от CDEK
• плагин задачи стандартного планировщика задач Joomla для копирования и обновления данных CDEK в локальную базу данных

Подключение библиотеки в своё расширение для Joomla

<?php

use Webtolk\Cdekapi\Cdek;

\defined('_JEXEC') or die;

// Вариант 1: брать credentials из настроек плагина
$cdek = new Cdek();

// Вариант 2: передать credentials явно
$cdek = new Cdek(test_mode: true, client_id: 'your_client_id', client_secret: 'your_client_secret');

Авторизация происходит автоматически. Токен кэшируется средствами Joomla.

Пример: поиск города

<?php

use Webtolk\Cdekapi\Cdek;

defined('_JEXEC') or die;

$cdek = new Cdek();

$result = $cdek->location()->getCities([
    'postal_code' => '410012',
    'city'        => 'Саратов',
    'size'        => 1,
]);

Результат запроса:

Array
(
    [0] => Array
        (
            [code] => 428
            [city_uuid] => 7e54a0b3-76f0-41e2-92e0-f1e600ad84fd
            [city] => Саратов
            [fias_guid] => bf465fda-7834-47d5-986b-ccdb584a85a6
            [country_code] => RU
            [country] => Россия
            [region] => Саратовская область
            [region_code] => 47
            [fias_region_guid] => df594e0e-a935-4664-9d26-0bae13f904fe
            [sub_region] => городской округ Саратов
            [longitude] => 46.034266
            [latitude] => 51.533562
            [time_zone] => Europe/Saratov
            [payment_limit] => -1
        )

)

Доступные сущности REST API CDEK

В 1.3.0 библиотека поддерживает следующие сущности:

• calculator()
• check()
• delivery()
• deliverypoints()
• intakes()
• international()
• location()
• oauth()
• orders()
• passport()
• payment()
• photoDocument()
• prealert()
• print()
• reverse()
• webhooks()

У каждой сущности свой набор методов. Подробные примеры вынесены в каталог docs/ в git репозитории библиотеки.

Официальный виджет выбора типа доставки от CDEK (выбор пунктов выдачи заказа на карте)

В состав библиотеки включен виджет последней на данный момент версии: 3.10.2.

Подключение JavaScript виджета CDEK

Javascript виджета оформлен как Joomla Web Asset. В своём коде подключаем его с помощью WebAssetManager следующим образом:

<?php
use Joomla\CMS\Factory;

defined('_JEXEC') or die('Restricted access');

$doc  = Factory::getApplication()->getDocument();

/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = $doc->getWebAssetManager();
$wa->useScript('cdek-widget-umd');

В остальном при настройке следуем документации виджета.

Service.php виджета

Виджет представляет собой Яндекс.карту, которая по ajax получает список пунктов выдачи заказа. Для работы с данной библиотекой нужно при инициализации виджета указать параметр servicePath - url для ajax-запроса. По умолчанию в комплекте с виджетом идёт файл service.php, который является точкой входа для ajax-запроса. В данной библиотеке функционал этого файла (получение списка ПВЗ и калькуляции тарифов) перенесён в системный плагин Joomla.

<?php
use Joomla\CMS\Uri\Uri;
use Joomla\CMS\Session\Session;

defined('_JEXEC') or die('Restricted access');

$service_url = new Uri(Uri::base());
$service_url->setPath('/index.php');
$service_url->setQuery([
    'option'                => 'com_ajax',
    'plugin'                => 'wtcdek',
    'group'                 => 'system',
    'format'               => 'raw',
    'city_code'          => $city_code, // CDEK код города для получения списка ПВЗ только для выбранного города
    Session::getFormToken() => 1
]);
// URL string
$service_url->toString();

Для javascript используем либо Joomla Script options, либо php echo, в зависимости от структуры вашего расширения.

Копирование и обновление данных CDEK в локальную базу данных

Добавлен плагин стандартного планировщика задач Joomla (появился в Joomla 4.1), который позволяет копировать и обновлять по расписанию списки стран и регионов доставки, населенных пунктов, а так же пунктов выдачи заказа. Эти данные вы можете использовать затем в своих расширениях.

Рекомендуется настроить выполнение задач планировщика Joomla с помощью серверного CRON, так как некоторые справочники довольно большого объёма и их обновление может занимать продолжительное время.

Чтобы запустить выполнение задач планировщика с помощью CLI Вам нужно подключиться к своему серверу по SSH и выполнить команду:

php /path/to/site/public_html/cli/joomla.php scheduler:run

Если требуется запустить конкретную задачу, то посмотреть список можно с помощью команды

php /path/to/site/public_html/cli/joomla.php scheduler:list

а затем запустить задачу по её id

php /path/to/site/public_html/cli/joomla.php scheduler:run --id=XXX

Также будьте внимательны, на некоторых хостингах существует ограничение на занимаемый объём базы данных.