VibeFox Andreani for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3), стандартная тема.

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

Учётная запись Andreani (только для тарифов в реальном времени): тарифы в реальном времени используют API расчёта Andreani. Andreani выдаёт коммерческим клиентам учётные данные API, клиентский код и номера договоров, обычно при объёме от примерно 300 отправлений в месяц. См. developers.andreani.com или напишите на ventapyme@andreani.com. Вам понадобятся имя пользователя и пароль API, клиентский код (código de cliente) и номер договора. Andreani выдаёт отдельный договор на каждую услугу (доставка на дом, самовывоз из отделения). Без доступа к API используйте фиксированные цены. Выбор отделения работает без учётных данных.

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

Установка

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

OpenCart 3

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

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

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

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

5. Укажите название, источник тарифов, цены по странам (например AR=5000) и для тарифов в реальном времени учётные данные API, клиентский код и номер договора (см. Конфигурация). Нажмите Save.

OpenCart 4

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

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

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

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

После установки Enable/Disable и Enable second option выключены, и Andreani не предлагается при оформлении заказа, пока вы не включите опцию и не нажмёте Save. Если вы установите расширение повторно после удаления, сохранённые настройки Andreani будут использованы снова, но обе опции выключены: включите их и нажмите Save.

Конфигурация

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox Andreani > Edit. Разделы перечислены слева. Одна кнопка Save сохраняет всю страницу без перезагрузки. После сохранения вы видите Settings saved. Cached token, branches and rates were cleared. Сохранять настройки могут только администраторы с правом изменения этого расширения.

Предупреждения об отсутствующих настройках выводятся в верхней части страницы: выбраны тарифы API без имени пользователя и пароля API или без номера договора, нет ARS exchange rate, когда валюта вашего магазина не ARS, или нет цены для Аргентины в Country prices. Предупреждение также появляется, если единица веса или длины магазина не распознаётся расширением (тогда веса считаются в килограммах, а размеры — в сантиметрах).

При сохранении отклоняются пустое название, название длиннее 64 символов или с одним из символов < > ; = # { }, Min weight (kg) больше Max weight (kg), а также Sort order, которое не является целым числом; при этом ничего не сохраняется. Значение, которое не является числом, отрицательное число или ARS exchange rate 0 или меньше не сохраняются, и предупреждение называет поле.

Общие

В оформлении заказа Andreani предлагает две опции: основную, которая настраивается здесь и в разделах Andreani API и Delivery and rates, и Second option. Обе отображаются под заголовком Andreani на шаге способа доставки.

Enable/Disable: включает или выключает основную опцию Andreani. По умолчанию: выключено. У второй опции свой переключатель.

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

Tax status: None (the API rate is taken with IVA) (по умолчанию) или один из ваших налоговых классов. С налоговым классом OpenCart добавляет налог к стоимости доставки, поэтому тариф API берётся без IVA. При None тариф API берётся с включённым IVA. Используется обеими опциями.

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

Andreani API (нужно для тарифов в реальном времени)

Environment: Sandbox / QA (apisqa.andreani.com) (по умолчанию) или Production (apis.andreani.com). Используйте среду, к которой относятся ваши учётные данные.

API username: ваше имя пользователя в API Andreani.

API password: ваш пароль в API Andreani. После сохранения поле остаётся пустым и показывает Saved - leave empty to keep it. Clearing the API username removes it too. Вводите новое значение, только если хотите его изменить.

Client code: клиентский код (código de cliente), который предоставляет Andreani, например CL0000000.

Contract number: договор на услугу, которая используется для тарифов, например доставка на дом. Вторая опция может использовать другой договор, например для самовывоза из отделения.

Origin branch code: необязательное отделение отправления (sucursalOrigen) для расчёта тарифов. Оставьте пустым, чтобы использовать отделение, указанное в вашем договоре.

Доставка и тарифы

Delivery modality: способ доставки основной опции. Первая часть показывает, откуда Andreani забирает посылку (ваш адрес или отделение, куда вы её сдаёте). Вторая часть показывает, где её получает покупатель.

Rate source: способ расчёта цены.

Country prices: фиксированная цена для каждой страны назначения в валюте магазина по умолчанию, без налога, по одной строке на страну в формате CC=ЦЕНА, например AR=5000. Используется в фиксированном режиме и как запасной вариант при сбое API. Страны без строки не получают фиксированной цены. Строки в другом формате пропускаются, и при сохранении предупреждение их перечисляет.

ARS exchange rate: Andreani считает в аргентинских песо. Нужно, только если валюта магазина по умолчанию не ARS: цена 1 ARS в валюте вашего магазина, например 0.001. Без этого значения тарифы API не используются.

Default product weight (kg): используется для товаров без веса при запросе тарифов API и при проверке ограничений по весу. Пустое значение означает 0,5 кг.

