VibeFox CTT for PrestaShop — Допомога

Вимоги

PrestaShop: 8.0 – 9.x.

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

Обліковий запис CTT e-commerce (лише для тарифів у реальному часі та пунктів CTT): тарифи в реальному часі та доставка до пункту CTT використовують API CTT e-commerce. Вам потрібен обліковий запис CTT e-commerce на enviosecommerce.ctt.pt (для клієнтів із договором CTT Expresso або запитайте у CTT пропозицію). На сторінці керування ключами цього облікового запису створіть пару ключів: публічний і приватний. App ID (X-APPID) видає CTT для вашої інтеграції: уточніть його у свого контакту CTT e-commerce. CTT також вирішує, які функції API (розрахунок вартості, пункти CTT) може використовувати ваш App ID. Нарешті, вам потрібен Carrier ID CTT у вашому обліковому записі. Після збереження ключів на сторінці налаштувань з'являється список перевізників вашого облікового запису. Якщо ви використовуєте лише таблицю цін і доставку на адресу, ключі API не потрібні.

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

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

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

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

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

4. Заповніть таблицю цін (принаймні рядок Portugal або * Default) і натисніть Save. За бажанням заповніть ключі API CTT і Carrier ID, увімкніть Live rates та Enable CTT point carrier (див. Налаштування).

Під час встановлення модуль створює двох перевізників. CTT (доставка на адресу покупця, текст терміну доставки CTT delivery to your address) увімкнений. CTT point / parcel locker (текст терміну доставки Pickup at a CTT point or parcel locker) вимкнений, доки ви його не увімкнете. Обидва прив'язані до зони Португалії та до всіх груп клієнтів. Зони, групи клієнтів, термін доставки, логотип і обмеження розмірів можна змінити в Shipping > Carriers. Не встановлюйте там ціни: ціна завжди береться з модуля.

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

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

Попередження над налаштуваннями повідомляють про порожню таблицю цін, відсутню ціну для Португалії, неповні ключі API, відсутній Carrier ID, валюту магазину, відмінну від EUR, без курсу обміну, збій підключення до API CTT і видаленого перевізника CTT. Некоректні значення повідомляються під час збереження: некоректне число не зберігається, а невідоме направлення або дубльований рядок у таблиці цін видаляється. Якщо модуль не розпізнає одиниці ваги чи розмірів вашого магазину, попередження попросить задати одиниці в International > Localization (Local units).

Загальні

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

Name: назва перевізника, яку бачить покупець під час оформлення замовлення, наприклад «CTT Expresso». За замовчуванням: CTT. Обов'язкове поле, до 64 символів.

Tax status: None означає, що ціни остаточні. Taxable з податковим правилом означає, що PrestaShop додає до цін податок на доставку (наприклад, IVA). Вибір зберігається для обох перевізників CTT.

Доставка до пункту CTT або поштомата

Другий перевізник CTT. Покупець шукає пункти CTT за поштовим індексом або містом і має вибрати один із них, перш ніж продовжити. Потрібні ключі API CTT і Carrier ID. Без них це перевізник без вибору пункту.

Enable CTT point carrier: вмикає або вимикає перевізника пунктів CTT. Це той самий перемикач, що й його статус у Shipping > Carriers. За замовчуванням: вимкнено.

CTT point carrier name: назва цього варіанта під час оформлення замовлення. За замовчуванням: CTT point / parcel locker. Обов'язкове поле, до 64 символів.

