VibeFox Coordinadora for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Ключ API Coordinadora (только для онлайн-тарифов): онлайн-тарифы поступают из Coordinadora Cotizador через сервис Coordinadora WooCommerce, тот же, который использует официальный плагин Coordinadora. Ключ API Coordinadora выдаёт клиентам с действующим коммерческим соглашением. Обратитесь к вашему менеджеру Coordinadora или посетите wc.coordinadora.com. Также нужен 8-значный код DANE города отправки. Без ключа перевозчик работает только с фиксированными ценами.

Товары: для онлайн-тарифа каждый товар в корзине должен иметь вес и габариты (ширина, высота, глубина).

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

Установка

1. В back office откройте Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox Coordinadora в списке модулей и нажмите Configure.

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

4. Введите ключ API, код DANE города отправки и, если ваша валюта по умолчанию не COP, курс обмена на COP. Добавьте хотя бы одну фиксированную цену для Колумбии как запасной вариант (см. Настройка). Нажмите Save.

5. Убедитесь, что Колумбия активна в вашем магазине, а у товаров есть вес и габариты.

При установке модуль создаёт перевозчика Coordinadora с текстом срока доставки Courier delivery in Colombia. Перевозчик назначается всем зонам и всем группам клиентов. Зоны, группы клиентов, срок доставки, логотип и ограничения по размеру можно изменить в Shipping > Carriers. Не задавайте там цены: цена всегда берётся из модуля.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Coordinadora > Configure. Они применяются ко всем зонам перевозчика. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Каждое сохранение также очищает кэш тарифов Coordinadora. Числа можно вводить с точкой или запятой (9,99 = 9.99).

Страница не сохраняет данные и показывает ошибку, если число или цена в таблице некорректны или отрицательны, COP per 1 unit of store currency равно 0, Min weight больше Max weight или Name длиннее 64 символов. Ничего не сохраняется, пока вы не исправите ошибку.

Страница показывает предупреждения вверху, если онлайн-тарифы не могут работать или перевозчик будет скрыт: Origin city (DANE code) пусто или некорректно, отсутствует COP per 1 unit of store currency, хотя валюта по умолчанию не COP, либо нет фиксированной цены для Колумбии (или *). Без ключа API и без такой фиксированной цены перевозчик никогда не показывается для колумбийских адресов. Предупреждение также появляется, если единица веса или размеров магазина в International > Localization (Local units) неизвестна модулю; тогда вес товаров читается как кг, а габариты как см.

Общее

Enable Coordinadora: включает или выключает перевозчика. Это тот же переключатель, что и статус перевозчика в Shipping > Carriers.

Name: название перевозчика, которое видит покупатель при оформлении заказа. По умолчанию: Coordinadora. Обязательно.

Tax: налоговое правило перевозчика или No tax. С правилом PrestaShop добавляет налог на доставку сверх тарифа. Выберите No tax, если ваши цены или тариф Coordinadora уже включают налог.

Онлайн-тарифы Coordinadora

Онлайн-тарифы запрашиваются для адресов в Колумбии. Оставьте ключ пустым, чтобы использовать только фиксированные цены.

API key: ваш ключ API Coordinadora WooCommerce, полученный у Coordinadora. После сохранения поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить. Ключ никогда не записывается в журнал.

Remove the saved API key: появляется, только если ключ сохранён. Включите и нажмите Save, чтобы удалить ключ; перевозчик тогда будет использовать только фиксированные цены.

Origin city (DANE code): 8-значный код DANE города, из которого вы отправляете, например 11001000 Bogotá, 05001000 Medellín, 76001000 Cali или 08001000 Barranquilla. Принимается также 5-значный код муниципалитета, который дополняется до 8 знаков.

COP per 1 unit of store currency: Coordinadora рассчитывает тарифы в колумбийских песо. Если валюта по умолчанию не COP, укажите, сколько COP составляет 1 единица вашей валюты, например 4300. Курс также используется для передачи объявленной стоимости в COP. Если оставить поле пустым, онлайн-тарифы не используются. Курс должен быть больше 0. Если валюта по умолчанию — COP, оставьте поле пустым.

Фиксированные цены (используются, когда нет ключа API, для направлений за пределами Колумбии и как запасной вариант, если онлайн-тариф недоступен)

Prices by country: таблица стран со столбцом Price и необязательными ценами по размеру посылки в вашей валюте по умолчанию, без налога. Размер определяется по весу корзины: XS до 1 кг, S 1–2 кг, M 2–3 кг, L 3–5 кг, XL свыше 5 кг. Price используется, когда в столбце размера стоит 0 или пусто. Нажмите Add country, чтобы добавить строку, и крестик, чтобы удалить. Страна * All other countries применяется к странам без собственной строки. Страна без строки (и без *) не получает фиксированной цены. Строка с Price 0 и без цены по размеру даёт бесплатную доставку.

Fixed price per: Order взимает цену один раз. Item (price × quantity) умножает её на количество товаров в корзине. Это относится только к фиксированным ценам; онлайн-тариф Coordinadora всегда покрывает весь заказ.

Условия

Min weight: скрывает перевозчика при весе корзины ниже этого значения, в кг. 0 означает без ограничения.

Max weight: скрывает перевозчика при весе корзины выше этого значения, в кг. По умолчанию: 25 (также используется, если поле пусто). 0 означает без ограничения. Не может быть меньше Min weight.

Minimum order subtotal: показывает перевозчика, только если промежуточная сумма корзины (после скидок, до налогов) не меньше этой суммы. Оставьте пустым, чтобы показывать всегда.

Free shipping: включает бесплатную доставку от суммы, указанной ниже.

