Оглавление

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

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

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

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

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

1.  В меню админки перейти в Магазин/Службы доставки нажать кнопку Добавить - Служба доставки Boxberry
2. На странице добавления службы доставки может отобразится окошко с уведомлением об обновлении данных. Модуль получает по API данные городов и пунктов приема, если они отсутствуют, все действие занимает буквально несколько секунд, выполняется только в случае отсутствия данных, текст сообщения сменится на успешный, либо на текст ошибки в случае ошибки. Окошко закроется автоматически через 2 секунды после завершения операции.
3. Для создания службы доставки нужно указать несколько обязательных настроек, это API токен из ЛК Boxberry и пункт приема заказов по умолчанию. Если какая то из настроек не заполнена, на соответствующей вкладке отобразится иконка с восклицательным знаком и вкладка будет подсвечена красным цветом. Не заполненные опции также выделяются красным цветом, под полем настройки отображается сообщение об ошибке.
4. Если API токен не заполнен отобразится ошибка: Укажите API токенЕсли API токен указан не верно отобразится ошибка переданная ЛК Boxberry
5. Если у вас на данный момент нет API токена, нажмите галку Тестовый режим, в этом случае модуль будет работать с тестовым токеном и ему не потребуется реальный токен клиента.
6. Для выбора пункта приема начните набирать название города в поле Пункт приема по умолчанию во вкладке Заказы, отобразится выпадающий список, где вы сможете выбрать нужный вам пункт приема, не редактируйте выбранное значение.
7. На вкладке Соответствие свойств заказа проверьте, что указанные по умолчанию свойства у вас существуют, настроены и активны, либо укажите свои. Свойства находятся в разделе Магазин/Свойства заказа/Список свойств.
8. Если у вас используются составные свойства ФИО или Адрес, выберите Раздельные свойства в соответствующей настройке службы доставки, иначе используйте одно свойство.
9. Если в магазине несколько типов плательщиков, вы можете задать для них одинаковый символьный код, либо создать новую службу доставки и в ней указать уже другие символьные коды, а чтобы они не пересекались, настроить ограничения, в этом случае действуйте как вам удобнее.
10. Нажмите Сохранить или Применить. Создание службы доставки завершено. После создания службы доставки модуль автоматически добавляет два профиля доставки - Самовывоз и Курьер.

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример заказа, оформленного со службой доставки Boxberry:

Разберем как это работает на практике:

1. Создадим этот заказ в ЛК Boxberry
2. После создания заказа в панели снизу отобразятся данные полученные от ЛК Boxberry, текст кнопки Создать заказ в ЛК сменится на Обновить заказ в ЛК. 
3. Вверху формы отобразится сообщение об успешном создании заказа. Станет активна кнопка Удалить заказ из ЛК
4. Сменим профиль доставки в форме на Курьер и нажмем Обновить заказ в ЛК. Отобразится сообщение об успешном расчете или ошибка в случае если для населенного пункта недоступна курьерская доставка
5. Расчет стоимости и смена способа доставки прошли успешно.
6. Изменим тип выдачи, пункт приема, сумму к оплате и нажмем кнопку Пересчитать стоимость 
7. Данные успешно обновились. Обратите внимание, вы можете не выполнять перерасчета при смене данных, а обновлять заказы с любыми данными, которые вам нужны. Перерасчеты выполняются автоматически только при смене профиля доставки т.к. в этом случае нужно убедится, что тариф по маршруту существует. В других случаях вам решать выполнять перерасчет или нет.
8. Форма редактирования не позволит создать заказ с не верными данными, она отобразит ошибку, которую возвращает ЛК Boxberry, например попробуем указать вес места больше возможного:
9. Получаем ошибку, заказ не будет обновлен. Такая валидация работает со всеми данными.
10. Теперь попробуем удалить заказ из ЛК Boxberry, при удалении всегда отображается окошко для подтверждения
11. Заказ успешно удален, из панели информации удалены данные, кнопки в форме сброшены.
12. Поработаем с заказом с другой службой доставки. Первое, что нужно сделать это выбрать профиль доставки, с которым хотим работать, иначе ничего не получится сделать. После выбора профиля производится расчет стоимости и с заказом можно работать.
13. Мы выбрали профиль доставки, получили расчет и автоматическое заполнение доступных данных, попробуем создать заказ в ЛК
14. Получаем ошибку т.к. для создания заказа с самовывозом нужно выбрать пункт выдачи, нажмем кнопку Выбрать ПВЗ, выберем тот, что нам нужен и снова нажмем Создать заказ в ЛК
15. Заказ успешно создан.
16. Если мы перейдем в админку Магазин/Заказы и распечатаем акт для этого заказа, ссылка на акт добавится в панель информации в просмотре заказа, обновление и удаление заказа станут недоступными

