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

Вимоги

PrestaShop: 8.0–9.x.

PHP: 8.0 або новішої версії. Модуль не встановлюється на старіших версіях PHP.

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

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

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

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

1. В адмін-панелі перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Після завершення завантаження натисніть Configure або пізніше знайдіть VibeFox Correos CityPaq у списку модулів і натисніть Configure.

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

4. Заповніть таблицю цін, оберіть, як покупець вибирає поштомат (див. Налаштування), і натисніть Save.

Під час встановлення модуль створює перевізника Correos CityPaq з текстом терміну доставки Delivery to a Correos CityPaq parcel locker. Перевізник призначається всім групам клієнтів і зоні Іспанія. Зони, групи клієнтів, термін доставки, логотип і обмеження за розміром можна змінити в Shipping > Carriers. Не встановлюйте там ціни: ціна завжди береться з модуля.

Налаштування

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Correos CityPaq > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Ціни та суми приймають десятковою комою або десятковою крапкою.

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

Загальні

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

Enable/Disable: вмикає або вимикає доставку Correos CityPaq. Це той самий перемикач, що й статус перевізника в Shipping > Carriers.

Name: назва способу доставки, яку бачить покупець під час оформлення замовлення. Вона також є назвою перевізника. За замовчуванням: Correos CityPaq. Обов'язкове поле, не більше 64 символів.

Tax: податкове правило перевізника. PrestaShop додає цей податок до цін із таблиці. No tax означає, що ціни остаточні.

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

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

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

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

Ваги товарів переводяться в кг з одиниці ваги вашого магазину (наприклад, kg, g, lb або oz).

Умови

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

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

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

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

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

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

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

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

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

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

My lockers: використовується, коли Locker selection налаштовано на ваш список. Один поштомат у рядку: CODE | Name | Address | Postal code | City. Код і назва обов'язкові. Якщо код вказано двічі, використовується лише перший рядок.

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

Розділ містить посилання на сторінку 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. Коли ви змінюєте облікові дані або вибір поштомата, кешовані списки поштоматів очищаються.

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

Ignore shipping zones: пропонувати CityPaq для будь-якої іспанської адреси, навіть якщо зона адреси не пов'язана з перевізником. Коли опцію ввімкнено, перевізник пов'язується з усіма активними зонами, включно з тими, що створені пізніше. Коли ви вимкнете її знову, перевізник отримує назад зони, які мав раніше. Вимкнено (рекомендовано) означає, що використовуються зони, задані в Shipping > Carriers.

Додатково

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

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

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

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

На кроці доставки PrestaShop запитує у модуля ціну CityPaq. Враховуються лише фізичні товари: віртуальні товари не додають ваги і не входять до суми замовлення. Модуль перевіряє, що адреса доставки знаходиться в Іспанії, вагу кошика та мінімальну суму замовлення, знаходить рядок цін для Іспанії (або рядок *) та розмір посилки, і повертає ціну. Якщо діє безкоштовна доставка, ціна дорівнює 0. Ціна розраховується у валюті магазину за замовчуванням, а потім відображається у валюті кошика покупця. Податок додається за податковим правилом перевізника.

Коли покупець вибирає CityPaq, під перевізником з'являється блок CityPaq locker. Вибір зберігається в кошику одразу після того, як покупець його зробив. Неприйнятний поштомат відхиляється з повідомленням, і попередній вибір залишається. Зі списком Correos код поштомата приймається, лише якщо Correos запропонував його для пошукового поштового індексу, а назва та адреса беруться з Correos. Покупець може шукати до 30 різних поштових індексів на один кошик. Після цього він бачить Забагато пошуків. Введіть поштомат CityPaq, який ви знайшли на карті Correos.

Кнопка Continue на кроці доставки не переходить далі без дійсного поштомата. Це також перевіряється на сервері. Покупець бачить, наприклад, Оберіть поштомат CityPaq, в якому ви хочете отримати посилку. Коли замовлення оформлено, поштомат із кошика зберігається в замовленні.

Список Correos запитується лише тоді, коли покупець вибирає CityPaq, а не для кожного відвідувача кроку доставки. Список кешується на 12 годин для кожного поштового індексу. Невдалий запит кешується на 10 хвилин, щоб оформлення замовлення не чекало на Correos під час кожного оновлення. Тайм-аут API — 12 секунд. Покупець ніколи не бачить технічну помилку, лише коротке повідомлення та поле ручного введення. Блок поштомата працює з темами Classic і Hummingbird.

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

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

Обраний поштомат зберігається в замовленні. Покупець бачить його як CityPaq locker: на сторінці підтвердження замовлення та на сторінці деталей замовлення в особистому кабінеті. У листі з підтвердженням замовлення та в листі про нове замовлення модуля Mail alerts поштомат додається до рядка перевізника, наприклад, Correos CityPaq - CityPaq locker: ....

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

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Correos CityPaq є першим блоком на сторінці Modules > Module Manager > VibeFox Correos CityPaq > Configure, над налаштуваннями. Введіть ключ у поле License key та натисніть Activate. Після цього блок показує ключ у прихованому вигляді, статус (наприклад, дату, до якої дійсна ліцензія, та ваш домен) і кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа та Remove key для видалення ключа з цього магазину. Нижче розташовані рядок Product: presta-shipping-correos-citypaq і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише співробітники з правом Configure для модуля. Тексти блоку відповідають мові back office (включено англійську та російську).

Якщо ключ не прийнято, блок повідомляє причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on з датою. Після зміни адреси магазину або звільнення слота домену в обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, модуль продовжує працювати за останнім відомим статусом.

Один ключ працює на одному домені: домені основного магазину, у тому числі за багатомагазинної конфігурації. Видалення ключа з магазину не звільняє слот домену. Звільніть слот в обліковому записі vibefox.net.

Без активного ключа перевізник Correos CityPaq не показується покупцям під час оформлення замовлення, і тариф не розраховується. Вітрина PrestaShop не знає, що ви увійшли в back office, тож перевізник приховано й для вас: модуль можна налаштувати до купівлі ключа, але не можна перевірити під час оформлення замовлення. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються.

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

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

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

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

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

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

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

Сторінка повідомляє, що перевізника не знайдено або його не вдалося оновити: перевізника було видалено в Shipping > Carriers. Скиньте модуль у Modules > Module Manager, щоб створити його знову. Скидання зберігає налаштування та статус перевізника.

Примітки для розробників: поштомат кошика та замовлення зберігається в таблиці vfd_cpq_locker (з префіксом вашої бази даних). Модуль використовує робочий API Correos «terminals».

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Correos CityPaq і оберіть Uninstall. Ліцензійний ключ, статус ліцензії, кешовані списки поштоматів Correos і остання помилка API завжди видаляються. Якщо Remove data on uninstall увімкнено, перевізника видаляється (замовлення зберігають свою історію), а налаштування, журнал і поштомати кошиків без замовлення видаляються. Якщо вимкнено, перевізника лише деактивують і всі налаштування зберігаються. Повторне встановлення модуля відновлює статус перевізника, який був раніше. Поштомати, збережені в замовленнях, ніколи не видаляються.

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