VibeFox Servientrega for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Аккаунт Servientrega (только для тарифов в реальном времени): тарифы в реальном времени используют Cotizador Corporativo Servientrega (корпоративный API расчета стоимости). Нужен корпоративный (кредитный) аккаунт Servientrega с доступом к нему. Понадобятся три значения: пользователь, пароль и код биллинга (código de facturación, обычно начинается с SER). Это ваши учетные данные SISCLINET, их выдает ваш коммерческий консультант Servientrega. Если вы используете только фиксированные цены, аккаунт Servientrega не нужен.

Доступ сервера (только для тарифов в реальном времени): ваш сервер должен иметь возможность обращаться к web.servientrega.com по HTTP на порт 8058 (API расчета стоимости) и порт 8081 (веб-служба шифрования пароля).

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

Установка

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

2. По окончании загрузки нажмите Configure или позже найдите VibeFox Servientrega в списке модулей и нажмите Configure.

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

4. Для тарифов в реальном времени введите пользователя, пароль и код биллинга, выберите продукт Servientrega, введите код DANE отправления и, если валюта вашего магазина не COP, курс конвертации валюты. Нажмите Add Colombian departments, если в вашем магазине их еще нет (см. Конфигурация).

5. По желанию добавьте фиксированные цены по стране и весу и резервную стоимость, затем нажмите Save.

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

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

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Servientrega > Configure. Они применяются ко всем зонам. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. Каждое сохранение очищает кэш котировок Servientrega и токен входа.

Если тарифы в реальном времени не могут работать с сохраненными настройками, предупреждение над формой сообщит причину: не указан пользователь, пароль или код биллинга, не задан курс конвертации или код DANE отправления. Предупреждение также появится, если единица измерения веса или размеров вашего магазина (International > Localization, Local units) неизвестна модулю; тогда веса читаются как кг, а размеры как см. При сохранении значение, которое не является числом, отрицательное число, курс конвертации 0, минимальный вес больше максимального, неверная цена в таблице или название метода длиннее 64 символов отклоняются с ошибкой, и ничего не сохраняется.

Общие

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

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

API Servientrega (тарифы в реальном времени для Колумбии) (необязательно; без учетных данных используются только фиксированные цены)

User (login): ваш пользователь Servientrega / SISCLINET. Очистка поля также удаляет сохраненный пароль.

Password: ваш пароль Servientrega / SISCLINET, как вы его вводите. Модуль шифрует его через веб-службу Servientrega перед входом. После сохранения поле остается пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Billing code: código de facturación вашего аккаунта Servientrega, который отображается в SISCLINET. Обычно начинается с SER.

Все три поля нужны для тарифов в реальном времени. Тарифы в реальном времени запрашиваются только для направлений в Колумбии. Для других стран используются фиксированные цены.

Servientrega product: услуга из вашего договора с Servientrega, по которой запрашивается тариф.

Расчетный вес — большее из фактического и объемного.

Currency conversion rate: Servientrega считает в COP. Если валюта магазина по умолчанию не COP, введите значение 1 COP в валюте вашего магазина, например 0.00023. Объявленная стоимость посылки переводится в COP так же. Оставьте поле пустым, если валюта вашего магазина — COP. Если магазин использует другую валюту и поле пустое, тарифы в реальном времени не используются, и действуют фиксированные цены. Модуль не загружает курсы валют. Точка и запятая принимаются как десятичный разделитель.

Colombian departments: департамент помогает различать муниципалитеты с одинаковым названием. В PrestaShop колумбийских департаментов по умолчанию нет; без них распознаются только названия городов, которые уникальны в Колумбии. Нажмите Add Colombian departments, чтобы добавить 33 департамента как регионы Колумбии (коды ISO ANT, DC…), включите Contains states для Колумбии и добавьте поле департамента в форму адреса для Колумбии. Уже существующие департаменты не добавляются повторно. Когда всё настроено, поле показывает, сколько департаментов есть у адресов в Колумбии.

Отправление из (используется для тарифов в реальном времени)

Origin city (DANE code): 8-значный код DANE муниципалитета, из которого вы отправляете, например 11001000 Bogotá, 05001000 Medellín, 76001000 Cali или 08001000 Barranquilla. Принимается и 5-значный код муниципалитета. Если поле пустое, а адрес вашего магазина в Shop Parameters > Contact > Stores находится в Колумбии, используется муниципалитет адреса магазина.

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

Price per country: таблица стран и цен в валюте магазина по умолчанию, без налога. Нажмите Add country, чтобы добавить строку, и значок корзины, чтобы удалить строку. Price действует для любого веса. Весовые колонки XS ≤1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg и XL >5 kg заменяют ее для этого веса, если они больше 0. Строка * Default действует для всех стран без собственной строки. Строка без цены не сохраняется.

Fallback cost: используется, когда нет тарифа в реальном времени и ни одна строка таблицы не подходит. Оставьте поле пустым, чтобы в этом случае скрыть перевозчика.

