VibeFox Correos CityPaq for OpenCart — Допомога

Вимоги

OpenCart: 3.0.x (перевірено на 3.0.5.0) або 4.0.2 і новіша (перевірено на 4.1.0.3).

PHP: 8.0 або новіша.

Доставка в Іспанію: поштомати CityPaq є лише в Іспанії, тому спосіб доставки пропонується лише для адрес доставки в Іспанії.

Облікові дані API Correos (лише для списку поштоматів у реальному часі): список CityPaq від Correos читає активні поштомати з API «terminals» Correos. На порталі розробників Correos відкрийте API «terminals» і натисніть Request access для вашого застосунку. Correos схвалює запити своїх бізнес-клієнтів і надсилає client ID та client secret. Вони також показані в розділі My applications на порталі. Якщо покупці вводять поштомат самі або обирають зі вашого списку, облікові дані API не потрібні.

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

Встановлення

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

OpenCart 3

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

2. Перейдіть до Extensions > Extensions, виберіть тип розширення Shipping. Знайдіть VibeFox Correos CityPaq і натисніть Install (зелена кнопка +).

3. Натисніть Edit (кнопка з олівцем), щоб відкрити сторінку налаштувань.

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

5. Заповніть таблицю цін, оберіть, як покупець вибирає поштомат (див. Конфігурація), увімкніть Enable/Disable і натисніть Save.

OpenCart 4

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл vfd_correos_citypaq.ocmod.zip. Не перейменовуйте файл: OpenCart 4 бере код розширення з назви файлу, і перейменований пакет не працює.

2. Пакет з'явиться у списку встановлених розширень на тій самій сторінці. Натисніть Install (зелена кнопка +) поруч із ним.

3. Перейдіть до Extensions > Extensions і виберіть тип розширення Shipping. Знайдіть VibeFox Correos CityPaq, натисніть Install (зелена кнопка +), а потім Edit (кнопка з олівцем).

4. Введіть ліцензійний ключ і налаштування так само, як у кроках 4 і 5 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях.

Після встановлення спосіб доставки вимкнено, доки ви не увімкнете Enable/Disable і не збережете налаштування. Якщо ви встановлюєте розширення повторно після видалення, знову використовуються збережені налаштування.

Конфігурація

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Shipping > VibeFox Correos CityPaq > Edit. Розділи перелічено зліва. Одна кнопка Save внизу зберігає всю сторінку без перезавантаження. Ціни та суми можна вводити з комою або крапкою як десятковим роздільником. Зберігати налаштування може лише адміністратор із правом змінювати це розширення.

У верхній частині сторінки з'являються попередження: якщо в таблиці цін немає рядка для Іспанії та рядка за замовчуванням; якщо обраний спосіб вибору поштомата не може працювати (у вашому списку немає поштоматів, немає облікових даних API); про останню помилку API Correos; а також якщо в магазині немає класу ваги з одиницею kg (ваги товарів тоді перераховуються за назвою одиниці: kg, g, lb або oz; невідомі одиниці вважаються kg). Перевірте System > Localisation > Weight Classes. Якщо назва порожня, недійсна або довша за 64 символи, якщо вага чи сума не є дійсним числом 0 або більше, якщо Min weight (kg) більше за Max weight (kg), або якщо Sort order не є цілим числом, сторінка показує помилку, і нічого не зберігається. Недійсні ціни в таблиці, дубльовані рядки та недійсні або дубльовані рядки в My lockers повідомляються як попередження, а решта зберігається.

Загальні

Поштомати CityPaq є лише в Іспанії, тому спосіб доставки ніколи не пропонується для інших країн.

Enable/Disable: вмикає або вимикає доставку Correos CityPaq. За замовчуванням: вимкнено.

Name: назва способу доставки, яку покупець бачить під час оформлення замовлення. За замовчуванням: Correos CityPaq. Обов'язково, не більше 64 символів, без < > ; = # { }.

Tax class: OpenCart додає податок цього класу до цін із таблиці. No tax означає, що ціни остаточні.

Sort order: місце способу доставки в списку способів доставки. Ціле число.

Ціни (у заголовку розділу показано валюту магазину за замовчуванням)

