VibeFox Coordinadora for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

PHP: 8.0 или новее.

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

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

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

Установка

Загрузка — это один zip-архив с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. Он содержит README.txt, пакет для OpenCart 3 vfd_coordinadora-oc3-(version).ocmod.zip и пакет для OpenCart 4 vfd_coordinadora.ocmod.zip. Устанавливайте только пакет для вашей версии OpenCart. Лицензионный ключ одинаковый для обеих версий.

OpenCart 3

1. В админке откройте Extensions > Installer, нажмите Upload и выберите файл vfd_coordinadora-oc3-(version).ocmod.zip. Расширение не добавляет модификации OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо Installer можно скопировать содержимое папки upload из этого пакета в корневую папку магазина.

2. Откройте Extensions > Extensions и выберите тип расширения Shipping. Найдите VibeFox Coordinadora и нажмите Install (зелёная кнопка +).

3. Нажмите Edit (кнопка с карандашом), чтобы открыть страницу настроек.

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

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

6. Убедитесь, что у ваших товаров есть вес и размеры.

OpenCart 4

1. В админке откройте Extensions > Installer, нажмите Upload и выберите файл vfd_coordinadora.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появится в списке установленных расширений на той же странице. Нажмите рядом с ним Install (зелёная кнопка +).

3. Откройте Extensions > Extensions и выберите тип расширения Shipping. Найдите VibeFox Coordinadora, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ и настройки, как в шагах 4–6 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях.

После установки способ выключен, пока вы не включите Enable Coordinadora и не сохраните настройки. Если вы установите расширение повторно после удаления, сохранённые настройки Coordinadora будут использованы снова.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox Coordinadora > Edit. Настройки действуют для всех гео-зон; способ можно ограничить гео-зоной и странами в разделе Conditions. Разделы перечислены слева. Одна кнопка Save внизу сохраняет всю страницу без перезагрузки. После сохранения вы увидите Settings saved. Cached Coordinadora rates were cleared. Числа можно вводить с точкой или с запятой (9,99 = 9.99). Сохранять настройки могут только администраторы с правом изменения этого расширения.

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

Над настройками страница показывает предупреждения, если актуальные тарифы не могут работать или способ был бы скрыт: Origin city (DANE code) пустое или некорректное; COP per 1 unit of store currency не заполнено, а валюта магазина по умолчанию не COP; для Колумбии нет фиксированной цены (или для *); нет ни ключа API, ни фиксированной цены для Колумбии, поэтому способ никогда не показывается для колумбийских адресов. Предупреждение также появляется, если в магазине нет класса веса в кг или класса длины в см, а единица по умолчанию неизвестна расширению; тогда веса товаров читаются как кг, а размеры как см (используйте kg, g, lb или oz и cm, mm, m или in в System > Localisation). Предупреждения обновляются после каждого сохранения.

Общие

Enable Coordinadora: показывает или скрывает Coordinadora при оформлении заказа. По умолчанию: выключено.

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

Sort order: позиция Coordinadora среди способов доставки при оформлении заказа. Целое число.

Актуальные тарифы Coordinadora

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

API key: ваш ключ API 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 (kg): скрывает способ, если вес корзины ниже этого значения. 0 означает отсутствие ограничения (по умолчанию).

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

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

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

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

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

Geo zone: предлагать Coordinadora только для адресов в этой гео-зоне. All zones (по умолчанию) означает отсутствие ограничения. Гео-зоны настраиваются в System > Localisation > Geo Zones.

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

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

Debug log: записывает расчёты тарифов в storage/logs/vfd_crd_debug.log.php (в OpenCart 4 — system/storage/logs/vfd_crd_debug.log.php). Файл нельзя прочитать из веба. Ошибки API и неполные настройки записываются всегда, даже когда эта опция выключена. Ключ API и адреса покупателей никогда не записываются. Когда файл достигает 5 МБ, он переносится в vfd_crd_debug.old.log.php и начинается новый журнал.

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

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

Импорт / экспорт

