VibeFox PostNL for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x, тема Classic или Hummingbird (или тема на их основе).

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

Ключ API PostNL (только для пунктов выдачи): пункты выдачи загружаются из PostNL Checkout API. Бизнес-клиенты PostNL находят ключ API в Mijn PostNL в разделе My account > API beheren. Для песочницы PostNL нужен отдельный ключ песочницы. Перевозчику доставки на домашний адрес ключ не нужен.

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

Установка

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

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

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

4. Заполните тарифы. Для пунктов выдачи также введите API key PostNL и Ship from (postcode) (см. Настройки). Нажмите Save.

При установке модуль создаёт двух перевозчиков: PostNL pickup point с текстом срока доставки Delivery to a PostNL pickup point и PostNL с PostNL delivery to the home address. Оба связаны с зонами Нидерландов и Бельгии и со всеми группами клиентов. Добавлять зоны и менять группы клиентов, срок доставки, логотип и ограничения по размеру можно в Shipping > Carriers. Цены там не задавайте: цена всегда берётся из модуля.

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox PostNL > Configure. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. В WooCommerce один способ добавляется в зону дважды, по одному на каждый тип доставки. В PrestaShop каждый тип доставки — отдельный перевозчик со своим названием, статусом и зонами.

Над настройками страница показывает предупреждения: не указан ключ API или индекс отправки для пунктов выдачи, включена песочница, не задан ни один тариф, последний неудачный запрос к PostNL с датой и ошибкой, единица веса магазина, которую модуль не знает, и удалённый перевозчик.

Общие

PostNL pickup point: включает или выключает перевозчика пункта выдачи. Покупатель должен выбрать пункт PostNL при оформлении заказа. Предлагается только для адресов в Нидерландах и Бельгии и только при наличии ключа API. Это тот же переключатель, что и статус перевозчика в Shipping > Carriers.

Pickup point carrier name: название, которое видят покупатели при оформлении заказа. По умолчанию: PostNL pickup point. Обязательно.

PostNL home address: включает или выключает перевозчика доставки на домашний адрес. Пункт не выбирается. Работает для каждой страны с тарифом. Тот же переключатель, что и статус перевозчика.

Home delivery carrier name: название, которое видят покупатели при оформлении заказа. По умолчанию: PostNL. Обязательно.

Tax status: налоговое правило обоих перевозчиков. Правило Taxable добавляет к тарифам налог на доставку по этому правилу. None означает, что тарифы окончательные.

API PostNL (пункты выдачи) (для доставки на домашний адрес не нужно)

API key: ваш ключ API PostNL из Mijn PostNL (My account > API beheren). Он передаётся в PostNL в заголовке "apikey" и никогда не показывается покупателям и не записывается в журнал. После сохранения поле остаётся пустым и показывает Saved - leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Remove the saved API key: отметьте флажок и нажмите Save, чтобы удалить сохранённый ключ. Перевозчик пункта выдачи после этого перестанет предлагаться.

Sandbox: использует песочницу PostNL (api-sandbox.postnl.nl) с ключом API песочницы. Покупатели видят тестовые пункты выдачи. На боевом магазине держите выключенным.

Ship from (country): страна, в которой вы передаёте посылки PostNL: Netherlands или Belgium. По умолчанию: Netherlands. PostNL использует адрес отправителя для даты забора.

Ship from (postcode): почтовый индекс отправителя, например 1234AB в Нидерландах или 1000 в Бельгии. Оставьте пустым, чтобы использовать почтовый индекс магазина из Shop Parameters > Contact > Stores, если магазин находится в той же стране. Неверный индекс сохраняется пустым с предупреждением. При изменении ключа API, настройки песочницы или адреса отправки очищаются кешированные списки пунктов выдачи и последняя ошибка API.

Цены (в валюте магазина по умолчанию, без налога)

Тарифы действуют для обоих перевозчиков. У PostNL нет публичного API тарифов, поэтому модуль не запрашивает тарифы в реальном времени. Если покупатель платит в другой валюте, PrestaShop пересчитывает тариф по курсу вашего магазина.

Price per country: одна строка на страну назначения. Нажмите + Add country, чтобы добавить строку, и значок корзины, чтобы удалить её. Выберите * All other countries для строки, которая покрывает все страны без собственной строки. В каждой строке есть Price и необязательные весовые классы по весу корзины: XS до 1 кг, S до 2 кг, M до 3 кг, L до 5 кг и XL свыше 5 кг. Тариф весового класса заменяет Price; оставьте его пустым, чтобы использовать Price. Price, равный 0, означает бесплатную доставку. Принимаются "6.95", "6,95", а также суммы с разделителем тысяч, например "1.234,50" или "1,234.50". Пустые строки и неверные коды стран удаляются при сохранении. Если страна встречается дважды, сохраняется первая строка. Неверные тарифы игнорируются с предупреждением.

Calculation: Per order берёт тариф один раз. Per item (price x quantity) умножает его на количество товаров, которые нужно доставить.

Price for other countries: используется, когда в таблице нет ни страны, ни строки *. Оставьте пустым, чтобы скрыть перевозчиков в этих странах.

Условия

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

Minimum subtotal: показывать перевозчиков, только если сумма корзины не меньше этой. Оставьте пустым, чтобы показывать их всегда.

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

Maximum weight (kg): скрывать перевозчиков для более тяжёлых корзин. По умолчанию: 30 (посылки PostNL в Benelux весят до 30 кг). 0 означает без ограничения. Если поле пустое, в зонах перевозчиков действуют 30 кг, а без ограничения — только для стран, доступных через Ignore zones. Минимальный вес больше максимального отклоняется с ошибкой, потому что перевозчики никогда бы не отображались.