Calculation type: Per order (по умолчанию) берёт цену один раз. Per item (price x number of items) умножает фиксированную цену из Country prices на количество товаров в корзине. Тариф Andreani в реальном времени уже относится ко всей корзине и не умножается.

Доступность

Min weight (kg): минимальный вес корзины, при котором появляется опция. 0 означает без ограничения (по умолчанию).

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

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

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

Ignore shipping zones: предлагает Andreani для стран, перечисленных ниже, независимо от географической зоны. По умолчанию: выключено.

Countries: страны назначения для этого режима. Оставьте пустым, чтобы разрешить все страны. Используется только при включённом Ignore shipping zones.

Бесплатная доставка

Free shipping: включает порог бесплатной доставки. По умолчанию: выключено.

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

Вторая опция

Вторая опция Andreani с собственным названием, способом доставки и договором, например «a domicilio» в основной опции и «retiro en sucursal» здесь, чтобы предлагать обе. Все остальные настройки общие.

Enable second option: предлагает вторую опцию при оформлении заказа. По умолчанию: выключено.

Second option name: название этой опции при оформлении заказа. По умолчанию: Andreani - branch pickup. Обязательно.

Delivery modality: Use global setting или один из четырёх способов. По умолчанию: Door to branch (Puerta a Sucursal).

Contract number: Andreani выдаёт отдельный договор на каждую услугу (доставка на дом, самовывоз из отделения). Оставьте пустым, чтобы использовать общий договор.

Выбор отделения (показывается для Door to branch и Branch to branch)

Province select width: ширина списка областей в CSS, например 100% или 300px. По умолчанию: 100%.

Branch select width: ширина списка отделений в CSS, например 100% или 400px. По умолчанию: 100%.

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

Debug log: записывает запросы к API и расчёты тарифов в storage/logs/vfd_andr_debug.log.php. Файл недоступен для чтения из веба. Ошибки записываются всегда. Учётные данные и токены никогда не записываются в журнал. Когда файл достигает 5 МБ, он переносится в vfd_andr_debug.old.log.php, и начинается новый журнал.

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

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

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

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

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

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

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену каждой включённой опции Andreani. Если задана Geo zone и не включено Ignore shipping zones, Andreani не предлагается для адресов вне географической зоны. Учитываются только товары с Requires Shipping = Yes: остальные не добавляют веса и не входят в промежуточный итог. Затем расширение проверяет страны (если включено Ignore shipping zones), вес корзины (веса товаров переводятся в кг, товары без веса используют Default product weight (kg)) и Minimum subtotal. Промежуточный итог — это цена товаров, которые нужно доставить, после скидки по купону и без налога.

В фиксированном режиме цена берётся из Country prices. В режимах тарифов в реальном времени расширение выполняет вход в API Andreani и запрашивает расчёт с почтовым индексом назначения, договором, клиентским кодом, весом в кг, объёмом по размерам товаров и заявленной стоимостью (промежуточный итог корзины в ARS). Тариф в реальном времени запрашивается только для корректного аргентинского почтового индекса (4 цифры или CPA, например C1425ABC). Сумма в ARS конвертируется с помощью ARS exchange rate, если валюта магазина не ARS. Цена рассчитывается в валюте магазина по умолчанию, округляется до её знаков после запятой и показывается покупателю в его валюте с налогом выбранного Tax status.

Токен входа хранится до 23 часов и автоматически обновляется, когда Andreani его отклоняет. Расчёты кэшируются на 1 час. Неудачный вызов API не повторяется в течение 5 минут. Всё это хранится в кэше OpenCart, поэтому запись никогда не живёт дольше срока жизни кэша OpenCart (по умолчанию 1 час), после чего запрашивается заново. Ошибки API никогда не показываются покупателю: опция скрывается, либо в резервном режиме используется фиксированная цена. Причина записывается в журнал.

Если Free shipping включено и промежуточный итог корзины достигает Free shipping from, цена равна 0. Бесплатная доставка применяется только там, где у опции есть цена: если API Andreani не возвращает тариф и нет фиксированной цены для замены, опция не показывается.

Расширение не создаёт отправления Andreani, не печатает этикетки и не отслеживает посылки. Для этого используйте веб-портал Andreani.

На OpenCart 4 покупатель нажимает Choose в блоке способа доставки на странице оформления заказа и выбирает опцию Andreani в окне Shipping method options. Опции работают так же, как на OpenCart 3; выбор отделения описан в разделе Пункты выдачи.

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

Когда предлагается опция с Door to branch или Branch to branch, сразу под ней на шаге способа доставки появляются список областей и список отделений. Область предварительно выбирается по региону адреса доставки. Список отделений берётся из публичного API отделений Andreani и кэшируется до 12 часов (в пределах срока жизни кэша OpenCart). Отделения, которые не принимают посылки, в список не попадают. Сам шаг доставки никогда не ждёт Andreani: если список ещё не в кэше, он загружается в фоновом режиме, а покупатель некоторое время видит Loading Andreani branches.... Если отделений нет, покупатель видит No Andreani branches available right now. Please try again later or choose another shipping method.