Correos не публікує API тарифів для CityPaq, тому вартість береться з цієї таблиці. Введіть ціни за вашим договором із Correos у валюті магазину за замовчуванням, без податку.

Price table: рядок для Spain (ES) та/або рядок за замовчуванням * Default. Кожен рядок має базову Price і необов'язкові ціни для розмірів XS (до 1 kg), S (до 2 kg), M (до 3 kg), L (до 5 kg) і XL (понад 5 kg). Ціна розміру 0 або порожня використовує базову ціну. Натисніть Add row, щоб додати рядок, і кнопку ×, щоб видалити його. Без відповідного рядка спосіб доставки приховується. Якщо країна вказана двічі, використовується лише перший рядок.

Calculation type: як визначається розмір посилки.

Per order (size by the total cart weight): одна ціна для всього кошика, обрана за загальною вагою. Це значення за замовчуванням.

Per item (size by each item weight, multiplied by quantity): кожен товар отримує ціну свого розміру, помножену на його кількість, і ціни додаються.

Ваги товарів переводяться в kg із класу ваги кожного товару.

Умови

Min weight (kg): приховує спосіб доставки, якщо кошик легший за це значення. 0 означає без обмеження.

Max weight (kg): приховує спосіб доставки, якщо кошик важчий за це значення. За замовчуванням: 30, оскільки CityPaq приймає посилки до 30 kg. 0 означає без обмеження.

Minimum order amount: показує спосіб доставки лише тоді, коли проміжна сума товарів, що потребують доставки (після купона, до податку), досягає цієї суми. Залиште порожнім, щоб показувати завжди.

Безкоштовна доставка

Free shipping: вмикає безкоштовну доставку CityPaq від суми, вказаної нижче.

Free shipping from: проміжна сума товарів, що потребують доставки (після купона, до податку), з якої цей спосіб коштує 0. Використовується лише тоді, коли Free shipping увімкнено.

Вибір поштомата CityPaq

Розділ містить посилання на офіційний пошук поштоматів CityPaq від Correos.

Locker selection: як покупець вибирає поштомат перед оформленням замовлення. За замовчуванням: покупець вводить поштомат.

Customer chooses from the Correos CityPaq list (Correos API, credentials below): покупець бачить активні поштомати CityPaq за поштовим індексом адреси доставки і може шукати інший 5-значний індекс. Якщо для індексу немає поштомата, показуються поштомати тієї самої зони, потім тієї самої провінції, спочатку найближчі індекси (до 50). Якщо список не завантажується або нічого не знаходить, покупець вводить поштомат вручну.

Customer enters the locker (code or address from the Correos finder): обов'язкове поле для коду поштомата (наприклад S0000213D) або адреси, від 3 до 120 символів, з посиланням на карту CityPaq від Correos.

Customer chooses from my list of lockers (below): обов'язковий випадаючий список поштоматів із My lockers. Поштомати поблизу поштового індексу покупця показуються першими.

Do not ask for a locker: питання про поштомат під час оформлення замовлення не ставиться.

Якщо ви обрали список Correos без облікових даних API або власний список, коли My lockers порожній, покупцю пропонується ввести поштомат вручну.

Список поштоматів CityPaq від Correos (API) (використовується лише зі списком поштоматів CityPaq від Correos)

Розділ містить посилання на сторінку API «terminals» на порталі розробників Correos. Читається лише список поштоматів. Ціни завжди беруться з таблиці цін.

API client ID: client_id вашого застосунку на порталі розробників Correos.

API client secret: client_secret вашого застосунку на порталі розробників Correos.

Після збереження обидва поля залишаються порожніми і показують Saved - leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити. Позначте Remove the saved client ID and client secret і натисніть Save, щоб видалити їх. Якщо нічого не збережено, розділ показує No credentials saved. Коли ви змінюєте облікові дані або вибір поштомата, кешовані списки поштоматів і остання помилка API очищаються.

Доступність

Geo zone: пропонує спосіб доставки лише для адрес у цій географічній зоні. All zones (за замовчуванням) означає всі адреси в Іспанії. Географічні зони керуються в System > Localisation > Geo Zones.

