VibeFox Correios for PrestaShop — Допомога
Вимоги
PrestaShop: 8.0–9.x.
PHP: 8.0 або новіша. Модуль не встановлюється на старіших версіях PHP.
Договір Correios (лише для актуальних тарифів): актуальні тарифи використовують API тарифів Correios Web Services (CWS) і потребують облікових даних договору Correios з posting card. Потрібні три значення: ваш логін Meu Correios (зазвичай CNPJ або CPF за договором), код доступу API і номер posting card. Код доступу створюється в порталі Correios Web Services (cws.correios.com.br; для homologação — cwshom.correios.com.br). Також потрібен CEP, з якого ви відправляєте. Без облікових даних модуль працює лише з фіксованими тарифами.
Ліцензійний ключ VibeFox: купується на vibefox.net. Один ключ працює на одному домені.
Встановлення
1. У back office відкрийте Modules > Module Manager і натисніть Upload a module. Виберіть ZIP-файл модуля.
2. Після завершення завантаження натисніть Configure або пізніше знайдіть VibeFox Correios у списку модулів і натисніть Configure.
3. Введіть ліцензійний ключ VibeFox у полі License key у блоці ліцензії у верхній частині сторінки Configure та натисніть Activate (див. розділ «Ліцензійний ключ»).
4. Введіть користувача API Correios, код доступу, номер posting card, CEP відправлення та послугу. Якщо валюта за замовчуванням вашого магазину не BRL, введіть курс BRL. Заповніть фіксовані тарифи для інших країн і як запасний варіант (див. Налаштування) та натисніть Save.
Під час встановлення модуль створює перевізника Correios з текстом строку доставки Correios (Brazilian Post). Перевізника призначено всім зонам і всім групам клієнтів. Зони, групи клієнтів, строк доставки, логотип і обмеження розміру можна змінити в Shipping > Carriers. Ціни там не задавайте: ціна завжди береться з модуля.
Налаштування
Усі параметри розташовані на сторінці модуля: Modules > Module Manager > VibeFox Correios > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Кожне збереження також очищає кеш цін Correios і токенів API. Числа можна вводити з крапкою або комою.
Сторінка показує попередження, коли актуальні тарифи або перевізник не можуть працювати: заповнені лише деякі з трьох облікових даних, не вказано CEP відправлення, немає курсу BRL для магазину з іншою валютою, або немає ні облікових даних, ні фіксованих тарифів. Кожне попередження повідомляє, чи використовуються тим часом фіксовані тарифи, чи перевізник приховано. Попередження також з'являється, якщо модуль не знає одиниці ваги або розміру магазину (тоді вона читається як кг або см); задайте кг, г, фунт або унцію та см, мм, м або дюйм в International > Localization (Local units).
Збереження відхиляється з повідомленням, якщо назва методу порожня або некоректна (максимум 64 символи), якщо числове поле або ціна в Country prices не є числом 0 або більше, якщо курс BRL дорівнює 0, якщо Min cart weight більше за Max cart weight, якщо CEP відправлення не має 8 цифр або інший код послуги має більше 5 цифр. Нічого не зберігається, доки ви не виправите значення.
Загальні
Enable Correios: вмикає або вимикає перевізника у всіх зонах одночасно. Це той самий перемикач, що й статус перевізника в Shipping > Carriers.
Method title: назва перевізника, яка показується в кошику та під час оформлення замовлення. За замовчуванням: Correios. Обов'язкове поле.
Tax: податкове правило, що додається до вартості доставки, або No tax (за замовчуванням).
API Correios (актуальні тарифи в Бразилії)
Для адрес у Бразилії ціна береться з API тарифів Correios. Якщо API не повертає ціну (API недоступний, CEP не обслуговується, посилка завелика), використовується фіксована ціна з Country prices, а якщо її немає, перевізника приховують. Подробиці помилок потрапляють у журнал, але ніколи не показуються покупцеві.
API user: ваш логін на порталі Meu Correios, зазвичай CNPJ або CPF за договором.
Access code: код доступу API (código de acesso), створений у порталі Correios Web Services. Це не пароль від порталу. Після збереження поле залишається порожнім і показує Saved — leave empty to keep it (empty the API user as well to remove it). Вводьте нове значення, лише якщо хочете його змінити. Щоб видалити збережений код, очистіть API user та Access code і збережіть.
Posting card: номер posting card (cartão de postagem) вашого договору: 10 цифр, зазвичай починається з двох нулів, наприклад 0012345678. Коротші номери доповнюються нулями зліва. Номер можна перевірити на сторінці Correios Fácil на сайті Correios.
Homologation: використовує тестове середовище Correios (homologação): запити надсилаються на apihom.correios.com.br з кодом доступу для homologação. Вимкніть цю опцію в робочому магазині.
Origin CEP: CEP (8 цифр), з якого відправляються посилки, наприклад 01001-000.
Service: послуга Correios, за якою розраховується ціна під час оформлення замовлення. Роздрібні коди: PAC (04510, за замовчуванням), SEDEX (04014), SEDEX 12 (04782), SEDEX 10 (04790), SEDEX Hoje (04804). Договірні коди: PAC (03298), SEDEX (03220), SEDEX 12 (03140), SEDEX 10 (03158), SEDEX Hoje (03204), Correios Mini Envios (04227). Договірним кодам потрібна posting card договору, до якого входить ця послуга.
Other service code: необов'язково, 5-значний код послуги вашого договору, якого немає у списку, наприклад 03085. Коротший код доповнюється нулями зліва. Якщо поле заповнено, код використовується замість Service.
Package format: тип об'єкта, який надсилається в Correios.
Default product weight: у кг, надсилається в Correios для кожного товару без ваги. За замовчуванням: 0.3. Ваги та розміри товарів перераховуються з одиниць вашого магазину (їх показує опис поля), а кошик розраховується як одна посилка.
BRL → store currency rate: назва поля показує валюту за замовчуванням вашого магазину, наприклад BRL → EUR rate. Тарифи Correios вказані в BRL. Якщо валюта за замовчуванням не BRL, введіть, скільки одиниць вашої валюти коштує один BRL, наприклад 0.17. Без цього курсу актуальні тарифи не використовуються. Курс має бути більшим за 0. Якщо валюта за замовчуванням — BRL, залиште поле порожнім.
Фіксовані тарифи (використовуються для країн поза Бразилією, без облікових даних API і як запасний варіант, коли API не повертає ціну)
Country prices: таблиця країн із базовою ціною Base та цінами залежно від ваги кошика у валюті за замовчуванням вашого магазину, без податку: XS до 1 кг, S 1–2 кг, M 2–3 кг, L 3–5 кг, XL понад 5 кг. Порожня або нульова ціна для розміру використовує базову ціну Base. Натисніть Add country, щоб додати рядок, і хрестик, щоб видалити його. Рядок * Default (all other countries) задає ціни для всіх країн без власного рядка. Країна без рядка (і без *) не отримує фіксованої ціни. Рядок без жодної ціни не зберігається. Ціна, яка не є числом або від'ємна, зупиняє збереження з помилкою. Базова ціна 0 означає безкоштовну доставку для цієї країни.
Fixed price per: Order стягує ціну один раз. Item (price × quantity) множить її на кількість товарів у кошику. Це стосується лише фіксованих тарифів. Актуальні тарифи завжди розраховуються для всієї посилки.
Умови
Min cart weight: у кг, приховує перевізника, якщо вага кошика нижча за це значення. 0 означає без обмеження. Не може бути більшою за Max cart weight.
Max cart weight: у кг, приховує перевізника, якщо вага кошика вища за це значення. За замовчуванням: 30. 0 означає без обмеження, порожнє поле означає 30 кг. Посилки PAC і SEDEX від Correios можуть важити до 30 кг.
Minimum order amount: показувати перевізника лише тоді, коли проміжна сума кошика (товари, що потребують доставки, після знижок, до податків) досягає цієї суми. Залиште порожнім, щоб показувати завжди.
Free shipping: вмикає безкоштовну доставку від суми, вказаної нижче.
Free shipping from: проміжна сума кошика (після знижок, до податків), від якої доставка безкоштовна. У цьому випадку запит до API не надсилається.
Доступність без зон доставки
Зазвичай перевізник показується в тих зонах, які йому призначено в Shipping > Carriers.
Ignore shipping zones: пропонує перевізника для країн, вказаних нижче, незалежно від того, яка зона підходить. Під час збереження перевізника додають до всіх зон. Вимкнення опції видаляє зони, які вона додала. Зона, створена пізніше, поки опція увімкнена, додається автоматично.
Countries: країни призначення для цього режиму. Залиште порожнім, щоб використовувати всі активні країни магазину. Це поле використовується лише тоді, коли увімкнено Ignore shipping zones.
Додатково
Debug log: записує розрахунки цін у logs/vfd_crr_debug.log.php у папці модуля. Файл не можна відкрити через веб. Помилки API завжди записуються в журнал, навіть коли ця опція вимкнена. Користувач API, код доступу, posting card, токен і CEP покупців у журнал не потрапляють.
Log: показує розмір і останні записи журналу налагодження. Натисніть Clear log, щоб очистити його.
Remove data on uninstall: коли ввімкнено, видалення модуля видаляє налаштування, перевізника, служби замовлень, кешовані ціни та журнал. Коли вимкнено, все зберігається для повторного встановлення.
Як це працює під час оформлення замовлення
На етапі доставки PrestaShop запитує в модуля ціну Correios. Враховуються лише фізичні товари: віртуальні товари не додають ваги і не входять до суми замовлення. Модуль спочатку перевіряє умови: дозволені країни (з Ignore shipping zones), вагу кошика та мінімальну суму замовлення. Якщо застосовується безкоштовна доставка, ціна дорівнює 0 і запит до Correios не надсилається.
Для адреси в Бразилії з вказаними обліковими даними модуль спочатку отримує токен API для вашої posting card. Токен також повертає номери договору та регіонального відділення, тож ціна є ціною вашого договору. Потім модуль запитує ціну вибраної послуги за CEP відправлення та призначення, вагою посилки в грамах і розміром посилки в см. Ціна запитується, лише якщо CEP призначення має 8 цифр. Якщо у всіх товарів є розміри, розмір посилки оцінюється за ними; інакше надсилається мінімальний розмір Correios. Посилки понад 30 кг до API не надсилаються. Ціна в BRL перераховується за вашим курсом. Ціна розраховується у валюті за замовчуванням вашого магазину, а потім показується у валюті кошика покупця.
Кожна ціна кешується на 1 годину для посилки. Невдалий запит кешується на 10 хвилин, щоб збій API не сповільнював кожне оновлення оформлення замовлення. Токен кешується до незадовго до закінчення строку дії і поновлюється автоматично; якщо Correios його відхиляє, запитується новий токен і запит ціни повторюється один раз. Тайм-аут API — 12 секунд.
Якщо API не повертає ціну, використовується фіксована ціна, а якщо її немає, перевізника приховують. Покупець ніколи не бачить подробиць помилок API; вони потрапляють у журнал налагодження.
Якщо ви редагуєте перевізника в Shipping > Carriers після того, як у нього з'явилися замовлення, PrestaShop зберігає його як нову версію перевізника. Модуль автоматично переходить на нову версію.
Модуль лише розраховує тарифи. Він не отримує міжнародні тарифи Correios (Exporta Fácil, Packet), оцінки строків доставки, етикетки, попередні відправлення, декларації чи відстеження. Покупці не можуть вибрати відділення або поштомат Correios. Додаткові послуги (оголошена цінність, вручення в руки, повідомлення про вручення) не додаються. Для магазину показується одна послуга Correios, а курси валют не оновлюються автоматично.
Замовлення
Коли замовлення оформлено з перевізником Correios, модуль зберігає, як була розрахована його вартість доставки. Сторінка замовлення в back office тоді показує блок Correios з Correios service (для актуального тарифу, наприклад PAC — contract (03298)) і Price source: Live price (Correios API), Fixed price або Free shipping.
Ліцензійний ключ
Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Correios є першим блоком на сторінці Modules > Module Manager > VibeFox Correios > Configure, над налаштуваннями. Введіть ключ у поле License key та натисніть Activate. Після цього блок показує ключ у прихованому вигляді, статус (наприклад, дату, до якої дійсна ліцензія, та ваш домен) і кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа та Remove key для видалення ключа з цього магазину. Нижче розташовані рядок Product: presta-shipping-correios і посилання 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.
Без активного ключа перевізник Correios не показується покупцям під час оформлення замовлення, і тариф не розраховується. Вітрина PrestaShop не знає, що ви увійшли в back office, тож перевізник приховано й для вас: модуль можна налаштувати до купівлі ключа, але не можна перевірити під час оформлення замовлення. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються.
Коли строк дії ліцензії спливає, модуль продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично перевіряється знову, поки ви працюєте в back office: раз на день протягом перших 14 днів після введення ключа, потім раз на тиждень. Cron-завдання не потрібне. Видалення або скидання модуля завжди видаляє ліцензійний ключ і статус ліцензії.
Усунення несправностей
Correios не з'являється під час оформлення замовлення: переконайтеся, що ліцензія активна і Enable Correios увімкнено. У Shipping > Carriers перевірте, що перевізник охоплює зону країни покупця та групу покупця (або що увімкнено Ignore shipping zones і країна дозволена). Перевірте обмеження ваги та Minimum order amount. Без актуальної ціни має існувати фіксований тариф для країни або для *. Товари також можуть бути обмежені певними перевізниками на сторінці товару.
Перевізник показує фіксовану ціну замість ціни Correios: перегляньте поле Log на сторінці модуля. Там записуються помилки Correios: невірний код доступу, послуга не входить до вашого договору, CEP не обслуговується, посилка понад 30 кг або понад обмеження розміру. Перевірте також, чи вказано CEP відправлення, чи має CEP покупця 8 цифр і, якщо валюта за замовчуванням не BRL, курс BRL. Увімкніть Debug log, щоб побачити кожен розрахунок.
Запит токена не проходить: перевірте користувача API, код доступу, posting card і середовище. Код доступу для homologação працює лише за увімкненої опції Homologation, а робочий код — лише за вимкненої.
Ціни виглядають застарілими після зміни: натисніть Save на сторінці модуля. Це очистить кешовані ціни та токен API.
Сторінка повідомляє, що перевізника Correios не знайдено: перевізника було видалено в Shipping > Carriers. Скиньте модуль у Modules > Module Manager, щоб створити його знову.
Під час збереження з'являється повідомлення про відсутність прав: ваш профіль співробітника може переглядати модуль, але не налаштовувати його. Збереження налаштувань і очищення журналу потребують права на налаштування модуля.
Видалення
Перейдіть до Modules > Module Manager, відкрийте меню біля VibeFox Correios і виберіть Uninstall. Ліцензійний ключ, статус ліцензії, кешовані ціни та токени завжди видаляються. Якщо Remove data on uninstall увімкнено, перевізника видаляють (замовлення зберігають свою історію), а налаштування, збережені послуги замовлень і журнал видаляються. Якщо вимкнено, перевізника лише деактивують і всі налаштування зберігаються. Повторне встановлення модуля відновлює перевізника зі статусом, який він мав раніше.
Correios — торговельна марка її відповідного власника. Цей модуль не пов'язаний з Correios і не схвалений Correios.