API CTT e-commerce (тарифи в реальному часі, пункти CTT) (необов'язково; без ключів використовується таблиця цін)

Public key: публічний ключ зі сторінки керування ключами вашого облікового запису CTT e-commerce.

Private key: секретний ключ, яким підписується кожен запит (HMAC-SHA256). Він ніколи не надсилається в CTT і не записується в журнал.

Обидва ключі після збереження більше не показуються. Тоді опис поля має вигляд Saved - leave empty to keep it. Вводьте нове значення, лише якщо хочете їх змінити. Позначте Remove the saved public and private key і збережіть, щоб видалити обидва ключі.

App ID (X-APPID): ключ застосунку, виданий CTT, надсилається в заголовку X-APPID.

Carrier ID: ідентифікатор перевізника CTT у вашому обліковому записі, використовується для тарифів у реальному часі та пошуку пунктів CTT. Після збереження ключів і App ID під полем показуються перевізники вашого облікового запису; ті, що підтримують пункти CTT, позначені (CTT points). Лише цифри.

Live rates: модуль запитує в CTT ціну (розрахунок вартості), щойно покупець введе вулицю, поштовий індекс і місто. Поки адреса неповна або CTT не повертає ціну, використовується таблиця цін. CTT називає цю ціну оцінкою. За замовчуванням: вимкнено.

Service ID: необов'язково. Якщо CTT повертає кілька послуг, використовується та, що має цей ServiceId. Залиште поле порожнім, щоб використовувати найдешевшу.

Exchange rate: ціни CTT вказані в євро. Якщо валюта магазину за замовчуванням інша, вкажіть, скільки одиниць валюти магазину дорівнює 1 одиниці валюти CTT. Без цього тарифи в реальному часі в іншій валюті не використовуються, і діє таблиця цін.

Default product size (cm): довжина x ширина x висота, які надсилаються в CTT для товарів без розмірів. За замовчуванням: 30x20x15. Товари з розмірами використовують свої. Розміри переводяться в см, а вага — у грами відповідно до одиниць вашого магазину.

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

Введіть ціни за вашим договором з CTT або за публічним прайсом CTT на ctt.pt у валюті магазину за замовчуванням, без податків. Коли тарифи в реальному часі вимкнені, ця таблиця визначає ціну. Коли вони увімкнені, таблиця слугує запасним варіантом.

Price table: один рядок на направлення. Виберіть країну, Portugal - Azores (PT-AC), Portugal - Madeira (PT-MA) або * Default (other destinations). Кожен рядок містить базову Price і необов'язкові ціни для розмірів XS (до 1 кг), S (до 2 кг), M (до 3 кг), L (до 5 кг) та XL (понад 5 кг). Порожня (або нульова) ціна розміру використовує базову ціну. Рядок, де обидва поля порожні, приховує перевізника. Рядок Azores застосовується до португальських поштових індексів 9500-9999, рядок Madeira (включно з Porto Santo) — до 9000-9499. Без них застосовується рядок Portugal. Натисніть Add destination, щоб додати рядок, і значок кошика, щоб видалити його. Ціни приймають десятковий розділювач у вигляді крапки або коми. Після встановлення таблиця порожня.

Calculation: як знаходиться ціна за таблицею.

Тариф CTT у реальному часі завжди стосується всього відправлення.

Умови

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

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

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

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

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

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

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

Зазвичай перевізники пропонуються в зонах доставки, до яких вони прив'язані в Shipping > Carriers.

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

Countries: країни призначення для цього режиму. За замовчуванням: Portugal. Залиште порожнім, щоб дозволити всі країни. Використовується лише коли увімкнено Ignore shipping zones. Клієнти в зонах, які перевізники мали раніше, обслуговуються завжди.

Додатково

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

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

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

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

На кроці доставки PrestaShop запитує в модуля ціну кожного перевізника CTT. Враховуються лише фізичні товари: віртуальні товари не додають ваги та не входять до суми замовлення. Модуль спочатку перевіряє Ignore shipping zones та його країни, вагу кошика і мінімальну суму замовлення. Якщо Live rates увімкнено і адреса повна, модуль надсилає в CTT адресу доставки та для кожної позиції кошика кількість, вагу в грамах і розміри в см, а потім використовує повернуту ціну. Інакше, або коли CTT не повертає ціну (помилка API, тайм-аут, немає покриття, функція не увімкнена для вашого App ID), ціна береться з таблиці. Якщо діє безкоштовна доставка, ціна дорівнює 0. Ціна розраховується у валюті магазину за замовчуванням і потім показується у валюті кошика покупця.

Ціна CTT кешується на 1 годину, тож той самий кошик не викликає нового запиту. Невдалий запит запам'ятовується на 5 хвилин, щоб оформлення замовлення не чекало на CTT під час кожного оновлення. Тайм-аут API — 12 секунд. Помилки API ніколи не доходять до покупця: використовується ціна з таблиці, або перевізник приховується, якщо для направлення немає ціни.

Якщо ви редагуєте перевізника в Shipping > Carriers після того, як у нього з'явилися замовлення, PrestaShop зберігає його як нову версію перевізника. Модуль автоматично слідує за новою версією.

Коли ключі API заповнені, модуль надсилає в CTT адресу доставки, ваги та розміри товарів і URL вашого магазину, щоб отримати ціну або найближчі пункти CTT.

Модуль не створює відправлень, не друкує етикетки, не замовляє забір, не надає номери для відстеження та не показує карту пунктів CTT. Для обох перевізників є одна таблиця цін і один набір налаштувань API.

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

Коли покупець обирає перевізника пунктів CTT, під ним з'являються поле пошуку та список. Поштовий індекс адреси доставки заповнюється і шукається автоматично. Покупець може шукати інші пункти CTT за поштовим індексом або містом (кнопка Search або Enter) і вибрати один зі списку. Вибір одразу зберігається в кошику. Приймається лише пункт зі списку CTT для цього пошуку.

Пункт потрібно вибрати, перш ніж покупець зможе продовжити. Коли покупець натискає Continue на кроці доставки, модуль повторно перевіряє пункт на сервері. Без пункту покупець бачить Please select a CTT point., а з пунктом, якого немає у списку CTT, — The selected CTT point is not in the CTT list for this search. Please choose the CTT point again. Списки пунктів CTT кешуються на 6 годин. Якщо CTT недоступний, покупець бачить CTT points cannot be loaded right now. Please try again in a few minutes or choose another shipping method.

Вибір пункту працює з темами Classic і Hummingbird. Він активний лише тоді, коли заповнені публічний ключ, приватний ключ, App ID і Carrier ID.

Вибраний пункт зберігається в замовленні. Він показується на сторінці замовлення в бекофісі в блоці CTT point (назва та ID), на сторінці підтвердження замовлення, у деталях замовлення в обліковому записі покупця і в листі з підтвердженням замовлення як CTT point: поруч із назвою перевізника. Новий лист про замовлення модуля Mail alerts також показує ID пункту.

На сторінці замовлення в бекофісі введіть поштовий індекс або місто в полі Change CTT point, натисніть Search, виберіть пункт і натисніть Save. Сторінка покаже CTT point updated., і додасться приватне повідомлення до замовлення CTT point changed to: з новим пунктом. Для зміни пункту потрібен дозвіл на редагування замовлень.

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox CTT — це перший блок на сторінці Modules > Module Manager > VibeFox CTT > Configure, над налаштуваннями. Введіть ключ у поле License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої дійсна ліцензія, і ваш домен) та кнопки Check now, щоб перевірити статус ще раз, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ із цього магазину. Нижче розташовані рядок Product: presta-shipping-ctt і посилання 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.

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

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

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

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

Покупець не може вибрати пункт CTT: вибір з'являється лише під перевізником пунктів CTT і лише тоді, коли заповнені публічний ключ, приватний ключ, App ID і Carrier ID. Перевірте попередження над налаштуваннями, увімкніть Debug log і подивіться поле Log на сторінці модуля.

Тарифи в реальному часі не з'являються: таблиця цін використовується, доки покупець не введе вулицю, поштовий індекс і місто. Перевірте попередження над налаштуваннями та журнал. Відповідь «405» означає, що функція не увімкнена для вашого App ID: уточніть це в CTT. У магазині, який працює не в євро, заповніть Exchange rate.

Не вдалося підключитися до API CTT: попередження над налаштуваннями показує помилку. Перевірте ключі та App ID. Модуль повторить спробу автоматично через кілька хвилин.

Ціни з ПДВ або без ПДВ: якщо Tax status має правило Taxable, PrestaShop додає податок на доставку до ціни. З None ціна остаточна.

Ціни виглядають застарілими після зміни: натисніть Save на сторінці модуля. Це очистить кеш відповідей CTT.

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

Для розробників: адресу API CTT можна змінити ключем конфігурації vfd_ctt_API_URL.

Видалення

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

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