VibeFox CTT for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Учётная запись CTT e-commerce (только для тарифов в реальном времени и пунктов CTT): тарифы в реальном времени и доставка в пункт CTT используют API CTT e-commerce. Нужна учётная запись CTT e-commerce на enviosecommerce.ctt.pt (для клиентов с договором CTT Expresso или запросите у CTT предложение). На странице управления ключами этой учётной записи создайте пару ключей: публичный и приватный. App ID (X-APPID) выдаёт CTT для вашей интеграции: уточните его у своего контакта CTT e-commerce. CTT также решает, какие функции API (расчёт стоимости, пункты CTT) может использовать ваш App ID. Наконец, вам нужен Carrier ID CTT в вашей учётной записи. После сохранения ключей на странице настроек появится список перевозчиков вашей учётной записи. Если вы используете только таблицу цен и доставку на адрес, ключи API не нужны.

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

Установка

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

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

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

4. Заполните таблицу цен (хотя бы строку Portugal или * Default) и нажмите Save. При желании заполните ключи API CTT и Carrier ID, включите Live rates и Enable CTT point carrier (см. раздел «Настройка»).

При установке модуль создаёт двух перевозчиков. CTT (доставка на адрес покупателя, текст срока доставки CTT delivery to your address) включён. CTT point / parcel locker (текст срока доставки Pickup at a CTT point or parcel locker) выключен, пока вы его не включите. Оба привязаны к зоне Португалии и ко всем группам клиентов. Зоны, группы клиентов, срок доставки, логотип и ограничения размеров можно изменить в Shipping > Carriers. Цены там не задавайте: цена всегда берётся из модуля.

Настройка

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

Предупреждения над настройками сообщают о пустой таблице цен, отсутствующей цене для Португалии, неполных ключах API, отсутствующем Carrier ID, валюте магазина, отличной от EUR, без курса обмена, сбое подключения к API CTT и удалённом перевозчике CTT. Некорректные значения сообщаются при сохранении: неверное число не сохраняется, неизвестное направление или повторяющаяся строка в таблице цен удаляется. Если модуль не распознаёт единицы веса или размеров вашего магазина, предупреждение попросит задать единицы в International > Localization (Local units).

Общие

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

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

Tax status: None означает, что цены окончательные. Taxable с налоговым правилом означает, что PrestaShop добавляет к ценам налог на доставку (например, IVA). Выбор сохраняется для обоих перевозчиков CTT.

Доставка в пункт CTT или на постамат

Второй перевозчик CTT. Покупатель ищет пункты CTT по почтовому индексу или городу и должен выбрать один из них, прежде чем продолжить. Нужны ключи API CTT и Carrier ID. Без них это перевозчик без выбора пункта.

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

CTT point carrier name: название этого варианта при оформлении заказа. По умолчанию: CTT point / parcel locker. Обязательно, до 64 символов.

API CTT e-commerce (тарифы в реальном времени, пункты CTT) (необязательно; без ключей используется таблица цен)

Public key: публичный ключ со страницы управления ключами вашей учётной записи CTT e-commerce.

Private key: секретный ключ, которым подписывается каждый запрос (HMAC-SHA256). Он никогда не отправляется в CTT и не записывается в журнал.

Оба ключа после сохранения больше не показываются. Тогда описание поля гласит Saved - leave empty to keep it. Вводите новое значение, только если хотите его изменить. Отметьте Remove the saved public and private key и сохраните, чтобы удалить оба ключа.

App ID (X-APPID): ключ приложения, выданный CTT, отправляется в заголовке X-APPID.

Carrier ID: ID перевозчика CTT в вашей учётной записи, используется для тарифов в реальном времени и поиска пунктов CTT. После сохранения ключей и App ID под полем показываются перевозчики вашей учётной записи; те, что поддерживают пункты CTT, отмечены (CTT points). Только цифры.

Live rates: модуль запрашивает у CTT цену (расчёт стоимости), как только покупатель введёт улицу, почтовый индекс и город. Пока адрес неполный или CTT не возвращает цену, используется таблица цен. CTT называет эту цену оценкой. По умолчанию: выключено.

Service ID: необязательно. Если CTT возвращает несколько услуг, используется услуга с этим ServiceId. Оставьте поле пустым, чтобы использовать самую дешёвую.

Exchange rate: цены CTT указаны в евро. Если валюта магазина по умолчанию другая, укажите, сколько единиц валюты магазина равны 1 единице валюты CTT. Без этого тарифы в реальном времени в другой валюте не используются и действует таблица цен.

Default product size (cm): длина x ширина x высота, которые отправляются в CTT для товаров без габаритов. По умолчанию: 30x20x15. Товары с габаритами используют свои. Габариты переводятся в см, а вес — в граммы по единицам вашего магазина.

Цены (в заголовке раздела показана валюта магазина по умолчанию)

Введите цены по вашему договору с CTT или по публичному прайсу CTT на ctt.pt в валюте магазина по умолчанию, без налогов. Когда тарифы в реальном времени выключены, эта таблица определяет цену. Когда они включены, таблица служит запасным вариантом.

Price table: одна строка на направление. Выберите страну, Portugal - Azores (PT-AC), Portugal - Madeira (PT-MA) или * Default (other destinations). Каждая строка содержит базовую Price и необязательные цены для размеров XS (до 1 кг), S (до 2 кг), M (до 3 кг), L (до 5 кг) и XL (свыше 5 кг). Пустая (или нулевая) цена размера использует базовую цену. Строка, где оба поля пусты, скрывает перевозчика. Строка Azores применяется к португальским почтовым индексам 9500-9999, строка Madeira (включая Porto Santo) — к 9000-9499. Без них применяется строка Portugal. Нажмите Add destination, чтобы добавить строку, и значок корзины, чтобы удалить её. Цены принимают десятичную точку или запятую. После установки таблица пуста.

