VibeFox Andreani for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

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

VibeFox license key: покупается на vibefox.net. Один ключ работает на одном домене.

Установка

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

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

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

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

При установке модуль создаёт два перевозчика:

Оба перевозчика привязаны к зоне Аргентины и ко всем группам клиентов. Зоны, группы клиентов, срок доставки, логотип и ограничения размеров можно изменить в Shipping > Carriers. Цены там не задавайте: цена всегда берётся из модуля.

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

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Andreani > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. После сохранения вы увидите Settings saved. Cached token, branches and rates were cleared. Предупреждения о недостающих настройках (учётные данные API, номер договора, курс ARS, нет цены для Аргентины, удалённый перевозчик) выводятся в верхней части страницы. Предупреждение также появляется, если модуль не распознаёт единицу веса или габаритов магазина (тогда вес читается как кг, а габариты как см). При сохранении название длиннее 64 символов или Min weight (kg) больше Max weight (kg) отклоняются, и ничего не сохраняется. Значение, которое не является числом, отрицательное число или ARS exchange rate 0 и меньше, не сохраняется, а предупреждение указывает поле.

General

Enable/Disable: включает или выключает доставку Andreani. Это тот же переключатель, что и статус основного перевозчика в Shipping > Carriers. У второго варианта свой переключатель.

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

Tax status: None или Taxable с одним из ваших налоговых правил. С налоговым правилом магазин добавляет налог к стоимости доставки, поэтому тариф API берётся без IVA. При None тариф API берётся с учётом IVA. Настройка сохраняется для обоих перевозчиков 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=PRICE, например 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 кг, 0 означает без ограничения.

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

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

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

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

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

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

Второй вариант

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

Enable second option: включает или выключает второго перевозчика. Это тот же переключатель, что и его статус в Shipping > Carriers. По умолчанию: выключено.

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 и расчёты тарифов в файл logs/vfd_andr_debug.log.php в папке модуля. Файл нельзя открыть из веба. Ошибки записываются всегда. Учётные данные и токены никогда не записываются.

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

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

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

На шаге доставки PrestaShop запрашивает у модуля цену каждого перевозчика Andreani. Учитываются только физические товары: виртуальные товары не добавляют веса и не входят в промежуточный итог. Модуль проверяет страны (когда включена опция Ignore shipping zones), вес корзины (веса товаров переводятся в кг, товары без веса используют Default product weight (kg)) и Minimum subtotal.

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

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

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

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

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

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

Когда выбран перевозчик с Door to branch или Branch to branch, под ним на шаге доставки появляются список провинций и список отделений. Провинция подставляется автоматически по адресу доставки. Список отделений берётся из публичного API отделений Andreani и кэшируется на 12 часов. Отделения, которые не выдают посылки, в список не попадают. Если отделения недоступны, покупатель видит 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.

Отделение, выбранное в Andreani до того, как покупатель переключился на другого перевозчика, не относится к заказу.

Заказы

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

Admin order page: блок Andreani показывает способ доставки и отделение (название, ID и провинцию). Нажмите Edit, выберите другую провинцию и отделение и нажмите Save, чтобы изменить его. Вы увидите Branch updated. Сохранить можно только отделения из списка Andreani. Если список недоступен, отделение изменить нельзя.

Покупатель: отделение отображается как Andreani pickup branch: на странице подтверждения заказа и на странице деталей заказа.

E-mails: в письме с подтверждением заказа и в письме о новом заказе магазину (модуль Mail alerts) отделение добавляется к названию перевозчика. В письме магазину также указывается ID отделения.

Существующие заказы сохраняют свои данные об отделении.

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

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

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

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

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

Andreani не появляется при оформлении заказа: проверьте, что лицензия активна и включён Enable/Disable (для второго перевозчика также Enable second option). В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и его группу клиентов, или включите Ignore shipping zones и проверьте Countries. Проверьте, что в Country prices есть строка для страны (для фиксированных цен или как резерв), а также ограничения по весу и Minimum subtotal. Прочитайте предупреждения в верхней части страницы Configure. Кроме того, товары могут быть ограничены определёнными перевозчиками на странице товара.

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

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

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

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

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

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

Удаление

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

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