Выбор сохраняется сразу, как только покупатель его делает. Принимается только отделение из текущего списка Andreani. Без отделения Continue на шаге доставки не проходит, и покупатель видит Please select an Andreani pickup branch. Сервер повторно проверяет отделение, когда покупатель продолжает оформление. Если отделения больше нет в списке, покупатель видит The selected Andreani branch is not available. Please choose another one.

На OpenCart 4 список областей и список отделений появляются в окне Shipping method options, сразу под опцией Andreani с отделением, с теми же текстами и проверками. Continue в окне без отделения не проходит, и под опцией появляется сообщение Please select an Andreani pickup branch. Если магазин отклоняет отделение, когда покупатель продолжает оформление, сообщение показывается в верхней части страницы оформления, а окно остаётся открытым. OpenCart 4 хранит один заказ для оформления и обновляет его при каждом подтверждении; отделение заказа обновляется вместе с ним, и оно удаляется, когда покупатель меняет заказ на другой способ доставки.

Отделение, выбранное под одной опцией Andreani, не относится к заказу, оформленному с другой опцией или другим способом доставки.

Выбор рассчитан на оформление заказа в одну страницу стандартной темы OpenCart 3 и на оформление заказа стандартной темы OpenCart 4. Тема с другой структурой шага доставки может потребовать изменений в скрипте выбора.

Заказы

Заказ сохраняет способ доставки и, для способов с отделением, выбранное отделение.

Shipping method of the order: отделение добавляется к тексту способа доставки, например Andreani - branch pickup: и название отделения. Если название опции не упоминает отделение, перед названием отделения добавляется текст Pickup branch: (или Andreani pickup branch:, если в названии нет Andreani), например Andreani - Pickup branch: и название отделения. Этот текст появляется в письмах о заказе покупателю и магазину, в истории заказов покупателя, на счёте и на странице заказа в админке. OpenCart ограничивает текст 128 символами; полные данные об отделении сохраняет расширение. Страница успешного оформления заказа в OpenCart способ доставки не показывает.

Admin order page: в Sales > Orders откройте заказ. Панель Andreani показывает Andreani modality и для способов с отделением Andreani branch (название, ID и область). Нажмите Edit, выберите другую область и отделение и нажмите Save, чтобы изменить его. Вы увидите Branch updated., и отделение в тексте способа доставки заказа тоже заменится. Сохранить можно только отделения из списка Andreani. Если список недоступен, вы увидите The Andreani branch list is not available right now - the branch cannot be changed. Для смены отделения нужно право изменения для sale/order и доступ к extension/shipping/vfd_andreani (OpenCart 3) или extension/vfd_andreani/shipping/vfd_andreani (OpenCart 4). Панель показывается и для заказов, уже оформленных с Andreani, даже когда расширение выключено.

Пока расширение выключено, панель Andreani не показывается. Данные об отделении сохраняются, текст способа доставки заказа не меняется. Существующие заказы сохраняют свои данные об отделении.

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

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

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

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

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

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

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

Andreani не появляется при оформлении заказа: проверьте, что лицензия активна и включено Enable/Disable (для второй опции также Enable second option), и что вы нажали Save после установки. Проверьте Geo zone, либо Ignore shipping zones и Countries. Проверьте, есть ли в Country prices строка для страны (для фиксированных цен или как запасной вариант), ограничения по весу и Minimum subtotal. Прочитайте предупреждения в верхней части страницы Edit. Проверьте, что у товаров Requires Shipping = Yes.

Тарифы в реальном времени не появляются: включите Debug log, обновите оформление заказа и посмотрите поле Log на странице расширения. В нём указана причина: нет учётных данных или номера договора, не удался вход (неверные имя пользователя, пароль или среда), пока нет корректного аргентинского почтового индекса, нет курса обмена или ошибка HTTP от Andreani. С Andreani API, fixed price if the API fails покупатели всё равно получают фиксированную цену, пока вы исправляете проблему.

Магазин не в аргентинских песо: укажите в ARS exchange rate значение 1 ARS в валюте магазина по умолчанию.

Налог на доставку выглядит неправильно: с налоговым классом в Tax status используется тариф Andreani без IVA, а OpenCart добавляет свой налог. При None используется тариф с IVA и налог не добавляется. Проверьте, что налоги включены в настройках магазина и что у налогового класса есть ставки для Аргентины.

В списке нет отделений: API отделений Andreani не ответил. Неудачный запрос повторяется через 5 минут. Проверьте журнал.

Предварительно выбрана не та область: область определяется по региону адреса доставки. Покупатель всегда может выбрать другую область.

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

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

Для разработчиков: адреса API Andreani можно заменить настройкой vfd_andr_api_url (для тестов); на странице настроек для неё нет поля.

Удаление

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

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

Andreani — торговая марка её правообладателя. Это расширение не связано с Andreani и не одобрено ею.