VibeFox Delhivery for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

API-токен Delhivery (только для актуальных тарифов): войдите в Delhivery One и откройте Settings > API setup. Статья поддержки Delhivery «API token generation» описывает шаги. Обе ссылки есть на странице модуля. Тестовые токены работают с окружением staging. Также понадобится 6-значный PIN-код вашего пункта отправления. Если вы используете только фиксированные цены, токен не нужен.

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

Установка

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

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

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

4. Введите API-токен и PIN-код отправления, выберите Express или Surface, а также Pre-paid или COD. Если валюта по умолчанию вашего магазина не INR, введите курс конвертации. При желании введите фиксированные цены (см. раздел «Настройка»). Нажмите Save.

При установке модуль создаёт перевозчика Delhivery с текстом срока доставки Courier delivery (India) и страницей отслеживания Delhivery в качестве URL отслеживания. Перевозчик назначается всем зонам и всем группам клиентов. Зоны, группы клиентов, срок доставки, логотип и ограничения по размеру можно изменить в Shipping > Carriers. Цены там не задавайте: цена всегда берётся из модуля.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Delhivery > Configure. Они действуют для всех зон. В каждом разделе есть своя кнопка Save, которая сохраняет всю страницу. При каждом сохранении также очищается кеш тарифов Delhivery. Суммы принимаются в формате «9.99» и «9,99». Если в числовом поле не указано неотрицательное число, появляется ошибка и ничего не сохраняется.

Если валюта по умолчанию вашего магазина не INR, API-токен сохранён, а курс конвертации не задан, предупреждение над формой напоминает, что актуальные тарифы не используются, пока вы не введёте курс. Если единица веса магазина не является стандартной (кг, г, фунты или унции), предупреждение просит задать её в International > Localization (Local units), поскольку иначе вес товаров считается в килограммах.

Общие

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

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

Tax: налоговое правило перевозчика или No tax. При наличии правила PrestaShop добавляет налог к стоимости доставки.

Учётная запись API Delhivery (нужна только для актуальных тарифов)

Environment: Production (track.delhivery.com) (по умолчанию) или Staging / test account (staging-express.delhivery.com). Используйте Staging только с тестовым токеном Delhivery.

API token: ваш API-токен Delhivery. Он передаётся только в заголовке авторизации и никогда не записывается в журналы. После сохранения поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Remove saved token: включите и сохраните, чтобы удалить сохранённый токен. После этого используются только фиксированные цены.

Origin pincode: 6-значный PIN-код вашего пункта отправления или склада, например 110001. Если в нём не 6 цифр, показывается предупреждение, и актуальные тарифы не запрашиваются, пока ошибка не исправлена.

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

Актуальный тариф запрашивается для индийских адресов назначения с корректным 6-значным PIN-кодом — для прямой отправки (доставки).

Shipping mode: режим тарификации Delhivery, по которому считается тариф: Express (по умолчанию) или Surface.

Payment type: тип оплаты, передаваемый в Delhivery: Pre-paid (по умолчанию) или COD (cash on delivery — Delhivery adds its COD charge). Модуль не переключает его в зависимости от способа оплаты, который выбирает покупатель.

Rate amount: Delhivery возвращает сумму с GST и без него.

INR to (shop currency) conversion rate: в надписи указана валюта по умолчанию вашего магазина. Тарифы Delhivery указаны в индийских рупиях. Если валюта по умолчанию не INR, введите, сколько единиц вашей валюты стоит одна рупия, например 0.011. Курс должен быть больше 0. Если оставить поле пустым, актуальные тарифы не используются и действуют фиксированные цены. Не нужно, если валюта по умолчанию — INR.

Фиксированные цены (используются, когда актуального тарифа нет)

Фиксированные цены используются, когда ещё нет токена или PIN-кода, когда адрес назначения находится за пределами Индии, когда PIN-код не обслуживается или когда API возвращает ошибку. Цены указываются в валюте по умолчанию вашего магазина без налогов.

Prices per country: по одной записи на строку в формате COUNTRY_CODE:price, например IN:120. Проверяется раньше резервной цены. Строки в другом формате удаляются при сохранении, и предупреждение их перечисляет.

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

Fixed price is charged: Per order взимает цену один раз. Per item (price × quantity) умножает её на количество товаров в корзине. Актуальный тариф Delhivery всегда рассчитывается по общему весу посылки.