Заказы Boxberry в админке

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• orderId -  id заказа в Битриксе

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

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

Модуль создает 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 профиля доставки. Id профиля доставки легко получить из объекта заказа или другими способами.

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

echo '<pre>';
print_r($options);
echo '</pre>';

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

Вы получите доступ как к опциям профиля доставки, так и к опциям службы доставки - родителя профиля.

Если передать несуществующий айди профиля, либо не принадлежащий службе доставки Boxberry, будет выброшено исключение.

Получение опций модуля

Работать с опциями модуля нужно через статичные методы класса \Boxberry\Bitrix\Helpers\Options, например:

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

echo '<pre>';
print_r(\Boxberry\Bitrix\Helpers\Options::getApiLogFilePath());
echo '</pre>';

Выполнение расчета стоимости доставки

Расчет стоимости доставки выполняется методом \Boxberry\Bitrix\Helpers\Delivery::calculate

Для выполнения расчета необходим объект отгрузки \Bitrix\Sale\Shipment

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

use Bitrix\Sale\Order;

$order = Order::load('7'); //айди заказа
$shipmentCollection = $order->getShipmentCollection();

$calculateResult = null;

foreach ($shipmentCollection as $shipment) {
    if (!$shipment->isSystem()) {
        $calculateResult = \Boxberry\Bitrix\Helpers\Delivery::calculate($shipment);
    }
}

echo '<pre>';
print_r($calculateResult);
echo '</pre>';

Как проверить содержится ли в заказе способ доставки Boxberry

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

use Bitrix\Sale\Order;

$order = Order::load('7'); // ID заказа
$isBoxberryDeliveryInOrder = \Boxberry\Bitrix\Helpers\Validator::isBoxberryDeliveryInOrder($order);

var_dump($isBoxberryDeliveryInOrder);

Получить объект City для управления параметрами города из API Boxberry

Получение по коду города из api Boxberry

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

$bbCity = \Boxberry\Bitrix\CitiesFullTable::getBbCityByCode('68'); // 68 - Москва, код города в api Boxberry

echo '<pre>';
print_r($bbCity);
echo '</pre>';

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

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

$bbCity = \Boxberry\Bitrix\CitiesFullTable::getBbCityByBitrixLocationCode('0000073738'); // 0000073738 - Москва, код города в Битриксе

echo '<pre>';
print_r($bbCity);
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);
}

Запуск агентов

Запуск агента синхронизации статусов заказов

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

$syncStatusesAgentRun = Boxberry\Bitrix\Agents\Tracking::syncStatuses();

echo $syncStatusesAgentRun;

Запуск агента обновлений городов

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

$citiesUpdateAgentRun = Boxberry\Bitrix\Agents\CitiesUpdate::run();

echo $citiesUpdateAgentRun;

Запуск агента обновлений пунктов приема заказа

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

$pointsForParcelsUpdateAgentRun = Boxberry\Bitrix\Agents\PointsForParcelsUpdate::run();

echo $pointsForParcelsUpdateAgentRun;

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

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

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

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

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

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

Также, вероятно, вам нужно будет добавить кнопку выбора ПВЗ в другой элемент на странице, не в тот, что добавляется по умолчанию, в этом случае перейдите в службу доставки, в ней настройка Оформление заказа→Добавить кнопку виджета к элементу и там в поле впишите id элемента.

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