VibeFox Jadlog for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

PHP: 8.0 или новее.

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

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

Установка

Скачанный файл — это один zip-архив с пакетами для обеих версий OpenCart. Распакуйте его на своем компьютере. В нем находятся README.txt, пакет для OpenCart 3 vfd_jadlog-oc3-(version).ocmod.zip и пакет для OpenCart 4 vfd_jadlog.ocmod.zip. Устанавливайте только пакет для вашей версии OpenCart. Лицензионный ключ одинаков для обеих версий.

OpenCart 3

1. В администраторской части перейдите в Extensions > Installer, нажмите Upload и выберите файл vfd_jadlog-oc3-(version).ocmod.zip. Расширение не добавляет модификации OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо установщика можно скопировать содержимое папки upload из этого пакета в корневую папку вашего магазина.

2. Перейдите в Extensions > Extensions и выберите тип расширения Shipping. Найдите VibeFox Jadlog и нажмите Install (зеленая кнопка +).

3. Нажмите Edit (кнопка с карандашом), чтобы открыть страницу настроек.

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

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

6. Включите Enable Jadlog home delivery, Enable Jadlog Pickup или обе опции и нажмите Save.

OpenCart 4

1. В администраторской части перейдите в Extensions > Installer, нажмите Upload и выберите файл vfd_jadlog.ocmod.zip. Не переименовывайте файл: OpenCart 4 берет код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появится в списке установленных расширений на этой же странице. Нажмите рядом с ним Install (зеленая кнопка +).

3. Перейдите в Extensions > Extensions и выберите тип расширения Shipping. Найдите VibeFox Jadlog, нажмите Install (зеленая кнопка +), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ и настройки так же, как в шагах 4–6 для OpenCart 3. Страница настроек и ее поля одинаковы в обеих версиях.

После установки обе опции выключены, пока вы их не включите и не сохраните. Если вы переустановите расширение после удаления, сохраненные настройки Jadlog будут использованы снова.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox Jadlog > Edit. Они применяются к обеим опциям Jadlog. Разделы перечислены слева. Одна кнопка Save сохраняет всю страницу без перезагрузки. При каждом сохранении также очищаются кэш актуальных цен Jadlog и списки пунктов выдачи. Сохранять настройки могут только администраторы с правом изменения этого расширения.

Вверху страницы расширение показывает предупреждения о неполной настройке: нет токена API (используются только фиксированные цены, а пункты выдачи не могут быть показаны), нет токена API и нет фиксированных цен (способ доставки никогда не показывается), нет CNPJ или расчетного счета, нет CEP отправления, нет курса BRL для магазина, который не продает в BRL, и нет весовой единицы «kg» или единицы длины «cm» в магазине (тогда веса и размеры пересчитываются по названию единицы их класса; проверьте System > Localisation > Weight Classes и Length Classes).

При сохранении некорректное название любой из опций (пустое, длиннее 64 символов или содержащее < > ; = # { }), Sort order, которое не является целым числом, или класс налога или геозона, которых не существует, останавливают сохранение с ошибкой. Другие неверные значения сохраняются с замечанием над настройками: недопустимое число или число меньше 0 не сохраняется, минимальный вес больше максимального оставляет оба сохраненных веса, курс BRL, который не является положительным числом, очищается, CEP без 8 цифр или CNPJ без 14 цифр (или 11 для CPF) сохраняется как введено, с предупреждением, а в таблице цен строка с неизвестной страной удаляется, а некорректная цена остается пустой.

Общие

У Jadlog две опции доставки: Jadlog home delivery (этот раздел) и Jadlog Pickup (отдельный раздел). Настройки на этой странице применяются к обеим.

Enable Jadlog home delivery: предлагает доставку Jadlog по адресу покупателя выбранной ниже услугой. По умолчанию: off.

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

Sort order: положение Jadlog среди способов доставки при оформлении заказа. Целое число.

Tax class: класс налога на стоимость доставки или No tax (по умолчанию). Цены Jadlog — окончательные тарифы перевозчика. Выберите No tax, если OpenCart не должен добавлять к ним налог. Относится к обеим опциям.

Актуальные цены Jadlog

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

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

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

CNPJ: CNPJ (14 цифр) или CPF (11 цифр) отправителя, зарегистрированного в договоре Jadlog, например 00.000.000/0000-00.

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

Contract number: номер вашего договора с Jadlog, если он у вас есть (его выдает франшиза).

Origin CEP: почтовый индекс, с которого отправляются посылки, 8 цифр (00000-000). Обязателен для актуальных цен: в OpenCart нет почтового индекса магазина, поэтому без этого поля используются только фиксированные цены.

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 (3 business days)») и рядом с каждым пунктом выдачи. Включено по умолчанию. Срок доставки всегда сохраняется с заказом.

Jadlog Pickup

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

Enable Jadlog Pickup: предлагает доставку в пункт выдачи Jadlog, выбранный при оформлении заказа. По умолчанию: off.

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

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

