VibeFox Jadlog for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP.

Договор с Jadlog (для актуальных цен и пунктов Pickup): актуальные цены и список пунктов Pickup поступают из API Embarcador Jadlog. Ваш франчайзи Jadlog выдаёт доступ после подписания договора. Вам понадобятся токен API Embarcador, CNPJ (или CPF) отправителя, указанный в договоре, расчётный счёт (conta corrente) и, если он у вас есть, номер договора. Если вы используете только фиксированные цены, договор с Jadlog не нужен.

Лицензионный ключ VibeFox: приобретается на vibefox.net. Один ключ работает на одном домене.

Установка

1. В панели администратора перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox Jadlog в списке модулей и нажмите Configure.

3. Введите лицензионный ключ VibeFox в поле License key в блоке лицензии вверху страницы Configure и нажмите Activate (см. Лицензионный ключ).

4. Вставьте токен API, укажите CNPJ, расчётный счёт, номер договора и CEP отправки, выберите услугу Jadlog и, если валюта магазина по умолчанию не BRL, введите курс BRL. При необходимости добавьте фиксированные цены или резервную стоимость доставки (см. раздел «Конфигурация»). Нажмите Save.

5. Чтобы предлагать также пункты Jadlog Pickup, включите Enable Jadlog Pickup и нажмите Save.

При установке модуль создаёт двух перевозчиков: Jadlog (доставка на дом, включён, текст срока доставки Jadlog delivery to your address) и Jadlog Pickup (выключен, текст срока доставки Pickup at a Jadlog Pickup point). Оба привязаны к зоне Бразилии и ко всем группам клиентов. Зоны, группы клиентов, срок доставки, логотип и ограничения по размеру можно изменить в Shipping > Carriers. Цены там не задавайте: цена всегда берётся из модуля.

Конфигурация

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Jadlog > Configure. Они применяются к обоим перевозчикам Jadlog. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. Каждое сохранение также очищает кэш цен Jadlog и списков пунктов Pickup.

Вверху страницы модуль выводит предупреждения о неполной настройке: нет токена API (используются только фиксированные цены, а пункты Pickup не могут быть выведены), нет ни токена API, ни фиксированных цен (способ доставки никогда не показывается), не указан CNPJ или расчётный счёт, не указан CEP отправки, не задан курс BRL для магазина, который продаёт не в BRL, единица измерения веса или размеров магазина, которую модуль не распознаёт (тогда вес принимается в кг, а размеры в см; задайте единицы в International > Localization, Local units), либо удалён перевозчик Jadlog. При сохранении сообщаются неверные значения: CEP без 8 цифр, CNPJ без 14 цифр (или 11 для CPF), недопустимое число, минимальный вес больше максимального (оба веса сохраняют прежние значения), неизвестная страна или недопустимая цена в таблице цен.

General

Enable/Disable: включает или выключает доставку на дом Jadlog. Это тот же переключатель, что и статус перевозчика в Shipping > Carriers.

Method title: название перевозчика для доставки на дом, которое отображается в корзине и при оформлении заказа. По умолчанию: Jadlog. Обязательное поле.

Tax status: None или Taxable с одним из ваших налоговых правил. Значение сохраняется для обоих перевозчиков Jadlog. Цены Jadlog являются окончательными ценами перевозчика. Выберите None, если PrestaShop не должен добавлять к ним налог.

Jadlog live prices

Актуальные цены запрашиваются только для адресов в Бразилии с полным 8-значным CEP.

API token: токен Embarcador от Jadlog. Его можно вставить с приставкой «Bearer» или без неё. Оставьте поле пустым, если нужны только фиксированные цены. После сохранения поле остаётся пустым и показывает Saved - leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Remove the saved API token: отметьте галочку и нажмите Save, чтобы удалить сохранённый токен.

CNPJ: CNPJ (14 цифр) или CPF (11 цифр) отправителя, указанный в договоре с Jadlog. Допускаются точки, косые черты и дефисы.

Current account (conta corrente): номер вашего расчётного счёта Jadlog. Без него и без CNPJ Jadlog не может рассчитать стоимость, и используются только фиксированные цены.

Contract number: номер вашего договора с Jadlog, если франчайзи его присвоил.