Ignore geo zone: пропонує CityPaq для всіх адрес в Іспанії, навіть якщо вони не входять до географічної зони вище.

Додатково

Debug log: записує рядки налагодження в storage/logs/vfd_cpq_debug.log.php (в OpenCart 4 — system/storage/logs/vfd_cpq_debug.log.php). Файл не можна прочитати з веб-браузера. Помилки API Correos записуються завжди, навіть коли ця опція вимкнена. Облікові дані та персональні дані ніколи не записуються.

Log: показує розмір і останні записи журналу. Натисніть Clear log, щоб його очистити.

Remove data on uninstall: якщо увімкнено, видалення розширення стирає налаштування, кешовані списки та журнали. Поштомати, збережені в замовленнях, залишаються. Якщо вимкнено (за замовчуванням), усе зберігається для повторного встановлення.

Імпорт / експорт

Export: натисніть Download JSON, щоб зберегти налаштування у файл JSON. Client ID і secret API до файлу не включаються.

Import: вставте JSON з налаштуваннями, експортований з цього розширення, і натисніть Import. Значення перевіряються так само, як під час звичайного збереження. Збережені облікові дані залишаються.

Як це працює під час оформлення замовлення

Коли OpenCart показує способи доставки, він запитує в розширення вартість CityPaq. Якщо задано Geo zone (і Ignore geo zone вимкнено) і адреса поза нею, CityPaq не пропонується. Враховуються лише товари з Requires Shipping, встановленим у Yes: інші товари не додають ваги й не входять до суми замовлення. Далі розширення перевіряє, що адреса доставки в Іспанії, вагу кошика та мінімальну суму замовлення, знаходить рядок цін для Іспанії (або рядок *) і розмір посилки та повертає ціну. Якщо діє безкоштовна доставка, ціна дорівнює 0. Ціна розраховується у валюті магазину за замовчуванням, округлюється до її десяткових знаків і показується покупцеві у його валюті з податком обраного Tax class. Для ціни запит до Correos не надсилається.

Блок CityPaq locker з'являється під способом CityPaq на кроці способу доставки. Вибір зберігається, щойно покупець його зробив. Неприйнятний поштомат відхиляється з повідомленням, і попередній вибір залишається. Зі списком Correos код поштомата приймається, лише якщо Correos запропонував його для пошукового поштового індексу; його назва й адреса беруться з Correos. Покупець може шукати до 30 різних поштових індексів за одну сесію оформлення. Після цього покупець бачить Too many searches. Please enter the CityPaq locker you found on the Correos map.

Кнопка Continue на кроці способу доставки не переходить до CityPaq без дійсного поштомата. Це перевіряється на сервері. Покупець бачить, наприклад, Please choose the CityPaq locker where you want to collect your parcel. Коли замовлення оформлено, поштомат зберігається в замовленні.

В OpenCart 4 покупець натискає Choose у блоці способу доставки на сторінці оформлення замовлення і вибирає CityPaq у вікні Shipping method options. Блок CityPaq locker з'являється у цьому вікні під варіантом CityPaq і працює так, як описано вище. Кнопка Continue у вікні не переходить далі з CityPaq без дійсного поштомата. OpenCart 4 зберігає одне замовлення для оформлення та оновлює його щоразу, коли покупець підтверджує вибір знову, а поштомат замовлення оновлюється разом із ним.

Список Correos запитується лише тоді, коли обрано CityPaq, а не під час відображення кроку. Список кешується на 12 годин для кожного поштового індексу. Невдалий запит кешується на 10 хвилин, щоб оформлення не чекало Correos під час кожного оновлення. Покупець ніколи не бачить технічну помилку, лише повідомлення The Correos CityPaq list cannot be loaded right now. і ручне поле.

Розширення не отримує тарифи Correos у реальному часі, не показує карту, не реєструє відправлення заздалегідь, не друкує етикетки, не замовляє забір і не відстежує посилки. Створюйте відправлення у своєму обліковому записі Correos, використовуючи поштомат, збережений у замовленні.

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

