VibeFox Delhivery for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

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

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

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

Установка

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

После установки способ доставки выключен, пока вы не включите Enable Delhivery и не сохраните настройки. Если вы устанавливаете расширение повторно после удаления, сохранённые настройки Delhivery снова используются.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox Delhivery > Edit. Разделы перечислены слева. Одна кнопка Save сохраняет всю страницу без перезагрузки. Каждое сохранение также очищает кэшированные тарифы Delhivery. Суммы принимают «9.99» и «9,99». Если значение неверно, ничего не сохраняется, а страница показывает причину, например Enter a valid method title (without < > ; = # { })., сообщение о том, что поле должно быть неотрицательным числом, или Sort order must be a whole number. Сохранять настройки могут только администраторы с правом изменения для этого расширения.

Если основная валюта магазина не INR, API-токен сохранён, а курс пересчёта не задан, предупреждение вверху страницы напоминает, что актуальные тарифы не используются, пока вы не введёте курс. Если в магазине нет класса веса в килограммах и его единица веса не стандартная (kg, g, lb или oz), предупреждение сообщает, что веса товаров читаются как килограммы. Задайте стандартную единицу в System > Localisation > Weight Classes.

Общие

Настройки применяются ко всем географическим зонам. Способ доставки можно ограничить в разделе Availability.

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

Method title: название способа доставки, которое видит покупатель в корзине и при оформлении заказа. По умолчанию: Delhivery. Обязательное поле, не более 64 символов, без символов < > ; = # { }.

Tax class: налоговый класс стоимости доставки или No tax (по умолчанию). Если класс выбран, OpenCart добавляет налог к стоимости доставки.

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

Учётная запись 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-значный pincode вашего пункта отправки или склада, например 110001. Если в нём не 6 цифр, настройки сохраняются с предупреждением The origin pincode must have 6 digits — live rates are not requested until it is fixed.

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

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

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 (store currency) conversion rate: в подписи указана основная валюта вашего магазина. Тарифы Delhivery указаны в индийских рупиях. Если основная валюта не INR, укажите, сколько единиц вашей валюты стоит одна рупия, например 0.011. Курс должен быть больше 0. Если оставить поле пустым, актуальные тарифы не используются и применяются фиксированные цены. Если основная валюта INR, это поле не нужно.

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

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

Prices per country: по одной на строку в формате КОД_СТРАНЫ:цена, например 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 (kg): минимальный вес корзины, при котором показывается способ доставки. 0 означает отсутствие ограничения (по умолчанию).

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

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

Доступность

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

Ignore zones: если включено, географическая зона не проверяется, и способ доставки предлагается для стран ниже (для всех стран, если список пуст).

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

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

Debug log: записывает расчёты тарифов в storage/logs/vfd_dlv_debug.log.php (в OpenCart 4 — в system/storage/logs/vfd_dlv_debug.log.php). Файл нельзя прочитать из интернета. Ошибки API записываются всегда, даже когда эта опция выключена. Токены и полные pincode покупателей никогда не записываются в журнал. Когда файл достигает 5 МБ, он переносится в vfd_dlv_debug.old.log.php, и начинается новый журнал.

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

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

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

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

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

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

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену Delhivery. Если задана Geo zone (и Ignore zones выключено), а адрес вне неё, Delhivery не предлагается. Учитываются только товары с Requires Shipping, установленным в Yes: остальные товары не добавляют веса и не входят в промежуточную сумму. Затем расширение проверяет страны (если включено Ignore zones), вес корзины и Show from subtotal. Промежуточная сумма — это цена товаров, требующих доставки, после скидки по купону и до налогов. Подарочные сертификаты, бонусные баллы и кредит магазина не учитываются. Если применяется бесплатная доставка, цена равна 0, и запрос в Delhivery не отправляется.

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

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

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

В OpenCart 4 покупатель нажимает Choose в блоке способа доставки на странице оформления заказа и выбирает Delhivery в окне Shipping method options. Способ работает так же, как в OpenCart 3.

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

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

В OpenCart 4 оформление заказа сохраняет один заказ и обновляет его каждый раз, когда покупатель повторно подтверждает заказ. Вместе с ним обновляются режим и источник цены. Если покупатель выбирает другой способ доставки до ввода AWB, панель Delhivery для этого заказа больше не показывается.

Создайте отправление в Delhivery One, затем введите его AWB в панели и нажмите Save. Страница не перезагружается. Буквы, цифры и тире сохраняются (до 64 символов). Чтобы удалить AWB, сохраните пустое поле. Если AWB указан, панель показывает ссылку Track on delhivery.com. Для сохранения AWB нужно право изменять заказы. Без него панель только для чтения.

Зарегистрированный покупатель видит на странице заказа в своём аккаунте строку Delhivery tracking: с AWB в виде ссылки на страницу отслеживания Delhivery. Когда вы добавляете запись в историю заказа и уведомляете покупателя, письмо о статусе заказа получает ту же строку со ссылкой. Письмо о новом заказе ссылки для отслеживания не содержит, потому что AWB вводится позже. Панель и ссылка для отслеживания работают и для старых заказов, даже когда расширение выключено.

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

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

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

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

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

Delhivery не появляется при оформлении заказа: проверьте, что лицензия активна и включено Enable Delhivery. Проверьте Geo zone или Ignore zones и Countries, ограничения по весу и Show from subtotal. Без актуального тарифа нужна цена для страны или Fallback price. Убедитесь, что у товаров Requires Shipping установлено Yes.

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

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

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

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

AWB не сохраняется: сообщение You do not have permission to modify orders. означает, что вашей группе администраторов нужно право изменения для sale/order в System > Users > User Groups.

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

Для разработчиков: расширение вызывает события OpenCart catalog/vfd_delhivery/api_url и catalog/vfd_delhivery/api_timeout, которые позволяют изменить адрес API и тайм-аут.

Удаление

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

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

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