Origin CEP: почтовый индекс, с которого отправляются посылки, 8 цифр. Сохраняется в формате 00000-000. Оставьте поле пустым, чтобы использовать почтовый индекс магазина из Shop Parameters > Contact > Stores, если адрес магазина находится в Бразилии.

Jadlog service: услуга (modalidade) вашего договора для доставки на дом: .Package (3, по умолчанию), .Com (9), Expresso (0), Rodoviário (4), Econômico (5), Doc (6), Corporate (7), Internacional (10), Cargo (12) или Emergencial (14). Jadlog Pickup (40) — второй перевозчик.

Insurance type: Normal (N) (по умолчанию) или Own insurance policy (A - apolice), как согласовано в вашем договоре с Jadlog.

Volumetric weight: Jadlog взимает большее из фактического и объёмного веса.

BRL exchange rate: Jadlog выставляет цены в бразильских реалах. Если валюта магазина по умолчанию — BRL, это поле не нужно. В противном случае введите, сколько стоит 1 BRL в валюте магазина по умолчанию, например 0.16. Цена Jadlog умножается на этот курс, а объявленная стоимость заказа, передаваемая в Jadlog, пересчитывается обратно в BRL. Без курса актуальные цены не используются, применяются только фиксированные цены. Разделителем дробной части можно считать как точку, так и запятую.

Delivery time: показывает срок доставки, возвращённый Jadlog, при оформлении заказа — под перевозчиком Jadlog и рядом с каждым пунктом Pickup, например «Delivery time: 3 business days». По умолчанию включено. Срок доставки всегда сохраняется с заказом.

Jadlog Pickup

Второй перевозчик с услугой Jadlog Pickup (40). Нужен токен API. Без пунктов перевозчик скрывается.

Enable Jadlog Pickup: включает или выключает перевозчика Jadlog Pickup. Это тот же переключатель, что и его статус в Shipping > Carriers. После установки выключен.

Jadlog Pickup carrier name: название этого варианта при оформлении заказа. По умолчанию: Jadlog Pickup. Обязательное поле.

Points to show: сколько пунктов Pickup предлагать, от 1 до 10. По умолчанию: 5.

Fixed prices (используются, когда нет токена API, для стран, которые Jadlog не обслуживает, и всякий раз, когда Jadlog не возвращает цену)

Price per country: таблица с колонками Country, Price, XS, S, M, L и XL в валюте магазина по умолчанию. Нажмите + Add country, чтобы добавить строку, и значок корзины, чтобы удалить строку. Колонка размера выбирается по весу корзины: XS до 1 кг, S до 2 кг, M до 3 кг, L до 5 кг, XL свыше 5 кг. Price используется, когда колонка размера пуста. Цена 0 означает бесплатную доставку для этой страны. Используйте * Default (other countries) для всех остальных стран. Строки без цен удаляются при сохранении.

Fallback cost: используется, когда ни Jadlog, ни таблица не дают цену. Оставьте поле пустым, чтобы в этом случае скрывать перевозчика.

Fixed price applies: Per order взимает цену один раз. Per item (price x quantity) умножает её на количество товаров в корзине. Это относится только к фиксированным ценам и резервной стоимости. Цены Jadlog уже учитывают всю корзину.

Conditions

Minimum weight (kg): скрывает перевозчиков, когда корзина весит меньше. 0 означает отсутствие ограничения.

Maximum weight (kg): скрывает перевозчиков, когда корзина весит больше. По умолчанию: 150. 0 означает отсутствие ограничения.

Minimum order amount: показывает перевозчиков только тогда, когда промежуточная сумма корзины (товары, требующие доставки, после скидок, до налогов) достигает этой суммы. Оставьте поле пустым, чтобы показывать их всегда.

Free shipping from: промежуточная сумма корзины (после скидок, до налогов), начиная с которой доставка бесплатна. Оставьте поле пустым, если бесплатной доставки нет.

Availability without shipping zones

Ignore shipping zones: предлагает Jadlog для стран, указанных ниже, даже если его перевозчики не привязаны к их зоне. Когда вы включаете эту опцию, оба перевозчика привязываются ко всем активным зонам, а зоны, созданные позже, тоже привязываются. Когда вы снова выключаете её, перевозчики получают обратно те зоны, которые были у них раньше.

Countries: страны назначения для этого режима, за пределами собственных зон перевозчиков. Оставьте поле пустым, чтобы разрешить все страны. Это поле используется только тогда, когда включено Ignore shipping zones.

