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 і не схвалене нею.