Установка и настройка модуля

Модуль совместим с модулем Главный модуль Битрикса 22 и новее. Требования к серверу (хостингу) для корректной работы модуля: PHP не ниже версии 8.1.

Установка из Маркетплейса

1. Перейти по ссылке
2. Нажать кнопку Установить, ввести адрес сайта, нажать Установить
3. В админке сайта нажать Загрузить, принять лицензионное соглашение, нажать Установить. Модуль установлен.

Установка из архива

1. Авторизоваться на Вашем сайте с доступом администратора
2. Проверить кодировку вашей установки Bitrix, нажать на клавиатуре Ctrl + U
3. В открывшейся вкладке вы увидите кодировку, она может быть windows-1251, либо UTF-8
4. Скачать модуль для соответствующей кодировки
5. В админке магазина перейти в Контент/Файлы и папки в поле Путь указать /bitrix/modules, нажать ОК
6. Нажать Загрузить файл, затем Добавить файл - выбрать скачанный ранее архив, нажать Сохранить
7. В меню напротив файла нажать кнопку Действия, нажать Распаковать, еще раз нажать Распаковать
8. В меню админки перейти в Marketplace/Установленные решения, нажать на меню действий загруженного модуля, нажать Установить. Модуль установлен.

Создание службы доставки

1. В меню админки перейти в Магазин/Службы доставки нажать кнопку Добавить - Служба доставки Яндекс Доставка

2. На странице добавления службы доставки может отобразится окошко с уведомлением об обновлении данных. Модуль получает по API данные городов и пунктов приема, если они отсутствуют, все действие занимает буквально несколько секунд, выполняется только в случае отсутствия данных, текст сообщения сменится на успешный, либо на текст ошибки в случае ошибки. Окошко закроется автоматически через 2 секунды после завершения операции.

3. Для создания службы доставки нужно указать несколько обязательных настроек, это API токен из ЛК и пункт приема заказов по умолчанию. Если какая то из настроек не заполнена, на соответствующей вкладке отобразится иконка с восклицательным знаком и вкладка будет подсвечена красным цветом. Незаполненные опции также выделяются красным цветом, под полем настройки отображается сообщение об ошибке.

4. Если API токен не заполнен отобразится ошибка: Укажите API токен

   Если API токен указан неверно, то отобразится ошибка переданная ЛК Яндекс Доставки.

5. Если у вас на данный момент нет API токена, нажмите галку Тестовый режим, в этом случае модуль будет работать с тестовым токеном и ему не потребуется реальный токен клиента.

6. Для выбора пункта приема начните набирать название города в поле Пункт приема по умолчанию во вкладке Заказы, отобразится выпадающий список, где вы сможете выбрать нужный вам пункт приема, не редактируйте выбранное значение.

7. На вкладке Соответствие свойств заказа проверьте, что указанные по умолчанию свойства у вас существуют, настроены и активны, либо укажите свои. Свойства находятся в разделе Магазин/Свойства заказа/Список свойств.

8. Если у вас используются составные свойства ФИО или Адрес, выберите Раздельные свойства в соответствующей настройке службы доставки, иначе используйте одно свойство.

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

10. Нажмите Сохранить или Применить. Создание службы доставки завершено. После создания службы доставки модуль автоматически добавляет два профиля доставки - Самовывоз и Курьер.

Описание настроек

Модуль содержит два типа настроек:

• Общие - доступны в меню Настройки/Модули/Яндекс Доставка
• В службе доставки

Это позволяет гибко настраивать службы доставки штатными средствами Битрикса без необходимости доработок.

Можно создавать службы доставки и устанавливать в них разные API токены для работы с несколькими кабинетами, разные пункты приема, использовать разные свойства заказа. Дополнительно каждый профиль в службе доставки предлагает широкий набор настроек калькуляции стоимости доставки.

Настройки службы доставки

Настройки профиля доставки

Общие настройки модуля

Печать этикеток и актов

Печать этикеток и актов доступна на странице заказов в админке: Магазин/Заказы. Если выбрать заказы, которые еще не созданы в ЛК Яндекс Доставки, при выборе печати этикетки заказ будет выгружен и будет возвращена этикетка, при печати актов будет сформирован акт и возвращен для печати.

Все этикетки формируются на печать в одной вкладке браузера, акты открываются для печати каждый в новой вкладке браузера.

В админке перейти в Магазин/Заказы, выбрать галочкой нужные заказы, в меню действий выбрать нужное действие.

Редактирование заказа в админке

В новом модуле добавлен функционал редактирования данных заказа в ЛК Яндекс Доставки в просмотре заказа в Битриксе.

В тулбаре с действиями вверху добавляется кнопка Яндекс Доставки, по нажатию на которую открывается форма для редактирования данных заказа. Повторное нажатие скрывает форму.

Вы можете редактировать любые данные доступные в форме, как перед отправкой заказа так и после. До тех пор пока не сформируете акт по заказу можете обновлять все данные любое количество раз.

Заказы Яндекс Доставки в админке

Посмотреть все статусы заказов со службой доставки Яндекс Доставки можно в админке в разделе Магазин/Заказы Яндекс Доставка. На этой странице доступен поиск, отображение текущих статусов заказов.

Агенты модуля