Фиксированные цены (используются, когда нет токена 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 уже покрывают всю корзину.

Условия

Minimum weight (kg): скрывает способ доставки при весе корзины ниже этого значения. 0 означает отсутствие ограничения (по умолчанию).

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

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

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

Доступность

Geo zone: предлагать Jadlog только для адресов в этой геозоне. All zones (по умолчанию) означает без ограничения. Геозона не проверяется, когда включена опция Ignore shipping zones. Геозоны настраиваются в разделе System > Localisation > Geo Zones.

Ignore shipping zones: когда включено, Geo zone не проверяется, и Jadlog предлагается для стран ниже. Когда выключено (по умолчанию), действует только Geo zone.

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

Дополнительно

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

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

Remove data on uninstall: когда включено, удаление расширения стирает все настройки Jadlog, журнал и выбор пунктов в оформлениях, которые так и не стали заказами. Когда выключено (по умолчанию), настройки сохраняются для повторной установки. Кэшированные цены удаляются всегда. Данные Jadlog в заказах никогда не удаляются.

Импорт / экспорт

Export: нажмите Download JSON, чтобы сохранить настройки в файл JSON. Токен API не экспортируется.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки, например в другом магазине. Значения проверяются так же, как при обычном сохранении. Сохраненный токен API остается.

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

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену каждой опции Jadlog: доставка на дом и Jadlog Pickup показываются как два варианта в рамках одного способа Jadlog. Если включена опция Ignore shipping zones, Jadlog предлагается только для разрешенной страны (геозона не проверяется). В противном случае, если задана Geo zone и адрес находится за ее пределами, Jadlog не предлагается. Учитываются только товары с Requires Shipping, установленным в Yes: другие товары не добавляют вес и не входят в сумму заказа. Сумма заказа — это цена товаров, требующих доставки, после скидки по купону и до налога. Расширение проверяет вес корзины и минимальную сумму заказа. Если промежуточный итог достигает Free shipping from, доставка бесплатна и запрос цены в Jadlog не отправляется.

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

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

В OpenCart 4 покупатель нажимает Choose в блоке способа доставки на странице оформления заказа и выбирает вариант Jadlog в окне Shipping method options. Цены такие же, как в OpenCart 3.

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

Пункты выдачи

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

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

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

Без токена API, когда Jadlog недоступен или когда рядом нет действующих пунктов, опция Jadlog Pickup скрывается. Заказ без пункта нельзя было бы отправить.

В OpenCart 4 список пунктов выдачи появляется в окне Shipping method options под опцией Jadlog Pickup. Он загружается в фоновом режиме: сначала из кэша, затем с ценами остальных пунктов из Jadlog. После того как покупатель выберет пункт, цена рядом с Jadlog Pickup в окне обновляется. Кнопка Continue в окне не продолжает оформление без действительного пункта, с теми же сообщениями.

Заказы

Когда заказ оформлен с опцией Jadlog, расширение сохраняет услугу Jadlog и, если Jadlog ее вернул, срок доставки в рабочих днях. Для заказа Jadlog Pickup также сохраняются название, адрес и ID пункта выдачи. В OpenCart 4 для одного оформления хранится один заказ, который обновляется каждый раз, когда покупатель подтверждает его снова, и данные Jadlog в этом заказе обновляются вместе с ним. Если покупатель переключает этот заказ на другой способ доставки, его данные Jadlog удаляются.

Пункт добавляется к способу доставки заказа после названия опции, например Jadlog Pickup:, затем название и адрес пункта. Этот текст появляется на страницах заказа в администраторской части и в кабинете покупателя, в письмах о заказе и в счете.

Страница заказа в администраторской части (Sales > Orders) показывает панель Jadlog с Jadlog service, Delivery time и, для Jadlog Pickup, Pickup point, Pickup point address и Pickup point ID. В OpenCart 4 панель показывается над блоком History.

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

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

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

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

Один ключ работает на одном домене: адрес магазина из конфигурации OpenCart. Удаление ключа из магазина не освобождает слот домена. Освободите слот в своем аккаунте на vibefox.net.

Без активного ключа способы доставки Jadlog не показываются покупателям при оформлении заказа, и стоимость доставки не рассчитывается. Администратор, вошедший в администраторскую часть в том же браузере, по-прежнему видит их в магазине с пометкой (unlicensed — visible to admins only), поэтому вы можете настроить и проверить расширение до покупки ключа. В OpenCart 4 такого предпросмотра нет: магазин не видит вход администратора, поэтому без активного ключа способы Jadlog скрыты для всех. После того как вы один раз откроете страницу Edit, на Dashboard администратора появится напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются.

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

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

Jadlog не появляется при оформлении заказа: проверьте, что лицензия активна и включено Enable Jadlog home delivery (или Enable Jadlog Pickup). Проверьте Geo zone или включите Ignore shipping zones и проверьте Countries. Проверьте предупреждения вверху страницы расширения, ограничения по весу, Minimum order amount и что у товаров Requires Shipping установлено в Yes. Если покупатель еще не ввел полный 8-значный CEP, можно использовать только фиксированные цены, поэтому добавьте строку Price per country или Fallback cost.

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

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

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

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

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

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

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

Страница пишет «Warning: You do not have permission to modify VibeFox Jadlog!»: ваша группа администраторов может только просматривать настройки. Предоставьте группе право изменения для extension/shipping/vfd_jadlog (OpenCart 3) или extension/vfd_jadlog/shipping/vfd_jadlog (OpenCart 4) в разделе System > Users > User Groups.

Удаление

Перейдите в Extensions > Extensions, выберите тип Shipping и нажмите Uninstall (красная кнопка −) рядом с VibeFox Jadlog. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда сбрасывает статус расширения, Sort order, Tax class и Geo zone. Кэшированные цены и списки пунктов выдачи удаляются всегда. Если Remove data on uninstall включено, также удаляются настройки Jadlog и журнал. Если опция выключена, остальные настройки сохраняются и будут использованы снова при повторной установке расширения. Услуга Jadlog, срок доставки и пункт выдачи, сохраненные с заказами, всегда сохраняются, а существующие заказы сохраняют свой способ доставки и стоимость.

В OpenCart 4, чтобы удалить также файлы расширения, после удаления перейдите в Extensions > Installer, нажмите Uninstall (оранжевая кнопка −) рядом с VibeFox Jadlog в списке установленных расширений, затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

Jadlog является товарным знаком его владельца. Это расширение не связано с Jadlog и не одобрено им.