Условия

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

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

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

Max weight: скрывать перевозчика, если корзина тяжелее, в кг. По умолчанию: 30. 0 означает отсутствие ограничения, пустое поле означает 30 кг. Min weight не может быть больше Max weight: страница показывает ошибку и ничего не сохраняет.

Веса товаров переводятся в кг из единицы веса вашего магазина. Тариф использует фактический вес корзины (сумму весов товаров), без объёмного веса и коробок.

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

Ignore zones: когда опция выключена, страны определяются зонами перевозчика в Shipping > Carriers. Когда включена, перевозчик привязывается ко всем зонам (в том числе к создаваемым позже) и предлагается для стран, указанных ниже. Выключение возвращает перевозчику его прежние зоны.

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

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

Debug log: записывает расчёты тарифов в logs/vfd_dlv_debug.log.php в папке модуля. Открыть файл из веба нельзя. Ошибки API всегда записываются в журнал, даже когда опция выключена. Токены и полные PIN-коды покупателей никогда не записываются.

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

Remove data on uninstall: когда опция включена, удаление модуля стирает настройки Delhivery, перевозчика, кешированные тарифы, данные заказов и журналы. Когда выключена, всё сохраняется для повторной установки. Номера AWB заказов никогда не удаляются.

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

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

Для индийского адреса с корректным 6-значным PIN-кодом модуль отправляет в Delhivery PIN-коды отправления и назначения, вес корзины в граммах, режим доставки и тип оплаты. Возвращённая сумма переводится из INR в валюту по умолчанию вашего магазина и затем показывается в валюте корзины покупателя. Каждый ответ кешируется на 1 час. Неудачный запрос кешируется на 10 минут, чтобы оформление заказа не ждало Delhivery при каждом обновлении. Тайм-аут API составляет 10 секунд.

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

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

Модуль рассчитывает тарифы и даёт покупателям ссылку для отслеживания. Он не создаёт отправления и накладные, не печатает этикетки, не вызывает курьера и не оформляет манифесты, не проверяет обслуживание PIN-кодов, не оценивает даты доставки, не синхронизирует статусы отслеживания и не рассчитывает международные тарифы Delhivery. За пределами Индии используются только фиксированные цены.

Заказы и отслеживание

Когда заказ оформлен с Delhivery, модуль сохраняет вместе с заказом режим доставки и источник цены. На странице заказа в админ-панели блок Delhivery показывает Mode: (Express или Surface), Price: (актуальный тариф Delhivery, фиксированная цена или порог бесплатной доставки) и Delhivery AWB / tracking number либо Not entered yet.

Создайте отправление в Delhivery One, затем введите его номер AWB как номер отслеживания заказа в блоке Carriers на странице заказа (Edit). После этого в блоке Delhivery появится ссылка Track on delhivery.com. Покупатель видит ссылку для отслеживания в истории заказа и получает письмо со статусом «В пути» от PrestaShop.

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

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

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

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

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

Delhivery не появляется при оформлении заказа: проверьте, что лицензия активна и включена опция Enable Delhivery. В Shipping > Carriers проверьте, что перевозчик охватывает зону страны покупателя и группу покупателя, либо включите Ignore zones и проверьте Countries. Проверьте ограничения по весу и Show from subtotal. Без актуального тарифа нужна цена для страны или Fallback price. Товары также можно ограничить определёнными перевозчиками на странице товара.

Актуальные тарифы не появляются: проверьте API-токен, корректный Origin pincode и, если валюта по умолчанию не INR, курс конвертации. Покупатель должен ввести корректный 6-значный индийский PIN-код. Включите Debug log, перезагрузите оформление заказа и посмотрите поле Log на странице модуля. В нём указана причина, например PIN-код вне зоны обслуживания или HTTP-ошибка от Delhivery.

GST начисляется дважды: общая сумма Delhivery уже включает GST. Установите Rate amount в значение Gross amount (excluding GST) или установите Tax в значение No tax.

Тестирование: установите Environment в значение Staging и используйте тестовый токен Delhivery.

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

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

Для разработчиков: модуль выполняет хуки actionVfdDlvApiUrl и actionVfdDlvApiTimeout, которые могут изменить адрес API и тайм-аут.

Удаление

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

Delhivery — торговая марка её владельца. Этот модуль не аффилирован с Delhivery и не одобрен ею.