VibeFox PostNL for OpenCart — Помощь

Требования

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

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

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

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

Установка

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

OpenCart 3

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

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

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

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

5. Включите PostNL pickup point и/или PostNL home address и укажите цены. Для пунктов выдачи также введите API key PostNL и Ship from (postcode) (см. «Настройка»). Нажмите Save.

OpenCart 4

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

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

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

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

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

Настройка

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

Если значение неверно, ничего не сохраняется, и страница показывает причину: пустое название варианта, название длиннее 64 символов или содержащее < > ; = # { }, порядок сортировки, который не является целым числом, минимальный вес больше максимального, либо неверный налоговый класс или геозона. Мелкие проблемы сохраняются с примечанием: неверное или отрицательное число оставляет поле пустым, неверный почтовый индекс отправителя сохраняется пустым, а неверная цена в таблице игнорируется.

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

Общие

Каждый тип доставки — отдельный вариант на оформлении заказа. Настройки этой страницы относятся к обоим.

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

Pickup point option name: название, которое видят покупатели при оформлении заказа. По умолчанию: PostNL pickup point. Обязательно, до 64 символов, без < > ; = # { }.

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

Home delivery option name: название, которое видят покупатели при оформлении заказа. По умолчанию: PostNL. Те же правила, что и для названия пункта выдачи.

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

Tax class: налоговый класс обоих вариантов. При налоговом классе OpenCart добавляет свой налог к ценам. No tax означает, что цены окончательные.

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: Нидерланды или Бельгия. PostNL использует адрес отправителя для даты забора. При установке значение выбирается по стране магазина, если это Нидерланды или Бельгия, иначе выбираются Нидерланды.

Ship from (postcode): почтовый индекс отправителя, например 1234AB в Нидерландах или 1000 в Бельгии. Обязателен для пунктов выдачи: в OpenCart нет почтового индекса магазина, поэтому он не берётся из адреса магазина. Неверный индекс сохраняется пустым с предупреждением.

При изменении API-ключа, настройки песочницы или адреса отправителя очищаются кешированные списки пунктов выдачи и последняя ошибка API.

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

Цены применяются к обоим вариантам. PostNL не предоставляет публичного API тарифов, поэтому расширение не запрашивает актуальные тарифы. Для покупателя, который платит в другой валюте, OpenCart пересчитывает цену по курсу вашего магазина.

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». Строки без цен удаляются при сохранении. Если страна встречается дважды, сохраняется первая строка. Неверные цены игнорируются с предупреждением.

Calculation: Per order берёт цену один раз. Per item (price x quantity) умножает её на количество товаров, требующих доставки.

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

Условия

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

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

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

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

Все суммы и веса принимают десятичную запятую.

Доступность

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

Ignore shipping zones: если включено, геозона не проверяется, и PostNL предлагается для стран, выбранных ниже (для всех стран, если список пуст). Если выключено, учитывается только геозона.

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

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

Debug log: записывает отладочные сообщения в storage/logs/vfd_ptnl_debug.log.php (в OpenCart 4 system/storage/logs/vfd_ptnl_debug.log.php). Файл нельзя прочитать из веба. Ошибки API и заказы без действительного пункта выдачи записываются всегда. Ни API-ключ, ни данные покупателей не записываются. Выключайте журнал, когда закончите. Когда файл достигает 5 МБ, начинается новый журнал.

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

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

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

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

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

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

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену каждого варианта PostNL. Если включено Ignore shipping zones, PostNL предлагается только для разрешённой страны, независимо от геозоны. Иначе, если задана Geo zone, адрес должен входить в неё. Учитываются только товары с Requires Shipping, равным Yes: остальные товары не добавляют веса и не входят в промежуточный итог. Расширение проверяет вес корзины и минимальный промежуточный итог. Затем оно берёт цену из таблицы для страны и весового класса или цену для других стран. Если цены нет, вариант скрывается. Если промежуточный итог корзины достигает Free shipping from, цена равна 0. Цена показывается покупателю в его валюте с налогом по выбранному Tax class.

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

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

Расширение не запрашивает актуальные тарифы PostNL и не создаёт транспортные этикетки, штрихкоды, отслеживание, возвраты или предварительные уведомления. Оно не предлагает варианты доставки в определённый день, вечером или утром. Создайте отправление в Mijn PostNL или другом инструменте PostNL, используя сохранённый пункт выдачи.

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

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

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

Пункт обязателен. Когда покупатель нажимает Continue на шаге способа доставки, сервер проверяет пункт по списку PostNL для адреса доставки. Без пункта покупатель видит «Please choose a PostNL pickup point.» Если пункта нет в списке, покупатель видит «The chosen PostNL pickup point is not available for this address. Please choose it again.» Если PostNL недоступен, покупатель видит «PostNL pickup points cannot be loaded right now. Please try again in a few minutes or choose another shipping method.» Пункт, выбранный для другого адреса, никогда не используется для заказа. Название и адрес, сохраняемые с заказом, берутся из PostNL, а не из браузера.

Страницы заказа, письма и счёт: пункт добавляется к способу доставки заказа, например «PostNL pickup point: название, адрес» (название варианта пункта выдачи, затем сам пункт) (до 128 символов, на OpenCart 4 до 255). Он показывается везде, где OpenCart показывает способ доставки: в истории заказов покупателя, в письмах о заказе, в счёте и в разделе Sales > Orders.

Страница заказа в администрировании: в Sales > Orders страница заказа показывает над историей панель PostNL pickup point с пунктом, Location code и Partner ID. Она показывается только для заказов с сохранённым пунктом, в том числе после отключения расширения.

На OpenCart 4 список пунктов появляется в окне Shipping method options, под вариантом PostNL pickup point, и загружается заново каждый раз, когда окно открывается, потому что адрес может меняться на одностраничном оформлении заказа. Кнопка Continue в окне не пропускает дальше без действительного пункта, с теми же сообщениями. OpenCart 4 ведёт один заказ на оформление и обновляет его каждый раз, когда покупатель подтверждает заказ снова; пункт выдачи заказа обновляется вместе с ним.

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

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

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

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

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

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

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

PostNL не появляется при оформлении заказа: проверьте, что лицензия активна и что включён PostNL pickup point или PostNL home address. Проверьте Geo zone (или что включено Ignore shipping zones и страна разрешена), что для страны задана цена, ограничения по весу и Minimum subtotal. Проверьте, что у товаров Requires Shipping равно Yes.

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

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

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

Веса товаров выглядят неверно: если страница расширения предупреждает, что в магазине нет весового класса «kg», проверьте System > Localisation > Weight Classes. Веса товаров переводятся по названию единицы их класса, а неизвестные единицы читаются как килограммы.

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

Для разработчиков: адрес API PostNL можно заменить настройкой vfd_ptnl_api_url (для тестов); у неё нет поля на странице настроек.

Удаление

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

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

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