VibeFox PostNord for OpenCart — Помощь

Требования

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

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

API-ключ PostNord (для выбора пункта обслуживания): создайте бесплатную учётную запись на developer.postnord.com, добавьте приложение и скопируйте его API-ключ. Без ключа способ доставки продолжит работать, но покупатели не смогут выбрать пункт обслуживания.

Договор с PostNord: для отправки посылок нужен ваш обычный клиентский договор с PostNord, например MyPack Collect или MyPack Home.

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

Установка

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

OpenCart 3

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

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

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

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

5. Включите Enable/Disable (доставка в пункт обслуживания) и/или Home delivery, вставьте API key PostNord, выберите Agreement country, заполните Country prices или Fallback cost (см. раздел Настройка) и нажмите Save.

OpenCart 4

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

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

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

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

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

Настройка

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

Если значение неверно, ничего не сохраняется, и страница показывает причину: пустое название, название длиннее 64 символов или содержащее < > ; = # { }, порядок сортировки, который не является целым числом, неверный статус налога или геозона, либо Min weight (kg), большее Max weight (kg). Числовое поле со значением, которое не является числом от 0 и выше, сохраняется пустым, с сообщением. Ячейка таблицы цен, которая не является числом от 0 и выше, сохраняется как 0, с сообщением.

Над настройками страница предупреждает, если ещё не задан API-ключ, не задана ни одна цена и в магазине нет весового класса «kg».

Общее

Оба варианта доставки предлагаются в геозоне, заданной в Availability, или для стран из Ignore shipping zones.

Enable/Disable: включает или выключает доставку PostNord в пункт обслуживания или постамат. Покупатель выбирает пункт при оформлении заказа. По умолчанию: выключено.

Name: название варианта «пункт обслуживания» при оформлении заказа, например «PostNord MyPack Collect». По умолчанию: PostNord. Обязательно, до 64 символов, без < > ; = # { }.

Home delivery: предлагать также домашнюю доставку PostNord, второй вариант без пункта обслуживания. По умолчанию: выключено.

Home delivery name: название варианта домашней доставки при оформлении заказа, например «PostNord MyPack Home». По умолчанию: PostNord Home delivery. Те же правила, что и для Name.

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

Tax status: None (the prices are final) (по умолчанию) или налоговый класс: тогда OpenCart добавляет налог на доставку этого класса к ценам. Относится к обоим вариантам.

API PostNord (выбор пункта обслуживания)

API key: API-ключ вашего приложения на developer.postnord.com. Он отправляется в PostNord только с вашего сервера, никогда в браузер, и никогда не записывается в журнал. После сохранения поле остаётся пустым и показывает Saved - leave empty to keep it. Вводите новое значение, только если хотите его изменить.

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

Test mode: использует тестовую среду PostNord (atapi2.postnord.com). Только для ключей, выданных для тестовой среды.

Agreement country: страна вашего клиентского договора с PostNord: Швеция, Дания, Норвегия или Финляндия. Она определяет, какие пункты обслуживания предлагаются. Same as the delivery country (по умолчанию) использует страну покупателя.

Цены

В заголовке раздела показана валюта магазина по умолчанию. Цены указаны в этой валюте, без налога, и одинаковы для обоих вариантов. У PostNord нет публичного API цен, поэтому вы задаёте свои цены, обычно это цены по вашему договору с PostNord. Порядок такой: порог бесплатной доставки, затем таблица по странам, затем резервная стоимость.

Calculation type: Per order (по умолчанию) взимает цену один раз. Per item (price x number of items) умножает её на количество товаров в корзине.

Country prices: цена по стране назначения и весу корзины. Нажмите Add country, чтобы добавить строку, и кнопку ×, чтобы её удалить. В каждой строке есть столбец Price и столбцы веса: XS до 1 кг, S до 2 кг, M до 3 кг, L до 5 кг и XL свыше 5 кг. Столбец веса со значением 0 использует столбец Price, а Price со значением 0 означает бесплатную доставку. Страна * All other countries охватывает все страны без собственной строки. Десятичные числа с запятой или точкой (9,99 или 9.99). Новая строка создаётся как * All other countries со всеми ценами 0. Выберите страну и введите цены до сохранения или удалите строку. Пустая ячейка сохраняется как 0.

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

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

