VibeFox PostNL for WooCommerce — Помощь

Требования

WordPress: 5.8 или новее.

WooCommerce: 7.0 или новее, установлен и активен. Плагин не активируется без него.

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

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

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

Установка

1. В WordPress перейдите в Plugins > Add New > Upload Plugin, выберите ZIP-файл плагина и нажмите Install Now. Также можно загрузить папку vfd_postnl в /wp-content/plugins/ по FTP.

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Shipping > VibeFox PostNL или нажмите Settings под названием плагина на странице Plugins.

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

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

6. Добавьте VibeFox PostNL в зону доставки: WooCommerce > Settings > Shipping > Shipping zones, например Нидерланды и Бельгия. В зоне укажите Title и Delivery to. Добавьте способ второй раз для другого типа доставки.

Настройка

Все настройки, кроме заголовка и типа доставки, находятся на одной странице: WooCommerce > Settings > Shipping > VibeFox PostNL. Они действуют для всех зон доставки. Когда вы добавляете способ в зону, в окне зоны два поля:

Title (zone): название, которое видит покупатель для этого способа в зоне. Оставьте пустым, чтобы использовать глобальное Name.

Delivery to (zone): As in the global settings (по умолчанию), PostNL pickup point (customer chooses a point) или Home address. Добавьте способ в зону дважды, чтобы предлагать оба варианта.

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

Общие

Enable/Disable: включает или выключает доставку PostNL во всех зонах сразу.

Name: название способа доставки, которое видит покупатель на оформлении заказа. Title, заданный в зоне, его заменяет. По умолчанию: PostNL.

Delivery to: тип доставки по умолчанию для способов зон с As in the global settings и для режима Ignore zones.

Tax status: Taxable добавляет налог WooCommerce к стоимости доставки, None не добавляет.

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

API key: ваш ключ API PostNL из Mijn PostNL (My account > API beheren). Он передаётся в PostNL в заголовке «apikey», хранится в базе данных WordPress и никогда не показывается покупателям и не записывается в журнал.

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

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

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

Тарифы (в валюте магазина)

У PostNL нет публичного API тарифов, поэтому плагин не запрашивает тарифы в реальном времени и никогда не конвертирует цены.

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): скрыть способ для более тяжёлых корзин. По умолчанию: 30 (посылки PostNL в Benelux весят до 30 кг). Оставьте пустым для отсутствия ограничения.

Hide for shipping classes: скрыть способ, если в корзине есть товар из любого из этих классов доставки WooCommerce.

Все суммы и веса принимают десятичную запятую, в том числе с разделителем тысяч (1.234,50 или 1,234.50). Неверное число игнорируется с сообщением.

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

Ignore zones: предлагать PostNL также в странах ниже, когда ни одна зона его не добавляет. Зоны, в которых есть этот способ, работают как обычно. Этот режим использует глобальные Name и Delivery to.

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

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

Debug log: пишет отладочные сообщения в WooCommerce > Status > Logs (источник «vfd-postnl»). Ошибки API всегда записываются в журнал. Ключ API и данные покупателей не записываются. Выключите журнал, когда закончите.

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

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

Когда покупатель вводит адрес доставки, WooCommerce запрашивает у плагина тариф. Плагин проверяет условия: вес корзины, минимальную сумму и классы доставки. Затем он берёт цену из таблицы для страны и весового класса или цену для других стран. Если цены нет, способ скрывается. Если сумма корзины достигает Free shipping from, цена равна 0.

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

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

Способ работает в классическом оформлении заказа и в блоках «Корзина» и «Оформление заказа». Он совместим с High-Performance Order Storage (HPOS) в WooCommerce.

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

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

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

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

Экран заказа в админке: PostNL pickup point с названием и адресом и Location code под адресом доставки.

Страница «Заказ получен» и просмотр заказа в «Моя учётная запись»: PostNL pickup point с названием и адресом.

Письма о заказе: название и адрес пункта в HTML- и текстовых письмах.

В базе данных пункт сохраняется в метаданных заказа _vfd_ptnl_servicepoint_id (код местоположения PostNL), _vfd_ptnl_servicepoint_name (название и адрес) и _vfd_ptnl_servicepoint (ID партнёра, компания, улица, номер дома, индекс, город, страна).

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

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится вверху страницы WooCommerce > Settings > Shipping > VibeFox PostNL. Вставьте ключ в поле License key и нажмите Activate. Блок показывает статус, например дату, до которой лицензия активна, и ваш домен. Используйте Check now, чтобы снова проверить статус, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить его с этого сайта. Ссылка Manage licenses and domains in your account открывает ваш аккаунт на vibefox.net.

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

Без активного ключа PostNL не показывается покупателям на оформлении заказа. Администраторы магазина, вошедшие в систему, видят его, отмеченным (unlicensed — visible to admins only), чтобы вы могли настроить и протестировать плагин до покупки ключа. Напоминание появляется на странице Plugins и на страницах WooCommerce. Существующие заказы не затрагиваются.

Когда срок лицензии истекает, плагин продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется в фоновом режиме.

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

PostNL не появляется на оформлении заказа: проверьте, что лицензия активна, что Enable/Disable включено и способ добавлен в зону страны покупателя (или включено Ignore zones и страна разрешена). Проверьте, что для страны задан тариф, ограничения по весу, Minimum subtotal и Hide for shipping classes.

Способ с пунктом выдачи не появляется: он показывается только для адресов в Нидерландах и Бельгии, только при наличии ключа API, почтового индекса отправки и тарифа, и только если PostNL возвращает пункты для индекса покупателя. Проверьте предупреждения над страницей настроек и WooCommerce > Status > Logs, источник «vfd-postnl». Ошибки всегда записываются; включите Debug log для подробностей.

«Пункты выдачи PostNL сейчас не могут быть загружены»: PostNL не удалось связаться, он отклонил ключ API, или не указан почтовый индекс отправки. Страница настроек показывает последнюю ошибку. Ключ песочницы работает только при включённой Sandbox, а боевой ключ — только при выключенной.

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

Фильтры для разработчиков: vfd_ptnl_number_of_locations (по умолчанию 3), vfd_ptnl_checkout_request (тело запроса) и vfd_ptnl_api_url.

Блок лицензии показывает ошибку: следуйте сообщению в блоке. Например, если ключ уже используется на другом домене, освободите слот в аккаунте на vibefox.net и нажмите Check now. Если адрес сайта изменился, нажмите Check now, чтобы активировать ключ для нового домена. Если сервер лицензий недоступен, плагин продолжает работать по последнему известному статусу.

Удаление

Деактивация плагина сохраняет все настройки и очищает только кешированные списки пунктов выдачи. Чтобы удалить плагин, деактивируйте его и удалите на странице Plugins. Лицензионный ключ и статус лицензии этого плагина всегда удаляются вместе с кешированными списками пунктов выдачи и последней ошибкой API. Настройки и способы зон удаляются, только если была включена опция Remove data on uninstall. Иначе они сохраняются для повторной установки. Существующие заказы сохраняют свои строки доставки и сохранённый пункт выдачи.

PostNL — товарный знак его правообладателя. Этот плагин не связан с PostNL и не одобрен PostNL.