Все суммы и веса принимают десятичную запятую, в том числе с разделителем тысяч. Неверное или отрицательное число игнорируется с предупреждением, и поле сохраняется пустым.

Доступность без зон доставки

Обычно перевозчики предлагаются в зонах доставки, с которыми они связаны в Shipping > Carriers.

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

Countries: страны назначения для этого режима. Оставьте пустым, чтобы разрешить все страны. Это поле используется только при включённой опции Ignore zones. В этих странах можно предлагать обоих перевозчиков; перевозчик пункта выдачи — только для Нидерландов и Бельгии.

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

Debug log: записывает отладочные сообщения в logs/vfd_ptnl_debug.log.php в папке модуля. Файл нельзя открыть через веб. Ошибки API всегда записываются в журнал. Ключ API и данные покупателей не записываются. Выключите журнал, когда закончите.

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

Remove data on uninstall: если включено, при удалении модуля удаляются настройки и перевозчики PostNL. Если выключено, при удалении перевозчики только отключаются. Пункты выдачи, сохранённые в заказах, всегда сохраняются.

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

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

Перевозчик пункта выдачи предлагается только для адресов в Нидерландах и Бельгии и только при наличии ключа API. Если в адресе доставки есть корректный почтовый индекс, модуль запрашивает у PostNL Checkout API три ближайших пункта выдачи. Он отправляет почтовый индекс, улицу, номер дома, город и страну покупателя, а также ваш адрес отправки. Для перевозчика доставки на домашний адрес ничего не отправляется. Если PostNL недоступен или для адреса нет пунктов, перевозчик пункта выдачи скрывается, а доставка на домашний адрес остаётся доступной. Тайм-аут API — 12 секунд.

Списки пунктов кешируются на 6 часов для каждого почтового индекса, ответы «нет пунктов» — на 1 час. Неудачные запросы кешируются на 10 минут, поэтому сбой не замедляет каждое обновление оформления заказа. Последняя ошибка показывается на странице модуля.

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

Модуль не запрашивает тарифы PostNL в реальном времени и не создаёт этикетки, штрихкоды, track and trace, возвраты или предварительные уведомления. У него нет опций доставки в определённый день, вечером или утром. Создайте отправление в Mijn PostNL или другом инструменте PostNL, используя сохранённый пункт выдачи.

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

Когда покупатель выбирает перевозчика пункта выдачи, под ним появляется список PostNL pickup point с тремя ближайшими пунктами: название компании, адрес и расстояние. Страница никогда не ждёт PostNL: если список ещё не в кеше, он загружается сразу после выбора перевозчика. До ввода полного почтового индекса покупатель видит «Введите почтовый индекс (например, 1234 AB), чтобы увидеть пункты выдачи PostNL.» (4 цифры для Бельгии). Выбранный пункт сохраняется в корзине и остаётся при обновлении оформления заказа.

Пункт обязателен. Без него покупатель не может продолжить и видит «Пожалуйста, выберите пункт выдачи PostNL.» Когда покупатель нажимает Continue, сервер сверяет пункт со списком PostNL для адреса доставки. Если его нет в списке, покупатель видит «Выбранный пункт выдачи PostNL недоступен для этого адреса. Пожалуйста, выберите его снова.» Если PostNL недоступен, покупатель видит «Пункты выдачи PostNL сейчас не могут быть загружены. Пожалуйста, повторите попытку через несколько минут или выберите другой способ доставки.» Пункт, выбранный для другого адреса, никогда не используется для заказа. Название и адрес, сохраняемые с заказом, берутся из PostNL, а не из браузера.

Страница заказа в админке: блок PostNL pickup point с названием и адресом, Location code и Partner ID.

Страницы подтверждения заказа и сведений о заказе: PostNL pickup point с названием и адресом.

Письма о заказе: название и адрес пункта добавляются к названию перевозчика в письме с подтверждением заказа. Письмо о новом заказе магазина (модуль Mail alerts) также показывает код местоположения.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox PostNL находится первым на странице Modules > Module Manager > VibeFox PostNL > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой лицензия действует, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-shipping-postnl и ссылка 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.

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

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

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

PostNL не появляется при оформлении заказа: проверьте, что лицензия действует и переключатель перевозчика включён. В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и группу покупателя (или что включена опция Ignore zones и страна разрешена). Проверьте, что для страны задан тариф, весовые ограничения и Minimum subtotal. Товары также могут быть ограничены определёнными перевозчиками на странице товара.

Перевозчик пункта выдачи не появляется: он показывается только для адресов в Нидерландах и Бельгии, только при наличии ключа API, почтового индекса отправки и тарифа, и только когда PostNL возвращает пункты для почтового индекса покупателя. Проверьте предупреждения над страницей модуля и поле Log. Ошибки всегда записываются в журнал; включите Debug log для подробностей.

"PostNL pickup points cannot be loaded right now": не удалось связаться с PostNL, PostNL отклонил ключ API или не указан почтовый индекс отправки. На странице модуля показана последняя ошибка. Ключ песочницы работает только при включённой опции Sandbox, а боевой ключ — только при выключенной.

Покупатели видят тестовые пункты выдачи: выключите Sandbox.

Веса товаров выглядят неверно: если на странице модуля есть предупреждение, что единица веса магазина не распознана, задайте стандартную единицу (kg, g, lb или oz) в International > Localization в разделе Local units. До тех пор веса товаров читаются как килограммы.

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

Удаление

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

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