Export: нажмите Download JSON, чтобы сохранить настройки в файл JSON. Ключ API не экспортируется.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки, например в другом магазине. Значения проверяются так же, как при обычном сохранении. Сохранённый ключ API остаётся.

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

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену Coordinadora. Если задана Geo zone и адрес находится вне неё, Coordinadora не предлагается. Учитываются только товары с Requires Shipping в значении Yes: остальные товары не добавляют вес и не входят в тариф. Промежуточный итог — это цена товаров, которые нужно доставить, после скидки по купону и до налога. Подарочные сертификаты, бонусные баллы и кредит магазина не учитываются. Расширение сначала проверяет условия: разрешённые страны, вес корзины и минимальную сумму заказа. Если применяется бесплатная доставка, цена равна 0 и запрос в Coordinadora не отправляется.

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

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

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

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

В OpenCart 4 покупатель нажимает Choose в блоке способов доставки на странице оформления заказа и выбирает Coordinadora в окне Shipping method options. Способ работает так же, как в OpenCart 3.

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Coordinadora — первый блок на странице Extensions > Extensions > Shipping > VibeFox Coordinadora > Edit, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в маскированном виде, статус (например, дату окончания действия лицензии и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: opencart-shipping-coordinadora и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Изменить ключ могут только администраторы с правом изменения для расширения. Тексты блока следуют языку админки (включены английский и русский).

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

Один ключ работает на одном домене: адрес магазина из настроек OpenCart. Удаление ключа из магазина не освобождает его слот домена. Освободите слот в вашем аккаунте на vibefox.net.

Без активного ключа Coordinadora не показывается покупателям при оформлении заказа, и тариф не рассчитывается. Администратор, вошедший в админку в том же браузере, всё ещё видит способ в магазине с пометкой (unlicensed — visible to admins only), поэтому вы можете настроить и проверить расширение до покупки ключа. В OpenCart 4 этот предпросмотр недоступен: магазин не видит вход в админку, поэтому без активного ключа способ скрыт для всех. После того как вы один раз откроете страницу Edit, на Dashboard админки появится напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются.

Когда срок лицензии истекает, расширение продолжает работать, но для обновлений и поддержки нужно продление. Статус проверяется автоматически при открытии Dashboard админки или страницы Edit: раз в день в течение первых 14 дней после ввода ключа, затем раз в неделю. Задание cron не требуется. Удаление расширения всегда удаляет лицензионный ключ и статус лицензии.

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

Coordinadora не появляется при оформлении заказа: проверьте, что лицензия активна и включён Enable Coordinadora. Проверьте предупреждения вверху страницы расширения, Geo zone, Countries, ограничения по весу и Minimum order subtotal. Без актуального тарифа должна существовать фиксированная цена для страны или для *. Проверьте, что у товаров Requires Shipping установлено в Yes.

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

Город назначения не распознан: установите колумбийский модуль оформления заказа для департаментов и городов, который записывает код DANE в поле города. Разработчики могут добавить другие города или изменить адрес API с помощью событий OpenCart vfd_coordinadora/dane_cities, vfd_coordinadora/destination_dane и vfd_coordinadora/api_url; адрес API также можно заменить настройкой vfd_crd_api_url (для тестов), для которой нет поля на странице настроек.

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

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

Страница пишет "Warning: You do not have permission to modify VibeFox Coordinadora!": ваша группа администраторов может иметь право только на просмотр настроек. Дайте группе право изменения для extension/shipping/vfd_coordinadora (OpenCart 3) или extension/vfd_coordinadora/shipping/vfd_coordinadora (OpenCart 4) в System > Users > User Groups.

Удаление

Откройте Extensions > Extensions, выберите тип Shipping и нажмите Uninstall (красная кнопка −) рядом с VibeFox Coordinadora. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда сбрасывает Enable Coordinadora, Sort order, Tax class и Geo zone. Кэшированные тарифы всегда удаляются. Если Remove data on uninstall включено, настройки Coordinadora и журнал тоже удаляются. Если выключено, остальные настройки сохраняются и используются снова при повторной установке расширения. Существующие заказы сохраняют свой способ доставки и стоимость.

Чтобы на OpenCart 4 удалить и файлы расширения, после деинсталляции откройте Extensions > Installer, в списке установленных расширений нажмите Uninstall (оранжевая кнопка −) рядом с VibeFox Coordinadora, затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

Coordinadora — товарный знак её правообладателя. Это расширение не аффилировано с Coordinadora и не одобрено ею.