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

Модуль совместим с модулем Главный модуль Битрикса 22 и новее.

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

При использовании другой версии модуля Главный модуль Битрикса, а также несовместимых версий PHP, корректная работа модуля не гарантируется!

Оглавление

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

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 
• В службе доставки

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

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

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

Вкладка	Наименование настройки	Описание настройки
Основные	API токен	Здесь указывается API токен из ЛК Boxberry для работы модуля, указанный токен проверяется по клику вне поля, при наличии ошибки отображается её текст из ЛК Boxberry, деактивируются кнопки Сохранить/Применить.
	Тестовый режим	При активации служба доставки будет использовать для работы тестовый токен. Опция будет полезна для проверки работы службы доставки или при отсутствии API токена. При включении тестового режима указание API токена не требуется.
Заказы	Помечать заказ оплаченным при успешной выдаче	Если статус заказа в api Boxberry сменяется на Успешно выдан в битриксе заказу проставляется отметка Оплачен, удобно использовать для заказов с наложкой.
	Тип выдачи заказа по умолчанию	При создании заказа по api модуль будет передавать выбранный тип выдачи, по умолчанию используется тот, что выбран в ЛК Boxberry в разделе Услуги. В каждом заказе можно поменять тип выдачи через форму редактирования.
	Пункт приема заказа по умолчанию	Пункт приема, в который сдаются заказы для отправки. Используется в расчете стоимости доставки и в создании заказа. В каждом заказе можно поменять пункт приема через форму редактирования.
	Префикс к номеру заказа	Введенное значение будет добавляться к номеру заказа при создании заказа.
Вес, габариты, места (В этой группе настроек размещены настройки габаритов и веса, которые применяются если в свойстве товара эти значения не указаны либо равны 0)	Применить вес и габариты по умолчанию к	Если выбрано к заказу, вес и габариты заказа, указанные в опциях выше всегда будут постоянными, независимо от количества товара в заказе. Создается только 1 место. Если выбрано к 1 товару вес и габариты по умолчанию будут применяться на каждый товар в заказе (если вес/габарит товара не заполнен или 0), будут создаваться места с авторазбивкой по лимитам веса/габаритов.
Индексы (Этот раздел будет со временем дополнятся другими опциями)	Проверять почтовый индекс для расчета курьерской доставки	Индекс переданный битриксом будет передаваться в api запрос калькуляции стоимости доставки для расчета более точной цены, деактивировано по умолчанию т.к. далеко не все индексы Битрикса совпадают с существующими индексами службы доставки Boxberry, рекомендуется активировать только при наличии ошибок в расчете стоимости курьерки.
Наложенный платеж		В этой группе настроек вам нужно пометить галочками платежные системы работающие как пост оплата (наложенный платеж) для расчета стоимости доставки с наложенным платежом при их выборе покупателем в оформлении заказа.
Соответствие свойств заказа		В этой группе настроек нужно указать соответствие полей заказа в Boxberry символьным кодам свойств в Битриксе. Символьный код свойства в Битриксе можно найти в разделе Магазин/Свойства заказа/Список свойств. Если у вас есть несколько плательщиков для них нужно задать одинаковый код свойства и указать его в настройке. Два последних поля Контактное лицо и Название компании предназначены для юр лиц. Если вы используете составные свойства ФИО или Адрес выберите соответствующую раздельную настройку и укажите существующие коды свойств.
Оформление заказа	Не разрешать оформление заказа без выбора ПВЗ	При активации не позволяет покупателю оформить заказ на самовывоз, если пункт выдачи не выбран. Код ПВЗ обязательно требуется при создании заказа в ЛК поэтому опция активна по умолчанию.
	Блокировать от изменений поле адреса ПВЗ при выборе самовывоза	Если активно, блокирует от изменений поле с адресом, т.к. иногда покупатели стирают адрес выбранного ПВЗ и пишут свой адрес. Активно по умолчанию.
	Добавить кнопку виджета по умолчанию	Следующие 5 настроек предназначены для размещения кнопки открытия виджета с выбором ПВЗ на странице оформления заказа. Активна может быть только 1 из 5-ти опций одновременно. Если у вас есть проблемы с опцией по умолчанию, пробуйте переключать другие опции, возможно проблема решится. Эти опции добавлены как возможное решение проблемы без необходимости править код. Если не включить ни одну из опций кнопка открытия виджета не будет отображаться.
	Добавить кнопку виджета к описанию службы доставки
	Добавить кнопку виджета после описания службы доставки
	Добавить кнопку виджета к сроку доставки
	Добавить кнопку виджета к элементу (Укажите id элемента)