Обраний поштомат додається до способу доставки замовлення, наприклад Correos CityPaq - CityPaq locker: .... Тож покупець бачить його в історії замовлень свого облікового запису та в листах про замовлення, а також його друкують на рахунку і показують у Sales > Orders. Сторінка успішного оформлення замовлення OpenCart спосіб доставки не показує.

На сторінці замовлення в адмін-панелі блок CityPaq locker над історією показує поштомат і його Locker code:, якщо його було обрано зі списку. Щоб змінити його, використайте поле Change CityPaq locker і натисніть Save: зі своїм списком оберіть інший поштомат у випадаючому списку; зі списком Correos введіть код поштомата (його перевіряють у Correos) або адресу; в інших випадках введіть новий код або адресу. Залиште поле порожнім або оберіть -- Keep the current locker --, щоб зберегти поточний поштомат. Кожна зміна також оновлює текст способу доставки замовлення і додає запис в історію CityPaq locker changed to: ... без сповіщення покупця. Для зміни поштомата потрібне право змінювати замовлення (sale/order). Доступ до налаштувань розширення не потрібен. Блок показується для замовлень CityPaq навіть тоді, коли розширення вимкнено.

Ліцензійний ключ

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

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

Коли ліцензія закінчується, розширення продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус перевіряється знову автоматично, коли ви відкриваєте Dashboard або сторінку Edit в адмін-панелі: щодня протягом перших 14 днів після введення ключа, далі раз на тиждень. Cron-завдання не потрібне. Видалення розширення завжди видаляє ліцензійний ключ і статус ліцензії.

Усунення несправностей

Correos CityPaq не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено і адреса доставки в Іспанії. Перевірте Geo zone (або увімкніть Ignore geo zone). Перевірте, що таблиця цін має рядок для Іспанії або рядок *, що кошик у межах обмежень ваги та Minimum order amount, і що товари мають Requires Shipping, встановлене в Yes.

Покупець мусить вводити поштомат, хоча обрано список Correos: перевірте, що API client ID і API client secret збережено, і подивіться попередження у верхній частині сторінки налаштувань. Воно показує останню помилку API Correos. HTTP 401/403 означає, що Correos відхилив облікові дані: перевірте їх і переконайтеся, що ваш застосунок має доступ до API «terminals». Після помилки наступна спроба відбувається через 10 хвилин.

Немає поштоматів для поштового індексу: Correos не знайшов активних поштоматів для цього індексу, його зони або провінції. Покупець може шукати інший поштовий індекс або ввести поштомат, знайдений на карті CityPaq від Correos.

Випадаючий список my lockers не з'являється: My lockers порожній або його рядки недійсні. Кожен рядок потребує щонайменше CODE | Name.

Де покупці знаходять код поштомата: на карті CityPaq від Correos, посилання на яку розміщено під полем поштомата.

Сторінка пише "Warning: You do not have permission to modify VibeFox Correos CityPaq!": ваша група адміністраторів, можливо, може лише переглядати налаштування. Надайте групі право змінювати extension/shipping/vfd_correos_citypaq (OpenCart 3) або extension/vfd_correos_citypaq/shipping/vfd_correos_citypaq (OpenCart 4) у System > Users > User Groups.

Для розробників: поштомат сесії оформлення та поштомат замовлення зберігаються в таблиці vfd_cpq_locker (з префіксом вашої бази даних). Адресу API Correos можна замінити налаштуванням vfd_cpq_api_url (для тестів); на сторінці налаштувань для неї немає поля.

Видалення

Перейдіть до Extensions > Extensions, виберіть тип Shipping і натисніть Uninstall (червона кнопка −) поруч із VibeFox Correos CityPaq. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди скидає Enable/Disable, Sort order, Tax class і Geo zone. Кешовані списки поштоматів Correos і остання помилка API завжди видаляються. Якщо Remove data on uninstall увімкнено, також видаляються налаштування, журнал і поштомати сесій оформлення без замовлення. Якщо вимкнено, інші налаштування зберігаються і знову використовуються під час повторного встановлення розширення. Поштомати, збережені в замовленнях, ніколи не видаляються, а наявні замовлення зберігають свій спосіб доставки та вартість.

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

Correos і CityPaq — торговельні марки їхніх власників. Це розширення не пов'язане з Correos і не схвалене Correos.