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

Вимоги

PrestaShop: 8.0–9.x.

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

Обліковий запис Servientrega (лише для актуальних тарифів): актуальні тарифи використовують Cotizador Corporativo Servientrega (корпоративний API розрахунку вартості). Потрібен корпоративний (кредитний) обліковий запис Servientrega з доступом до нього. Знадобляться три значення: користувач, пароль і код білінгу (código de facturación, зазвичай починається з SER). Це ваші облікові дані SISCLINET, які видає ваш комерційний консультант Servientrega. Якщо ви використовуєте лише фіксовані ціни, обліковий запис Servientrega не потрібен.

Доступ сервера (лише для актуальних тарифів): ваш сервер має мати змогу звертатися до web.servientrega.com через HTTP на порт 8058 (API розрахунку вартості) і порт 8081 (веб-служба шифрування пароля).

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

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

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

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

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

4. Для актуальних тарифів введіть користувача, пароль і код білінгу, оберіть продукт Servientrega, введіть код DANE відправлення та, якщо валюта вашого магазину не COP, курс конвертації валюти. Натисніть Add Colombian departments, якщо в магазині їх ще немає (див. Налаштування).

5. За бажанням додайте фіксовані ціни за країною та вагою і резервну вартість, потім натисніть Save.

Під час встановлення модуль створює перевізника Servientrega з текстом строку доставки Servientrega courier delivery. Перевізника призначено всім зонам і всім групам клієнтів. Зони, групи клієнтів, строк доставки, логотип і обмеження розміру можна змінити в Shipping > Carriers. Ціни там не встановлюйте: ціна завжди береться з модуля.

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

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

Якщо актуальні тарифи не можуть працювати із збереженими налаштуваннями, попередження над формою повідомить причину: відсутні користувач, пароль або код білінгу, відсутній курс конвертації або код DANE відправлення. Попередження також з'явиться, якщо одиниця ваги або розмірів вашого магазину (International > Localization, Local units) невідома модулю; тоді ваги читаються як кг, а розміри як см. Під час збереження значення, що не є числом, від'ємне число, курс конвертації 0, мінімальна вага більша за максимальну, неправильна ціна в таблиці або назва методу довша за 64 символи, відхиляється з помилкою, і нічого не зберігається.

Загальні

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

Method title: назва перевізника, яку бачить покупець у кошику та під час оформлення замовлення. За замовчуванням: Servientrega. Обов'язкове поле, не більше 64 символів.