Advanced

Debug log: записывает каждый запрос и ответ Jadlog в logs/vfd_jdlg_debug.log.php в папке модуля. Файл нельзя открыть через веб. Ошибки API записываются всегда, даже когда эта опция выключена. Токен, CNPJ и счёт никогда не записываются, а CEP покупателя сокращается. Выключите журнал, когда закончите.

Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы очистить его.

Remove data on uninstall: если включено, при удалении модуля удаляются все настройки Jadlog и его перевозчики. Если выключено, при удалении перевозчики только отключаются. Кэшированные цены всегда удаляются. Заказы никогда не изменяются.

Как это работает при оформлении заказа

На этапе доставки PrestaShop запрашивает у модуля цену каждого перевозчика Jadlog. Учитываются только физические товары: виртуальные товары не добавляют вес и не входят в сумму заказа. Модуль сначала проверяет условия: вес корзины и минимальную сумму заказа, а при включённой опции Ignore shipping zones — разрешённые страны. Если промежуточная сумма корзины достигает Free shipping from, доставка бесплатна и запрос цены в Jadlog не отправляется.

Для адреса доставки в Бразилии с полным 8-значным CEP модуль передаёт Jadlog CEP отправки и назначения, вес, ваш CNPJ, расчётный счёт, договор, услугу, тип страховки и объявленную стоимость заказа. Возвращённая цена пересчитывается в валюту магазина по умолчанию и отображается в валюте корзины покупателя. Корзины без веса рассчитываются как 0,1 кг. Если актуальной цены нет (нет токена, адрес за пределами Бразилии, неполный CEP, нет курса BRL, ошибка Jadlog), модуль использует таблицу Price per country, а затем Fallback cost. Если ни один из вариантов не даёт цену, перевозчик скрывается для этой корзины.

Каждая цена кэшируется на 1 час, поэтому одна и та же корзина не вызывает новый запрос. Неудачный запрос кэшируется на 10 минут. Если Jadlog не отвечает, возвращает ошибку сервера или отклоняет токен, API не вызывается повторно в течение 10 минут. Тайм-аут API составляет 10 секунд. Покупатель никогда не видит ошибку API. Причина записывается в журнал.

Если вы редактируете перевозчика в Shipping > Carriers после того, как по нему есть заказы, PrestaShop сохраняет его как новую версию перевозчика. Модуль автоматически переходит на новую версию.

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

Пункты Pickup

Перевозчик Jadlog Pickup предлагается только для адресов в Бразилии и только когда сохранён токен API. Когда покупатель ввёл полный 8-значный CEP, модуль запрашивает у Jadlog ближайшие активные пункты Pickup и выводит под перевозчиком до Points to show пунктов, каждый с ценой, например «название пункта — цена (3 business days) — адрес». Если список ещё не закэширован, он загружается, когда покупатель выбирает перевозчика, чтобы этап доставки не ждал ответа Jadlog.

Цена до каждого пункта запрашивается у Jadlog. Если Jadlog не даёт цену для пункта, используется фиксированная цена, а пункт без какой-либо цены пропускается. Списки пунктов кэшируются на 12 часов. Цена перевозчика — это цена выбранного пункта. До выбора пункта это цена ближайшего пункта, у которого есть цена. Пункт без цены не скрывает перевозчика, пока у других пунктов есть цена. После того как покупатель выбрал пункт, этап доставки обновляется с новой ценой.

Пункт обязателен. Без пункта покупатель не может продолжить и видит Please select a Jadlog Pickup point. Модуль проверяет, что пункт есть в списке Jadlog для CEP доставки. Если его там нет, покупатель видит The selected Jadlog Pickup point is not in the Jadlog list for this CEP. Please choose the point again. Когда CEP неполный, рядом нет пунктов или Jadlog недоступен, под перевозчиком выводится сообщение.

Без токена API, без 8-значного CEP, когда Jadlog недоступен или когда рядом нет активных пунктов, перевозчик Jadlog Pickup скрывается. Заказ без пункта нельзя было бы отправить.

Заказы

Когда заказ оформляется с перевозчиком Jadlog, модуль сохраняет услугу Jadlog и, если Jadlog её вернул, срок доставки в рабочих днях. Для заказа Jadlog Pickup он также сохраняет название, адрес и ID пункта Pickup.