Calculation: как находится цена по таблице.

Цена CTT в реальном времени всегда относится ко всему отправлению.

Условия

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

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

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

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

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

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

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

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

Ignore shipping zones: предлагает перевозчиков в странах, указанных ниже, без привязки к их зоне. При включении оба перевозчика привязываются ко всем активным зонам (в том числе к зонам, которые вы создадите позже). При выключении они возвращаются к зонам, которые были у них раньше.

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

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

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

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

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

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

На шаге доставки PrestaShop запрашивает у модуля цену для каждого перевозчика CTT. Учитываются только физические товары: виртуальные товары не добавляют вес и не входят в сумму заказа. Модуль сначала проверяет Ignore shipping zones и его страны, вес корзины и минимальную сумму заказа. Если включены Live rates и адрес заполнен полностью, модуль отправляет в CTT адрес доставки и для каждой позиции корзины количество, вес в граммах и габариты в см, а затем использует возвращённую цену. В противном случае, или когда CTT не возвращает цену (ошибка API, тайм-аут, нет покрытия, функция не включена для вашего App ID), цена берётся из таблицы. Если действует бесплатная доставка, цена равна 0. Цена рассчитывается в валюте магазина по умолчанию и затем показывается в валюте корзины покупателя.

Цена CTT кэшируется на 1 час, поэтому одна и та же корзина не вызывает новый запрос. Неудачный запрос запоминается на 5 минут, чтобы оформление заказа не ждало CTT при каждом обновлении. Тайм-аут API — 12 секунд. Ошибки API никогда не доходят до покупателя: используется цена из таблицы или перевозчик скрывается, если для направления нет цены.

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

Когда ключи API заполнены, модуль отправляет в CTT адрес доставки, веса и габариты товаров и URL вашего магазина, чтобы получить цену или ближайшие пункты CTT.

Модуль не создаёт отправления, не печатает этикетки, не заказывает забор, не выдаёт трек-номера и не показывает карту пунктов CTT. Для обоих перевозчиков есть одна таблица цен и один набор настроек API.

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

Когда покупатель выбирает перевозчика пунктов CTT, под ним появляются поле поиска и список. Почтовый индекс адреса доставки подставляется и ищется автоматически. Покупатель может искать другие пункты CTT по почтовому индексу или городу (кнопка Search или Enter) и выбрать один из списка. Выбор сразу сохраняется в корзине. Принимается только пункт из списка CTT для этого поиска.

Пункт нужно выбрать, прежде чем покупатель сможет продолжить. Когда покупатель нажимает Continue на шаге доставки, модуль повторно проверяет пункт на сервере. Без пункта покупатель видит Please select a CTT point., с пунктом, которого нет в списке CTT, — The selected CTT point is not in the CTT list for this search. Please choose the CTT point again. Списки пунктов CTT кэшируются на 6 часов. Если CTT недоступен, покупатель видит CTT points cannot be loaded right now. Please try again in a few minutes or choose another shipping method.

Выбор пункта работает с темами Classic и Hummingbird. Он активен только тогда, когда заполнены публичный ключ, приватный ключ, App ID и Carrier ID.

Выбранный пункт сохраняется в заказе. Он отображается на странице заказа в админке в блоке CTT point (название и ID), на странице подтверждения заказа, в сведениях о заказе в аккаунте покупателя и в письме с подтверждением заказа в виде CTT point: рядом с названием перевозчика. Новое письмо о заказе модуля Mail alerts также показывает ID пункта.

На странице заказа в админке введите почтовый индекс или город в поле Change CTT point, нажмите Search, выберите пункт и нажмите Save. Страница покажет CTT point updated., и добавится приватное сообщение к заказу CTT point changed to: с новым пунктом. Для изменения пункта нужно право на редактирование заказов.

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

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

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

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

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

CTT не появляется при оформлении заказа: проверьте, что лицензия активна и включён Enable/Disable (или Enable CTT point carrier). В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и группу покупателя, или что включён Ignore shipping zones и страна разрешена. Проверьте, что для направления есть строка в таблице цен (или строка * Default), что вес корзины находится в пределах Min weight и Max weight и что достигнута Minimum order amount. Товары также можно ограничить определёнными перевозчиками на странице товара.

Покупатель не может выбрать пункт CTT: выбор появляется только под перевозчиком пунктов CTT и только когда заполнены публичный ключ, приватный ключ, App ID и Carrier ID. Проверьте предупреждения над настройками, включите Debug log и посмотрите поле Log на странице модуля.

Тарифы в реальном времени не появляются: таблица цен используется, пока покупатель не введёт улицу, почтовый индекс и город. Проверьте предупреждения над настройками и журнал. Ответ «405» означает, что функция не включена для вашего App ID: уточните это у CTT. В магазине, работающем не в евро, заполните Exchange rate.

Не удалось подключиться к API CTT: предупреждение над настройками показывает ошибку. Проверьте ключи и App ID. Модуль повторит попытку автоматически через несколько минут.

Цены с НДС или без НДС: при Tax status с правилом Taxable PrestaShop добавляет налог на доставку к цене. При None цена окончательная.

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

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

Для разработчиков: адрес API CTT можно изменить ключом конфигурации vfd_ctt_API_URL.

Удаление

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

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