Новый модуль для 1С-Битрикс

Оглавление

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

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, по нажатию на которую открывается форма для редактирования данных заказа. Повторное нажатие скрывает форму.

Пример заказа, оформленного со службой доставки 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();

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

Модуль создает 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>';

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

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

\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;