Free shipping from: промежуточная сумма корзины (после скидок, до налогов), начиная с которой доставка бесплатна. Используется, только если включено Free shipping. В этом случае запрос к API не выполняется.

Countries: предлагать Coordinadora только для этих стран назначения. Перечислены только активные страны. Оставьте пустым, чтобы разрешить все страны зон перевозчика.

Дополнительно

Debug log: записывает расчёты тарифов в logs/vfd_crd_debug.log.php в папке модуля. Файл нельзя открыть через веб. Ошибки API и неполные настройки всегда записываются в журнал, даже когда эта опция выключена. Ключ API и адреса покупателей никогда не записываются.

Log: показывает размер и последние записи журнала отладки. Нажмите Clear log, чтобы его очистить.

Remove data on uninstall: если включено, при удалении модуля удаляются настройки Coordinadora, перевозчик, кэшированные тарифы и журналы. Если выключено, всё сохраняется для повторной установки.

Как это работает при оформлении заказа

На шаге доставки PrestaShop запрашивает у модуля цену Coordinadora. Учитываются только физические товары: виртуальные товары не добавляют вес и не входят в расчёт. Модуль сначала проверяет условия: разрешённые страны, вес корзины и минимальную сумму заказа. Если применяется бесплатная доставка, цена равна 0 и запрос в Coordinadora не отправляется.

Для адреса в Колумбии с ключом API модуль находит код DANE города назначения в таком порядке: код DANE в поле города (модули выбора департаментов и городов Колумбии записывают его, например MEDELLIN (ANT) (05001000)), 8-значный почтовый индекс или встроенный список столиц департаментов и примерно 40 крупнейших городов. Если в адресе указан департамент (регион), город из списка проверяется по нему. Диакритические знаки и регистр не учитываются.

Затем модуль передаёт Coordinadora код DANE назначения и каждый товар с городом отправления, его весом (кг), габаритами (см), количеством и объявленной стоимостью (COP). Объявленная стоимость — это сумма строки товара до налогов и до скидок корзины. Единицы измерения магазина пересчитываются автоматически. Coordinadora возвращает цену в COP, а модуль пересчитывает её в валюту по умолчанию, а затем в валюту корзины покупателя. Каждый тариф кэшируется на 1 час. Неудачный запрос запоминается на 10 минут, чтобы сбой Coordinadora никогда не замедлял каждое обновление страницы оформления. Тайм-аут API — 10 секунд.

Если онлайн-тариф недоступен (ошибка API, неизвестный город, товар без веса или габаритов, отсутствующие настройки), используется фиксированная цена. Если её нет, перевозчик скрывается для этой корзины. Сведения об ошибках попадают в журнал отладки, никогда не покупателю.

Если вы редактируете перевозчика в Shipping > Carriers после того, как по нему есть заказы, PrestaShop сохраняет его как новую версию перевозчика. Модуль автоматически следует за новой версией.

Модуль только рассчитывает тарифы. Он не создаёт отправления и накладные (guías), не печатает этикетки, не заказывает забор посылок (recogidas), не отслеживает посылки, не принимает наложенный платёж (recaudo) и не предлагает пункты выдачи Droop; для этого используйте портал Coordinadora. Международные направления используют фиксированные цены.

Лицензионный ключ

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

Без активного ключа перевозчик Coordinadora не показывается покупателям при оформлении заказа, и тариф не рассчитывается. Витрина PrestaShop не знает, что вы вошли в бэк-офис, поэтому перевозчик скрыт и для вас: модуль можно настроить до покупки ключа, но проверить его при оформлении заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются.

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

Устранение неполадок

Coordinadora не появляется при оформлении заказа: проверьте, что лицензия активна и включён Enable Coordinadora. В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и его группу клиентов. Проверьте Countries, ограничения по весу и Minimum order subtotal. Без онлайн-тарифа должна существовать фиксированная цена для страны или для *. Товары также можно ограничить определёнными перевозчиками на странице товара.

Онлайн-тариф не показывается, только фиксированная цена: включите Debug log, перезагрузите оформление заказа и посмотрите поле Log на странице модуля. Типичные причины: город назначения не распознан, у товара нет веса или габаритов, отсутствует код DANE города отправки или курс COP, либо Coordinadora вернула ошибку.

Город назначения не распознан: установите модуль выбора департаментов и городов Колумбии, который записывает код DANE в поле города. Разработчики могут сопоставить больше городов с помощью хуков модуля actionVfdCrdDaneCities и actionVfdCrdDestinationDane, или изменить адрес API через actionVfdCrdApiUrl.

Тариф включает налог? Тариф — это то, что рассчитывает Coordinadora. С правилом Tax PrestaShop добавляет налог на доставку сверху; выберите No tax, если тариф уже включает его.

Тарифы выглядят устаревшими после изменения: нажмите Save на странице модуля. Это очистит кэш тарифов.

Страница сообщает, что перевозчик Coordinadora не найден: перевозчик был удалён в Shipping > Carriers. Сбросьте модуль в Modules > Module Manager, чтобы создать его заново.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Coordinadora и выберите Uninstall. Лицензионный ключ, статус лицензии и кэшированные тарифы удаляются всегда. Если Remove data on uninstall включено, перевозчик удаляется (заказы сохраняют историю), а настройки и журнал удаляются. Если выключено, перевозчик только отключается и все настройки сохраняются. При повторной установке модуля или Reset сохранённый перевозчик возвращает статус, который был у него раньше: перевозчик, который вы отключили, остаётся отключённым.

Coordinadora — товарный знак её владельца. Этот модуль не связан с Coordinadora и не одобрен ею.