Профили		В данном разделе можно добавить необходимые профили службы доставки.
Ограничения		В данном разделе можно добавить необходимые, встроенные в битрикс, ограничения для службы доставки,
Кнопка "Обновить данные"	Кнопка Обновить данные открывает выпадающий список с вариантами обновления. Выбираете какие данные нужно обновить, жмете на них, выполняется api запрос в ЛК Boxberry, затем данные обновляются в таблицах в БД битрикса. Если api запрос вернет ошибку, её текст отобразится в окошке обновления. Все данные обновляются автоматически через агент фоновым заданием ежедневно. Города обновляются раз в сутки, пункты приема раз в 6 часов.  Этот вариант обновления "вручную" добавлен на случай возникновения непредвиденных ошибок, не нужно выполнять обновление без необходимости. Показать скриншот
Кнопка "Очистить кеш"	Модуль хранит кеш селективно, что позволяет очищать не весь кеш битрикса целиком, а только определенные данные самого модуля. Кеш api запросов хранится в папке /bitrix/cache/bb_api/ + название api метода, кеш найденных местоположений хранится в папке /bitrix/cache/bb_locations. Если в настройках интеграции в ЛК  изменяете настройки со вкладки Скрывать ПВ или Расчеты нужно очистить кеш Настройки виджета и Калькулятор. В других случаях очистку кеша производите на свое усмотрение.  Показать скриншот

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

Вкладка	Наименование настройки	Описание настройки
Тип доставки		При создании профиля доставки на вкладке Тип доставки нужно обязательно выбрать, какой тип профиля вы хотите создать: самовывоз или курьерская доставка. Не забывайте изменить название профиля. После создания профиля изменить его тип уже нельзя.
Источник настроек расчета (Каждый профиль позволяет выбрать источник настроек расчета стоимости доставки)	ЛК Boxberry	Будут использоваться настройки из ЛК Boxberry отсюда со вкладки Расчеты.
	Профиль доставки	Позволяет использовать настройки внутри профиля. Все опции аналогичны настройкам из ЛК со вкладки Расчеты, работают также с одинаковой логикой и также называются. Выбор этой опции открывает настройки в профиле, а настройки расчета из ЛК будут игнорироваться.
Описанные далее настройки применимы, если выбран источник настроек расчета - Профиль доставки.
Срок доставки	Скрыть срок доставки	Скрывает срок доставки в оформлении заказа и при любом расчете стоимости доставки с данным профилем.
	Укажите количество дней, которое необходимо добавить к основному сроку доставки Boxberry	Добавляет указанное число к сроку доставки.
Округление	Округление до	Позволяет округлить расчет стоимости. Возможные варианты: Не округлять До рублей До десяти рублей До сотен рублей
	Округлить как	Округление математическое - округление до ближайшего целого, например стоимость доставки 124р будет округляться как 120р при округлении до десяти рублей, либо 124.35р будет округляться как 124р при округлении до рублей Округление в большую сторону - округление до целого в большую сторону, например стоимость доставки 124р будет округляться как 130р при округлении до десяти рублей, либо 124.35р будет округляться как 125р при округлении до рублей
Стоимость доставки		Позволяет настроить бесплатную стоимость доставки от определенной суммы заказа, либо полностью бесплатную стоимость доставки. Например, при таком условии стоимость доставки будет рассчитана по тарифу для заказов <= 7000р, а затем доставка будет бесплатной. Показать скриншот
Надбавки (Позволяет настроить надбавки ко многим параметрам) Важно: все надбавки могут быть как положительными, так и отрицательными. Например, указание надбавки к весу со знаком минус -300, вычтет 300 грамм из переданного для расчета веса, а указание надбавки 1000  – добавит 1000 грамм к переданному весу.  Чтобы убрать из стоимости доставки страховку укажите в надбавке Процент от объявленной стоимости -0.5	Вес	Добавляет\убавляет вес, переданный для расчета на сайте.
	Процент от тарифа Boxberry	Добавляет\убавляет процент от итоговой стоимости доставки.
	Процент от объявленной стоимости	Добавляет\убавляет процент от стоимости услуги страховки.
	Процент от суммы к оплате	Добавляет\убавляет процент от стоимости услуги Прием платежа (Наложенный платеж).
	Фиксированная сумма	Добавляет\убавляет фиксированную сумму от стоимости доставки
Опции	Минимальная стоимость доставки	Позволяет задать минимальную стоимость доставки, т.е. даже если реальный расчет стоимости будет ниже указанной, модуль все равно отобразит минимальную стоимость.
	Максимальная стоимость доставки	Позволяет задать максимальную стоимость доставки, т.е. даже если реальный расчет стоимости будет выше указанной, модуль все равно отобразит максимальную стоимость.

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

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

Печать этикеток и актов доступна на странице заказов в админке: Магазин/Заказы. Если выбрать заказы, которые еще не созданы в ЛК 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();

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

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;