API Servientrega (актуальні тарифи для Колумбії) (необов'язково; без облікових даних використовуються лише фіксовані ціни)

User (login): ваш користувач Servientrega / SISCLINET. Очищення поля також видаляє збережений пароль.

Password: ваш пароль Servientrega / SISCLINET, як ви його вводите. Модуль шифрує його через веб-службу Servientrega перед входом. Після збереження поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Billing code: código de facturación вашого облікового запису Servientrega, який відображається в SISCLINET. Зазвичай починається з SER.

Усі три поля потрібні для актуальних тарифів. Актуальні тарифи запитуються лише для напрямків у Колумбії. Для інших країн використовуються фіксовані ціни.

Servientrega product: послуга з вашого договору з Servientrega, за якою запитується тариф.

Mercancía Premier (посилки; розрахункова вага щонайменше 3 кг): варіант за замовчуванням. Об'ємна вага — 222 кг на м³.

Mercancía Industrial (важкі вантажі): об'ємна вага — 400 кг на м³.

Documento unitario (документи): для документів.

Розрахункова вага — більша з фактичної та об'ємної.

Currency conversion rate: Servientrega розраховує в COP. Якщо валюта магазину за замовчуванням не COP, введіть значення 1 COP у валюті вашого магазину, наприклад 0.00023. Оголошена вартість посилки перераховується в COP так само. Залиште поле порожнім, якщо валюта магазину — COP. Якщо магазин використовує іншу валюту, а це поле порожнє, актуальні тарифи не використовуються і діють фіксовані ціни. Модуль не завантажує курси валют. Крапка і кома приймаються як десятковий роздільник.

Colombian departments: департамент допомагає розрізняти муніципалітети з однаковою назвою. У PrestaShop колумбійських департаментів за замовчуванням немає; без них розпізнаються лише назви міст, які унікальні в Колумбії. Натисніть Add Colombian departments, щоб додати 33 департаменти як регіони Колумбії (коди ISO ANT, DC…), увімкніть Contains states для Колумбії та додайте поле департаменту до форми адреси для Колумбії. Департаменти, які вже існують, не додаються повторно. Коли все налаштовано, поле показує, скільки департаментів є в адресах Колумбії.

Відправлення з (використовується для актуальних тарифів)

Origin city (DANE code): 8-значний код DANE муніципалітету, з якого ви відправляєте, наприклад 11001000 Bogotá, 05001000 Medellín, 76001000 Cali або 08001000 Barranquilla. Приймається також 5-значний код муніципалітету. Якщо поле порожнє, а адреса вашого магазину в Shop Parameters > Contact > Stores знаходиться в Колумбії, використовується муніципалітет адреси магазину.

Фіксовані ціни (використовуються, коли немає актуального тарифу: немає облікових даних, напрямок поза Колумбією, невідомий муніципалітет, не задано курс конвертації, помилка API або немає покриття маршруту)

Price per country: таблиця країн і цін у валюті магазину за замовчуванням, без податку. Натисніть Add country, щоб додати рядок, і значок смітника, щоб видалити рядок. Price діє для будь-якої ваги. Вагові колонки XS ≤1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg і XL >5 kg замінюють її для цієї ваги, якщо вони більші за 0. Рядок * Default діє для всіх країн без власного рядка. Рядок без жодної ціни не зберігається.

Fallback cost: використовується, коли немає актуального тарифу і жоден рядок таблиці не підходить. Залиште поле порожнім, щоб у такому разі приховати перевізника.

Fixed price applies: як нараховуються фіксовані ціни.

Per order (weight tier of the whole cart): ціна ваговій колонці, що відповідає вазі всього кошика, нараховується один раз.

Per item (weight tier of each product × quantity): ціна ваговій колонці кожного товару, помножена на його кількість, і підсумована. Резервна вартість множиться на кількість товарів.

Актуальні тарифи Servientrega завжди розраховуються за відправлення.

Умови

Minimum weight: приховує перевізника, коли кошик важить менше, у кг. 0 означає без обмеження.

Maximum weight: приховує перевізника, коли кошик важить більше, у кг. За замовчуванням: 50. 0 означає без обмеження.

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

Free shipping from: доставка безкоштовна, коли проміжна сума кошика (після знижок, до податку) досягає цієї суми, і запит до Servientrega не надсилається. Це стосується всіх напрямків, де пропонується перевізник, зокрема країн без рядка в таблиці цін. Залиште поле порожнім, щоб ніколи не пропонувати безкоштовну доставку.

Tax: правило податку перевізника або No tax. Котирування Servientrega (ValorTotal) вже включають збори перевізника. Оберіть No tax, якщо не хочете додавати податок зверху.

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

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

Ignore shipping zones: пропонує Servientrega для країн, зазначених нижче, навіть якщо перевізника не призначено їхній зоні. Тоді перевізника призначається всім зонам, зокрема зонам, які ви створите пізніше. Вимкнення опції повертає перевізнику його попередні зони.

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

Додатково

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

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

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

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

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

Для напрямку в Колумбії з вказаними обліковими даними модуль знаходить код DANE муніципалітету покупця. Він використовує код DANE, введений як поштовий індекс або в полі міста, або співставляє департамент і місто з вбудованою таблицею приблизно з 1 130 муніципалітетів. Наголоси та «D.C.» ігноруються. Назва міста, яка є лише в одному департаменті, знаходиться навіть без департаменту.

Далі модуль надсилає в Servientrega одне місце на замовлення: загальну вагу, перераховану з одиниці вашого магазину в кг, і коробку з довжиною та шириною найбільшого товару і загальним об'ємом усіх товарів, перерахованим у см. Товари без розмірів вважаються як 10 × 10 × 10 см. Оголошена вартість — проміжна сума кошика, перерахована в COP, але не менше 6 000 COP. Servientrega повертає підсумок у COP. Модуль перераховує його у валюту магазину за замовчуванням, а покупець бачить її у валюті кошика.

Токен входу зберігається до закінчення строку, але не більше 4 днів. Відхилений токен оновлюється автоматично один раз. Кожне котирування кешується на 1 годину для маршруту та посилки, тому той самий кошик не викликає новий запит. Невдалий запит (шифрування, вхід або котирування) кешується на 10 хвилин, щоб оформлення замовлення не чекало Servientrega під час кожного оновлення. Тайм-аут становить 10 секунд на запит.

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

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

Модуль лише розраховує тарифи. Він не створює накладні (guías), етикетки чи наліпки, не замовляє забір відправлень, не відстежує і не скасовує відправлення та не дозволяє покупцям вибрати відділення Servientrega (Centro de Soluciones). Створіть накладну в SISCLINET або на порталі Servientrega. Накладений платіж (logística de recaudo) не розраховується. Актуальні тарифи стосуються лише внутрішніх відправлень у межах Колумбії. Для інших країн використовуються фіксовані ціни.

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

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

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

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

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

Servientrega не з'являється під час оформлення замовлення: перевірте, що ліцензія активна і ввімкнено Enable Servientrega. У Shipping > Carriers перевірте, що перевізник охоплює зону країни покупця і групу клієнтів, або ввімкніть Ignore shipping zones і перевірте Countries. Перевірте обмеження ваги та Minimum order amount. Без актуального тарифу перевірте, що для країни або рядка * Default є ціна, або що задано Fallback cost. Товари також можуть бути обмежені певними перевізниками на сторінці товару.

Актуальні тарифи не з'являються: увімкніть Debug log, перезавантажте оформлення замовлення і подивіться поле Log на сторінці модуля. Типові причини: немає курсу конвертації (валюта магазину не COP), немає коду DANE відправлення, департамент або місто покупця ще не введені чи не є відомим муніципалітетом, неправильні облікові дані або немає покриття для маршруту. Фіксовані ціни покривають ці випадки, якщо ви їх задали.

Вхід не вдається: перевірте користувача, пароль і код білінгу у свого комерційного консультанта Servientrega. Після невдалого входу модуль чекає 10 хвилин перед наступною спробою. Збережіть налаштування, щоб спробувати одразу.

Місто покупця не розпізнається: натисніть Add Colombian departments, щоб покупці могли обрати свій департамент. Для рідкісних написань покупець може ввести 8-значний код DANE як поштовий індекс.

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

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

Для розробників: хуки actionVfdSvtgDaneCode і actionVfdSvtgQuoteRequest дозволяють змінити код DANE призначення та запит котирування.

Видалення

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

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