Fixed price applies: как начисляются фиксированные цены.

Тарифы Servientrega в реальном времени всегда рассчитываются за отправление.

Условия

Minimum weight: скрывает перевозчика, когда корзина весит меньше, в кг. 0 означает без ограничения.

Maximum weight: скрывает перевозчика, когда корзина весит больше, в кг. По умолчанию: 50. 0 означает без ограничения.

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

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

Tax: правило налога перевозчика или No tax. Котировки Servientrega (ValorTotal) уже включают сборы перевозчика. Выберите No tax, если не хотите добавлять налог сверху.

Доступность без зон доставки

Обычно перевозчик предлагается в зонах, назначенных ему в Shipping > Carriers.

Ignore shipping zones: предлагает Servientrega для стран, указанных ниже, даже если перевозчик не назначен их зоне. Тогда перевозчик назначается всем зонам, в том числе зонам, которые вы создадите позже. Выключение опции возвращает перевозчику его прежние зоны.

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

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

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

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

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

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

На шаге доставки PrestaShop запрашивает у модуля цену Servientrega. Учитываются только физические товары: виртуальные товары не добавляют вес и не входят в сумму заказа. Модуль сначала проверяет условия: страну доставки (с учетом Ignore shipping zones), вес корзины и минимальную сумму заказа. Если действует бесплатная доставка, цена равна 0 и запрос в Servientrega не отправляется. Затем модуль ищет цену: тариф Servientrega в реальном времени, затем таблицу цен и, наконец, резервную стоимость. Если цены нет, перевозчик скрывается для этой корзины.

Для направления в Колумбии при заданных учетных данных модуль находит код DANE муниципалитета покупателя. Он использует код DANE, введенный как почтовый индекс или в поле города, либо сопоставляет департамент и город со встроенной таблицей примерно из 1 130 муниципалитетов. Ударения и «D.C.» игнорируются. Название города, которое есть только в одном департаменте, находится даже без департамента.

Затем модуль отправляет в Servientrega одно место на заказ: общий вес, переведенный из единицы вашего магазина в кг, и коробку с длиной и шириной самого большого товара и общим объемом всех товаров, переведенными в см. Товары без размеров считаются как 10 × 10 × 10 см. Объявленная стоимость — подытог корзины, переведенный в COP, но не менее 6 000 COP. Servientrega возвращает итог в COP. Модуль переводит его в валюту магазина по умолчанию, а покупатель видит его в валюте корзины.

Токен входа хранится до истечения срока, но не более 4 дней. Отклоненный токен обновляется автоматически один раз. Каждая котировка кэшируется на 1 час для маршрута и посылки, поэтому одна и та же корзина не вызывает новый запрос. Неудачный запрос (шифрование, вход или котировка) кэшируется на 10 минут, чтобы оформление заказа не ждало Servientrega при каждом обновлении. Тайм-аут составляет 10 секунд на запрос.

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

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

Модуль только рассчитывает тарифы. Он не создает накладные (guías), этикетки или наклейки, не заказывает забор отправлений, не отслеживает и не отменяет отправления и не позволяет покупателям выбрать офис Servientrega (Centro de Soluciones). Создайте накладную в SISCLINET или в портале Servientrega. Наложенный платеж (logística de recaudo) не рассчитывается. Тарифы в реальном времени действуют только для внутренних отправлений внутри Колумбии. Для других стран используются фиксированные цены.

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

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

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

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

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

Servientrega не появляется при оформлении заказа: проверьте, что лицензия активна и включен Enable Servientrega. В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и группу клиентов, или включите Ignore shipping zones и проверьте Countries. Проверьте ограничения по весу и Minimum order amount. Без тарифа в реальном времени проверьте, что для страны или строки * Default задана цена, или что задана Fallback cost. Товары также могут быть ограничены определенными перевозчиками на странице товара.

Тарифы в реальном времени не появляются: включите Debug log, перезагрузите оформление заказа и посмотрите поле Log на странице модуля. Частые причины: нет курса конвертации (валюта магазина не COP), нет кода DANE отправления, департамент или город покупателя еще не введены либо не являются известным муниципалитетом, неверные учетные данные или нет покрытия для маршрута. Фиксированные цены покрывают эти случаи, если вы их задали.

Вход не выполняется: проверьте пользователя, пароль и код биллинга у вашего коммерческого консультанта Servientrega. После неудачного входа модуль ждет 10 минут перед следующей попыткой. Сохраните настройки, чтобы повторить попытку сразу.

Город покупателя не распознается: нажмите Add Colombian departments, чтобы покупатели могли выбрать свой департамент. Для редких написаний покупатель может ввести 8-значный код DANE как почтовый индекс.

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

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

Для разработчиков: хуки actionVfdSvtgDaneCode и actionVfdSvtgQuoteRequest позволяют изменить код DANE назначения и запрос котировки.

Удаление

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

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