Доступность

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену каждого варианта PostNord. Учитываются только товары, у которых Requires Shipping установлено в Yes: остальные товары не добавляют вес и не входят в промежуточную сумму. Расширение проверяет геозону или список стран, вес корзины и минимальную сумму. Если действует бесплатная доставка, цена равна 0. Иначе цена берётся из таблицы по странам, а затем из резервной стоимости. Если цены нет, вариант скрывается. Цена рассчитывается в валюте магазина по умолчанию и показывается покупателю в его валюте с налогом, выбранным в Tax status. Расчёт цены никогда не обращается к PostNord.

Для варианта пункта обслуживания и адреса доставки в Швеции, Дании, Норвегии или Финляндии ваш сервер запрашивает у PostNord Business Location API 10 пунктов обслуживания, ближайших к почтовому индексу доставки. Он передаёт страну и почтовый индекс доставки, а также страну договора. Таймаут API составляет 10 секунд. Списки кэшируются на 6 часов для каждого почтового индекса, а ответы «нет пунктов» — на 1 час. Ошибки API кэшируются на 5 минут, чтобы сбой PostNord не замедлял каждое обновление оформления заказа. Кэш хранится в собственной таблице базы данных расширения. Шаг доставки никогда не ждёт PostNord: если список ещё не в кэше, он загружается после того, как покупатель выбирает вариант.

Для других направлений варианты по-прежнему могут предлагаться с вашими ценами, но без выбора пункта. Вариант домашней доставки никогда не показывает выбор пункта.

Расширение не запрашивает актуальные цены PostNord и не создаёт этикетки для отправлений, не бронирует отправки (EDI), не выдаёт номера для отслеживания и не отправляет письма с отслеживанием. Режима карты нет. Для отправлений используйте PostNord Portal, Skicka Direkt Business или инструмент для печати этикеток; этим инструментам нужен сохранённый ID пункта обслуживания.

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

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

Когда адрес доставки находится в Швеции, Дании, Норвегии или Финляндии, под вариантом пункта обслуживания появляется список PostNord service point с ближайшими пунктами, сгруппированными по городам, каждый с адресом и расстоянием. До ввода почтового индекса покупатель видит «Введите почтовый индекс, чтобы выбрать пункт обслуживания PostNord.» Выбор сразу сохраняется для оформления заказа.

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

Выбор пункта никогда не блокирует продажу. Если список не удаётся загрузить (API-ключ ещё не задан, API PostNord недоступен, рядом с почтовым индексом нет пунктов), покупатель видит примечание и всё равно может оформить заказ. Тогда PostNord доставит посылку в ближайший к адресу пункт обслуживания.

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

Страница заказа в админке: в разделе Sales > Orders страница заказа показывает над историей панель PostNord service point с названием, адресом и Service point ID. Если пункт не выбран, там написано «не выбран — PostNord доставит в ближайший к адресу доставки пункт обслуживания».

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

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox PostNord — первый блок на странице Extensions > Extensions > Shipping > VibeFox PostNord > Edit, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой лицензия действует, и ваш домен), а также кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: opencart-shipping-postnord и ссылка 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.

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

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

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

PostNord не появляется при оформлении заказа: проверьте, что лицензия активна и включено Enable/Disable (или Home delivery). Проверьте Geo zone или список Countries, если включено Ignore shipping zones. Проверьте, что для страны задана цена (строка страны, строка * или Fallback cost), ограничения веса и Minimum subtotal. Проверьте, что у товаров Requires Shipping установлено в Yes.

Выбор сообщает, что пункты обслуживания не загружаются: проверьте API key и настройку Test mode. Производственный ключ не работает в тестовой среде, и наоборот. Включите Debug log, обновите страницу оформления заказа и посмотрите поле Log на странице расширения. Заказ всё равно можно оформить: PostNord доставит его в ближайший пункт обслуживания.

Неожиданные пункты обслуживания: проверьте Agreement country. Она определяет, какие пункты обслуживания предлагаются.

Доставка бесплатна по ошибке: проверьте Country prices на строки с Price 0, особенно строку * , добавленную через Add country и не заполненную, а также проверьте Free shipping from.

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

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

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

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

Удаление

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

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

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