Модуль создает 4 агента при установке:

1. Агент обновления городов, интервал 86400 секунды (раз в сутки)

   Boxberry\Bitrix\Agents\CitiesUpdate::run();
   

2. Агент обновления пунктов приема, интервал 21600 секунды (раз в 6 часов)

   Boxberry\Bitrix\Agents\PointsForParcelsUpdate::run();
   

3. Агент проверки активности API токенов, интервал 3600 секунд (раз в час)

   Boxberry\Bitrix\Agents\KeysChecker::checkToken();
   

4. Агент синхронизации статусов заказов, интервал 3600 секунд (раз в час). Настройки этого агента можно менять в настройках модуля

   Boxberry\Bitrix\Agents\Tracking::syncStatuses();
   

События модуля

onBeforeGetWeights - позволяет менять массив мест перед выгрузкой заказа в ЛК.

Метод обработчик получает объект \Bitrix\Main\Event содержащий два параметра:

• orderId - id заказа в Битриксе
• boxes - массив мест в заказе, его можно изменять

onBeforeSetNotice - позволяет добавлять комментарий к заказу, строка с комментарием передается в параметре notice API метода ParcelCreate.

Метод обработчик получает объект \Bitrix\Main\Event содержащий два параметра:

• orderId - id заказа в Битриксе
• notice - строка с комментарием, его можно изменять

Таблицы модуля

Модуль создает 3 таблицы в БД при установке:

• b_boxberry_cities_full - таблица с городами
• b_boxberry_points_for_parcels - таблица с пунктами приема
• b_boxberry_orders - таблица с заказами

Для разработки

Загрузка модуля

Для начала загружаем модуль используя класс Loader:

\Bitrix\Main\Loader::includeModule('boxberry.delivery');

Работа с API клиентом

Создание экземпляра класса с тестовым токеном:

$client = new \Boxberry\Api\Client(\Boxberry\Api\Client::TEST_TOKEN);

Выполнение API запроса GetKeyIntegration:

\Bitrix\Main\Loader::includeModule('boxberry.delivery');
$client = new \Boxberry\Api\Client(\Boxberry\Api\Client::TEST_TOKEN);
$widgetKey = $client->getKeyIntegration();
var_dump($widgetKey);

Получение опций профиля и службы доставки

Для получения опций профиля и службы доставки нужно создать экземпляр класса \Boxberry\Bitrix\Helpers\Options передав аргументом id профиля доставки:

\Bitrix\Main\Loader::includeModule('boxberry.delivery');
$options = new \Boxberry\Bitrix\Helpers\Options('95'); //замените id профиля на ваш существующий
echo '<pre>';
print_r($options);
echo '</pre>';

Изменение мест в заказе

Регистрируем обработчик события onBeforeGetWeights, затем, для примера, меняем вес у первого места:

use Bitrix\Main\EventManager;
//Регистрация обработчика
$eventManager = EventManager::getInstance();
$eventManager->registerEventHandler(
    'boxberry.delivery',
    'onBeforeGetWeights',
    'boxberry.delivery',
    '\Boxberry\Bitrix\Entity\Order',
    'modifyPlaces'
);

// Метод-обработчик события в классе \Boxberry\Bitrix\Entity\Order
public static function modifyPlaces(Event $event): void
{
    $boxes = $event->getParameter('boxes');
    $boxes[0]['Weight'] = 1301;
    $event->setParameter('boxes', $boxes);
}

Передача комментария для заказа

Регистрируем обработчик события onBeforeSetNotice, затем, для примера, добавляем комментарий к заказу:

use Bitrix\Main\EventManager;
//Регистрация обработчика
$eventManager = EventManager::getInstance();
$eventManager->registerEventHandler(
    'boxberry.delivery',
    'onBeforeSetNotice',
    'boxberry.delivery',
    '\Boxberry\Bitrix\Entity\Order',
    'setNotice'
);

// Метод-обработчик события в классе \Boxberry\Bitrix\Entity\Order
public static function setNotice(Event $event): void
{
    $event->setParameter('notice', 'Комментарий к заказу');
}

Доработка для кастомных компонентов оформления заказа

"Из коробки" модуль гарантировано работает только со стандартным пошаговым компонентом оформления заказа sale.order.ajax. Под другие компоненты/кастомы он не тестировался, но вполне может работать с ними после доработок со стороны магазина.

Что стоит учесть если вы планируете использовать его с кастомным компонентом оформления заказа:

1. Модуль подписан на событие OnSaleComponentOrderJsData для определения выбранного способа доставки в оформлении заказа
2. Модуль подписан на событие OnSaleOrderBeforeSaved для проверки выбранного ПВЗ при сохранении заказа
3. Модуль подписан на событие OnSaleOrderSaved для обработки и сохранения данных заказа

Все указанные выше подписки находятся в файле /bitrix/php_interface/include/sale_delivery/boxberry/handler.php

Если в вашем кастоме этот функционал изменен/работает по другому, вам нужно адаптировать его под модуль самостоятельно.

Во фронте модуль не использует объект BX.Sale.OrderAjaxComponent. Модуль создает два своих объекта это bbParams и bbDelivery, значения в bbParams устанавливаются во время отработки события onAjaxSuccess.