Страница заказа в панели администратора показывает блок Jadlog с Jadlog service, Delivery time и для Jadlog Pickup — Pickup point, Pickup point address и Pickup point ID. Покупатель видит выбранный пункт на странице подтверждения заказа и в деталях заказа. Пункт добавляется к названию перевозчика в письме с подтверждением заказа. Письмо магазина о новом заказе (если вы используете модуль оповещений по e-mail) также содержит ID пункта.

Оформите отправление в системе Jadlog самостоятельно. В заказе указаны услуга и ID пункта Pickup, которые вам для этого нужны.

Лицензионный ключ

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Jadlog — первый блок на странице Modules > Module Manager > VibeFox Jadlog > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-shipping-jadlog и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока соответствуют языку админ-панели (включены английский и русский).

Если ключ не принят, блок сообщает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После изменения адреса магазина или после освобождения слота домена в вашем аккаунте нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

Один ключ работает на одном домене: домене основного магазина, в том числе при мультимагазинной настройке. Удаление ключа из магазина не освобождает слот домена. Освободите слот в своём аккаунте vibefox.net.

Без действующего ключа перевозчики Jadlog не показываются покупателям при оформлении заказа и стоимость не рассчитывается. Витрина PrestaShop не знает, что вы вошли в админ-панель, поэтому перевозчики скрыты и для вас: модуль можно настроить до покупки ключа, но нельзя протестировать при оформлении заказа. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются.

Когда срок лицензии истекает, модуль продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется снова, пока вы работаете в админ-панели: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Cron-задача не нужна. Удаление или сброс модуля всегда удаляет лицензионный ключ и статус лицензии.

Устранение неполадок

Jadlog не появляется при оформлении заказа: проверьте, что лицензия активна и включён Enable/Disable (или Enable Jadlog Pickup). В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и группу покупателя, или включите Ignore shipping zones. Проверьте предупреждения вверху страницы модуля, ограничения по весу и Minimum order amount. Если покупатель ещё не ввёл полный 8-значный CEP, можно использовать только фиксированные цены, поэтому добавьте строку в Price per country или Fallback cost. Также товары можно ограничить определёнными перевозчиками на странице товара.

Показываются только фиксированные цены: включите Debug log, обновите оформление заказа и посмотрите поле Log на странице модуля. Там указана причина: нет CNPJ или расчётного счёта, нет CEP отправки, неполный CEP назначения, нет курса BRL или текст ошибки Jadlog.

HTTP 401 или 403 в журнале: Jadlog отклонил токен API. Проверьте его у своего франчайзи Jadlog. После этой ошибки API приостанавливается на 10 минут. Сохранение настроек снимает приостановку, так что можно повторить попытку сразу.

Пункты Pickup не появляются: для перевозчика Jadlog Pickup нужны Enable Jadlog Pickup, токен API и полный 8-значный CEP в Бразилии. Если у Jadlog нет активных пунктов рядом с CEP, перевозчик скрывается. Причину смотрите в журнале.

Цены в реалах, а не в моей валюте: введите BRL exchange rate (сколько стоит 1 BRL в валюте магазина по умолчанию).

Цены кажутся слишком низкими или слишком высокими: заполните веса и размеры товаров. Корзины без веса рассчитываются как 0,1 кг, а объёмному весу нужны размеры.

К ценам Jadlog добавляется налог: установите Tax status в None.

Цены выглядят устаревшими после изменения: нажмите Save на странице модуля. Это очистит кэш цен Jadlog и списков пунктов Pickup.

Страница сообщает, что перевозчик Jadlog не найден: перевозчик был удалён в Shipping > Carriers. Сбросьте модуль в Modules > Module Manager, чтобы создать его заново.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Jadlog и выберите Uninstall. Лицензионный ключ и статус лицензии всегда удаляются. Кэшированные цены и списки пунктов Pickup удаляются всегда. Если Remove data on uninstall включено, оба перевозчика удаляются (заказы сохраняют свою историю), а настройки и журнал удаляются. Если выключено, перевозчики только отключаются, и все настройки сохраняются. При повторной установке модуля перевозчики получают обратно прежний статус. Услуга Jadlog, срок доставки и пункт Pickup, сохранённые с заказами, всегда сохраняются.

Jadlog — торговая марка её владельца. Этот модуль не связан с Jadlog и не одобрен компанией.