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. Для sandbox PostNL потрібен окремий ключ sandbox. Перевізнику доставки на адресу ключ не потрібен.

Ліцензійний ключ 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 або поштовий індекс відправлення для пунктів видачі, увімкнено sandbox, не встановлено жодної ціни, остання невдала відповідь 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: використовує sandbox PostNL (api-sandbox.postnl.nl) із ключем API sandbox. Тоді покупці бачать тестові пункти видачі. На робочому магазині тримайте вимкненим.

Ship from (country): країна, з якої ви передаєте посилки PostNL: Netherlands або Belgium. За замовчуванням: Netherlands. PostNL використовує адресу відправника для дати забору.

Ship from (postcode): поштовий індекс відправника, наприклад 1234AB у Нідерландах або 1000 у Бельгії. Залиште порожнім, щоб використовувати поштовий індекс магазину з Shop Parameters > Contact > Stores, якщо магазин розташований у тій самій країні. Неправильний індекс зберігається порожнім із попередженням. Під час зміни ключа API, налаштування sandbox або адреси відправлення очищаються закешовані списки пунктів видачі та остання помилка 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 недоступний, відхилив ключ API або бракує поштового індексу відправлення. Сторінка модуля показує останню помилку. Ключ sandbox працює лише з увімкненим 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.